Incomex AI Portal
KB-7C09

dot-iu-cutter v0.2 — canonical_address Reconciliation Options (2026-05-15)

18 min read Revision 1
dieu44-trien-khaidot-iu-cutterv0.2canonical-addressreconciliationoptionsplanning-only2026-05-15

dot-iu-cutter v0.2 — canonical_address Reconciliation Options

document_path: knowledge/dev/laws/dieu44-trien-khai/v0.2-planning/dot-iu-cutter-v0.2-canonical-address-reconciliation-options-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 — anticipated)
secondary: Opus
phase: v0.2 planning — options (planning-only, no execution)
predecessor: dot-iu-cutter-v0.2-canonical-address-reconciliation-discovery-2026-05-15.md
mutation_performed: false
ddl_written: false
migration_started: false

§1 — Decision Framing

The discovery established that the existing public.tac_logical_unit.canonical_address column is text NOT NULL UNIQUE with a production-specific syntax (D{doc}-DIEU{N}-{S|ROOT}[-P{N}][-{N}]), denormalized into 7 sister tables (≈ 44,840 rows total when including event_outbox), and lacks every companion field the v0.1 P0-1 design proposed (authority, format_version, supersession FKs, alias table).

Four reconciliation options follow. For each: pros, cons, risks, required governance, dry-run requirement, compatibility with the v0.1 live schema (cutter_governance.*), and a verdict.

§2 — Option A — Reuse existing column as canonical SSOT

summary: accept public.tac_logical_unit.canonical_address (text NOT NULL UNIQUE, syntax D{doc}-DIEU{N}-…) as the v0.2 canonical SSOT; revise v0.1 P0-1 design to adopt this syntax; do NOT alter the column.

2.1 Pros

  • Zero production schema change for the SSOT column. No risk of breaking 44,726 event_outbox rows or 98 information_unit rows.
  • No new constraint reversal. Global uniqueness is already enforced at DB level — operationally safer than P0-1's "application-layer + future PG constraint" recommendation.
  • No reader/writer disruption. public.fn_event_unread, the canonical_address NOT NULL trigger logic, and all existing app paths continue to work unchanged.
  • Fastest path to unblocking P0-2/P0-4/P0-6 (manifest_envelope, verify_result, review_decision) which all cite canonical_address per row.
  • Format already system-wide consistent. All 7 sister tables already use this syntax — no cross-table drift on day 0.
  • Smallest dry-run surface. No tac_logical_unit migration to validate, so v0.2 dry-run focuses purely on the new tables.

2.2 Cons

  • P0-1 design must be revised to adopt the production syntax (D38-DIEU28-S2-P1) instead of the proposed Vietnamese-diacritic syntax (Đ44 §5.3.1). This is a design rewrite, not a code change.
  • Companion fields (authority, format_version, supersession FKs, alias table) must still be added — they are additive and uncontroversial, but they are new design work.
  • The chosen syntax is less human-friendly for direct law citation (no § separator, no Vietnamese article marker) — citation discipline downstream (D11 §4.13) may want a presentation-layer renderer that maps D38-DIEU28-S2-P1 → Đ28 §2.1 for display.
  • Collision policy in P0-1 §7-8 (multi-row-same-address with differing authority) is INCOMPATIBLE with the global uniqueness constraint and must be revised. The revision is constraining (single row per address) which is simpler — not necessarily a loss.

2.3 Risks

  • Format-version migration deferred indefinitely. If a future format needs to land, the existing column has no format_version stamp to disambiguate. Mitigation: add canonical_address_format_version text DEFAULT 'd38-v0' in v0.2 as an additive column; backfill is trivial (single UPDATE setting a constant for all 86 tac rows; sister tables can opt in later).
  • Authority backfill for the 86 existing rows: derivable from lifecycle_status (draft_only → authority=draft)? Or from doc_code regex match? Decision needed; not a blocker for choosing this option but is a v0.2 design task.
  • Supersession history for any rename-style change is lost (no alias table). Mitigation: add a canonical_address_alias table in v0.2 (additive, low-risk).

2.4 Required governance

  • Đ32 sign-off on the syntax-adoption decision (HIGH-risk path because it locks the system-wide vocabulary into the existing form).
  • Đ24 ratification of the production syntax as v1 of the canonical_address format vocabulary.
  • Đ0-G review for the authority backfill rule (lifecycle_status mapping).
  • G-4 Custodian sign-off on the revised P0-1 design.

2.5 Dry-run requirement

  • No tac_logical_unit alteration to dry-run. The dry-run focuses on the v0.2 additive surface only (companion columns + alias table + manifest_envelope + manifest_unit_block + review_decision + decision_backlog remainder).
  • HB-05-equivalent rollback dry-run still required for the additive columns and new tables.
  • Scenario coverage: backfill of authority + format_version on the 86 existing rows; rename via alias table; collision (now a duplicate-attempt rejection rather than a multi-authority allowance).

2.6 Compatibility with v0.1 live schema (cutter_governance.*)

  • Fully compatible. No v0.1 table needs to change. P0-2/P0-3/P0-4 tables (when added later) will reference canonical_address as text (denormalized, matching the sister-table pattern); no FK to canonical_address text is needed because the production model has none.

2.7 Verdict

option_a_verdict: VIABLE; lowest-risk; design rewrite cost is moderate; operational risk is minimal

§3 — Option B — Reuse existing column AND add companion metadata later (additive only)

summary: keep existing column unchanged; defer all P0-1 companion fields (authority, format_version, supersession, alias) to a SEPARATE later v0.3+ cycle; v0.2 ships only manifest/review/decision_backlog remainder and treats canonical_address as opaque text.

3.1 Pros

  • Minimal v0.2 schema surface. The smallest possible v0.2 — fewer dry-run scenarios, fewer review touchpoints.
  • Defers the authority/format_version vocabulary decision until more is known about Đ0-G ratification and downstream needs.
  • No syntax debate now. P0-1 design can remain "open" until later.

3.2 Cons

  • manifest_envelope / manifest_unit_block / verify_result lose authority awareness. P0-4 axis-1 verify depends on authority precedence (per P0-1 §7); without authority, the verify path must fall back to "treat all addresses as a single authority class".
  • review_decision findings cannot cite the authority of the unit reviewed — reviewer independence and citation discipline (D11) lose a dimension.
  • Supersession via the cutter pathway is unsupported. Any rename or supersession needs a future migration before it can be expressed in the new tables — this kicks the can to v0.3+.
  • Defers a critical decision unnecessarily. The existence of the existing column is not a reason to defer companion fields; it just changes the syntax debate.

3.3 Risks

  • Premature v0.2 ship that needs immediate v0.3 follow-up to add the deferred fields, with sister tables (information_unit, event_outbox) potentially needing the same fields. Defers, not eliminates, the migration cost.
  • Citation drift — if review_decision and verify_result are added without authority awareness, then later when authority is added, prior review_decision / verify_result rows are retroactively ambiguous.

3.4 Required governance

  • Đ32 sign-off on the deferral decision.
  • Explicit Đ24 / Đ0-G ack that companion vocabulary is on hold.
  • G-4 Custodian sign-off on the deliberately narrowed v0.2 design.

3.5 Dry-run requirement

  • Smallest possible dry-run: just the new tables (manifest_*, review_decision, decision_backlog remainder) wired against the existing canonical_address text column.
  • Rollback test scenario matrix unchanged in form; size reduced.

3.6 Compatibility with v0.1 live schema

  • Fully compatible. v0.1 cutter_governance tables remain unchanged; new tables join them in the same schema or in tac.

3.7 Verdict

option_b_verdict: VIABLE but suboptimal — defers necessary design work without lasting benefit; recommended only if v0.2 must ship under severe time pressure

§4 — Option C — Deprecate existing column and create a new governed address path

summary: introduce a new column (e.g., tac_logical_unit.governed_address text + companion fields) as the v0.2 canonical; mark public.tac_logical_unit.canonical_address as legacy; plan a future cutover that migrates the 7 sister tables off the legacy column and onto the new path.

4.1 Pros

  • Allows P0-1 design syntax (Đ44 §5.3.1) to be adopted unchanged without a system-wide vocabulary battle on day 0.
  • Format_version mechanism gets a clean origin — governed_address_format_version starts at v1.0.0 with full P0-1 design.
  • Authority distinction can be modeled exactly as P0-1 §7 proposed without compromise.

4.2 Cons

  • Two address sources of truth simultaneously. During the cutover window, both canonical_address and governed_address exist on the same table; reader code must pick one; risk of citation drift and migration bugs is HIGH.
  • 44,726 event_outbox rows + 98 information_unit + 13 unit_edit_draft + … all need a sister-table migration if the legacy column is to be retired. This is the largest operation in the entire dieu44-trien-khai initiative.
  • Reader/writer inventory is exhaustive — every function (public.fn_event_unread, the INSERT trigger, application code) must be inventoried and migrated.
  • Sandbox tac.logical_unit and sandbox_tac.logical_unit complicate the cutover.
  • Largest dry-run surface of any option — must validate cutover behavior across 7 tables.

4.3 Risks

  • Citation drift during the cutover window — published outputs referencing one address form must be re-resolved if the form changes mid-cutover.
  • Migration of event_outbox — 44,726 rows is not huge but the table is the system's audit trail; a botched migration creates an audit gap.
  • No rollback path once the legacy column is dropped. Mitigation: retain legacy column indefinitely; never DROP.

4.4 Required governance

  • Đ32 sign-off on the cutover plan (HIGH-risk; potentially MAX-risk depending on event_outbox handling).
  • Đ24 ratification of the new format syntax as v2.
  • Đ0-G review of authority semantics — full review.
  • G-4 Custodian + operational DBA + G-2 backlog custodian sign-off.
  • Multi-stakeholder approval (every team consuming event_outbox / information_unit).

4.5 Dry-run requirement

  • Full HB-05-equivalent dry-run + extended migration dry-run across 7 sister tables.
  • Synthetic event_outbox dataset of comparable size.
  • Application-code regression suite against the new column.
  • Estimate: this dry-run alone is larger than the entire HB-05 dry-run done for v0.1.

4.6 Compatibility with v0.1 live schema

  • Partially compatible. v0.1 cutter_governance tables don't reference canonical_address yet (because no CUT has been run), but P0-3/P0-4 design assumed canonical_address per row in payload — if v0.2 switches the canonical form mid-flight, P0-3/P0-4 design notes must be revisited.

4.7 Verdict

option_c_verdict: VIABLE but DISPROPORTIONATE — highest cost, highest risk, no proportional benefit; only justified if production syntax has a defect that cannot be papered over with a presentation-layer renderer

§5 — Option D — Hybrid / migration-safe approach

summary:
  - keep public.tac_logical_unit.canonical_address as the SSOT (Option A core)
  - add additive companion fields IN PHASES, gated by individual GPT review:
      Phase D-α  (v0.2):       canonical_address_format_version, authority (with backfill from lifecycle_status), canonical_address_alias table
      Phase D-β  (v0.3 candidate): superseded_by_unit_id / supersedes_unit_id FKs, supersession lifecycle
      Phase D-γ  (v0.4 candidate): birth_gate_class refinement, format_version mechanism upgrade
  - sister-table coupling held STABLE — no sister-table migration in v0.2 or v0.3; revisit only if a concrete need emerges
  - presentation-layer renderer (e.g., D11 citation surface) handles Vietnamese display syntax separately from storage syntax

5.1 Pros

  • Option A's safety (no SSOT-column change) combined with structured progress on the companion fields.
  • Each phase is its own HB-05-equivalent dry-run with explicit GPT gating — no surprise expansions.
  • P0-2 / P0-4 / P0-6 can land in v0.2 referencing canonical_address (text) with authority (new) — full design intent achievable without altering the SSOT column.
  • Presentation-layer rendering decouples storage syntax from human-facing form — D11 citation discipline can still display Đ28 §2.1 even if storage says D38-DIEU28-S2-P1.
  • Lowest operational risk per phase. Each phase is bounded.

5.2 Cons

  • More documents to author: one phase = one design + one closure + one review cycle.
  • Slightly slower than Option A's single-shot revision — Option D ships Phase α in v0.2, defers β and γ to v0.3/v0.4.
  • Phase boundaries must be carefully designed to avoid leaving v0.2 in a half-functional state.

5.3 Risks

  • Risk that Phase β / γ get deprioritized and the system runs without supersession / format_version forever. Mitigation: log them as enforceable backlog items with explicit owners.
  • Risk that the additive columns in Phase α conflict with existing identity_profile jsonb usage if that jsonb already stores authority-like data. Mitigation: discovery §3.9 noted identity_profile is unverified — v0.2 design must inspect it BEFORE Phase α DDL is authored.

5.4 Required governance

  • Đ32 sign-off on the phase plan as a whole.
  • Per-phase Đ32 + G-4 sign-off at each transition.
  • Đ24 ratification of: (a) production syntax as v1; (b) authority enum mapping.
  • Đ0-G review for authority backfill rule.

5.5 Dry-run requirement

  • Phase α dry-run (v0.2): additive columns on tac_logical_unit + alias table + manifest_* + review_decision + decision_backlog remainder.
  • Each subsequent phase has its own HB-equivalent.
  • Scenario matrix smaller than Option C, larger than Option B; comparable to Option A + companion-table dry-run.

5.6 Compatibility with v0.1 live schema

  • Fully compatible. v0.1 cutter_governance tables remain unchanged. P0-2 / P0-4 designs adopt canonical_address as text reference (matching sister-table pattern); presentation-layer renderer handles human display.

5.7 Verdict

option_d_verdict: RECOMMENDED — best balance of risk, reversibility, design fidelity, and explicit gating

§6 — Comparison Matrix

Dimension A: Reuse SSOT B: Reuse + defer C: Deprecate + new D: Hybrid phased (RECOMMENDED)
SSOT column changed? NO NO YES (replaced) NO
New columns on tac_logical_unit? YES (companion) NO (deferred) YES (governed_address + companions) YES (additive, phased)
Sister tables affected? NO NO YES (7 tables) NO
44,726 event_outbox rows touched? NO NO YES NO
P0-1 design rewrite needed? YES (adopt prod syntax) partial (defer fields) NO (full P0-1 syntax used on new column) YES (adopt prod syntax + phase β/γ design)
Dry-run size medium small large medium (per phase)
Risk class standard standard HIGH standard with explicit gates
Unblocks P0-2/P0-4/P0-6 in v0.2? YES YES (without authority) YES (with cutover risk) YES (with authority via Phase α)
Reversibility high (additive only) high low (after legacy DROP) high (additive only)
Governance burden moderate low very high moderate (per phase) 
recommended_option: D — Hybrid / migration-safe phased approach
rationale_summary:
  - Preserves the operationally-safe existing column unchanged (Option A's core).
  - Adds authority + format_version + alias capability in v0.2 (Phase α), unblocking P0-2/P0-4/P0-6 with full P0-1 design intent.
  - Defers supersession and birth_gate refinement to bounded later phases with their own GPT gating.
  - Avoids the system-wide cutover risk of Option C.
  - Avoids the deferral debt of Option B.
  - Each phase is its own HB-equivalent dry-run + explicit production execution prompt cycle — matches the discipline established by v0.1.
recommendation_authority: Agent recommendation; binding decision requires GPT review and explicit User selection.

If GPT prefers Option A instead (faster ship, single-shot revision), the report file marks Option A as the v0.2 baseline and adjusts dependency impact accordingly. The report file leaves the final selection to GPT/User.

§8 — Hard Boundaries

no_DDL_written: TRUE
no_SQL_mutation: TRUE
no_ALTER_TABLE: TRUE
no_migration_started: TRUE
no_change_to_tac_logical_unit: TRUE
no_change_to_cutter_governance: TRUE
no_deploy: TRUE
no_CUT_VERIFY: TRUE
no_design_expansion_beyond_reconciliation: TRUE
output_form: options_planning_documentation_only

End of options document.

Back to Knowledge Hub knowledge/dev/laws/dieu44-trien-khai/v0.2-planning/dot-iu-cutter-v0.2-canonical-address-reconciliation-options-2026-05-15.md