dot-iu-cutter v0.5 — S2→CUT Capability Readiness · Production Schema & Writer Gap Review

doc 3 of 5 · 2026-05-19 · live PostgreSQL probed READ-ONLY (read-only role, information_schema + pg_catalog + 2 sample rows). No write, no DDL, no mutation.

1. Production IU substrate — what a CUT writer must satisfy (NEW evidence)

directus.public.information_unit is a governed two-layer birth-gated table:

constraints:
  PK  information_unit_pkey (id uuid)
  UNIQUE information_unit_canonical_address_key (canonical_address)   # collision guard
  FK  fk_iu_version_anchor: version_anchor_ref -> unit_version(id) DEFERRABLE INIT DEFERRED
  TRIGGER trg_iu_birth_gate_layer2 (DEFERRABLE INITIALLY DEFERRED, constraint trigger)
triggers/functions:
  fn_iu_birth_gate_layer1()  BEFORE  — synchronous field/vocab gate
  fn_iu_birth_gate_layer2()  COMMIT  — deferred anchoring/consistency gate
  fn_iu_updated_at()         touch
existing_rows: 98 total IU; 0 with canonical_address LIKE 'ICX-CONST%' or doc_code
  'ICX-CONST' ⇒ the 60 Constitution IUs are a CLEAN INSERT (no collision today), but
  the UNIQUE(canonical_address) means a second CUT of the same 60 would hard-fail
  (natural collision guard; a writer needs explicit idempotency / pre-existence check).

fn_iu_birth_gate_layer1 (BEFORE INSERT) requires, else RAISE EXCEPTION:

- canonical_address, unit_kind, lifecycle_status, owner_ref, conformance_status non-empty
- unit_kind ∈ dot_config key 'vocab.unit_kind.<unit_kind>'
- identity_profile->>'title' non-empty
- identity_profile->>'owner_lookup_ref' non-empty
- identity_profile->>'primary_section_type_ref' non-empty AND ∈ 'vocab.section_type.<v>'
- identity_profile->>'publication_type_ref' (if present) ∈ 'vocab.publication_type.<v>'
- identity_profile->>'publication_authority_ref' / 'publication_type_ref':
    currently RAISE WARNING 'PILOT-ONLY … production sẽ BLOCK' — i.e. PRODUCTION WILL
    REQUIRE both (treat as mandatory for the Constitution production CUT).

fn_iu_birth_gate_layer2 (DEFERRED, at COMMIT) requires:

- content_anchor_ref non-empty
- version_anchor_ref NOT NULL
- a unit_version row WHERE id=version_anchor_ref AND unit_id=information_unit.id
- content_anchor_ref == version_anchor_ref::text

unit_version (the FK target — 16 cols)

id uuid · unit_id uuid NOT NULL (→ the IU) · body text NOT NULL · content_hash text NOT NULL
· version_seq int NOT NULL · lifecycle_status text NOT NULL · content_profile jsonb NOT NULL
· created_at/by NOT NULL · title? · description? · review_state? · provenance? · editor?
· enacted_at? · updated_at?

2. Birth transaction shape a Constitution CUT writer MUST implement (per IU)

1 INSERT information_unit (id, canonical_address=ICX-CONST/<path>, unit_kind=<vocab>,
    lifecycle_status, owner_ref, conformance_status,
    identity_profile{title, owner_lookup_ref, primary_section_type_ref(vocab),
      publication_authority_ref(vocab), publication_type_ref(vocab), …})    # passes L1
2 INSERT unit_version (id, unit_id=IU.id, body, content_hash, version_seq=1,
    lifecycle_status, content_profile, created_by, provenance)
3 UPDATE information_unit SET version_anchor_ref=unit_version.id,
    content_anchor_ref=unit_version.id::text  WHERE id=IU.id                # passes L2 @ COMMIT
4 set parent_or_container_ref for the NGUYEN_TAC/KIEN_TRUC/DIEU hierarchy (N-2)
prereq dot_config vocab rows must EXIST for every unit_kind / section_type /
  publication_type / publication_authority the 60 IUs use (else L1 RAISES).

Note: step 3 is an in-transaction self-anchoring UPDATE — the sanctioned birth pattern (an IU updating its own version anchor inside its birth txn), distinct from the v0.4 "append-only, no UPDATE" model. The production model is governed-birth, not the v0.4 ledger.

3. Exact implementation gap (GAP-W) — the controlling production blocker

GAP-W1 no manifest→information_unit/unit_version writer exists anywhere:
  - cutplan.py is a planner; its preview models v0.4 ledger families, NOT this birth model.
  - v0.4 ledger.py/phases.py write manifest_envelope/cut_change_set; NO information_unit /
    unit_version insert; do NOT honor the birth-gate triggers; cli refuses production.
GAP-W2 manifest→IU field mapping undefined for the governed schema:
  the MARK manifest carries {level, canonical_address, effective_status, source_span,
  span_sha256, provenance.source_document_version_id}. The birth gate additionally needs:
  unit_kind (vocab), owner_ref, conformance_status, lifecycle_status, identity_profile
  (title, owner_lookup_ref, primary_section_type_ref(vocab), publication_authority_ref,
  publication_type_ref), and a unit_version body+content_hash+content_profile+version_seq.
  These are NOT derivable from the manifest digest/spans alone — a ratified mapping +
  N-2 (NGUYEN_TAC/KIEN_TRUC = IU or container) ruling is required.
GAP-W3 dot_config vocab prerequisites not confirmed/seeded for ICX-CONST unit_kind/
  section_type/publication_type/publication_authority.
GAP-W4 credential/signing production path not built (v0.4 signing is Stub/Deferred;
  cli/db_adapter refuse production; cutter_exec/cutter_verify not provisioned).
GAP-W5 no separate explicit production-DB-write approval; governed VERIFY path for the
  birth-gated model not defined.
gap_class: IMPLEMENTATION (not information) — the schema is now known; what is missing is
  built code + a mapping ruling + vocab seeding + credentials + approval.

4. Collision / idempotency / rollback risk (read-only assessment)

collision: UNIQUE(canonical_address) ⇒ re-CUT of the same 60 hard-fails at the DB; a writer
  MUST pre-check existence per manifest digest / address (G-CUT-ONCE) and treat re-CUT as
  a no-op, never a duplicate or a blind INSERT.
idempotency: S2's OD-1 key (source_version_id, canonical_address, content_hash) is a sound
  basis for a per-IU idempotency ledger the future writer should persist + check.
rollback: birth is multi-row + deferred-constraint; any L1/L2 RAISE aborts the txn ⇒
  clean all-or-nothing per-IU (or per-batch single txn). Post-commit correction = governed
  forward-compensation (lifecycle_status/superseding version), never physical delete.
verification: VERIFY must assert 60 IU + 60 unit_version, birth-gate satisfied,
  canonical_address set ≡ manifest candidates, version_anchor/content_anchor consistent,
  zero Điều-44/excluded, provenance bound to source_document_version icxconst-008a06….

doc 3 of 5. Read-only. Nothing committed/executed. Self-advance PROHIBITED.