dot-iu-cutter v0.5 — Lifecycle Enactment Design · Existing Docs & Code Review

doc 2 of 6 · 2026-05-20 · DISCOVER-FIRST READ-ONLY

phase             : G2 — existing lifecycle docs/code discovery
outcome           : PASS — prior assessment + Pack 22 + tac vocab found;
                    NO existing fn_iu_enact / lifecycle adapter
production_mutation : NONE

0. Discover scope

DISCOVER-FIRST: before authoring a new design, exhaustively check KB + production code for any existing lifecycle/enactment infrastructure that the design must build on (or avoid duplicating). Sources covered:

knowledge/dev/laws/dieu44-trien-khai/ (Điều 44 + cutter pipeline)
knowledge/dev/laws/dieu38-trien-khai/ (TAC parent pipeline; seed-G6 vocab)
knowledge/dev/laws/dieu35-trien-khai/ (Điều 35 logical-unit lineage)
KB review docs for v0.5 main-FF merge / write-VERIFY / canonical-CUT closeouts
Pack 22 design + report + readme
cutter_agent code (repo + KB references)

1. Prior lifecycle assessment — `doc 4 of 6` in v0.5-post-cut-verify-governed-recording-release-readiness

Source: knowledge/dev/laws/dieu44-trien-khai/v0.5-post-cut-verify-governed-recording-release-readiness/dot-iu-cutter-v0.5-04-lifecycle-enactment-assessment-2026-05-20.md

Status: REPORT-ONLY · 6,897 chars · doc 4 of 6 in prior bundle · OUR DIRECT PREDECESSOR.

1.1 What the prior assessment delivered

Three sovereign architectural options surfaced (verbatim):

OPT-E1 (RECOMMENDED): extend canonical with fn_iu_enact
  signature_proposed : public.fn_iu_enact(
                         p_canonical_address text,
                         p_actor text,
                         p_review_decision_id uuid)
  semantics_proposed : SECURITY DEFINER ; sets app.canonical_writer marker
                       (new allowed value e.g. 'fn_iu_enact' added to policy) ;
                       UPDATEs lifecycle_status='draft' → 'enacted' ;
                       runs fn_law_enacted_must_have_* invariant precheck ;
                       emits audit record into cutter_governance (new
                       manifest_envelope OR decision_backlog event).
  estimated_complexity : moderate
  suitability_for_60_ICX_CONST : excellent ; one call per IU
                                  (or bulk fn_iu_enact_batch)
  cutter_agent_integration : add cutter_agent/lifecycle_enact_adapter.py
                              that loops fn_iu_enact() over 60 addresses

OPT-E2 (NOT RECOMMENDED): drafts ARE the constitution
  scope : downstream consumers query by canonical_address pattern,
          not lifecycle_status. The 60 IUs remain 'draft' deliberately.
  trade_off : weaker semantic invariant ; any
              `lifecycle_status='enacted'` filter misses constitution.

OPT-E3 (NOT RECOMMENDED): one-shot exemption marker
  scope : workflow_admin sets exemption value accepted by gateway trigger ;
          issues UPDATE ; removes marker afterwards.
  risk  : sets precedent for ad-hoc exemptions ; Pack 22-P3 explicitly
          warns against "permanent back doors".

1.2 What the prior assessment EXPLICITLY left for the next macro

NOT addressed by prior assessment :
  - finalized fn_iu_enact function body (only signature proposed)
  - idempotency strategy (if already enacted, what?)
  - rollback / compensation procedure
  - role/grant matrix (only "role grant" listed as a dep)
  - batch-vs-single API decision
  - governance-link record schema (only "manifest_envelope OR
    decision_backlog event" sketched)
  - vocab decision (only 'draft' and 'enacted' mentioned;
    no superseded/retired)
  - L1 birth-gate P-pub1/P-pub2 interaction
  - fn_iu_apply_edit_draft global-coupling side-effect (not surfaced)
  - audit log table location (new vs reuse vs cutter_governance link)

Sovereign disposition (verbatim):
  "surfaced for sovereign architectural decision in a SEPARATE
   macro/cycle. Out of scope here."

⇒ This is the macro that fills those gaps. The present design package extends OPT-E1 from a single-signature sketch to a full, executable contract.

2. Pack 22 — IU Creation Gateway (CLOSED 2026-05-06)

Sources:

knowledge/dev/laws/dieu44-trien-khai/reports/22-pack-closure-iu-native-create-and-gateway.md (closure)
knowledge/dev/laws/dieu44-trien-khai/readme/iu-create-gateway-readme.md (operator-facing rules)
knowledge/dev/laws/dieu44-trien-khai/design/22-p3-iu-creation-gateway-scope.md (scope design)

2.1 Closure status (verbatim, slightly compressed)

Pack 22 — IU Native Create + Gateway : COMPLETE
phases:
  P1     : 5 helper functions (preflight, verify_invariants, classify_existing,
            resolve_default, content_hash)
  P2     : fn_iu_create (complete-or-nothing) + fn_iu_create_plan (dry-run)
  P3-P0  : Read-only inspection (51 queries)
  P3-P1  : 9 policy keys + canonical_writer marker patch
  P3-P2  : Trigger guard ENFORCED on IU + UV
  README : Gateway README published
runtime_state:
  trg_aa_iu_gateway_write_guard         : enabled (BEFORE INSERT OR UPDATE)
  trg_aa_uv_gateway_write_guard         : enabled (BEFORE INSERT OR UPDATE)
  iu_create.gateway.mode                : 'enforced'
deferred (NOT in scope):
  L3 Detector              : when scale demands
  Role separation          : when Directus dependency allows
  DOT wrapper              : when needed to standardize callers
  system_health_checks     : when health infrastructure refreshes

2.2 README rules — non-negotiable doctrine

Verbatim from readme/iu-create-gateway-readme.md:

KHÔNG direct INSERT hoặc UPDATE vào public.information_unit hoặc public.unit_version.

Mọi IU mới phải đi qua canonical path: fn_iu_create_plan → fn_iu_create.

"Không tự SET app.canonical_writer = 'fn_iu_create' rồi INSERT — marker là speed bump chặn lỗi vô ý, không phải cơ chế cấp quyền. Tự set marker = bypass có chủ đích, sẽ bị detector phát hiện."

2.3 Scope design — exempt-mechanism policy (Opus strong opinion, verbatim)

"Exempt mechanism: migration role có thể SET app.canonical_writer = 'migration:<ticket_id>' — trigger chấp nhận prefix migration: ngoài fn_iu_create. Hoặc dùng SET app.canonical_writer_exempt = 'true' với audit log.

Opus strong opinion: Exempt list phải hẹp và mỗi exempt phải có lý do + expiry. Không tạo 'cửa hậu vĩnh viễn'. Exempt cho migration = OK. Exempt cho 'tiện' = KHÔNG."

⇒ Adding a new specific canonical writer (fn_iu_enact) is on-doctrine. Adding a generic exemption marker is OFF-doctrine and is what makes OPT-E3 the explicit anti-pattern in the prior assessment.

2.4 Pack 22 implication for fn_iu_enact

A new canonical writer requires:

1. Author the SECDEF function (fn_iu_enact) owned by directus
2. UPDATE one row in public.dot_config :
   key='iu_create.gateway.allowed_marker_values'
   value: from 'fn_iu_create,fn_iu_apply_edit_draft'
       to 'fn_iu_create,fn_iu_apply_edit_draft,fn_iu_enact'
3. GRANT EXECUTE ON FUNCTION public.fn_iu_enact(...) TO cutter_exec
4. (Optional) seed iu_enact.* dot_config keys for self-description
   (mirroring iu_create.gateway.* family)
5. Update gateway README to mention fn_iu_enact lifecycle path

⇒ No DDL trigger surgery. No relaxation of the guard. No exempt marker. The design composes onto the existing Pack 22 enforcement; it does not weaken it.

3. TAC seed-G6 vocab — `{draft, enacted, superseded, retired}` is canonical

Source: knowledge/dev/laws/dieu38-trien-khai/seed-g6/seed-tac-uv-lifecycle.sql

Verbatim INSERT (one row per state):

INSERT INTO p9_g6_dryrun.tac_uv_lifecycle_vocab (code, name, description, sort_order) VALUES
    ('draft',      'Bản nháp',     'Mới tạo, chưa approve, sửa tại chỗ',         10),
    ('enacted',    'Đã ban hành',  'Approve qua change-set + APR. Bất biến.',     20),
    ('superseded', 'Bị thay',      'Bị version mới enacted thay. Giữ audit.',     30),
    ('retired',    'Đã rút',       'Quyết định retire qua change-set + APR.',     40);

tac_uv_lifecycle_vocab is mirrored LIVE in public.tac_uv_lifecycle_vocab (4 rows, identical) — confirmed by the G1 live survey.

⇒ For IU domain, the vocab decision is DERIVED, not invented: adopt the same 4-state set verbatim. This is the canonical name pattern across TAC; reusing it preserves cross-domain semantic uniformity. Logical-unit-level vocab ({active, draft_only, retired}) is parallel but DIFFERENT — IU sits at the unit-version-of-content level, not the logical-unit level.

4. cutter_agent code — NO callers of any lifecycle path

Source: knowledge/dev/laws/dieu44-trien-khai/v0.5-fn-iu-create-canonical-path-survey-and-redesign/dot-iu-cutter-v0.5-03-existing-codepath-and-docs-review-2026-05-20.md (S3 doc, prior survey)

cutter_agent code surface (as of feature branch HEAD 32cfa93):
  prod_iu_adapter_canonical.py        : calls fn_iu_create (canonical-path adapter)
  cutprod_canonical.py                : CLI entry for canonical CUT
  ledger_v2_canonical_cut.py          : leg-B governed recording (cutter_governance writes)
  ledger_v2_canonical_verify.py       : M2 write-VERIFY (verify_result + dot_pair_signature)
  prod_iu_adapter.py (v0.4)           : pre-canonical adapter (still on tree)
  ledger.py (v0.4 dry-run skeleton)   : NOT canonical for leg-B (per memory CD-A4)

callers of any draft→enacted transition : ZERO
callers of fn_iu_apply_edit_draft       : ZERO (in cutter_agent;
                                          a Directus flow may call it server-side
                                          but that is outside repo scope)
lifecycle_enact_adapter.py              : DOES NOT EXIST
fn_iu_enact_batch_runner                : DOES NOT EXIST

⇒ There is no existing cutter_agent caller to integrate with. A NEW adapter module must be authored — cutter_agent/lifecycle_enact_adapter.py (or similar) is greenfield.

5. Dieu44 Pack 22 + Pack 22-P3 doc cluster — supplementary findings

The full Pack 22 doc cluster, beyond the closure + readme + scope, also contains:

prompts/22-p3-p1-iu-gateway-policy-and-canonical-marker-prompt.md (rev6) — the seeding prompt for the 9 dot_config keys. Our fn_iu_enact seed will use the same INSERT…ON CONFLICT pattern.
reports/22-p3-p1-iu-gateway-policy-and-canonical-marker-report.md — confirms the 9 keys live.
reports/22-p3-p2-iu-gateway-trigger-guard-report.md — confirms trg_aa_iu_gateway_write_guard + trg_aa_uv_gateway_write_guard enforced.
reports/22-p2-iu-native-create-main-functions-report.md — fn_iu_create production-shipped report.
design/p3d-pack1-iu-canonical-contract-and-tac-iu-reconciliation-design.md — TAC↔IU schema reconciliation; confirms unit_version.enacted_at exists by design intent.

None of these documents define an enactment function or workflow. Pack 22 stops at "the gateway exists"; enactment is genuinely net-new.

6. CUT-pipeline closeout docs — confirm 60 IUs in `'draft'`, governance linked

Sources (read 2026-05-20 + 2026-05-20):

reviews/dot-iu-cutter-v0.5-first-controlled-canonical-cut-pass-gpt-ruling-2026-05-20.md — confirms 60 ICX-CONST IUs born in 'draft' deliberately, A-3 ruling accepted.
reviews/dot-iu-cutter-v0.5-write-verify-dot992-pass-gpt-ruling-2026-05-20.md — confirms write-VERIFY persisted 2 rows in cutter_governance, lifecycle still draft uniform.
reviews/dot-iu-cutter-v0.5-main-fast-forward-merge-pass-gpt-ruling-2026-05-20.md — confirms M4-FF merged, M3 lifecycle is the NEXT recommended xhigh macro.
v0.5-post-cut-verify-governed-recording-release-readiness/dot-iu-cutter-v0.5-04-lifecycle-enactment-assessment-2026-05-20.md — see §1 above.

Linked governance row IDs that the new fn_iu_enact must be able to reference (verbatim from M2 write-VERIFY ruling):

change_set_id          : 456c6830-a747-4b53-ac2f-665e25e12cd0
review_decision_id     : 29c88a7b-60f7-41bd-af45-43cc9b9f41c0  -- the GPT/User ruling on the CUT
manifest_envelope_id   : 638cf363-f45a-4bb3-b9bb-928c5e24c15b
executor_signature_id  : 3a249063-e33a-406a-9302-2e9e646a0938
verify_result_id       : 18278460-438c-4fb4-bf9c-997c82447f92
verifier_signature_id  : f5c3ee34-7f9f-4af3-879d-1bdcf5508a8f

The enactment will need ITS OWN review_decision (because the CUT review_decision approved CREATION, not ENACTMENT — distinct sovereign acts). Design surfaces this as OQ-5.

7. Cross-domain lifecycle templates available for reuse

Source artifact	What we adopt	Adjustment for IU
`tac_uv_lifecycle_vocab` rows (4-state)	Vocab codes + names verbatim	Mirror as `public.iu_lifecycle_vocab`
`fn_tac_enacted_immut` body	Immutability check shape for UV	Re-author as `fn_uv_enacted_immut`
`fn_law_enacted_immutable` shape	Immutability check for IU-level	Re-author as `fn_iu_enacted_immut` (IU has fewer "content" fields than law)
`fn_nrm_enacted_must_have_approval`	"must have approval" pattern	Become `IF p_review_decision_id IS NULL THEN RAISE` inside fn_iu_enact body
`lifecycle_log` integer-key schema	Column SHAPE (entity_collection, from/to_status, transition_type, reason, performed_by, performed_at, metadata)	UUID-key version: new `iu_lifecycle_log`
`fn_iu_create` SECDEF marker pattern	`set_config('app.canonical_writer', '<fn_name>', true)`	Identical pattern, value `'fn_iu_enact'`
Pack 22-P3-P1 seed prompt pattern	`INSERT … ON CONFLICT (key) DO UPDATE`	Same idempotent seed style for `iu_enact.*` keys
`fn_iu_verify_invariants(p_addr)`	Precondition probe	Called inside fn_iu_enact before UPDATE

⇒ The design is largely composition of existing patterns, not invention. This is the strongest argument for OPT-E1 over OPT-E2/E3.

8. Discovery summary — what exists, what's missing

EXISTS in production today:
  - Gateway: trg_aa_iu_gateway_write_guard + trg_aa_uv_gateway_write_guard
  - Canonical writers: fn_iu_create, fn_iu_apply_edit_draft (only INSERT-side
    or edit-side; no enactment)
  - Vocab pattern: tac_uv_lifecycle_vocab live with 4 states
  - Immutability templates: fn_law_enacted_immutable, fn_tac_enacted_immut,
    fn_nrm_enacted_immutable
  - Generic transition function: fn_transition_lifecycle (INTEGER-keyed,
    NOT reusable for IU)
  - Audit log skeleton: public.lifecycle_log (INTEGER-keyed, NOT reusable)
  - Governance backbone: cutter_governance schema with cut_change_set,
    review_decision, manifest_envelope, dot_pair_signature, verify_result

EXISTS in KB documentation:
  - Prior assessment (3 OPTs surfaced; OPT-E1 recommended; signature sketch)
  - Pack 22 design + closure (gateway doctrine)
  - TAC seed-G6 vocab (4-state canonical)
  - CUT pipeline closeouts (governance IDs linked to the 60-IU CUT)

DOES NOT EXIST (this design fills):
  - fn_iu_enact function (any signature)
  - public.iu_lifecycle_vocab table
  - public.iu_lifecycle_log table (UUID-keyed)
  - trg_iu_enacted_immut + fn_iu_enacted_immut (IU-level immutability)
  - trg_uv_enacted_immut + fn_uv_enacted_immut (UV-level immutability for
    public.unit_version — currently only tac_unit_version has its analog)
  - cutter_agent/lifecycle_enact_adapter.py
  - dot_config iu_enact.* policy keys
  - Operator README for enactment workflow
  - Compensation/retire/supersede path design (this scope: design;
    later: implement)

OPEN COUPLINGS (must be resolved in design):
  - fn_iu_apply_edit_draft global "uniform lifecycle_status" check
    (see G1 §6.1) — breaks the moment any UV becomes 'enacted'.

9. G2 disposition

G2_existing_docs_code_discovery : PASS
production_mutation              : NONE
recommendation_after_discovery   : OPT-E1 confirmed as the only on-doctrine
                                    path; no existing function to repurpose
next                              : G3 — design options analysis
                                    (see [[dot-iu-cutter-v0-5-03-design-options-analysis-2026-05-20]])