dot-iu-cutter v0.5 — Existing Implementation Review

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

phase                : G2 — discover existing implementation
outcome              : PASS — author new ledger_v2_canonical_cut.py
                       (no existing committed-code path matches the live shape)
production_mutation  : NONE this phase

1. DISCOVER-FIRST inventory

laptop_repo : /Users/nmhuyen/iu-cutter-build/repo/iu-cutter
HEAD        : f20c79c   (per MEMORY ; the v0.5 feature branch)
untracked   :
  cutter_agent/prod_iu_adapter_canonical.py
  cutter_agent/cutprod_canonical.py
  tests/test_prod_iu_adapter_canonical.py

cutter_agent/* (tracked + untracked v0.5 files) :
  ledger.py                         (192 lines ; v0.4 dry-run SKELETON)
  signing.py                        (StubSigning + DeferredSigning + interface)
  prod_iu_adapter.py                (legacy direct-INSERT adapter ; PIN block)
  prod_iu_adapter_canonical.py      (canonical fn_iu_create adapter ; ratified)
  cutprod_canonical.py              (CLI wrapper for canonical adapter)
  cutwrite.py                       (pure factory ; writer_digest source)
  …

contabo_repo : /opt/incomex/dot   HEAD = e93424b (v0.4 BASELINE — NO v0.5 code)
  → the v0.5 canonical CUT was executed using LAPTOP code via sidecar.
  → leg-B must follow the same pattern (stage cutter_agent → run via sidecar).

2. Why cutter_agent.ledger.py cannot be reused as-is (GAP-B1 confirmed)

ledger.py.write_cut_change_set builds (6-key dict) :
  change_set_id, decision_backlog_entry_id, executor_signature_id,
  verifier_signature_id, manifest_id, content_hash

LIVE cut_change_set requires (NOT NULL no-default) :
  rollback_key, manifest_id, manifest_version, review_decision_id,
  executor_tool_revision, verifier_tool_revision, emitted_by

  ⇒ 6 NOT NULL no-default cols ABSENT in ledger.py dict.
  ⇒ 1 EXTRA col in ledger.py dict (`content_hash`) not in live shape.

Similar shape gaps exist for ledger.py.write_manifest_envelope (live needs
operation_kind/status/source_doc_ref/created_by ; skeleton has different
keys), .write_review_decision (live needs governance_event_kind,
manifest_id, manifest_version, review_scope, status, verdict, findings,
reviewer_class, reviewer_identity, risk_class_assessment, decision_at,
decided_by, version, created_at, updated_at — many missing in skeleton),
.write_signature (uses `lane` not `signature_kind` ; uses `payload_digest`
not `payload_hash` ; uses `placeholder_signature` not `signature_payload`),
.write_affected_row (uses `target_ref` not target_table+target_row_id, uses
`effect` not before/after_state_snapshot).
.write_verify_result (live verify_result needs many additional cols including
manifest_id, manifest_version, executor_tool_revision, verifier_tool_revision,
review_decision_id ; out of M1 scope).

Decision : ledger.py is the design-time skeleton and IS NOT a production-
shaped row-builder. M1 authors a NEW module that matches the live shape
exactly (no shape guessing).

3. Why StubSigning IS reused (D-4 ruling accepted)

signing.StubSigning :
  - emits a non-cryptographic, deterministic placeholder
  - enforces lane separation (DOT-991 vs DOT-992 distinct signer identity)
  - is the ratified contract in v0.4 + accepted for M1 per D-4
  - imports only stdlib (hashlib) — no key/secret/cred access

reuse : yes — the recorder constructs StubSigning() by default. The signer
        receives the canonical-JSON-bytes payload_envelope and produces a
        64-char hex `placeholder_signature` which is written verbatim into
        cutter_governance.dot_pair_signature.signature_payload.

upgrade_path : if a future ruling requires real cryptographic signing for
        the constitution-foundational record, the recorder can swap
        StubSigning for a real SigningInterface — the row shape does not
        change (signature_payload is text, payload_hash is text).

4. Why pinned identity IS reused unchanged

pinned_identity_block (re-used from cutter_agent.prod_iu_adapter) :
  PIN_WRITER_DIGEST        = d99a31d4a4be907c510ae15965e9f7bb3387e9e28676e9f32adf463828b1aa28
  PIN_MANIFEST_FILE_SHA    = 7d56f3ce066950ccef3de4156c5afeea81b2450b8e38393205b52c1fca012179
  PIN_MANIFEST_DIGEST      = 9d908a62fcf01bb88e05a1af4335b960710006ddcfd21c811ca63efb33dd324f
  PIN_REGION_SHA           = 17660443e0f23e994e1807cf8e22920951a9e70c598956dbd0e752f4f5cae80c
  PIN_SOURCE_VERSION       = icxconst-008a06ace23a96ea6cd456146e805c97
  PIN_CANDIDATE_COUNT      = 60

leg-B-specific pins (recorded inside ledger_v2_canonical_cut) :
  PIN_CUT_COMMITTED_AT     = 2026-05-20T04:18:21.854512+00:00
  PIN_CUT_STARTED_AT       = 2026-05-20T04:18:14+00:00
  PIN_EXECUTOR_TOOL_REV    = iu-cutter@f20c79c+canonical-A4-patch+autocommit-fix

The recorder asserts equality with the legacy prod_iu_adapter pin block at test time (TestPinsAreRatified.test_pins_match_prod_iu_adapter) — pin drift would fail-closed before any DB call.

5. Decision

G2 decision : AUTHOR new module cutter_agent/ledger_v2_canonical_cut.py
              (live-shape-correct ; reuses pinned identity + StubSigning ;
              no fabrication ; explicit per-table NOT NULL/UNIQUE/CHECK
              compliance ; INSERT order chosen for forward-consistency since
              cutter_governance has NO FK enforcement).

NOT reused as-is :
  cutter_agent.ledger.LedgerWriter     (shape mismatches live ; see §2)

Reused unchanged :
  cutter_agent.signing.StubSigning     (per D-4 ruling)
  cutter_agent.prod_iu_adapter.PIN_*   (writer_digest + manifest identity)

Authored fresh :
  cutter_agent/ledger_v2_canonical_cut.py
  tests/test_ledger_v2_canonical_cut.py   (21 unit tests ; see doc 3)
  /tmp/cutter_legB_runner.py             (sovereign-authored ephemeral runner
                                          ; see doc 4)

doc 2 of 7.