Plan: 22.9 Review Workflow, Lifecycle Mutations & Automation (#1081 program)

approval_level is DERIVED: the caller’s highest office role, recorded verbatim. The matrix check is caller_office >= required_level(action, cause). No office role → no approval-requiring mutation (403-shaped 400 naming the required office).

approved_by / verified_by / supervisor_approved_by are server-set to the AUTHENTICATED session’s claims.sub (typed principal: Worker(sub) | System). verified_by IS the completion actor (no separate completed_by column — one meaning); when a caseworker’s field work preceded a supervisor-called completion, that fact lives in the evidence reference, never in an attested column.

Supervisor approval = the supervisor’s own session. Outcomes requiring supervisor approval (amended/suspended/terminated) and terms amendments must be CALLED by a caller holding the supervisor or admin REALM role ("supervisor-or-above" is defined on the realm-role axis; office roles are the ORTHOGONAL authority axis and both checks apply); supervisor_approved_by/_at are server-set from that session. Caseworkers may perform schedule_review and continued completions on assigned agreements (their session is the record — verified_by = them, no approval fields).

Store primitives take proof types: transition_status/append_term_revision/review writers require an ApprovedAction with exactly TWO constructors in approvals: authorize_worker(claims, action) (office-checked against the matrix) and authorize_system(witness, leg) — the witness is buildable only from the enforcement settings by the sweep, covers ONLY the two enforcement legs, and records approval_level = "system" (a NEW fourth token added to the intervals + reviews CHECKs by the U1 migration — automation never fabricates a human office; the knob is the recorded authority). As built (U1): authorize_system + EnforcementWitness land WITH their consumer in U4 (dead-code deny; the interim — no system proofs mintable — is strictly tighter); the system token and the store-side ApprovedAction::covers(action) re-check (the proof is re-validated against the action actually performed, against in-tx truth, with the system arm restricted to the two enforcement shapes) shipped in U1. create_agreement/import_agreement_history stay ApprovalStamp-based and are RECORDED as outside the matrix (the #1071 import writes historical approvals no session can re-authorize; creation ships with #1069/#1070 which will carry their own proofs) — the "cannot be bypassed" claim is scoped to the #1081 mutation surface. Existing #1067/#1068 store tests that call the writers directly are reworked to mint proofs via authorize_worker with office-role claim fixtures (~24 call sites, enumerated in U1; NO test-only constructor — that would void the property).

Anchors bootstrap a type’s FIRST slot; never consulted once rows exist. Anchor preservation: any term append (renewal or amendment) first MATERIALIZES missing slots from the current anchors, then copies column values TRUTHFULLY (renewal appends write the fresh renewal dues but COPY the paper column from the paper slot’s reality; amendments copy both) — legal even when overdue because the dues-after-start CHECKs are dropped. An amendment can never erase an overdue obligation and a renewal append never moves the paper schedule. As built (U1): the append kind is the explicit typed parameter TermsAppendKind (Amendment | Renewal{new_renewal_due}), the store DERIVES the anchor columns (caller values ignored), appends are gated to active|suspended heads, and the ERR paper fallback ends truthfully at NULL.

Completions write the completion BEFORE ensuring the next slot (cycle+1, due completed_on + 12/+6 months, exact — cycle identity means no date shifting). As built (U1): completed_on never post-dates today (the same rule transitions enforce — a typed InvalidBusinessDate, and a U3 BusinessClock seam).

Reschedule/supersede (replaces slot-delete): one atomic operation writes superseded_* on the old slot and inserts the successor (same cycle, new due, reasoned, evented) under the parent FOR UPDATE. Reinstatement refresh uses the same primitive (supersede + fresh cycle rows; multi-overdue evidence survives as superseded rows).

Evaluation reads slots-∪-anchors (pure); backdated "historical observation" is REMOVED — as_of is always today; historical questions go to status_as_of/terms_as_of and the immutable rows.

State×operation matrix (explicit): schedule/complete/reschedule are legal on active AND suspended heads (the recovery path — a sweep-suspended agreement’s overdue review must be completable/reschedulable WITHOUT racing reinstatement; leg-1 actionability fires only on active heads, so no re-suspension race exists); amend-terms is active-only; everything is 400 on pending (reviews begin at activation — activation’s refresh seeds the first slots) and on terminal heads. Every slot mutation takes the parent FOR UPDATE and re-checks head status AND the caller’s assignment IN-TX; nested ownership is always WHERE agreement_id = $id AND id = $rid.

Payment repair is durable, not claimed: every mutation that can invalidate OR newly cover a generated month (backdated transition, term append, reinstatement) inserts the affected (agreement, month) pairs into subsidy_reconcile_queue in the same tx. The #1068 generator gains a SECOND loop after run_batch: drain queued pairs (child resolved from the agreement; the existing per-child tx + pay-excl lock machinery, specialized to the queued month), running the SAME reconcile-then-generate logic — which both VOIDS stale undisbursed months and GENERATES months a backdated reinstatement newly covers (retroactive money is intended: coverage restored ⇒ months owed, and the mutation that queued it carried regional/state approval). Sweep enforcement never queues anything — its business_date is always business-today, so enforcement never backdates money. As built (U1): the drain is CLAIM-FIRST (each row stamped processed before its repair runs, so a mutation committing mid-repair inserts a fresh live signal), a failed pair re-enqueues itself with its ORIGINAL cause, and the drain is infallible from the batch’s perspective (bookkeeping failures degrade to counted errors; GenerationReport.queue_drained reports settled pairs). One bounded pass (500 rows) per run; a retry cap / dead-letter policy is filed as #1098 (U4’s operator surface is its natural home).

Jurisdiction gate on every GA-policy WRITE entry point (the five mutation endpoints
the sweep pair + the scheduler): non-georgia deployments 400 UNSUPPORTED_JURISDICTION. The GET detail (the #1083 read surface) stays UNGATED — TX keeps its reads.

Business clock (U3, #1092): craig_common::BusinessClock — jurisdiction → business today() (GA = America/New_York calendar date). ALL date bounds, actionability, and business_date = today writes in this program AND the #1068 generator/endpoint consume it. Tests pin the Eastern-midnight boundary. The U1/U2 UTC seams are swapped (U3 landed — today threads as request context); automation (U4) ships only after U3.

Operation discriminator, deny-unknown: the resource-ref attr is operation ∈ {transition, schedule_review, complete_review, reschedule_review, amend_terms, review_sweep} (+ target_status for transitions). Ruleset rows key on named operations; the caseworker row allows exactly {schedule_review, complete_review} on assigned agreements. CRITICAL RE-SCOPING (fail-closed is otherwise defeated): the GA SUPERVISOR row is wildcard-action today and would allow ANY unnamed operation — U2 REPLACES it with operation/action-scoped rows (read, list, and the named operations minus reinstatement), with the reinstatement DENY above them; the ADMIN row stays wildcard (root-equivalent, recorded). Unnamed operations then genuinely fall to default deny for every non-admin role. Zen mechanics: all rows gain cells for the new inputs; absent-attr Null is null-safe.

Bounded, indexed, run-recorded sweep (U4): generator-style keyset batches; an index backing the candidate scan; a subsidy_sweep_runs row persisted BEFORE processing and finalized after (counters + per-agreement error set + affected IDs); the completion event carries run_id + write flags; enforcement transitions carry run_id, coupled completions carry review_id. Observe mode takes NO row locks (pure reads) and is documented as writing exactly one run row + one event — never "zero writes". Manual mass-action safety: the sweep endpoint is two-step — preview persists a run row (state previewed) with the affected IDs and returns them + a single-use token; execute (regional_director+ office) requires the token, transitions the run row previewed → executing via CAS (a concurrent second execute 409s), operates on the PINNED ID set re-verifying each agreement’s actionability in-tx (drifted agreements skip + count), expires 15 minutes after preview, and a replayed execute → 409 naming the run state. Devstack scheduler: OFF in the test posture — deliberate asymmetry with the #1068 generator’s always-on tick (payments are additive + idempotent; sweep enforcement MUTATES agreement status), recorded; a compose profile demonstrates enablement.

Replay/idempotency, honest per endpoint: transitions/amendments = CAS (retry after success → 409 stale-head, correct and documented); schedule = natural-key replay (same cycle+due → 200 existing; different due for the open slot → 409, never silent); reschedule/supersede = idempotent on (old slot id, new due); complete = full-payload fingerprint (ALL semantic fields incl. verified_by and offices) → identical 200 / differing 409 / post-transition 409 (recorded boundary). No middleware idempotency dependency.

Validation completeness: NUMERIC(10,2) scale + max on money; nonblank bounded citations; UUID-parsed identity strings; deny_unknown_fields on all new DTOs; evidence keys validated by namespace shape + recorded as untrusted references (evidence-store integration is a named non-goal → follow-up issue).

Events/audit completeness: review-driven term appends emit the terms event; term_id precedes agreement_id in the subsidy resource-id family; every write path has an event or a recorded exemption; the parse arms + family tests.