dot-iu-cutter v0.2 — Phase α Design Report

document_path: knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-design-report-2026-05-15.md
revision: r1
date: 2026-05-15
author: Agent (Claude Code CLI, Opus 4.7 1M)
sovereign: User / anh Huyên
verifier: GPT (Đ32 HIGH-risk path / standard path for Phase α)
secondary: Opus
phase: v0.2 — Phase α design CONSOLIDATED REPORT (planning only)
mutation_performed: false
ddl_written: false
dry_run_started: false
production_migration_allowed: false

§1 — Files Created (this session)

knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-design-master-2026-05-15.md — design master (objective, scope, dependency graph, gates)
knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-canonical-address-schema-design-2026-05-15.md — logical schema design (authority + format_version + sandbox mirror)
knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-canonical-address-alias-design-2026-05-15.md — alias table design (purpose, types, placement, full field set)
knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-dry-run-plan-2026-05-15.md — 26-scenario HB-equivalent dry-run plan
knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-risk-review-plan-2026-05-15.md — Đ32 risk class + 8 risk surfaces + 10 mitigations
(this file) — design report consolidating the above

§2 — Recommended Schema Placement

new_columns:
  public.tac_logical_unit.authority                                text NULL DEFAULT 'draft'
  public.tac_logical_unit.canonical_address_format_version         text NOT NULL DEFAULT 'canonical-address-v1'
  sandbox_tac.logical_unit.authority                               text NULL DEFAULT 'draft'   (mirror; no backfill in Phase α)
  sandbox_tac.logical_unit.canonical_address_format_version        text NOT NULL DEFAULT 'canonical-address-v1'   (mirror)

new_table:
  cutter_governance.canonical_address_alias                        (0 rows at create; placement detail in §3)

what_is_preserved_unchanged:
  public.tac_logical_unit.canonical_address (SSOT; UNIQUE, NOT NULL, text)
  all 6 sister-table canonical_address columns (information_unit, unit_edit_draft, event_outbox, iu_notification_event, event_pending, birth_registry)
  cutter_governance.{decision_backlog_entry, dot_pair_signature, cut_change_set, cut_change_set_affected_row, verify_result}   (v0.1 live; remain empty)
  all 21 PG functions
  all 11 triggers
  Nuxt SSR + client bundles (no app deploy)
  Directus collections (no flow changes)

§3 — Recommended Alias Table Placement

recommended_placement: cutter_governance.canonical_address_alias

rationale_summary:
  - aliases are a governance concern, driven by Phase β review/change-set workflows
  - cutter_governance is the existing governance-machinery home (v0.1-live)
  - placement consistency with cut_change_set / dot_pair_signature / verify_result
  - rollback symmetry with v0.1 (DROP TABLE inside cutter_governance is operationally proven)

target_unit_id_FK_policy_in_Phase_α:
  - stored as uuid soft reference (no PG FK to public.tac_logical_unit.id)
  - cross-schema PG FK is technically feasible but adds coupling; defer to Phase β
  - alias rows are 0 in Phase α so the dormant FK risk is acceptable

sandbox_alias_table:
  decision: OMIT in Phase α
  rationale: sandbox is a static test fixture; alias governance is a public-data concern; mirroring would duplicate without operational benefit

fallback_if_GPT_prefers_public_schema:
  - acceptable alternative: public.canonical_address_alias
  - design changes are minimal: replace schema qualifier; no field-level change
  - Agent's preference remains cutter_governance for cohesion reasons

§4 — Recommended Backfill Rule

recommended_rule: BR-4 Candidate B — Derive from lifecycle_status mapping

mapping_(ratified_in_BR_4_closure):
  draft_only → draft
  active     → enacted
  retired    → enacted   (rationale: retired carries the source's enacted authority; lifecycle_status carries the retirement)

target_for_phase_α: public.tac_logical_unit (86 rows)
expected_post_backfill_distribution_on_current_data:
  authority='draft'   → 86 rows
  authority='enacted' → 0 rows (no active/retired rows exist today)
  authority='runtime' → 0 rows (not applicable to tac_logical_unit; reserved for information_unit family — out of Phase α scope)

sandbox_tac_backfill_in_phase_α: SKIPPED
  - 76 sandbox rows get authority=NULL after column-add
  - sandbox backfill deferred to Phase β alongside production lifecycle-transition write hook

backfill_implementation_form:
  UPDATE public.tac_logical_unit
     SET authority = CASE lifecycle_status
                       WHEN 'draft_only' THEN 'draft'
                       WHEN 'active'     THEN 'enacted'
                       WHEN 'retired'    THEN 'enacted'
                     END
   WHERE authority IS NULL;
  (form shown for design clarity; executable form authored in a future Phase α DDL session)

§5 — Risk Class

proposed_risk_class: STANDARD
escalation_to_HIGH_council_required: NO
council_acknowledgements_already_secured:
  Đ0-G: authority class semantics (BR-4 closure)
  Đ24: canonical-address-v1 grammar + storage form (BR-5 closure)
Đ32_review_path: standard (Phase α has no DOT-pair signing, no CUT/VERIFY, no sister-table touch)

§6 — Open Questions (deferred to GPT review)

Q1 — alias table placement:
  agent_recommendation: cutter_governance.canonical_address_alias
  alternative: public.canonical_address_alias
  decision_owner: GPT

Q2 — cross-schema FK from alias to tac_logical_unit:
  agent_recommendation: NO in Phase α (soft uuid reference)
  alternative: add FK in Phase α
  decision_owner: GPT

Q3 — authority CHECK constraint in Phase α:
  agent_recommendation: NO (deferred to Phase β)
  alternative: add CHECK in Phase α
  decision_owner: GPT

Q4 — sandbox_tac.canonical_address_alias mirror:
  agent_recommendation: OMIT
  alternative: mirror for parity
  decision_owner: GPT

Q5 — dry-run env reuse vs fresh:
  agent_recommendation: SPIN FRESH sibling env (pg-dry-run-v0.2-phase-alpha-<date>)
  alternative: reuse HB-05 env (NOT recommended)
  decision_owner: GPT

Q6 — identity_profile jsonb cleanup:
  agent_recommendation: NOT IN Phase α (cosmetic)
  alternative: bundle the cleanup into Phase α
  decision_owner: GPT

§7 — Blockers

7.1 Before Phase α DDL authoring

B-DDL-1: GPT review of these 6 design docs → explicit prompt to author DDL
  status: PENDING (this report is the trigger)
B-DDL-2: open questions Q1–Q6 (§6) resolved
  status: PENDING GPT review
B-DDL-3: read-only inspection of fn_tac_birth_gate_lu body
  status: deferred until DDL authoring session (informational)

7.2 Before dry-run

(See dry-run plan §11 + risk review plan §5.)

B-DR-1: Phase α DDL authored + GPT-reviewed
B-DR-2: fresh dry-run env provisioned
B-DR-3: baseline backup taken / verified
B-DR-4: explicit User/GPT prompt to enter dry-run authoring lane

7.3 Before production

(See risk review plan §6.)

B-PROD-1..B-PROD-11 — full enumeration in risk-review §6
  - dry-run 26/26 PASS
  - HB-equivalent closure document
  - final readiness review
  - command-review package
  - GPT review of each
  - fresh production-bound backup < 60 min
  - explicit User production execution prompt
  - separate execution session

7.4 BR-6 status (not blocking Phase α)

BR-6: split/merge metadata propagation TD — OPEN
gates: P0-2 manifest_envelope / manifest_unit_block design ONLY
does_NOT_block_Phase_α_additive_columns_or_alias_table_creation: TRUE
recommended_action: author or read the TD in parallel; can run on its own track

§8 — Phase α Readiness for GPT Review

phase_α_design_status: ready_for_gpt_review
all_6_design_docs_authored: TRUE
internally_consistent: TRUE
  - BR-4 Candidate B mapping reflected in schema design backfill (§3.3)
  - BR-5 canonical-address-v1 string reflected in format_version DEFAULT (§4.2)
  - BR-7 Option II reflected in sandbox mirror (§6)
  - BR-2 jsonb finding reflected in §10 of schema design + RS-7 in risk review
  - BR-3 reader/writer inventory reflected in compatibility statements (§7 of schema design + RS-4/5/6 in risk review)
recommendations_consistent_across_docs: TRUE
ddl_written: FALSE
mutation_performed: FALSE
dry_run_started: FALSE
production_migration_allowed: FALSE

what_gpt_review_should_decide:
  - approve / revise the 6 design docs as a set
  - select alias table placement (Q1)
  - decide on optional Phase α extras (Q2–Q6)
  - issue explicit prompt to enter Phase α DDL authoring lane

agent_self_advance_at_any_step: PROHIBITED
each_subsequent_lane_terminates_at_GPT_review_or_explicit_user_prompt: TRUE

§9 — Negative Confirmations

no_DDL_written: TRUE
no_SQL_executed: TRUE
no_ALTER_TABLE: TRUE
no_INSERT_UPDATE_DELETE: TRUE
no_migration: TRUE
no_change_to_tac_logical_unit (production state): TRUE
no_change_to_sandbox_tac (production state): TRUE
no_change_to_cutter_governance (production state): TRUE
no_change_to_sister_tables: TRUE
no_app_code_modified: TRUE
no_directus_flow_modified: TRUE
no_dry_run_started: TRUE
no_dry_run_env_provisioned: TRUE
no_production_migration_allowed: TRUE
no_CUT_or_VERIFY: TRUE
no_HB_05_v0_1_env_modified: TRUE
output_form: phase_alpha_design_consolidated_report

§10 — Sign-Off Block

agent (author):                  Claude Code CLI / Opus 4.7 1M    action: 6 Phase α design docs authored
verifier (Đ32 standard path):    GPT                              action: Phase α design review — PENDING
secondary (record keeping):      Opus                              action: docs stored in Agent Data — DONE
sovereign (authorizing party):   User / anh Huyên                  action: explicit prompt for Phase α DDL authoring — PENDING
council_status:
  Đ0-G:  ratified at BR-4 closure (authority semantics)
  Đ24:   ratified at BR-5 closure (canonical-address-v1 grammar)
  Đ32:   pending standard-path review of Phase α design

§11 — Cross-References

phase_α_design_master:  knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-design-master-2026-05-15.md
schema_design:          knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-canonical-address-schema-design-2026-05-15.md
alias_design:           knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-canonical-address-alias-design-2026-05-15.md
dry_run_plan:           knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-dry-run-plan-2026-05-15.md
risk_review_plan:       knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-phase-alpha-risk-review-plan-2026-05-15.md

closure_predecessors:
  br_4_closure:                       knowledge/dev/laws/dieu44-trien-khai/v0.2-planning/dot-iu-cutter-v0.2-br-4-authority-backfill-rule-closure-2026-05-15.md
  br_5_closure:                       knowledge/dev/laws/dieu44-trien-khai/v0.2-planning/dot-iu-cutter-v0.2-br-5-canonical-address-v1-ratification-closure-2026-05-15.md
  br_4_5_closure_report:              knowledge/dev/laws/dieu44-trien-khai/v0.2-planning/dot-iu-cutter-v0.2-br-4-5-closure-report-2026-05-15.md
  br_2_3_7_discovery_report:          knowledge/dev/laws/dieu44-trien-khai/v0.2-planning/dot-iu-cutter-v0.2-br-2-3-7-discovery-report-2026-05-15.md
  canonical_address_reconciliation:   knowledge/dev/laws/dieu44-trien-khai/v0.2-planning/dot-iu-cutter-v0.2-canonical-address-reconciliation-report-2026-05-15.md

v0_1_predecessors:
  production_handoff: knowledge/dev/laws/dieu44-trien-khai/execution/dot-iu-cutter-v0.1-production-handoff-status-2026-05-15.md
  v0_2_scope_backlog: knowledge/dev/laws/dieu44-trien-khai/planning/dot-iu-cutter-v0.2-scope-backlog-2026-05-15.md
  v0_1_p0_1_design_baseline: knowledge/dev/laws/dieu44-trien-khai/migration-design/dot-iu-cutter-v0.1-p0-1-canonical-address-migration-design-2026-05-15.md

open_blocker:
  split_merge_TD_(BR-6; gates_P0_2_only): knowledge/dev/laws/dieu44-trien-khai/backlog/td-p1-split-merge-metadata-propagation-gap-2026-05-15.md

End of Phase α design report.