dot-iu-cutter v0.5 — Write-VERIFY · Existing Implementation Review

doc 2 of 7 · 2026-05-20 · M2 macro

phase                : G2 — DISCOVER FIRST: is there a reusable VERIFY writer?
outcome              : reuse path BLOCKED — ledger.py is dry-run skeleton ;
                       no v0.4 VERIFY writer was ever committed against the
                       LIVE cutter_governance shape. Author ledger_v2_canonical_verify.py
                       on the same pattern as ledger_v2_canonical_cut.py (M1).
production_mutation  : NONE this phase (code authoring + AST scan)

1. DISCOVER FIRST — what already exists ?

1.1 In-repo (/Users/nmhuyen/iu-cutter-build/repo/iu-cutter, HEAD f20c79c)

cutter_agent/ :
  ledger.py                       v0.4 dry-run skeleton (192 LOC ; not used in M2)
                                  · `write_verify_result(...)` builds an
                                    incompatible 6-key dict not matching the
                                    live verify_result NOT NULL shape (26 cols).
                                  · skeleton-only; never ran against a real DB.
  ledger_v2_canonical_cut.py      M1 leg-B canonical writer (uncommitted ;
                                  authored 2026-05-20). Used as the structural
                                  TEMPLATE for ledger_v2_canonical_verify.py.
  signing.py                      StubSigning supports both DOT-991 and DOT-992
                                  lanes ; signer_identity:
                                     DOT-991 → 'stub-exec-identity'
                                     DOT-992 → 'stub-verify-identity'
  prod_iu_adapter.py / _canonical PIN_* (writer_digest, manifest_file_sha256,
                                  manifest_digest, source_version_id, etc.)
                                  reused for VERIFY findings + envelope.
  cutprod_canonical.py            production driver for leg-A ; NOT used in M2.

tests/test_ledger_v2_canonical_cut.py : 21 tests against M1 leg-B recorder.

1.2 On contabo (/opt/incomex/dot/specs, HEAD e93424b = v0.4 baseline)

v0.4 baseline does NOT contain a v0.5 VERIFY writer. The v0.4 trial verify_result
row (633f2c51-…) was inserted by the v0.4 cutter-agent flow on 2026-05-17
against the DRY-RUN governance schema, before the M1 canonical CUT. The
authoring code path for that v0.4 verify is NOT compatible with the
canonical-A4 / autocommit-fix runtime we used in M1.

1.3 Conclusion

ledger.py skeleton write_verify_result : INCOMPATIBLE with live 26-col shape.
v0.4 production-VERIFY writer            : not in the v0.4 branch we have.
canonical leg-B writer (ledger_v2)       : same author pattern → REUSE the
                                           module structure (LegBRecorder
                                           pattern → VerifyRecorder).

⇒ Author cutter_agent/ledger_v2_canonical_verify.py from scratch but structurally mirroring ledger_v2_canonical_cut.py: live-shape-aware, no psycopg import, plan()/record() seam, StubSigning per signing.py.

2. New module — design contract

file                     : cutter_agent/ledger_v2_canonical_verify.py
class                    : VerifyRecorder
  __init__(*, signer=StubSigning())
  plan(live_state) -> dict       # pure ; validates 14 invariants ; pre-gen UUIDs
  record(conn, live_state) -> dict
exceptions               :
  VerifyLiveStateMismatch        # bad live_state shape / cardinality / pins
  VerifyAlreadyRecorded          # G-VERIFY-ONCE refusal

required live_state keys (14) :
  change_set_id, review_decision_id, manifest_envelope_id, executor_signature_id,
  iu_count, uv_count, anchored_exact, distinct_canonical_address,
  distinct_content_hash, section_type_cardinality, dieu_44_intrusion,
  body_hash_match_60, lifecycle_uniform_draft, publication_type_uniform_law

pinned M1 ids that live_state MUST match (refuse otherwise) :
  change_set_id          = 456c6830-a747-4b53-ac2f-665e25e12cd0
  review_decision_id     = 29c88a7b-60f7-41bd-af45-43cc9b9f41c0
  manifest_envelope_id   = 638cf363-f45a-4bb3-b9bb-928c5e24c15b
  executor_signature_id  = 3a249063-e33a-406a-9302-2e9e646a0938

2.1 Tool revision (SoD invariant)

PIN_EXECUTOR_TOOL_REVISION : iu-cutter@f20c79c+canonical-A4-patch+autocommit-fix
                              (same string as M1 cut_change_set ; verify
                              records it for cross-reference)
PIN_VERIFIER_TOOL_REVISION : iu-cutter@f20c79c+write-verify-dot992-stub
                              (DISTINCT from executor revision ⇒ SoD)
tool_revision_match        : false   (invariant)

2.2 Insert order + FK reasoning

1. dot_pair_signature (verifier)
     signature_id = pre-generated  (no FK from anywhere requires it first
                                    EXCEPT verify_result.verifier_signature_id)
     cross_reference_verify_result_id = pre-generated verify_result_id
       (column has NO FK → safe to point ahead)
     cross_reference_change_set_id   = NULL    (XOR satisfied)
     prior_signature_id              = M1 executor signature_id
                                       (chains cross-lane provenance)

2. verify_result
     verifier_signature_id = signature_id from step 1 (FK satisfied)
     executor_signature_id = M1 executor signature_id (FK satisfied, row exists)
     change_set_id         = M1 change_set_id        (FK satisfied, row exists)

2.3 Signature payload_envelope (DOT-992)

canonical-JSON over :
  verify_result_id, change_set_id, review_decision_id, manifest_envelope_id,
  executor_signature_id, executor_payload_hash, writer_digest, manifest_digest,
  manifest_version (=writer_digest), source_version_id, candidate_count=60,
  docprefix='ICX-CONST', verifier_tool_revision, executor_tool_revision,
  tool_revision_match=false, verify_kind='axis_1_round_trip',
  verdict='pass', axis_1_status='pass', axis_1_drift_count=0,
  axis_2_status='pass', findings_summary{60/60/60/…}, lane='DOT-992',
  is_production=false, signer_identity='stub-verify-identity',
  canonicalization_rule_used='canon-md-v0.1.0'

payload_hash = sha256(canonical_json(payload_envelope))
signature_payload = StubSigning.sign(DOT-992, envelope_bytes, prior=M1 executor sig).placeholder_signature

2.4 G-VERIFY-ONCE

probe : SELECT count(*) FROM cutter_governance.verify_result
        WHERE change_set_id = '456c6830-…'
expected : 0 before commit ; 1 after commit
on collision : raise VerifyAlreadyRecorded (refuse to fabricate or re-write).

3. Disposition

G2 (existing-impl review + new module design) : PASS
  · DISCOVER-FIRST inventory                    : done (ledger.py incompatible)
  · new module + tests authored                 : done (see doc 3)
  · structural template                         : ledger_v2_canonical_cut.py (M1)
  · DOT-992 StubSigning identity                : 'stub-verify-identity'
production_mutation                            : NONE
next                                            : G3 local fake-conn tests (doc 3)

doc 2 of 7.