dot-iu-cutter v0.5 — Canonical Path Survey · Redesign

doc 5 of 7 · 2026-05-20

phase             : S5 — canonical-path code redesign + local tests
outcome           : REDESIGN_READY  (3 new files ; 27/27 PASS + 122/122 PASS regression)
production_mutation : NONE (no commit ; no push ; ratified files untouched)

1. Files authored (new — feature branch only, NOT committed in this macro)

cutter_agent/prod_iu_adapter_canonical.py   : NEW (~10 KB)
cutter_agent/cutprod_canonical.py           : NEW (~7  KB)
tests/test_prod_iu_adapter_canonical.py     : NEW (~13 KB)

UNCHANGED ratified files (sha re-verified equal to rerun macro post-G5) :
  cutter_agent/cutprod.py
  cutter_agent/prod_iu_adapter.py
  cutter_agent/cutwrite.py
  cutter_agent/cutplan.py
  cutter_agent/dryrun.py
  tests/test_prod_iu_adapter.py
  tests/test_cutwrite_snapshot.py
  tests/test_dryrun_snapshot_mark.py
  tests/test_cutplan_snapshot.py

2. prod_iu_adapter_canonical.ProdIuBirthAdapterCanonical

Mirrors ProdIuBirthAdapter's public surface (G1..G7 + single atomic txn) so cutprod_canonical can compose it against the same argv shape. Renamed body method to leg_a_in_txn_canonical to prevent silent mixing with the legacy direct-INSERT body.

construction              : never connects ; default provider RAISES
                            ProductionAccessNotAuthorized
no_psycopg_at_module_load : enforced (AST test asserts no `import psycopg*`)
pinned_identity_reuse     : imports PIN_* from prod_iu_adapter (single
                            source of truth ; cutwrite digest preserved)
canonical_fn              : public.fn_iu_create(text,text,text,text,text,
                            text,text,text,uuid)  -- per dot_config policy
canonical_writer_marker   : 'fn_iu_create' (the function sets it itself)
allowlisted SQL only      :
  SELECT current_user
  SELECT count(*) FROM public.information_unit WHERE canonical_address LIKE 'ICX-CONST%'
  <drift catalog probe>  (read-only)
  BEGIN
  SELECT public.fn_iu_create(%s, %s, %s, %s, %s, %s, %s, %s, %s)   × 60
  COMMIT  (or ROLLBACK on any failure)
no_raw_INSERT/UPDATE      : enforced by adapter — only SELECT and the
                            canonical function call ; verified by
                            `test_only_safe_sql_emitted`

2.1 Argument mapping (cutwrite row → fn_iu_create args)

addr             = iu["canonical_address"]
title            = iu["identity_profile"]["title"]   # required by L1; cutwrite asserts non-empty
body             = uv["body"]
actor            = "cutter_exec/DOT-991/constitution-cut"
unit_kind        = iu["unit_kind"]                   # "law_unit"
section_type     = iu["section_type"]                # principle | section | article
owner_ref        = iu.get("owner_ref")
publication_type = None                              # cutwrite doesn't carry one
parent_ref       = iu.get("parent_or_container_ref") # NULL for top-level

2.2 Per-call success assertion

fn_iu_create returns jsonb with status :
  'created'                 → counted (expected on fresh G-CUT-ONCE-clean addresses)
  'exists_complete'         → RAISES CanonicalCallFailed (G6 already proved no pre-existence)
  any other status          → RAISES CanonicalCallFailed (health/remediation)

content_hash equivalence assertion :
  res['content_hash']  ==  uv['content_hash']   ELSE RAISE
  ⇒ proves the body bytes that reach the DB are byte-identical to the cutwrite-emitted body

2.3 Writer-digest equivalence proof

The writer_digest is content-addressed over [canonical_address, unit_kind, section_type, content_hash, idempotency_key] per row (cutwrite.build_rows line 337-340).

The canonical adapter PRESERVES all five elements:

element	preserved?	how
canonical_address	YES	passed through as p_canonical_address
unit_kind	YES	passed through as p_unit_kind
section_type	YES	passed through as p_section_type
content_hash	YES	fn_content_hash = sha256_hex(body) = cutwrite._sha(body)
idempotency_key	YES	computed by cutwrite from the above three; unchanged

Therefore writer_digest equivalence holds end-to-end. The pinned PIN_WRITER_DIGEST = d99a31d4… continues to validate (cutwrite still produces it from the same manifest input ; the canonical adapter asserts it before opening the txn).

3. cutprod_canonical.main()

Same argv shape as cutprod (R1 production-leg-a-only) except :

• --mode production-leg-a-only-canonical (REPLACES the legacy mode)
• --production-intent CONFIRM-LEG-A-ONLY-CONSTITUTION-CUT-CANONICAL (literal)
• All other flags identical (manifest pins, sovereign approval, GRANT approval id, fresh backup sha, connection-provider-module, etc.)

Success line :

CUT_OK_LEG_A_CANONICAL iu_created=60 uv_created=60 anchor_updates=60
writer_digest=d99a31d4… txn=COMMITTED
leg_b=DEFERRED_TO_POST_CUT_GOVERNED_RECORDING_PACKAGE
canonical_fn=public.fn_iu_create
approval_id=<kb> grant_approval_id=<kb> backup_sha=<64-hex>

4. Test results

python3 -m unittest tests.test_prod_iu_adapter_canonical
Ran 27 tests in 0.014s
OK

python3 -m unittest tests.test_prod_iu_adapter tests.test_cutwrite_snapshot
                    tests.test_dryrun_snapshot_mark tests.test_cutplan_snapshot
                    tests.test_prod_iu_adapter_canonical
Ran 122 tests in 0.147s
OK

Test breakdown (27 new) :

• TestNoConnectGuarantees (3) : default provider refuses ; construction never connects ; no import psycopg* at module load (AST scan)
• TestPinsAreRatified (2) : PIN_* re-exported byte-identical from prod_iu_adapter ; canonical_fn qname matches dot_config policy
• TestPreConnectGuards (5) : G1 absent/false approval, G2/G3 rowset PIN match, G7 backup gate false
• TestConnectedGuards (4) : G4 principal mismatch + correct, G6 G-CUT-ONCE non-zero + zero
• TestLegAInTxnCanonical (4) : happy path → 60 fn_iu_create calls ; argv shape (text,text,text,text,text,text,text,text,uuid) ; non-'created' status raises ; content_hash mismatch raises ; only safe SQL emitted
• TestExecuteLegAOnlyCanonical (1) : end-to-end fake-conn run commits with canonical_fn = 'public.fn_iu_create'
• TestCutprodCanonicalCli (8) : missing approval/intent/backup/provider → exit 2 ; wrong mode / wrong writer_digest → exit 2 ; bad provider spec → exit 3 ; PGPASSWORD env guard → exit 2 ; happy CLI not in test scope

5. Equivalence vs the legacy direct-INSERT path

dimension	direct (cutprod legacy)	canonical (cutprod_canonical)
writer_digest	preserves PIN	preserves PIN (equivalence proof §2.3)
60 IU + 60 UV + 60 anchor	direct INSERT/UPDATE × 180 stmts	SELECT fn_iu_create(...) × 60
atomic txn	one (BEGIN…COMMIT)	one (BEGIN…COMMIT)
G1..G7 guards	identical	identical (re-exported pins)
persisted lifecycle_status	'enacted' (cutwrite OD-W8)	'draft' (column DEFAULT)
persisted doc_code	'ICX-CONST'	NULL
persisted section_code	per cutwrite	NULL
persisted section_type column	per cutwrite	NULL (value in identity_profile)
persisted identity_profile JSON	rich	minimal (3-4 keys)
ids	deterministic per cutwrite	gen_random_uuid()
gateway compatibility	BLOCKED by trg_aa_iu_gateway_write_guard	PASSES (function sets marker)
birth_registry side-effect	trig fires once per direct INSERT	trig fires once per canonical INSERT

6. Gaps surfaced for sovereign ruling

G-A : lifecycle_status persisted as 'draft', not 'enacted'.
  Effect : downstream queries `WHERE lifecycle_status='enacted'` would
           NOT match the constitution rows. The 60 enacted laws would be
           silently invisible to enacted-only filters until a separate
           enactment workflow runs.
  Resolution paths (sovereign choice) :
    (A1) Accept drafts ; design a separate enactment workflow later (out
         of cutter_agent scope).
    (A2) Request DB team to extend fn_iu_create with p_lifecycle_status
         (or add fn_iu_enact). Out of cutter_agent scope.
    (A3) Request a controlled-exemption marker per Pack 22 design §4 T2
         and re-enable the legacy direct path under sovereign exemption.
         Conflicts with the GPT 2026-05-20 ruling rejecting OPT-B
         (bypass) — but a documented "controlled import" is architecturally
         distinct (per the design doc).

G-B : doc_code / section_code / section_type column NULL.
  Effect : depends on downstream consumers. `canonical_address` itself
           still contains the prefix `'ICX-CONST/'` and the section_code
           in its trailing path segment, so address-based filtering still
           works. `identity_profile->>'primary_section_type_ref'` still
           carries section_type.
  Resolution : usually acceptable since the dedicated columns are
               redundant with canonical_address + identity_profile. Mark
               as ACCEPTABLE pending downstream-query audit.

G-C : ids server-generated (not deterministic).
  Effect : cutwrite's deterministic id assignment is for offline
           bookkeeping (writer_digest does NOT include id). Downstream
           references use canonical_address, not id, by convention.
  Resolution : ACCEPTABLE.

G-D : L1 PILOT-ONLY warnings for P-pub1 / P-pub2.
  Effect : the rollback-only test produced warnings about future strict
           L1 mode blocking on missing publication metadata. Today's L1
           is permissive ; this does NOT block the CUT. But the next
           strict-L1 release would.
  Resolution : pass `p_publication_type='law'` in the canonical adapter
               (cutwrite has it implicitly via doc_code='ICX-CONST' →
               publication_type='law'). The current code does NOT pass
               it ; should be added as a defensive update. ⇒ recommend
               a small follow-up patch to set
               `publication_type = 'law'` for ICX-CONST rows.

7. Disposition

S5                          : REDESIGN_READY  (code authored + tests green +
                              regression clean ; NOT committed)
production_mutation         : NONE
sovereign_gates_remaining   : doc 4 GRANT delta approval +
                              doc 6 production CUT approval (canonical) +
                              ruling on G-A / G-B / G-C / G-D gaps

doc 5 of 7.