dot-iu-cutter v0.5 — Post-CUT · Leg-B Governed Recording Package

doc 3 of 6 · 2026-05-20

phase                : G3 — leg-B governed recording survey + execute-or-package
outcome              : PACKAGED  (NOT executed — recommended dedicated macro)
production_mutation  : NONE this phase
audit_debt_window    : 24h from 2026-05-20T04:18:22Z (CUT commit) →
                       expires 2026-05-21T04:18:22Z
remaining_at_session : >23h

1. Why not execute leg-B in this macro

risk_dimensions :
  - 8 target tables (cut_change_set + affected_row + manifest_envelope +
    manifest_unit_block + dot_pair_signature + decision_backlog_entry +
    decision_backlog_history + review_decision)
  - ~30 NOT NULL no-default columns total (doc 1 §2.2 inventory) — each
    needs a deliberate value chosen, not guessed
  - multi-table FK ordering (review_decision → manifest_envelope →
    manifest_unit_block × 60 → decision_backlog_entry → cut_change_set
    → cut_change_set_affected_row × 60 → dot_pair_signature ×N) ; one
    atomic txn — wrong order = ABORT
  - DOT-991 executor signature (signer_tool_revision, payload_envelope,
    signature_payload) — must follow the binding mandate
    dot-iu-cutter-v0.4-dot-lane-overlap-prevention-gpt-mandate-2026-05-17
    (cross_reference_change_set_id only, NOT cross_reference_verify_result_id)
  - committed code path : `cutter_agent/ledger.py` is the v0.4 design-time
    SKELETON ; `write_cut_change_set` builds a 6-key dict and supplies
    `content_hash` (not in live shape) while missing 6 NOT NULL no-default
    cols. GAP-B1 confirmed. A new "ledger v2" builder must be authored.

execution_safety :
  - prior macros had two psycopg2-level surprises (autocommit=True NO-OP
    bug, _NOW sentinel sentinel needing wrapper-level swap) — both were
    fixable in-scope but ate session time. A 8-table 126-row leg-B has
    proportionally MORE surface for similar discovery-after-execution
    surprises.
  - the prompt's autonomy clarification explicitly accepts in-scope
    technical fixes, but ALSO requires "Không fabricate leg-B" — a single
    NOT NULL field given a wrong sentinel value is fabrication.

mitigations_unavailable_this_session :
  - no scratch staging DB with the same cutter_governance schema (the live
    DB is the only target) ; a rollback-only smoke would lock the same
    constraint paths and still risk side-effects (e.g. triggers calling
    fn_birth_registry_auto for any IU row touch).
  - the v0.4 governed CUT was never executed on this branch, so no prior
    "shape-correct" row template exists in KB to copy.

decision : PACKAGE the gap with exact NOT NULL inventory + recommended row
           shapes + builder-author plan ; defer execution to a separately-
           gated macro that focuses solely on leg-B authoring-and-execution.

2. Exact NOT NULL no-default inventory (per table) — VALUES TO SUPPLY

Where gen_random_uuid() or now() is the column DEFAULT, leg-B can omit the value. The following columns have NO DEFAULT and are NOT NULL — they MUST be supplied by the builder :

2.1 review_decision (one row ; written FIRST so cut_change_set can FK to it)

governance_event_kind     : 'cut_constitution_first'
manifest_id               : <new uuid ; the manifest_envelope.envelope_id chosen below>
manifest_version          : '20260520T041822Z-canonical-A4'
                            (or the SemVer 'v0.5-canonical-A4' or the
                             writer_digest tag)
review_scope              : 'document'   (the whole constitution snapshot)
status                    : 'approved'
verdict                   : 'approve'
findings                  : jsonb_build_object('iu_count',60, ...)
                            ⇒ the same shape as VW findings in doc 2 §4.2
reviewer_class            : 'sovereign'   (per GPT/User approval as the reviewer)
reviewer_identity         : jsonb_build_object('kb_doc_id', '<GPT ruling KB id>')
risk_class_assessment     : 'standard'
decision_at               : <when sovereign approved this CUT ; e.g.
                              2026-05-20T03:00:00Z = the canonical-path-redesign
                              ruling timestamp>
decided_by                : 'GPT/User'
cross_signed_by_dot_verifier : false  (we have NOT run VERIFY yet)
version                   : '1.0.0'
created_at                : now()
updated_at                : now()

2.2 manifest_envelope (one row)

envelope_id    : gen_random_uuid()
operation_kind : 'cut_constitution_first'
status         : 'approved'
source_doc_ref : 'tests/fixtures/constitution-normalized-17660443e0f23e99.md'
                 (or the canonical KB path for the snapshot)
created_by     : 'cutter_exec/DOT-991/constitution-cut'
created_at     : now()
(optional: reviewer, reviewed_at, rationale, cut_change_set_ref — set later
 once cut_change_set row exists)

2.3 manifest_unit_block × 60 (one per IU)

envelope_id        : <FK envelope_id from §2.2>
unit_local_id      : iu['canonical_address']    (or per-row short id ; must be
                                                 unique per (envelope_id, unit_local_id))
block_role         : 'birth'
source_span        : jsonb_build_object('body_length', length(uv.body),
                                        'content_hash_preview',
                                          substring(uv.content_hash,1,16),
                                        'cutwrite_idem_key',
                                          cutwrite['idempotency_key'])
render_order       : iu.row_index_in_cutwrite (numeric 1..60)
target_unit_id     : iu.id (FK back to the live information_unit row)
proposed_canonical_address : iu.canonical_address  (informational)
proposed_authority         : 'incomex_council'
payload_summary    : jsonb_build_object('unit_kind', 'law_unit',
                                        'section_type', iu.section_type,
                                        'publication_type', 'law')
created_at         : now()

2.4 decision_backlog_entry (one row)

entry_id      : gen_random_uuid()
kind          : 'cut_change_set_proposal'
status        : 'closed'   (CUT executed and committed already)
payload       : jsonb_build_object('manifest_id', <envelope_id>,
                                   'cut_summary', jsonb_build_object(...))
emitted_at    : (when cutwrite manifest was produced ; can be the manifest
                 file timestamp or now())
scenario_ref  : 'v0.5-first-controlled-canonical-cut'

2.5 decision_backlog_history (1+ rows for state transitions)

history_id            : gen_random_uuid()
entry_id              : <FK entry_id from §2.4>
entry_version_before  : NULL    (or '0' if string-typed)
entry_version_after   : '1'
change_kind           : 'open→approved→closed'  (record state transitions)
change_diff           : jsonb_build_object('field','status',
                                            'from','open','to','closed')
changed_by            : 'GPT/User'
changed_at            : (the GPT ruling timestamp for this CUT)
rationale             : 'first controlled canonical CUT approved + executed'

2.6 dot_pair_signature (executor) — one row

signature_id           : gen_random_uuid()
signature_kind         : 'executor'   (DOT-991 lane)
signer_dot_id          : 'DOT-991'
signer_tool_revision   : 'iu-cutter@f20c79c+canonical-A4-patch+autocommit-fix'
                         (record full provenance ; the EXACT tool revision)
payload_hash           : encode(digest(payload_envelope::text,'sha256'),'hex')
payload_envelope       : jsonb_build_object(
                           'writer_digest', PIN_WRITER_DIGEST,
                           'manifest_file_sha256', PIN_MANIFEST_FILE_SHA,
                           'manifest_digest', PIN_MANIFEST_DIGEST,
                           'region_sha256', PIN_REGION_SHA,
                           'source_version_id', PIN_SOURCE_VERSION,
                           'candidate_count', 60,
                           'docprefix', 'ICX-CONST',
                           'iu_ids_persisted', <array of 60 iu.id from live>,
                           'gateway_path', 'fn_iu_create',
                           'cut_committed_at', '2026-05-20T04:18:21.854512+00')
signature_payload      : <StubSigning placeholder ; signing.py StubSigning class>
                         OR <real ed25519/etc. signing per DOT-991 doctrine>
signed_at              : now()
cross_reference_change_set_id : <FK cut_change_set row written below>
cross_reference_verify_result_id : NULL  ← MANDATORY per lane-overlap mandate
validation_state       : 'pending'  (default)
prior_signature_id     : NULL (first signature for this CUT)

NOTE: signing.py:StubSigning is in-repo and can produce the placeholder signature deterministically. Whether "real" signing is required is a sovereign question (the lane-overlap-mandate doc references "production MAY require real signing for foundational CUTs like the constitution").

2.7 cut_change_set (one row ; written after review_decision + envelope + entry + executor signature exist for FKs)

change_set_id              : gen_random_uuid()
rollback_key               : 'cut-constitution-first-20260520-canonical'
manifest_id                : <FK envelope_id from §2.2>
manifest_version           : '20260520T041822Z-canonical-A4'
review_decision_id         : <FK review_decision_id from §2.1>
executor_tool_revision     : 'iu-cutter@f20c79c+canonical-A4-patch+autocommit-fix'
verifier_tool_revision     : 'iu-cutter@f20c79c+VERIFY-stub'   (or the actual
                             verifier tool when VERIFY runs)
tool_revision_match        : false
executor_signature_id      : <FK signature_id from §2.6>
verifier_signature_id      : NULL  (will be set when VERIFY writes
                             verify_result + DOT-992 signature ; OD-6)
state                      : 'committed'
cut_started_at             : '2026-05-20T04:18:14Z'
cut_committed_at           : '2026-05-20T04:18:21.854512Z'
affected_unit_count        : 60
payload_summary            : jsonb_build_object('canonical_path','fn_iu_create',
                                                'lifecycle_status','draft',
                                                'publication_type','law')
decision_backlog_entry_id  : <FK entry_id from §2.4>
emitted_by                 : 'cutter_exec/DOT-991/constitution-cut'
idempotency_key            : <cutwrite-derived ; can use writer_digest>
version                    : '1.0.0'
risk_class                 : 'standard'
scenario_ref               : 'v0.5-first-controlled-canonical-cut'

2.8 cut_change_set_affected_row × 60 (one per IU)

affected_row_id        : gen_random_uuid()
change_set_id          : <FK change_set_id from §2.7>
target_table           : 'public.information_unit'
target_row_id          : iu.id::text
operation_kind         : 'insert'
before_state_snapshot  : NULL  (canonical path = new IUs ; no prior state)
after_state_snapshot   : jsonb_build_object(
                           'canonical_address', iu.canonical_address,
                           'unit_kind', iu.unit_kind,
                           'lifecycle_status', 'draft',
                           'identity_profile', iu.identity_profile,
                           'version_anchor_ref', iu.version_anchor_ref,
                           'content_anchor_ref', iu.content_anchor_ref)
applied_at             : iu.created_at

(Optionally another 60 rows for unit_version inserts — depends on the sovereign decision whether to model UV writes separately or roll them into the IU after_state_snapshot.uv slot.)

3. Recommended builder code (NOT authored in this macro)

proposed_module : cutter_agent/ledger_v2_canonical_cut.py
shape :
  - reads the 60 ICX-CONST iu rows from live DB (cutter_verify SELECT,
    or via the canonical adapter's connection)
  - reads the 60 anchored UV rows
  - reads the cutwrite manifest (already in /tmp staging or regenerable
    via cutter_agent.dryrun)
  - builds the 8 row dicts above ; uses signing.StubSigning by default
    (sovereign overrides to real signing per DOT-991)
  - writes the 8 tables in a SINGLE atomic transaction, ordered per
    §§2.1→2.8, on a cutter_exec connection (the same provider module
    already pre-deployed at sha 26ebb918f9a0…)
  - emits a CUT_LEG_B_OK line with all FK ids
  - on any error, ROLLBACK + raise (R-2 atomic abort)
test_strategy :
  - fake-conn unit tests (~15 tests) similar to test_prod_iu_adapter_canonical
  - rollback-only smoke (BEGIN; …; ROLLBACK) inside the docker network
  - then sovereign-approved committing run
estimated_session_size : a single 45–60 min macro
remaining_audit_debt_at_recommended_run : ≥20h

4. Disposition

G3 (leg-B governed recording) : PACKAGED
production_mutation_this_phase: NONE (no fabrication ; no leg-B SQL emitted)
audit_debt                    : 24h budget ; >23h remaining ; package +
                                next macro fits comfortably
recommended_next_macro        : single-shot "ledger-v2 author + execute"
                                using §§2-3 of this doc as the spec
gates_for_that_macro          :
  - G0..G2 identical shape (live state still ICX-CONST=60)
  - G3 NEW : sovereign approval of the row shapes in §2 (this doc)
  - G4 author cutter_agent/ledger_v2_canonical_cut.py + tests
  - G5 fake-conn green ; rollback-only smoke green
  - G6 execute single atomic txn ; capture FK ids
  - G7 verify_result write (gated on the new cut_change_set / review_decision rows)
  - G8 reports

doc 3 of 6.