KB-7749
dot-iu-cutter v0.1 — P0 Migration Design Master
14 min read Revision 1
dot-iu-cuttermigration-designp0masterno-ddlrev5d
dot-iu-cutter v0.1 — P0 Migration Design Master
Date: 2026-05-15 Status: P0 MIGRATION DESIGN PHASE — ACTIVE (DESIGN ONLY) Trigger: GPT explicit-approval prompt unlocks P0 Migration Design Package phase per P0 Gate
OPEN_PENDING_EXPLICIT_PROMPT_APPROVAL→ nowOPEN_AND_PROMPTED. Baseline: Đ44 P0-blocking ratified_with_notes + Đ24 P0 batch ratified_with_notes + 5 Council governance gaps ratified_with_notes + 12 design deliverables + 4 planning + 10 closures + 2 ratifications. Scope: DESIGN ONLY. No code, no DDL, no SQL, no CREATE TABLE, no ALTER TABLE, no column DDL, no migration execution, no PG mutation, no Qdrant mutation, no implementation planning, no implementation execution.
1. Phase Scope
P0 Migration Design Package converts the 6 P0 schema gaps (from P0 Schema Planning §5) into logical migration designs — fields, lifecycle, dependencies, risks, open decisions — without writing any DDL/SQL or executing any schema change.
phase_id: dot-iu-cutter-v0.1-p0-migration-design
phase_type: design_only
phase_authorization: GPT explicit prompt (2026-05-15) acting per User delegation
phase_completion_signals:
- master document (this file)
- six per-item design files (P0-1 through P0-6 in topological order)
- one risk/coverage report
phase_does_not_advance_to: implementation_planning OR implementation_execution
next_phase_gate: post-design Đ32 risk approval per P0 item (separate phase) → implementation planning prompt approval (separate prompt)
2. Hard Boundaries
no_code: true
no_ddl: true
no_sql: true
no_create_table: true
no_alter_table: true
no_column_ddl: true
no_index_ddl: true
no_constraint_ddl: true
no_migration_executed: true
no_pg_mutation: true
no_qdrant_mutation: true
no_directus_mutation: true
no_data_writes: true
no_implementation_planning: true
no_implementation_execution: true
no_previous_file_modified: true
no_design_or_planning_or_closure_or_ratification_file_modified: true
output_form: logical_design_in_markdown_only
Logical design includes: field NAMES, conceptual TYPE-CLASSES (text / integer / boolean / JSONB / FK reference / timestamp / enum-ref), lifecycle state-machine notation, dependency graphs, risk notes, open decisions.
Logical design EXCLUDES: SQL syntax, CREATE/ALTER statements, exact column definitions, index strategy syntax, constraint syntax, RLS policies, triggers, functions, migrations files.
3. Dependency Graph
Topological order (chosen for design; not execution):
[P0-5 decision_backlog_entry]
│
│ (independent root;
│ foundational for all
│ governance tracking)
▼
[P0-1 canonical_address]
│
│ (field on tac_logical_unit;
│ used by manifest_unit_block
│ per-unit identity)
▼
[P0-2 manifest_envelope +
manifest_unit_block]
│
│ (envelope+block is the
│ manifest substrate)
▼
[P0-6 review_decision]
│
│ (FK to manifest_envelope;
│ governance_event umbrella)
▼
[P0-3 cut_change_set +
rollback_key]
│
│ (FK to manifest_envelope;
│ carries change-set + DOT
│ signatures)
▼
[P0-4 verify_result]
│ (FK to manifest_envelope +
│ cut_change_set; verify gate)
▼
[P0 design complete]
Each downstream item logically depends on at least one upstream item. Migration execution order in a future implementation phase may match or differ; this design package fixes only the design order so dependencies are resolved correctly when fields cross-reference.
4. Item Order
Per the dependency graph and explicit prompt approval:
| Order | P0 ID | Logical artifact(s) | File |
|---|---|---|---|
| 1 | P0-5 | decision_backlog_entry + history/dependency/sweep_log |
dot-iu-cutter-v0.1-p0-5-decision-backlog-entry-migration-design-2026-05-15.md |
| 2 | P0-1 | canonical_address (field family on tac_logical_unit) |
dot-iu-cutter-v0.1-p0-1-canonical-address-migration-design-2026-05-15.md |
| 3 | P0-2 | manifest_envelope + manifest_unit_block (joint per Đ44 Step 1) |
dot-iu-cutter-v0.1-p0-2-manifest-envelope-unit-block-migration-design-2026-05-15.md |
| 4 | P0-6 | review_decision |
dot-iu-cutter-v0.1-p0-6-review-decision-migration-design-2026-05-15.md |
| 5 | P0-3 | cut_change_set + rollback_key |
dot-iu-cutter-v0.1-p0-3-cut-change-set-rollback-key-migration-design-2026-05-15.md |
| 6 | P0-4 | verify_result (joint with P0-3 per Đ44 Step 2) |
dot-iu-cutter-v0.1-p0-4-verify-result-migration-design-2026-05-15.md |
5. Shared Assumptions
These assumptions apply across all 6 per-item designs unless explicitly overridden.
target_db: directus (existing PG database)
target_schema_class: TAC schema (existing) OR new schema_class under directus (decision per item)
target_layers:
- Não (analytical / state record)
- Kho (data persistence; SSOT artifacts)
- Lớp KHO (governance anti-forgetting class — used by decision_backlog_entry per D5 §4.1)
versioning:
manifest_envelope: semver-style versioned (per D2 §4.1)
cut_change_set: typically frozen post-cut; new change-set per CUT execution
verify_result: immutable record per verify event
review_decision: typically immutable (re-review = new row OR new version per per-item decision)
decision_backlog_entry: version history via decision_backlog_history (per D5 §4.7)
nullability: all FK references nullable until upstream object exists (bootstrap); enforce NOT NULL via constraints post-bootstrap (separate migration design phase)
identifiers:
primary_id_form: bigserial OR uuid (decision deferred to per-item open decisions)
composite_id_acceptable: YES for manifest_unit_block (per Đ44 outcome A.2)
provenance_fields_standard:
- emitted_by (actor: ai / human / system_role)
- emitted_at (timestamp with timezone)
- tool_revision (text — references cutter tool_revision per D4 §4.6)
timezones: UTC for storage; display layer per Đ37 policy
text_storage: PG TEXT (not VARCHAR(n)); enums via Đ24-controlled lookup tables OR PG enum types (per-item decision)
jsonb_acceptance: YES for G5/G6 group fields per Đ44 outcome A.6 #3
mirror_to_kb: pattern is PG=SSOT, KB markdown=mirror; mirror generator implementation is FUTURE (per G-2 closure §5.7)
6. Shared Naming Conventions
table_names: snake_case singular subject (e.g. decision_backlog_entry, manifest_envelope)
field_names: snake_case
boolean_field_names: predicate form (is_*, has_*, was_*); no negative ("not_") prefixes
timestamp_field_names: <event>_at suffix
fk_field_names: <referent_singular>_id suffix
enum_field_names: bare noun (e.g. status, kind, risk_class)
event_kind_values: snake_case (sweep_overdue, dot_pair_drift, wrong_audience_result_event)
version_field_names: <object>_version (semver-style text)
history_table_names: <subject>_history
junction/edge_table_names: <a>_<b> singular or pluralized depending on existing convention; cutter prefers <subject>_<relation>
no_reserved_keyword_collisions: avoid pg/sql reserved keywords as field names
no_prefix_for_tac_schema: existing tac_ prefix preserved for TAC family (tac_logical_unit, tac_unit_version, tac_publication)
new_table_prefix_convention:
manifest_*: manifest family (manifest_envelope, manifest_unit_block)
cut_*: change-set family (cut_change_set)
verify_*: verify family (verify_result)
review_*: review family (review_decision)
decision_backlog_*: governance backlog family
governance_event_* (FUTURE): umbrella family per Đ44 Step 3
7. Đ32 Review Model
Per Council Ratification Outcome §7 + P0 Schema Planning §4 cross-link:
dieu32_review_model:
scope: each P0 item gets its own Đ32 risk review post-design
review_unit: per-item design document (one of the 6 per-item files)
review_inputs:
- logical design content
- risk class (assigned per design)
- cross-law dependencies
- rollback implications
- data exposure surface
review_outputs:
- approval / approval_with_notes / rejection
- residual-risk register
- migration-execution preconditions (e.g., backup taken, downtime window scheduled)
review_phase_status: NOT_STARTED (Đ32 review begins after P0 design package is complete and reviewed by GPT)
approval_required_before_implementation_planning: YES
Per-item risk class proposals (subject to Đ32 confirmation):
| P0 item | Proposed risk class | Rationale |
|---|---|---|
| P0-5 decision_backlog_entry | Standard | Anti-forgetting infrastructure; no direct data exposure |
| P0-1 canonical_address | Standard | Identity field; affects round-trip; backfill carries data risk |
| P0-2 manifest_envelope + manifest_unit_block | Standard | New tables; bootstrap risk only |
| P0-6 review_decision | Standard | New table; reviewer identity is mild PII surface |
| P0-3 cut_change_set + rollback_key | HIGH | Rollback authority + DOT-pair signature schema → criterion 28 binding; failure mode = no valid REPORT PASS |
| P0-4 verify_result | HIGH | Verify gate; criterion 28 dual-signature; security-adjacent (wrong_audience_result_event also routes here in future) |
Two items (P0-3, P0-4) are HIGH because they implement the dual-signature mandate.
8. Shared Cross-Law Dependencies
| Dependency | Where binding |
|---|---|
| Đ24 vocabulary (Step 1 ratified) | P0-2 (section_type/unit_kind/body_source_policy/collision_status/risk_class), P0-1 (authority), P0-5 (kind, status), P0-6 (status, kind) |
| Đ32 risk class enum (Standard ratified via Đ24 group 4) | All 6 items use risk_class field |
| Đ37 role mapping (G-1, G-2, G-3, G-4, G-5 ratified_with_notes) | P0-5 owner field, P0-6 reviewer_identity, P0-3/P0-4 DOT-pair signing |
| Đ38 manifest-as-code (authoritative) | P0-2 manifest_envelope versioning, P0-3 change-set versioning, P0-5 backlog entry versioning |
| Đ39 universal_edges-first (authoritative) | P0-2 candidate_edges field carries reference to universal_edges (no parallel edge tables for P0) |
| Đ0-G birth gate (authoritative + Đ24 group 10 authority enum) | P0-1 authority field, P0-2 birth_gate_class hint |
| Đ44 Family Registry (Steps 1-3 ratified_with_notes) | P0-2, P0-3, P0-4, P0-5, P0-6 are families ratified at Đ44 level |
9. What Is Explicitly NOT Authorized
not_authorized_by_this_design_phase:
- writing_ddl: false
- writing_sql: false
- writing_create_table_statements: false
- writing_alter_table_statements: false
- writing_column_definitions_in_ddl_form: false
- writing_index_or_constraint_ddl: false
- writing_trigger_function_or_rls_policy: false
- executing_migration: false
- mutating_pg: false
- mutating_qdrant_or_vector: false
- mutating_directus_collections: false
- writing_data: false
- implementation_planning_for_p0_items: false (separate phase post-Đ32 approval)
- implementation_execution: false
- tool_revision_deployment: false
- retrieval_layer_implementation: false
- audience_filter_implementation: false
- p1_p2_p3_schema_work: false (P0-only scope)
- dieu44_step_4_semantic_thread_design: false (P2-deferred)
- dieu24_step_2_high_risk_vocab_use_in_design: limited (placeholder references only; final Đ24 Step 2 ratification gates G-5 operational handoff)
10. What Is Authorized
authorized_by_this_design_phase:
- logical_field_design (names, conceptual type-classes)
- lifecycle_state_machine_notation
- dependency_graphs
- risk_assessment_notes
- open_decision_recording
- cross-law_dependency_mapping
- migration_execution_preconditions_listing (NOT the migration itself)
- đ32_review_preparation
11. Per-Item File Skeleton (every per-item file follows this)
1. Purpose
2. Source design references
3. Logical object/table intent
4. Proposed fields at conceptual level
5. Field ownership / vocabulary dependency
6. Lifecycle
7. Dependencies
8. Risks
9. Open decisions
10. Đ32 risk review notes
11. Explicit "no DDL / no SQL / no migration / no PG mutation" confirmation
Per-item content is logical: field names + conceptual type-class only. No SQL is written anywhere in this package.
12. Status
master_document_status: COMPLETE
files_in_package: 8 (this master + 6 per-item + 1 risk/coverage report)
files_to_be_created_after_this_master: 7
implementation_planning_allowed: false
implementation_execution_allowed: false
dieu32_review_phase: not_started (begins after package complete + GPT review)
no_code: true
no_ddl: true
no_sql: true
no_pg_mutation: true
no_qdrant_mutation: true
no_previous_file_modified: true