dot-iu-cutter v0.1 — P0 Schema Planning Package

Date: 2026-05-15 Status: PLANNING — no DDL, no migration, no PG mutation Trigger: User PASS_DESIGN_WITH_NOTES + Review Control §4 P0 grouping Baseline: 11 design deliverables + 4 Gate reviews Scope: PLANNING ONLY. Identifies P0 schema gaps that BLOCK implementation planning. No DDL written, no SQL proposed, no schema mutated.

1. Purpose

Đặc tả 6 schema gaps được phân loại P0 trong Design Review Control §4 — đây là tập gaps bắt buộc phải có migration design riêng trước khi bất kỳ implementation planning nào được phép.

Package này KHÔNG:

Viết DDL.
Đề xuất SQL cụ thể (CREATE TABLE, ALTER, INDEX, …).
Thay đổi schema PG hiện tại.
Áp dụng migration.
Mutate Qdrant / vector / Directus / TAC schema.

Package này CHỈ:

Mô tả purpose / source / lý do P0 / dependency.
Đặt giả định data ownership ở mức assumption (target DB, layer).
Liệt kê open decisions cần đóng trước migration design.
Định nghĩa scope của migration design sẽ làm sau (không thực hiện ở đây).

2. Hard Boundaries

no_ddl: true
no_sql_proposed: true
no_schema_change: true
no_migration_executed: true
no_pg_mutation: true
no_qdrant_change: true
no_directus_change: true
no_data_writes: true
implementation_unblock_dependency: true

3. P0 Definition (per Review Control §4)

P0 = "Required before any implementation planning."

Đặc trưng P0:

Là trục cốt lõi của Cut Flow / Manifest contract / Rollback / Governance.
Không có những object này → không thể plan migration cho P1 / P2 / P3.
Vắng những object này → Gate 2 correctness không runtime-realizable.

P1/P2/P3 (15 / 14 / 21 objects) không thuộc package này — chúng sẽ được lên kế hoạch trong các phase migration design tiếp theo, sau khi P0 đóng.

4. Cross-Links to Governance Closure

P0 migration design phụ thuộc vào (must close first):

G-2 Backlog custodian (cho P0-5).
G-4 DOT-pair signing (cho P0-3 và P0-4 — verify_result signature schema).
G-1 Threading roles (gián tiếp, cho P0-5 routing).

Nếu governance closure chưa đóng → migration design vẫn nên CHỜ. Schema mà thiếu governance owner sẽ thành ungoverned infrastructure (Gate 4 §3.5).

5. P0 Items

5.1 P0-1 — `canonical_address` on `tac_logical_unit`

Purpose: Stable human-readable address (e.g. "Đ44 §5.3.1") cho từng IU. Dùng cho:

Manifest per-unit block (D2 §4.2).
Round-trip verification ordering (D1 §4.7).
Citation discipline (D11 §4.13 consumer contract).
Cross-doc reference resolution (D6 §4.2).

Source deliverable: D6 §6 (item 1), D7 §6 (item 1), D8 §6.1 (item 1).

Why required before implementation planning:

Manifest contract (D2) trỏ tới canonical_address ở per-unit block — implementation không thể realize manifest nếu trường không tồn tại.
Round-trip verify (Axis 1) cần stable address ordering — nếu fallback sang internal ID, ordering không deterministic across cuts.
Retrieval citation (D11) yêu cầu canonical_address — D11 implementation phụ thuộc trực tiếp.
KG candidate_edges và universal_edges target resolution dùng canonical_address — Đ39 surface cần.

Related law / governance dependency:

Đ24: address format vocabulary — cần Đ24 governance ratify format trước.
Đ44 / UOSL G1 (identity): canonical_address là G1 field hint (D7 §4.3).
Đ0-G: address phải distinguish base / draft / runtime authority levels (D7 §4.9).
Đ38 (TAC manifest): citation must reference canonical_address.

Data ownership / target DB / layer assumption:

Target DB: directus.
Schema: TAC schema, tac_logical_unit table (existing).
Layer: Kho (data persistence).
Mode: first-class column on tac_logical_unit (NOT JSON profile, vì lookup nhanh và ordering quan trọng).
Cardinality: 1:1 với IU.

Open decisions (must close before migration design):

Format spec — full canonical address syntax (e.g. "Đ{N} §{path}" vs "{doc}/{path}" vs hierarchy-based).
Uniqueness scope — unique per source_revision, per document_kind, hay globally?
Collision policy — khi 2 IUs cùng address (e.g. supersession), priority rule?
Mutation policy — address có được phép thay đổi sau cut hay không? Nếu có, alias chain?
Indexing posture — single-column index, composite với source_revision, hay trigram (pg_trgm) cho fuzzy lookup?
Backfill strategy cho existing tac_logical_unit rows — null-allow initial, populate retroactively?
Vocabulary placement — section path notation Đ24 ratified?

Migration design needed later (scope, not action):

Đ24 vocabulary ratification.
Add column to tac_logical_unit with format constraint.
Backfill of existing rows.
Index strategy.
Update fn_iu_create birth gateway to enforce address discipline (Đ0-G).
Verifier (DOT-pair) updated to use canonical_address in round-trip.

Migration design is OUT OF SCOPE for this package.

5.2 P0-2 — `manifest_envelope` + `manifest_unit_block`

Purpose: PG-native persistence cho manifest (D2 §4.1 — manifest as code). Envelope chứa manifest-level fields; per-unit block chứa per-IU fields.

Source deliverable: D2 §4.2 (full field set), D2 §6 (items 1, 2), D8 §6.2 (items 16, 17).

Why required before implementation planning:

Toàn bộ Cut Flow (D1 §4.1) operate trên manifest — không có persistent envelope → không thể implement MARK / REVIEW / CUT.
Manifest-as-code (Đ38, P3) yêu cầu versioned, diffable PG rows — KB markdown không đáp ứng.
REVIEW decision (P0-6) trỏ tới manifest_id + manifest_version — FK target không tồn tại.
Independent reviewer needs PG read access to envelope.
Diff (D2 §4.11) là materialized view derive từ envelope versions.

Related law / governance dependency:

Đ38: manifest-as-code is binding.
Đ24: section_type / unit_kind / body_source_policy enums must be Đ24-controlled.
Đ32: risk_class field gates approval flow.
Đ44 / UOSL: manifest_envelope là family mới (D7 §4.4, §6 items 47, 48) — Family Registry submission yêu cầu trước.
Đ33 / Đ43: target DB placement.
Đ0-G: birth gate readiness flag per per-unit block.

Data ownership / target DB / layer assumption:

Target DB: directus (TAC schema).
Layer: Kho.
Envelope: separate table, distinct from tac_logical_unit.
Per-unit block: open decision (xem User Decision Pack §5).
Versioning: semver-style on envelope; each version is a row.

Open decisions (must close before migration design):

Per-unit block shape — child rows vs JSONB array (cross-link User Decision Pack §5). This is THE critical decision.
Envelope vs per-unit block FK direction — envelope→blocks or blocks→envelope.
JSONB schema validation — PG jsonb_check constraint or app-level only.
manifest_version uniqueness — per source_path + source_revision.
Reviewer_identity column shape — text, FK to actor table, or JSONB capability fingerprint?
Risk_class enum vocabulary — Đ32 ratification.
Body_source_policy enum vocabulary — Đ24 ratification.
Collision_status enum vocabulary — Đ24 ratification.
UOSL Family Registry — pending G-1 / G-3 governance closure + Đ44 submission.

Migration design needed later:

Đ44 Family Registry submission (waits for governance).
Đ24 / Đ32 vocabulary ratifications.
Create envelope table + per-unit storage (shape per User Decision §5).
Create version index + diff materialized view spec.
Wire MARK output to PG (replacing transient markdown).

Migration design is OUT OF SCOPE for this package.

5.3 P0-3 — `cut_change_set` + `rollback_key`

Purpose: Exact-key rollback (D1 §4.8). Mỗi CUT execution tạo một cut_change_set row + rollback_key để reverse atomically nếu VERIFY fail hoặc REPORT khi NEEDS_HUMAN block.

Source deliverable: D1 §4.8, D2 §6 (item 7 implicit), D8 §6.2 (item 19), Gate 2 §3.5.

Why required before implementation planning:

"Automatic rollback, no partial publish" (D1 §4.8) là acceptance criterion 6 — không có change-set → không thể rollback atomically.
Verifier (DOT-pair) co-sign cần signed reference to change-set.
F2 Health / Correction (D3 §4.11) cũng dùng rollback model này cho Split/Merge.
Capability intake (D4) khi patch tool_revision cần cut_change_set audit trail để re-cut.

Related law / governance dependency:

Đ32: rollback is high-risk surface — Đ32 approval pattern.
Đ37: DOT-pair signing authority (G-4) controls signature schema.
Đ38: change-set as code — versioned, diffable.
Đ44 / UOSL: new family (D7 §6 item 49).
Đ0-G: change-set must respect birth gate (no half-born units).

Data ownership / target DB / layer assumption:

Target DB: directus (TAC schema).
Layer: Kho.
Schema: change-set row references all tac_logical_unit + tac_unit_version rows created/modified.
rollback_key: deterministic identifier referencing the change-set.
Idempotency: rollback of an already-rolled-back change-set is no-op.

Open decisions (must close before migration design):

Change-set scope granularity — single CUT execution, or batchable across one user command?
Atomicity guarantee — PG transaction wrap entire change-set, or use savepoints?
Rollback semantics for downstream signals (already-emitted health signals after CUT) — invalidate or preserve?
DOT-pair signature attachment — separate signing row or column on change-set?
Cascade rules — if change-set references units later modified by another change-set, what's the rollback ordering policy?
Retention — how long change-sets persist post-publication (audit vs storage cost)?
UOSL Family Registry — pending G-4 + Đ44 submission.

Migration design needed later:

Đ44 Family Registry submission.
Đ37 G-4 signing authority closure.
Create change-set table + rollback_key field.
Define cascade and idempotency policy.
DOT-pair signature recording table (cross-link with missing instrumentation item #8).

Migration design is OUT OF SCOPE for this package.

5.4 P0-4 — `verify_result`

Purpose: Persist VERIFY stage outcome (D1 §4.7) — round-trip drift count, axis-2 coverage metadata, DOT-pair dual-signature outcome, NEEDS_HUMAN signal, escalation refs.

Source deliverable: D1 §4.7, D2 §4.6, D8 §6.2 (item 20), Gate 2 §3.4.

Why required before implementation planning:

VERIFY is mandatory before PASS — without persistent verify_result, no audit trail of correctness.
DOT-pair dual signature lives here (criterion 28).
Rollback decision (D1 §4.8) reads verify_result to decide automatic rollback vs publish.
Health signals (D3) cross-link to verify_result for post-cut anomaly correlation.
Self-Review (D4 §4.4) audits verify_result trends for staleness detection.

Related law / governance dependency:

Đ32: VERIFY failure is risk event — Đ32 escalation path.
Đ37: G-4 DOT-pair signing authority owns signature schema.
Đ38: verify_result as code — versioned, diffable.
Đ44 / UOSL: G7 provenance field group hint (D7 §4.3).
Đ0-G: VERIFY enforces birth gate (no published unit without verify_result PASS).

Data ownership / target DB / layer assumption:

Target DB: directus (TAC schema).
Layer: Não (analytical / state record).
Schema: 1 verify_result row per (manifest_id, manifest_version, cut_change_set_id) tuple.
Fields: axis_1_drift_count, axis_1_status, axis_2_coverage_score, axis_2_advisory_findings, dot_pair_executor_sig, dot_pair_verifier_sig, status (PASS/FAIL/NEEDS_HUMAN), findings (JSONB).
Cross-FK to manifest_envelope (P0-2), cut_change_set (P0-3), review_decision (P0-6).

Open decisions (must close before migration design):

Axis-2 coverage score semantics — numeric (0-1) or banded (low/med/high)?
Axis-2 advisory vs hard-fail boundary (Gate 2 §3.4 closure).
DOT-pair signature schema — JWS, raw signature, or content-addressable hash?
Drift count semantics — byte-level, line-level, AST-node-level (Gate 2 §4 item 3)?
NEEDS_HUMAN routing — directly to Đ37 escalation queue, or buffered for batch review?
Retention — verify_result lifecycle independent of change-set or cascaded?

Migration design needed later:

Đ44 Family Registry submission (joint with P0-3).
Đ37 G-4 closure.
Create verify_result table.
Define canonical-form comparison spec (Gate 2 §4 item 3).
DOT-pair signature column / external store.
Wire VERIFY to PG output (replacing transient state).

Migration design is OUT OF SCOPE for this package.

5.5 P0-5 — `decision_backlog_entry`

Purpose: PG SSOT cho Decision Backlog Registry (D5 §4.1). Anti-forgetting infrastructure. Mọi producer (D1–D11) emit entries vào đây.

Source deliverable: D5 §4.2 (envelope), D5 §6 (item 1), D8 §6.2 (item 34).

Why required before implementation planning:

"No decision lost" (criterion 22) cannot be enforced without persistent registry.
Mọi governance gap closure (5 gaps) lưu lại trong registry — không có table → closure không track được.
Capability intake (D4), health signal (D3), retrieval gap signal (D11) đều emit vào đây — multiple producers blocked.
Sweep mechanism (D5 §4.4) phụ thuộc PG queryability.
Markdown mirror (D5 §4.8) generated from PG — mirror không có nguồn.

Related law / governance dependency:

Đ37: G-2 Backlog custodian (governance closure prerequisite).
Đ32: routing field gates by risk class.
Đ38: entry as code — versioned, diffable.
Đ44 / UOSL: new family hint (could be "Governance Event" — D7 §4.4 item 5).
Đ33 / Đ43: explicit placement — Lớp KHO.

Data ownership / target DB / layer assumption:

Target DB: directus.
Layer: Lớp KHO (D5 §4.1 SSOT pattern — anti-forgetting infrastructure).
Schema: decision_id, date_discussed, summary, status, dependencies, next_review_date, owner, source_discussion, related_law_or_design, risk, kind.
Versioning: separate decision_backlog_history table.
Edges: decision_backlog_dependency for entry-to-entry graph.
Sweep audit: decision_backlog_sweep_log.

Open decisions (must close before migration design):

Backlog scope — cutter-only vs federated (cross-link User Decision Pack §4).
Default next_review_date policy per risk × kind (cross-link).
Auto-resolve policy — D5 §8 recommends no auto-resolve; ratify in User Decision Pack.
Markdown mirror path — fixed at knowledge/dev/laws/dieu44-trien-khai/registry/ or per-scope?
Dependency graph cyclic detection — PG cycle check or app-level?
Owner field — text, FK to Đ37 role table, or external SSOT?
Kind enum — fixed list (gap/decision/threshold_tune/vocabulary_request/escalation/open_question) or extensible?

Migration design needed later:

Đ37 G-2 custodian closure.
Create entry + history + dependency + sweep_log tables.
Define markdown mirror generator (out-of-band batch job).
Wire all producers (D1–D11) to emit entries.

Migration design is OUT OF SCOPE for this package.

5.6 P0-6 — `review_decision`

Purpose: Persist REVIEW stage outcome (D2 §4.6) — independent AI review or human review verdict + findings + reviewer identity.

Source deliverable: D2 §4.6, D2 §6 (item 3), D8 §6.2 (item 18).

Why required before implementation planning:

"Independent review before cut" (criterion 4) cannot be enforced without persistent record.
CUT (D1 §4.6) pre-condition: manifest in PASS state — PASS state IS a review_decision row.
Reviewer identity (D8 missing instrumentation; reviewer_identity field gap) lives here.
NEEDS_HUMAN routing audit trail anchored here.
Cross-FK from verify_result (P0-4) for dual-gate audit.

Related law / governance dependency:

Đ37: reviewer roles (G-1, G-3 cross-link).
Đ32: risk class triggers human review.
Đ24: findings vocabulary (no parallel taxonomy).
Đ38: review as code — versioned, diffable.
Đ44 / UOSL: new family hint "Governance Event" (D7 §4.4 item 2).

Data ownership / target DB / layer assumption:

Target DB: directus (TAC schema).
Layer: Não.
Schema: review_id, manifest_id, manifest_version, status (PASS/FAIL/NEEDS_HUMAN), findings (JSONB checklist results), reviewer_identity, reviewer_class (ai/human/council), reviewed_at, escalation_ref.
FK: manifest_envelope (P0-2).

Open decisions (must close before migration design):

Reviewer_identity shape — AI capability fingerprint (model, revision, context hash) + human ID; mixed schema.
Findings JSONB schema — structured per D2 §4.6 checklist (10 items) or free-form per finding.
Escalation_ref target — decision_backlog_entry (P0-5) or Đ37 queue identifier?
Re-review semantics — new row per re-review or version on same row?
Reviewer independence guarantee — enforced at app level (separate execution context) or DB level (constraint)?
AI vs Human vs Council distinction — single status enum or separate column?

Migration design needed later:

Đ44 Family Registry submission.
Đ37 G-1 / G-3 reviewer role closure.
Create review_decision table.
Define findings JSONB schema.
Wire REVIEW emit-side to PG.

Migration design is OUT OF SCOPE for this package.

6. Cross-Dependency Matrix

P0 Item	Depends on (P0)	Depends on (Governance)	Depends on (User Decision)	Depends on (UOSL Family)
P0-1 canonical_address	—	G-1 (vocab)	—	G1 identity (D7)
P0-2 manifest_envelope/block	P0-1 (refs canonical_address)	G-1, G-3	§5 per-unit block shape	New family (Manifest envelope)
P0-3 cut_change_set	P0-2 (consumes manifest)	G-4 DOT-pair signing	—	New family (Cut change-set)
P0-4 verify_result	P0-2, P0-3	G-4 DOT-pair signing	—	G7 provenance hint
P0-5 decision_backlog_entry	—	G-2 custodian	§4 backlog scope	New family (Governance Event)
P0-6 review_decision	P0-2	G-1, G-3 reviewer roles	—	New family (Governance Event)

Topological order for migration design (NOT for execution — execution is later phase):

P0-5 (registry — independent, foundational)
   ↓
P0-1 (address — independent of envelope, but foundational for envelope)
   ↓
P0-2 (envelope/block — depends on P0-1)
   ↓
P0-6 (review_decision — depends on P0-2)
   ↓
P0-3 (cut_change_set — depends on P0-2)
   ↓
P0-4 (verify_result — depends on P0-2, P0-3)

7. Migration Design Scope (NOT THIS PACKAGE)

When migration design phase IS authorized (after User PASS + governance closure + User decisions), the migration package must produce, for each P0 item:

DDL spec.
Backfill plan for existing rows (where applicable, e.g. P0-1).
Index strategy.
Constraint design.
FK definition.
Backwards-compatibility shims (if any).
Rollback procedure (per migration, not per cutter).
Acceptance tests.
Đ32 risk approval evidence.
Đ37 owner signatures.
Đ44 Family Registry confirmation.
Đ0-G birth gate impact assessment.

None of the above is performed in this package.

8. Schema Gaps Recorded (Cross-Reference Only)

This package does NOT add new schema gaps. It groups existing gaps from D1, D2, D5, D6, D7, D8 §6, and Review Control §4 P0.

For full gap inventory (56 gaps total), see D8 §6 and Review Control §4.

9. Status Block

package_status: READY_FOR_USER_AND_GOVERNANCE_REVIEW
p0_items_identified: 6
p0_topological_order_defined: true
governance_closure_dependency: true
user_decision_dependency: true
uosl_family_registry_dependency: true
no_ddl_written: true
no_sql_proposed: true
no_schema_changed: true
no_migration_performed: true
no_pg_mutation: true
implementation_planning_blocked: true

10. Recommended Next Actions (NOT to be executed in this package)

Wait for User to confirm User Decision Pack §5 (per-unit block shape) — unblocks P0-2 design.
Wait for governance closure of G-1, G-2, G-3, G-4 — unblocks P0-2, P0-3, P0-4, P0-5, P0-6 design.
Wait for Đ44 Family Registry decisions on the 4 new families implied here — unblocks design of P0-2, P0-3, P0-4, P0-5, P0-6.
Then, and only then, draft a separate Migration Design Package per P0 item (or batched logically).
Migration design package itself is subject to Đ32 review before any execution.

11. Coverage of Review Findings

Review source	This package addresses
Review Control §4 P0 (6 items)	All 6 items (§5.1 – §5.6)
Gate 2 §3.5 (rollback schema-dependent)	P0-3, P0-4
Gate 2 §3.7 (per-unit block shape)	P0-2 + User Decision §5 cross-link
Gate 2 §4 closure items 1–8	Mapped into P0-2 / P0-3 / P0-4 open decisions
Gate 4 §3.2 (P0 critical path)	This package
D5 (registry SSOT)	P0-5
D8 §6 (schema gap consolidation)	P0 subset

dot-iu-cutter v0.1 — P0 Schema Planning Package

1. Purpose

2. Hard Boundaries

3. P0 Definition (per Review Control §4)

4. Cross-Links to Governance Closure

5. P0 Items

5.1 P0-1 — canonical_address on tac_logical_unit

5.2 P0-2 — manifest_envelope + manifest_unit_block

5.3 P0-3 — cut_change_set + rollback_key

5.4 P0-4 — verify_result

5.5 P0-5 — decision_backlog_entry

5.6 P0-6 — review_decision

6. Cross-Dependency Matrix

7. Migration Design Scope (NOT THIS PACKAGE)

8. Schema Gaps Recorded (Cross-Reference Only)

9. Status Block

10. Recommended Next Actions (NOT to be executed in this package)

11. Coverage of Review Findings

5.1 P0-1 — `canonical_address` on `tac_logical_unit`

5.2 P0-2 — `manifest_envelope` + `manifest_unit_block`

5.3 P0-3 — `cut_change_set` + `rollback_key`

5.4 P0-4 — `verify_result`

5.5 P0-5 — `decision_backlog_entry`

5.6 P0-6 — `review_decision`