dot-iu-cutter v0.5 — Canonical Path Survey · Existing Codepath & Docs Review

doc 3 of 7 · 2026-05-20

phase             : S3 — existing code/docs review
outcome           : PASS — no cutter_agent fn_iu_create callers ; design+
                    closure docs fully read
production_mutation : NONE

1. Repo-side audit — cutter_agent/* and tests/*

$ grep -rn 'fn_iu_create\|fn_iu_apply_edit_draft\|canonical_writer\|app\.canonical_writer\|gateway' \
        cutter_agent/ tests/
cutter_agent/cutplan.py:12:   …no … fn_iu_create, or write …
cutter_agent/dryrun.py:12:    …no … fn_iu_create, or write Directus/vector …

The only matches are comments saying the dryrun/cutplan code does NOT call fn_iu_create. There is no live caller in any cutter_agent module. The ratified leg-A path was authored BEFORE Pack 22-P3-P2 rev7 (2026-05-06) and assumed direct INSERT into public.information_unit / public.unit_version.

2. VPS-side audit — /opt/incomex/dot/*

$ ssh contabo 'grep -rln "fn_iu_create\|canonical_writer" /opt/incomex/dot/'
(no matches)

The deployed iu-cutter working tree on the VPS (HEAD e93424b5, May 17 2026, an older snapshot pre-dating the production-leg-a-only mode authored in this session's f20c79c) also has no callers. The constitution CUT has NEVER actually executed via the canonical path before today.

3. KB design documents reviewed (FULL)

• knowledge/dev/laws/dieu44-trien-khai/design/22-dot-iu-create-wrapper-design.md (Pack 22 rev6, 2026-05-06) — Native Creation Contract :

  • Caller provides: canonical_address, title, body, actor (required) ; unit_kind, section_type, owner_ref, publication_type, parent_ref (optional with defaults).
  • System derives: IU id, UV id, content_hash, version_seq=1, identity_profile, anchors.
  • All adapters → same contract.
  • "Direct INSERT = non-canonical."
  • Confirms fn_iu_create returns from the existing function name set.

• knowledge/dev/laws/dieu44-trien-khai/design/22-p3-iu-creation-gateway-scope.md (Pack 22 P3, 2026-05-06) — 4-Layer Gateway design :

  • L0: Policy registry (dot_config entries) — implemented (§3 of doc 1)
  • L1: Permission gate — partially implemented (function-level EXECUTE only granted to directus ; cutter_exec NOT granted)
  • L2: Trigger guard — implemented (this session's trg_aa_iu_gateway_write_guard)
  • L3: Detector — not yet implemented (audit-trail safety net)
  • Explicitly addresses constitution-CUT-like cases under §4 TAC pipeline :

    "Option T2: TAC giữ direct INSERT nhưng với: exempt marker trong L2 trigger guard ; TAC tự verify invariants sau batch ; L3 detector chấp nhận TAC marker, không flag as incident."

  • Opus opinion records: "T2 (controlled import path) cho hiện tại, T3 cho dài hạn." — i.e. the design ANTICIPATES a controlled-import exemption path for bulk-content-import. The constitution snapshot CUT arguably fits this pattern, but no exemption is currently active (iu_create.gateway.exempt_policy = 'none_active').

• knowledge/dev/laws/dieu44-trien-khai/reports/22-pack-closure-iu-native-create-and-gateway.md (Pack 22 Closure, 2026-05-06) — Runtime state confirmed:

  • public.fn_iu_create(...) : Production, SECURITY DEFINER, canonical_writer marker
  • public.fn_iu_gateway_write_guard() : Production, SECURITY DEFINER, policy from dot_config
  • trg_aa_iu_gateway_write_guard : Enabled, BEFORE INSERT OR UPDATE on information_unit
  • trg_aa_uv_gateway_write_guard : Enabled, BEFORE INSERT OR UPDATE on unit_version
  • dot_config.iu_create.gateway.mode = 'enforced'
  • Deferred items include "Role separation" and "DOT wrapper" — i.e. the Pack-22 team anticipated that an external caller adapter (like our cutter_agent) would later be GRANTed EXECUTE on fn_iu_create. That grant has NOT yet been issued for cutter_exec (G3 surveyed function_acl = {directus=X/directus} for ALL fn_iu_* functions).

4. Implication for the redesign

The cutter_agent must add a NEW canonical-path code module that calls SELECT public.fn_iu_create(...) per row. None of the existing cutter_agent modules can be reused as-is, because:

• prod_iu_adapter.py emits direct INSERT statements (gateway-blocked).
• cutwrite.py produces an in-memory rowset — keeps unchanged ; the redesigned adapter MAPS that rowset to fn_iu_create's argument list.
• cutprod.py exposes the legacy modes only ; a NEW entrypoint module is needed.

This is exactly the "new module / parallel entrypoint" approach taken by the code authored in this session — see doc 5 (canonical-path-redesign).

5. Existing pilot rows in production (per Pack 22 closure)

"Pilot rows : 4 IU, 4 UV, 4 birth (P2 + P3-P1 + P3-P2 pilots, retained)"

So fn_iu_create has been exercised in production 4 times (pilot rows retained for audit). Confirms the canonical path is operationally exercised, not theoretical. The 60-row constitution CUT will be the first larger-scale exercise.

6. Disposition

S3                       : PASS — confirmed no callers in cutter_agent ; gap
                            anticipated by Pack 22 closure ("DOT wrapper deferred")
no_production_mutation   : confirmed
next                     : S4 — GRANT delta recommendation

doc 3 of 7.