dot-iu-cutter v0.5 — Production Bridge · Guarded Production Adapter Package

doc 4 of 7 · 2026-05-19 · implementation-ready DESIGN. Code WITHHELD by discipline (rationale §4). No repo change. No DB connection. No mutation.

1. Why an adapter is needed (and why cutwrite.py is not it)

cutwrite.py (f0120ac, ratified W-3): import-isolated (stdlib + dryrun only),
  db-isolated; ScratchGovernedDB faithfully mirrors prod birth-gate L1/L2 +
  constraints; production mode REFUSED (exit 2); any DB env ⇒ exit 2. By
  construction it CANNOT and MUST NOT connect. It is the deterministic row
  factory (build_rows → 60 IU + 60 unit_version; writer_digest d99a31d4…).
db_adapter.RealPostgresAdapter (v0.4): psycopg3 over the cutter_governance
  LEDGER shape; NOT a public.information_unit/unit_version birth writer; refuses
  prod connect in the v0.4 cycle. Reusable for the LEDGER leg only.
⇒ GAP-C4: a SEPARATE guarded module is needed to (a) connect as cutter_exec,
  (b) replay cutwrite's deterministic rowset into public.* under the real
  birth-gate, and (c) write the cutter_governance ledger leg — in ONE txn.

2. Module contract — cutter_agent/prod_iu_adapter.py (NEW, future)

isolation: a NEW module NOT imported by cutwrite's db-isolated path. cutwrite.py
  stays byte-unchanged; a thin separate prod entrypoint composes
  cutwrite.build_rows() (pure) + prod_iu_adapter (connect/write). The rowset is
  produced by the RATIFIED pure factory; the adapter never re-derives rows.
inputs: the cutwrite-emitted iu_rowset.json / unit_version_rowset.json +
  writer_digest + the pinned manifest/region identity (read-only artifacts).
dependencies: psycopg3 only; secret from approved .env (DOT_CUTTER_EXEC_DB_*),
  never logged / never argv / never KB.

Hard guards — fail-closed, ALL required before a single connect

G1 explicit flag --i-have-sovereign-production-write-approval <kb-doc-id> AND
   that KB doc resolvable & marks this exact manifest digest; absent ⇒ exit 2,
   no connect.
G2 --manifest sha == 7d56f3ce… · digest == 9d908a62… · candidate_count == 60 ·
   --source-version-id == icxconst-008a06… · --expect-region-sha == 17660443… ;
   recompute, any mismatch ⇒ exit 3, no connect.
G3 --expect-writer-digest == d99a31d4a4be907c510ae15965e9f7bb3387e9e28676e9f32adf463828b1aa28 ;
   adapter recomputes from the pure factory; mismatch ⇒ exit 3.
G4 post-connect, BEFORE any write, same session:
   SELECT current_user = 'cutter_exec' (else abort; reject cutter_ro/
   workflow_admin/directus/postgres).
G5 in-session read-only drift precheck (catalog): information_unit 19 cols ·
   unit_version 16 cols · 4 IU constraints · md5(fn_iu_birth_gate_layer1)=
   f38c94d0043a61507a8c2e85afd59998 · md5(fn_iu_birth_gate_layer2)=
   078ba0051ce4d894cabcc0102c4320f8 · dot_config vocab keys present ;
   any mismatch ⇒ abort, zero writes.
G6 G-CUT-ONCE: SELECT count(*) public.information_unit WHERE canonical_address
   LIKE 'ICX-CONST%' == 0  AND no cut_change_set for digest 9d908a62… ;
   non-zero ⇒ NO-OP exit 0 (already applied), never re-insert.
G7 fresh verified backup gate (doc 6) clean & ≤ 60 min, else abort.

The single atomic transaction (psycopg3, one connection, one txn)

BEGIN;
SET CONSTRAINTS ALL DEFERRED;          -- FK version_anchor_ref + L2 are DEFERRED
-- leg A — birth (public), per the 60-row ratified rowset, in order:
--   60 × INSERT public.information_unit (...)                 -- L1 BEFORE fires
--   60 × INSERT public.unit_version (unit_id = IU.id, ...)
--   60 × UPDATE public.information_unit
--          SET version_anchor_ref = uv.id,
--              content_anchor_ref = uv.id::text
--        WHERE id = iu.id;                                    -- self-anchor
-- leg B — governed ledger (cutter_governance), same txn:
--   1 × INSERT manifest_envelope + 60 × manifest_unit_block
--   1 × INSERT decision_backlog_entry + decision_backlog_history transition
--   1 × INSERT cut_change_set (content_hash = manifest digest 9d908a62…)
--   1 × INSERT dot_pair_signature (DOT-991 executor; cross-ref change_set_id
--          ONLY; verify_result_id NULL; lane-overlap invariants enforced)
--   60 × cut_change_set_affected_row (target_ref = IU id)
COMMIT;     -- deferred FK + trg_iu_birth_gate_layer2 fire here, per IU

failure semantics: any L1/L2 RAISE, drift, principal/grant failure, digest
  mismatch ⇒ single-txn ROLLBACK ⇒ zero rows (no partial cut, no orphan
  unit_version). G-CUT-ONCE makes a retry of the same digest a no-op.
determinism: rows come ONLY from cutwrite.build_rows(); the adapter asserts
  writer_digest == d99a31d4… immediately before COMMIT.

3. Test / proof plan for the gated build (U-W4d)

- unit: guard matrix (G1..G7) each ⇒ correct exit, no connect on any failure.
- lane-overlap negative tests (doc 3 §2.2): swapped / both / neither / mismatch.
- scratch integration: run leg A+B against an isolated ScratchGovernedDB-style
  fixture extended with a cutter_governance ledger mirror; assert 60/60/60 +
  1 cut_change_set + 1 DOT-991 sig + history transition; assert all-or-nothing
  rollback on an injected L2 failure.
- determinism: writer_digest stable d99a31d4…; idempotent re-run ⇒ no-op.
- NO production connection in any test (fixture/scratch only).

4. Code WITHHELD — rationale (decision GD-2)

authoring connect-capable production code is now UNBLOCKED (C1 delta exact,
  C2 resolved, schema/birth-gate pinned) — but it is deliberately WITHHELD this
  phase because:
  - a module that CAN open a production write connection is itself a
    production-risk artifact; project discipline (W-1..W-4 precedent) reviews
    connect-capable code under its own command-review gate, not as a side
    effect of a readiness package;
  - it cannot be exercised honestly without the isolated ledger-mirror fixture,
    which is part of the build cycle, not this readiness pass;
  - the apply-principal (GD-1) and the C3 signing ruling (RD-C3) should be fixed
    BEFORE the adapter hard-codes its connect principal and signing call.
⇒ recommended as the single remaining build = gate U-W4d (design here is
  implementation-ready: a mechanical build, not open-ended).

5. Status

guarded_production_adapter: DESIGN_COMPLETE · CODE_WITHHELD (gate U-W4d)
blocking_inputs_for_the_build: GD-1 apply principal + RD-C3 signing ruling
production_mutation: NONE

doc 4 of 7. No production mutation. Self-advance PROHIBITED.