dot-iu-cutter v0.5 — Leg-B Authoring & Local Test Result

doc 3 of 7 · 2026-05-20 · M1 macro

phase                : G3 — author ledger_v2 + fake-conn tests
outcome              : PASS — 21 / 21 unit tests green (0.010s) ; no DB
production_mutation  : NONE this phase

1. Authored module: cutter_agent/ledger_v2_canonical_cut.py

location_local : /Users/nmhuyen/iu-cutter-build/repo/iu-cutter/cutter_agent/
                 ledger_v2_canonical_cut.py
location_stage : /tmp/iu-cutter-v05-stage/cutter_agent/ledger_v2_canonical_cut.py
                 (on contabo ; staged for sidecar import)
sha256         : 3270f1df4d52890edcc04e34f8e7c4a58e98d98f7424dc9132d0c4cb108ce2e9
size           : ~520 lines (recorder + plan + _insert helper)
no_psycopg     : verified by AST scan in the unit test
                 (TestConstruction.test_module_does_not_import_psycopg).

1.1 Public surface

class LegBRecorder :
  __init__(*, signer=None)              # default StubSigning()
  plan(live_state) -> dict              # pure ; no DB ; row-builder + UUID gen
  record(conn, live_state) -> dict      # runs INSERTs inside caller-owned txn

exceptions :
  LegBLiveStateMismatch                 # bad live_state shape
  LegBAlreadyRecorded                   # G-LEG-B-ONCE refusal

1.2 Live-shape invariants enforced by plan()

live_state required keys (11) each length 60 :
  iu_ids, uv_ids, canonical_addresses, content_hashes, idempotency_keys,
  section_types, unit_kinds, identity_profiles, version_anchor_refs,
  content_anchor_refs, body_lengths

cross-row invariants :
  unit_kinds uniform 'law_unit'             (per cutwrite OD-W2)
  section_types cardinality NT15·KT3·DIEU42  (per cutwrite OD-W2 / live state)
  canonical_addresses all distinct (60)
  canonical_addresses all start with 'ICX-CONST/'
  content_hashes all distinct (60)

1.3 Insert order chosen by the recorder

order (forward consistency only ; no FK enforces it) :
  1. decision_backlog_entry        (entry_id ; kind='cut_request')
  2. decision_backlog_history      (entry_version_after='1' ; change_kind='cut_committed')
  3. manifest_envelope             (status='applied' ; cut_change_set_ref pre-generated)
  4. manifest_unit_block × 60      (PK (envelope_id, unit_local_id=address))
  5. review_decision               (verdict='approve' ; reviewer_class='sovereign')
  6. dot_pair_signature  (executor)(cross_reference_change_set_id set ; XOR check OK)
  7. cut_change_set                (state='committed' ; idempotency_key UNIQUE)
  8. cut_change_set_affected_row × 60

1.4 Key field values (selected)

cut_change_set :
  rollback_key      : rbk:canonical:constitution-first:d99a31d4a4be907c:<change_set_id>
  idempotency_key   : ick:canonical:constitution-first:<PIN_WRITER_DIGEST>
  manifest_version  : <PIN_WRITER_DIGEST>            (60-hex)
  state             : committed
  affected_unit_count : 60
  emitted_by        : cutter_exec/DOT-991/constitution-cut
  scenario_ref      : v0.5-first-controlled-canonical-cut

review_decision :
  governance_event_kind        : cut_first_controlled_canonical
  manifest_version             : <PIN_WRITER_DIGEST>
  review_scope                 : manifest
  reviewer_class               : sovereign
  reviewer_identity            : { reviewer:'GPT/User', kb_doc_id:<M1 ruling doc> }
  findings                     : { iu_count:60, anchored_exact:60,
                                    section_type:{principle:15,section:3,article:42},
                                    body_hash_match_60:60, … }
  decision_at                  : 2026-05-20T03:00:00+00:00
  cross_signed_by_dot_verifier : false

dot_pair_signature (executor) :
  signature_kind                  : executor
  signer_dot_id                   : DOT-991
  signer_tool_revision            : iu-cutter@f20c79c+canonical-A4-patch+autocommit-fix
  payload_envelope (canonical-JSON, sha256→payload_hash) :
    writer_digest, manifest_file_sha256, manifest_digest, region_sha256,
    source_version_id, candidate_count=60, docprefix='ICX-CONST',
    gateway_path='fn_iu_create', cut_committed_at, cut_started_at,
    executor_tool_revision, iu_ids_persisted (60), uv_ids_persisted (60),
    lane='DOT-991', is_production=false (StubSigning per D-4),
    signer_identity='stub-exec-identity'
  signature_payload                : <StubSigning sha256(lane|identity|digest|prior)>
  cross_reference_change_set_id    : <change_set_id>      (XOR satisfied)
  cross_reference_verify_result_id : NULL

2. Authored tests: tests/test_ledger_v2_canonical_cut.py

test_count      : 21
classes         : 5
  TestConstruction         (2)
  TestPinsAreRatified      (1)
  TestPlanValidation       (8)
  TestPlannedRowShape      (7)
  TestRecordEmits          (2)
  TestStubSigning          (1)

fake_conn       : FakeCursor + FakeConn that record (sql, params) ;
                  G-LEG-B-ONCE probe returns (0,) so record() proceeds.

verifications (selected) :
  · NO psycopg/psycopg2 import (AST scan)                            PASS
  · pins identical to prod_iu_adapter (writer_digest etc.)           PASS
  · plan() rejects missing key / wrong cardinality / wrong section
    type cardinality / non-law-unit / duplicate addresses /
    address prefix violation / duplicate content_hashes              PASS (×8)
  · cut_change_set NOT NULL no-default fields all populated          PASS
  · review_decision required-field invariants                        PASS
  · dot_pair_signature XOR cross-reference                           PASS
  · manifest_unit_block PK (envelope_id, unit_local_id) distinct     PASS
  · idempotency_key + rollback_key content-addressed to digest pin   PASS
  · payload_hash = sha256(canonical-JSON(payload_envelope))          PASS
  · record() emits exactly 1 SELECT + 126 INSERTs in dependency order PASS
  · record() refuses on idempotency_key collision                    PASS
  · StubSigning: payload_hash != signature_payload (lane-distinct)   PASS

run :
  $ python3 -m unittest tests.test_ledger_v2_canonical_cut -v
  Ran 21 tests in 0.010s — OK

3. Runner module: /tmp/cutter_legB_runner.py

authored      : in-session 2026-05-20 (sovereign-authored ephemeral artifact)
location      : /tmp/cutter_legB_runner.py (laptop)
                /tmp/cutter_legB_runner.py (contabo ; scp-staged)
sha256        : 964c85d14d668e2cd2446f35de54b08cb9ac9e4099f1dcc37f4440b7f2964de6

modes :
  --mode rollback-only-smoke   BEGIN ; recorder.record() ; ROLLBACK ; exit 0
  --mode commit                BEGIN ; recorder.record() ; COMMIT  ; exit 0

connection :
  psycopg2 ; DSN = host=127.0.0.1 port=5432 dbname=directus user=cutter_exec
  trust-auth via pg_hba 'host all all 127.0.0.1/32 trust' (works ONLY when
  the process shares the postgres container's network namespace ; same model
  as the leg-A provider).

execution :
  ssh contabo 'docker run --rm --network=container:postgres
                          -v /tmp/iu-cutter-v05-stage:/stage
                          -v /tmp/cutter_legB_runner.py:/runner.py:ro
                          -e CUTTER_AGENT_ROOT=/stage
                          agent-data-local:latest
                          python3 /runner.py --mode <smoke|commit>'

guards (pre-write) :
  G4 : connected user = cutter_exec        (raise on mismatch)
  G6 : G-LEG-B-ONCE — cut_change_set has 0 rows with the M1 idempotency_key
       (raise on collision ; refuses double-recording without rollback)
  G5 : read 60 IU + 60 UV anchored rows ; cardinality + distinct invariants

forbidden (per GPT M1 ruling — enforced by runner code) :
  · no lifecycle / source_document mutation
  · no deploy/restart/merge/tag
  · no SQL emitted outside the recorder body + G4/G5/G6 read-only probes

4. Disposition

G3 (local proof) : PASS — 21/21 ; no DB ; ratified pins ; live shape correct
production_mutation : NONE
next : G4 execution precheck (rollback-only smoke ; doc 4 §1)

doc 3 of 7.