dot-iu-cutter v0.5 — Writer Code-Authoring Brief

doc 4 of 6 · 2026-05-19 · spec for the SEPARATELY-GATED W-3 code-authoring phase. NO writer code authored here. Assumes the doc-3 PROPOSED rulings are accepted by GPT/User.

1. Scope of W-3 (DB-isolated, no production)

deliverable: a new entrypoint `cutter_agent/cutwrite.py` (working name) + its unittest,
  mirroring the ratified MARK/S2 lineage (feature branch only; no merge/push/deploy):
  - INPUT: the accepted manifest.json (digest 9d908a62…, file sha 7d56f3ce…, 60 cands)
    AND/OR the cut-plan artifacts (iu_mapping + idempotency_keys), re-validated by digest.
  - MODE: a DB-ISOLATED dry-run mode that targets a SCRATCH schema (or a transactional
    rollback harness), NOT production. Production mode is WITHHELD until W-5.
  - It builds + (in scratch) exercises the birth-gate-compliant write transaction and
    proves fn_iu_birth_gate_layer1 (BEFORE) and layer2 (DEFERRED @ COMMIT) PASS for all 60.
NOT in W-3: production credentials, real DOT-991/992 signing, any production DB write.

2. Per-IU write contract (60×; from doc-3 accepted rulings)

for each cut-plan iu_mapping row (canonical_address, level, effective_status=enacted,
  source_span{line_start,line_end,span_sha256}, content_hash, provenance.sv):

  body  := exact text slice of the PINNED snapshot region [line_start..line_end]
           (cutter_agent.dryrun.extract_region over the committed fixture; deterministic)
  assert sha256(body_canonicalized_as_in_MARK) == content_hash == span_sha256   # fail-closed
  title := the unit heading (first structural line of the slice)                # OD-W9

  INSERT information_unit:
    id                     := uuid4 (writer-generated)
    canonical_address      := row.canonical_address              # VERBATIM (OD-W4)
    unit_kind              := "law_unit"                         # OD-W2 (vocab ✓)
    lifecycle_status       := "enacted"                          # OD-W8 (confirm)
    owner_ref              := "incomex_council"
    conformance_status     := "open"                             # OD-W8
    doc_code               := "ICX-CONST"
    section_type           := {NGUYEN_TAC:"principle", KIEN_TRUC_SECTION:"section",
                               DIEU:"article"}[level]            # vocab ✓
    section_code           := derived from canonical_address path
    parent_or_container_ref:= NULL for top-level; else owning container IU id  # OD-W3
    identity_profile (jsonb):
      title                     := title
      owner_lookup_ref          := "incomex_council"
      primary_section_type_ref  := same as section_type above    # vocab ✓
      publication_type_ref      := "law"                         # vocab ✓
      publication_authority_ref := "incomex_council"             # vocab ✓
      provenance := { source_document_version_id: icxconst-008a06…,
                      manifest_digest: 9d908a62…,
                      snapshot_region_sha256: 17660443…,
                      span_sha256: row.content_hash,
                      idempotency_key: OD-1 key }
  INSERT unit_version:
    id            := uuid4 ; unit_id := IU.id ; version_seq := 1
    body          := body ; content_hash := row.content_hash
    lifecycle_status := "enacted"
    content_profile (jsonb) := { level, source_span, source_document_version_id,
                                 manifest_digest }
    created_by    := writer principal label (scratch/dry-run: a non-prod marker)
  UPDATE information_unit SET version_anchor_ref = unit_version.id,
        content_anchor_ref = unit_version.id::text  WHERE id = IU.id   # satisfies L2

3. Birth-gate transaction contract

ordering: build the parent/container IU rows BEFORE their children so
  parent_or_container_ref FKs resolve in-txn (NGUYEN_TAC/KIEN_TRUC_SECTION before their DIEU).
atomicity: ONE transaction for all 60 (deferred constraint trigger layer2 fires at COMMIT).
  Any layer1 (BEFORE) RAISE or layer2 (COMMIT) RAISE ⇒ full ROLLBACK ⇒ zero rows.
  NO partial cut, NO autocommit-per-row.
self-anchor: the IU→unit_version→UPDATE-anchor triple is the SANCTIONED birth pattern
  (an IU updating its own version anchor inside its birth txn); this is NOT the v0.4
  "append-only no UPDATE" rule and must be explicitly allowed in the writer's design doc.
order-of-operations per IU: INSERT IU (L1 BEFORE validates fields+vocab) → INSERT
  unit_version → UPDATE IU anchors; L2 (deferred) validates anchor consistency at COMMIT.
guards (fail-closed, abort): manifest digest≠9d908a62… / file sha≠7d56f3ce… /
  candidate_count≠60 / any Điều-44 or excluded address present / body sha≠span_sha256 /
  duplicate canonical_address / a pre-existing ICX-CONST row set (G-CUT-ONCE) ⇒ STOP.

4. Idempotency / collision

pre-check: SELECT count(*) FROM information_unit WHERE canonical_address = ANY($60) — if
  ANY exist for this manifest_digest ⇒ treat as already-cut ⇒ NO-OP (exit 0, "already
  applied"), never blind INSERT.
backstop: UNIQUE(canonical_address) — a race/duplicate hard-fails the txn (clean abort).
identity: OD-1 key persisted in identity_profile.provenance; re-CUT of the same manifest
  digest is a deterministic no-op (G-CUT-ONCE).

5. CI / acceptance gate for the W-3 commit (mirror MARK/S2 precedent)

- targeted unittest suite GREEN (the writer's own suite is the gate of record);
- a scratch-schema (or txn-rollback) birth-gate dry-run proving all 60 pass L1+L2 with
  the doc-3 mapping, reproducing 60 IU + 60 unit_version, 0 Điều-44, addresses verbatim,
  body sha == span_sha256, deterministic;
- import discipline: production driver isolated from any dry-run/no-DB path;
- py_compile clean; branch/HEAD/tree precheck; no DB env in the no-DB path;
- the lone pre-existing test_security_boundaries baseline failure remains a SEPARATE,
  already-tracked remediation (not a W-3 regression) — same R1 precedent as S2.

6. Explicitly NOT authorized by this brief

- NO production DB write / NO production IU creation / NO CUT / NO VERIFY (W-5 only).
- NO real credential/signing (W-4 only).
- NO invented production writer command. W-3 is design→author→CI→commit of a DB-isolated
  writer + scratch dry-run; production is a later, separately gated phase.

doc 4 of 6. Design/spec only. No production mutation. Self-advance PROHIBITED.