dot-iu-cutter v0.5 — production-leg-a-only mode · Authoring Report

doc 1 of 4 · 2026-05-20 · GAP-A1 → R1 closed via micro-authoring on the feature branch (no push, no merge, no tag). Re-verifies that the R1 path is guarded ⊇ R2 and that the production-leg-a-only runnable now exists.

result              : R1_AUTHORED_AND_TESTED  (feature branch only)
pre_commit_HEAD     : 152e7db
post_commit_HEAD    : f20c79c
production_mutation : NONE
self_advance        : PROHIBITED

1. Scope of this authoring (R1)

goal     : add a runnable seam so the UB-2 first controlled CUT (leg-A only)
           is executable WHEN sovereign approvals + scoped GRANTs are in
           place ; the seam itself executes nothing this phase.
out_of_scope_for_R1 :
  - leg-B governed-ledger row-builder (still GAP-B1 ; recorded post-CUT
    via the v0.4 governed path per UB-2 doc 6 of the prior package)
  - any production GRANT / REVOKE
  - any production DB write
  - any deploy / restart / merge / push / tag
  - any change to cutter_agent/cutwrite.py (ratified W-3 factory ; sha
    31ce88dc… byte-unchanged)

2. Files & commit

repo  : /Users/nmhuyen/iu-cutter-build/repo/iu-cutter
branch: feature/constitution-snapshot-mark-dryrun  (NOT main ; no push/merge/tag)
pre   : 152e7db  →  post: f20c79c  (3 files modified, 0 new files, +487 / -25)

cutter_agent/prod_iu_adapter.py
  sha256 (post)            : 07618c41 422ebe0f 4077a3b8 ccb44404
                             7524ae65 09159b51 3e2fee7a 2ee6131d
  delta                    : +48 lines = new ProdIuBirthAdapter
                             .execute_leg_a_only(args) method ONLY.
  existing behavior        : unchanged ; execute_cut() still raises
                             LegBUnavailable (GAP-B1) ; default
                             _default_provider still REFUSES.

cutter_agent/cutprod.py
  sha256 (post)            : 9d1cd336 24f52e28 227143ea 0ca2f468
                             7c612efe faa85fa3 25d78dbc e39f2345
  delta                    : +205 / -25 lines = new third mode
                             "production-leg-a-only" + extra sovereign-intent
                             flag set + _load_provider helper ; plan-only and
                             production modes byte-equivalent.

tests/test_prod_iu_adapter.py
  sha256 (post)            : 1c2c8d0e aa2d5c57 3c4d4dfe 411f6ed2
                             ee578b6b f947f7db dd8b24ab 8278522b
  delta                    : +259 lines = TestProductionLegAOnlyCli + 2
                             direct-adapter seam tests + sys.modules
                             registry helper for stub provider loading.

ratified W-3 factory (UNCHANGED, byte-identical) :
  cutter_agent/cutwrite.py : sha256 31ce88dc a8f68abd 1bff484d 665235f3
                                    96272b0b 4f644488 12de8a93 a1f901d3
no remote configured → push is not possible from this checkout.

3. New code shape (high-density summary)

ProdIuBirthAdapter.execute_leg_a_only(args) -> dict :
  step 1  (no-connect)  : iu, uv, wdig = self._g23_rows(args)
                          self._g1_approval()
                          self._g7_backup()
  step 2  (connect)     : conn = self._provider({"role": PRINCIPAL_EXEC,
                                                 "intent": "leg-a-only-
                                                 constitution-cut"})
  step 3  (session)     : self._g4_principal(conn)         # SELECT current_user
  step 4  (single txn)  : conn.execute("BEGIN")
                          self._g5_drift(conn)             # in-txn catalog
                          self._g6_cut_once(conn)          # in-txn G-CUT-ONCE
                          self.leg_a_in_txn(conn, iu, uv)  # 1 + 180 stmts
                          conn.commit()
  step 5  (atomic abort): on ANY exception inside the txn boundary
                          conn.rollback() (best-effort, benign on most drivers)
                          re-raise the original exception ; ZERO partial rows.
  returns               : {"iu_inserted": 60, "uv_inserted": 60,
                           "anchor_updates": 60,
                           "writer_digest": "d99a31d4…",
                           "txn": "COMMITTED",
                           "leg_b_status":
                             "DEFERRED_TO_POST_CUT_GOVERNED_RECORDING_PACKAGE"}

cutprod  --mode production-leg-a-only :
  universal pre-mode guards (apply to ALL modes):
    --mode ∈ {plan-only, production, production-leg-a-only}    else exit 2
    --fail-closed + --exclude-dieu-44                          mandatory
    --expect-writer-digest == d99a31d4…                        else exit 2
    no PG_DSN / DATABASE_URL / DIRECTUS_URL / PGPASSWORD /
        PGHOST / PGUSER in env                                 else exit 2
  per-mode mandatory flags (NEW, only in production-leg-a-only):
    --i-have-sovereign-production-write-approval <kb-id>       else exit 2
    --i-have-grant-execution-approval-kb-id     <kb-id>        else exit 2
    --production-intent CONFIRM-LEG-A-ONLY-CONSTITUTION-CUT    else exit 2
                                                               (literal token)
    --fresh-backup-sha256 <64-hex>                             else exit 2
    --connection-provider-module <pkg.mod:callable>            else exit 2
  provider resolution :
    _load_provider() : strict 'pkg.mod:callable' regex ; importlib.import_module
    target factory must be callable ; factory() must return a Callable
    ANY ImportError/AttributeError/ValueError ⇒ exit 3 (BLOCKED)
    repo ships NO real provider ⇒ default state = exit 3 here ;
    operator-authored module is the runnable hook.
  on success : prints exactly one line ;
    CUT_OK_LEG_A iu_inserted=60 uv_inserted=60 anchor_updates=60
    writer_digest=d99a31d4… txn=COMMITTED
    leg_b=DEFERRED_TO_POST_CUT_GOVERNED_RECORDING_PACKAGE
    approval_id=<kb> grant_approval_id=<kb> backup_sha=<64-hex>
  on any failure : single STDERR BLOCKED/REFUSED line ; non-zero exit ;
                   conn.rollback() if a connection was opened.

4. Fail-closed map — what enforces what

G1 sovereign approval      : --i-have-sovereign-...-approval flag (cutprod) +
                             _g1_approval (adapter) ; absent ⇒ no connect.
G2 pinned identity         : --expect-manifest-* + --source-version-id +
                             --expect-region-sha + --expect-writer-digest +
                             _g23_rows constants ; any mismatch ⇒ exit 2/3.
G3 writer_digest           : --expect-writer-digest == d99a31d4… +
                             cutwrite.run_dry digest assertion.
G4 cutter_exec principal   : _g4_principal SELECT current_user (session-level).
G5 zero drift              : _g5_drift in-txn catalog read of IU cols / UV
                             cols / L1 md5 / L2 md5 / vocab count ;
                             mismatch ⇒ rollback, no writes.
G6 G-CUT-ONCE              : _g6_cut_once in-txn count(ICX-CONST%) == 0 ;
                             else rollback, no writes.
G7 fresh backup            : --fresh-backup-sha256 (cutprod) + backup_gate
                             callable (adapter) ; absent/false ⇒ exit 2/3.
allowlists                 : _IU_TABLE / _UV_TABLE table allowlist +
                             _IU_COLS / _UV_COLS column allowlists +
                             _ANCHOR_UPDATE_COLS (the only UPDATE columns) ;
                             any rejected statement ⇒ exit 3, atomic rollback.
DOT-991 lane invariants    : assert_lane_overlap_invariants enforced for any
                             signature row ; signature emission is NOT part of
                             this leg-A path (lives in leg-B post-CUT).
env-secret hygiene         : _DB_ENV_GUARD refuses any caller-side DB env var
                             leak ; the operator's provider sources its DSN
                             ONLY from a sovereign secret-store, never argv,
                             never KB, never STDOUT.

5. What this CHANGES vs the prior package

prior status (2026-05-20 morning)         : READY_CONDITIONAL_ON_GAP_A1
                                            (R1 micro-author OR R2 wrapper)
this commit                               : R1 chosen + AUTHORED + TESTED
                                            on feature branch ; CUT command
                                            for leg-A IS NOW RUNNABLE under
                                            sovereign-authored provider +
                                            sovereign approvals.
remaining sovereign approval gates        : GD-1 · U-W4b · C5 · U-W5
                                            (unchanged ; doc 3 + doc 4)
post-CUT obligation                       : leg-B governed-recording package
                                            (unchanged ; doc 6 of the prior
                                            approval package)
production mutation in this phase         : NONE
self_advance                              : PROHIBITED

6. Status

authoring                                 : DONE on feature branch ; reversible
                                            via git reset --hard 152e7db
tests                                     : doc 2 (37/37 + 95/95 targeted)
runnable seam                             : production-leg-a-only AVAILABLE
                                            (operator must still provide
                                            sovereign-authored connection
                                            provider module)
production mutation                       : NONE
next                                      : doc 3 (updated GRANT+CUT pkg) ·
                                            doc 4 (final readiness report)

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