dot-iu-cutter v0.4 — Runtime State Machine Design

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

⛔ DESIGN ONLY. The states/transitions below are a target model carried on decision_backlog_entry.status (text; BATCH-1 documented allowed values; NO PG enum). Nothing here is created or executed.

---

§1 — State Set (decision_backlog_entry.status; text, documented)

S0  marked                  : MARK committed; awaiting promotion
S1  review_pending          : sweep promoted; awaiting reviewer authority
S2  reviewed_approved       : REVIEW approve; manifest bound; CUT-eligible
S3  reviewed_deferred       : REVIEW defer; re-enters backlog
S4  reviewed_rejected       : REVIEW reject; TERMINAL (no CUT)
S5  cut_in_progress         : TXN-CUT in flight (transient; guarded)
S6  cut_applied             : CUT committed + executor-signed; VERIFY-eligible
S7  verify_in_progress      : TXN-VERIFY in flight (transient; guarded)
S8  verified_complete       : VERIFY pass; TERMINAL SUCCESS
S9  verify_failed_escalated : VERIFY fail; compensating set + escalation entry; MANUAL
S10 abandoned               : manual sovereign/GPT decision; TERMINAL
note: S5/S7 are short-lived in-txn markers; if a process dies mid-txn the
  PG transaction aborts and the row never reaches S5/S7 (it stays at the
  prior committed state) — so S5/S7 are recovery-safe by construction.

§2 — Allowed Transitions

∅   → S0   : MARK (TXN-MARK)
S0  → S1   : sweep promotion (decision_backlog_sweep_log row)
S1  → S2   : REVIEW approve
S1  → S3   : REVIEW defer
S1  → S4   : REVIEW reject  (TERMINAL)
S3  → S1   : sweep re-promotion of a deferred entry
S2  → S5   : CUT start (guarded G-CUT-APPROVED, G-CUT-DEPS, G-CUT-ONCE)
S5  → S6   : CUT commit (executor-signed)
S6  → S7   : VERIFY start (guarded G-VERIFY-CUT, G-VERIFY-SOD)
S7  → S8   : VERIFY pass   (TERMINAL SUCCESS)
S7  → S9   : VERIFY fail   (compensating + escalation; MANUAL)
S9  → S1   : manual/GPT re-queue of the ESCALATION entry (a NEW entry's own
             lifecycle; the failed entry itself stays at S9 as the record)
S2  → S3   : reviewer-authority re-defer before CUT (optional, append review_decision)
any → S10  : explicit sovereign/GPT abandon (records reason in history)

§3 — Forbidden Transitions (hard invariants)

F-1  S4  → anything (except S10 abandon bookkeeping) : reject is terminal
F-2  S8  → anything (except S10)                     : success is terminal
F-3  S0/S1/S3 → S5/S6                                : no CUT without approve (S2)
F-4  S2  → S7/S8                                     : no VERIFY without CUT (S6)
F-5  S6  → S6                                        : no second CUT on same
        (entry, approved review_decision) — re-cut requires a NEW superseding
        review_decision and a NEW change set; never a silent re-apply
F-6  any → S0 via cutter_ro                          : cutter_ro never writes
F-7  S9  → S8                                        : a failed verify cannot
        be "promoted" to success; only a NEW entry/CUT/VERIFY can succeed
F-8  skipping a phase (S0→S6, S2→S8, etc.)           : every phase persists
        its artefact + history; no fast-path bypass

§4 — Terminal States

terminal_success : S8 verified_complete
terminal_negative: S4 reviewed_rejected
terminal_manual  : S10 abandoned
quasi_terminal   : S9 verify_failed_escalated — the entry row is frozen at
  S9 as the historical record; forward progress happens through the SEPARATE
  escalation entry it spawned (its own S0→… lifecycle). S9 is "terminal for
  this entry, live for its successor".

§5 — Re-Entrant / Idempotent Operations

MARK   : idempotent on payload.idempotency_key (IK-MARK) — replay = no-op
REVIEW : idempotent on (entry, manifest content hash) — identical re-review
         = no-op; different = NEW superseding review_decision
CUT    : idempotent on (entry, approved review_decision, attempt) — replay
         returns existing non-rolled-back change_set
VERIFY : idempotent on change_set_id — at most one non-superseded
         verify_result per change set; re-verify chains prior_verify_result_id
sweep  : idempotent — re-running a sweep over the same backlog re-promotes
         only entries still in promotable states; each pass = one sweep_log
crash_recovery: because each phase = one atomic txn, restart re-reads
  committed status and resumes from the last committed state; no phase is
  ever "half done". All four phase operations are safe to invoke again.

§6 — Audit Trail Expectations

A-1 every transition in §2 MUST write a decision_backlog_history row
    (history_id, entry_id, from_state, to_state, actor, reason, at) — using
    the table's existing 9 columns; richer detail goes in its jsonb/text col.
A-2 every CUT writes an executor dot_pair_signature; every VERIFY writes a
    verifier dot_pair_signature — the signature chain is the cryptographic
    audit complementing the history narrative.
A-3 every sweep pass writes a decision_backlog_sweep_log row — liveness/
    cadence is itself audited (proves the backlog is being drained).
A-4 history is APPEND-ONLY: no UPDATE/DELETE of a history row, ever. A
    correction is a new history row, not an edit.
A-5 the only mutable scalar in the whole schema is
    decision_backlog_entry.status; its every change is mirrored by an A-1
    history row in the SAME txn — status and history can never disagree.
A-6 reconstructable: the full lifecycle of any entry is replayable purely
    from history + signatures + the immutable artefact rows; the read-
    observability views (v0.3) expose the non-redacted projection of this.

§7 — Open Decisions (state-machine-specific)

OD-SM-1 concurrency guard mechanism for F-5 / S2→S5: advisory lock on
  entry_id vs. optimistic UPDATE … WHERE status='reviewed_approved'
  (compare-and-set). Recommend compare-and-set on status (no extra infra).
  GPT to confirm.
OD-SM-2 S5/S7 persistence: persist the in-flight marker before the heavy
  work, or keep S5/S7 purely conceptual (txn-internal, never committed)?
  Recommend purely conceptual (simpler, crash-safe). GPT to confirm.
OD-SM-3 sweep promotion authority: is S0→S1 promotion done by the same
  agent run or a separate sweeper principal? Recommend same agent, separate
  logical pass, logged in sweep_log. GPT to confirm.

End of v0.4 runtime state-machine design (design only; nothing built).