dot-iu-cutter v0.4 — Canonicalization / Signing / Signal Integration Plan

document_path: knowledge/dev/laws/dieu44-trien-khai/v0.4-design/dot-iu-cutter-v0.4-canonicalization-signing-signal-integration-plan-2026-05-16.md
revision: r1
date: 2026-05-16
author: Agent (Claude Code CLI, Opus 4.7 1M)
phase: v0.4 — Tier 2 integration-placeholder DESIGN (companion to design-master)
status: design_only_pending_gpt_review

⛔ DESIGN ONLY. These are integration placeholders — interface contracts and reservation points, NOT implementations. No library is written, no key is generated, no signal source is wired, no harness is built.

---

§1 — Canonicalization Library Runtime (PLACEHOLDER)

purpose: resolve an IU reference to a stable canonical address + alias set
  used when populating manifest_unit_block and (later) canonical_address_alias.
v0.4_decision: canonical_address_alias is DEFERRED (OD-2). v0.4 flow neither
  reads nor writes aliases. The canonicalization runtime is a NAMED
  integration point with a frozen interface contract, not a v0.4 deliverable.
interface_contract (target, not built):
  resolve(iu_ref, scenario_ref) -> { canonical_address, unit_blocks[],
    content_hash } — pure, deterministic, side-effect-free; same input ⇒
    same output (required for IK-MARK / IK-REVIEW idempotency hashes).
constraints:
  - MUST be deterministic and versioned (a canon-lib version stamped into
    manifest_envelope body so a manifest is reproducible).
  - MUST NOT write any cutter_governance row itself (only the planned
    writer writes; the lib is a pure function consumed inside REVIEW).
risk: HIGH — alias resolution semantics are unsettled; improvising them
  inside v0.4 is FORBIDDEN. Owns its own future design→review chain.

§2 — Signing-Scheme Runtime (PLACEHOLDER)

purpose: produce/verify the executor (DOT-991) and verifier (DOT-992)
  dot_pair_signature rows.
v0.4_decision: signing scheme (algorithm, key custody, chaining proof) is
  DEFERRED to its own workstream. v0.4 reserves ONLY the integration shape.
interface_contract (target, not built):
  sign(lane, canonical_bytes, prior_signature_id) -> signature_row_fields
  verify(signature_row, canonical_bytes) -> bool
constraints:
  - executor and verifier lanes use DISTINCT keys (doc 5 §D-2).
  - prior_signature_id forms a per-lane hash chain; a broken chain ⇒
    invalid (tamper-evident lineage).
  - signatures cover a CANONICAL byte serialization of the artefact
    (depends on §1 determinism) — serialization spec is part of the
    deferred signing workstream, flagged so v0.4 does not freeze it wrongly.
risk: HIGH (cryptographic) — not to be hand-rolled in v0.4 flow code.

§3 — Signal Routing (PLACEHOLDER)

purpose: deliver external "this IU needs cutting" signals into MARK and
  drive the sweep cadence (decision_backlog_sweep_log).
v0.4_decision: the concrete upstream signal source/contract is a SEPARATE
  later design (OD-4). v0.4 fixes only the INGRESS shape and the sweep model.
ingress_contract (target, not built):
  a signal = { signal_source_id, iu_ref, scenario_ref, proposed_cut_spec };
  the router computes IK-MARK and calls MARK (idempotent).
sweep_model:
  - a periodic sweep pass scans promotable backlog states (S0→S1, S3→S1),
    writes one decision_backlog_sweep_log row per pass (cadence ledger).
  - cadence (interval, batch size, backoff) = config; not fixed here.
constraints: the router NEVER writes cutter_governance directly; it only
  invokes the planned MARK write path. No signal bus / queue is built in v0.4.
risk: STANDARD (interface), but the source contract is an OPEN dependency.

§4 — Dry-Run CUT/VERIFY Harness (PLACEHOLDER)

purpose: exercise the full MARK→REVIEW→CUT→VERIFY path against an ISOLATED
  ephemeral PG (the established dry-run env pattern), never production.
v0.4_decision: the harness is DESIGNED (shape below) but NOT built; building
  + running it is a later authorized cycle gated by GPT review of code.
harness_shape (target):
  - spin an isolated postgres:16 env restored from a sha-pinned prod backup
    (read-only pg_dump; never touch prod; tear down after).
  - run the four phases end-to-end on synthetic IUs; assert: row counts per
    table, FK integrity, signature-chain validity, idempotency (replay =
    no dup), state-machine legality (no forbidden transition), rollback
    path (induced VERIFY fail ⇒ compensating set + escalation entry).
  - structural / catalog-based assertions, schema-qualified (lesson from
    the P0-6/P0-5 false-negative: pg_get_constraintdef emits schema-
    qualified refs — comparisons MUST match or compare structurally).
constraints: prod read-only; env torn down; no prod CUT/VERIFY; harness
  itself reviewed before any dry-run run.
risk: STANDARD; the harness is the gate that de-risks first prod runtime.

§5 — Failure / Rollback Handling Integration

- DB-txn rollback (per-phase atomic) — write-path doc §6.
- semantic rollback = forward compensating cut_change_set referenced by
  verify_result.rollback_change_set_id_triggered (no physical delete).
- every failure that exhausts retry creates an escalation
  decision_backlog_entry (verify_result.escalation_ref) → tracked, sweepable.
- the dry-run harness MUST exercise an induced failure to prove the
  compensating + escalation path before any prod authorization.

§6 — Directus / PG Interface

- control plane = PostgreSQL (MODEL-C; Directus registration of
  cutter_governance DEFERRED — unchanged from v0.3).
- the cutter-agent talks DIRECTLY to PG as its writer principal; it does
  NOT go through the Directus API for cutter_governance writes.
- v0.4 proposes NO Directus collection/role/policy/permission/RLS change.
- if/when UI/API exposure of the governance ledger is wanted, that is a
  distinct future design→review→execution chain (Directus metadata + read
  policy), explicitly out of v0.4 scope.
- the v0.3 read-observability views remain the ONLY external read surface;
  the write path does not alter or depend on them.

§7 — Placeholder Status Summary

canonicalization_runtime : PLACEHOLDER, deferred, HIGH risk, own chain
signing_scheme_runtime   : PLACEHOLDER, deferred, HIGH risk (crypto), own chain
signal_routing           : PLACEHOLDER, ingress shape fixed, source = OD-4
dry_run_harness          : DESIGNED-not-built, gate before prod, STANDARD
failure_rollback         : integrated into flow/state-machine design
directus_pg_interface    : PG-direct, no Directus change, MODEL-C unchanged

End of v0.4 canonicalization/signing/signal integration plan (placeholders; nothing built).