ADR-052: Subsidy-Agreement Temporal Ledger

subsidy_agreements (immutable identity: child, program, signed-artifact metadata, counties, evidence linkage, import provenance, predecessor lineage) · subsidy_agreement_parties (signatories) · subsidy_agreement_terms (effective-dated immutable revisions: amount + basis, review schedule, education extension, approval binding) · subsidy_agreement_status_intervals (business-effective status ledger with reason codes + approvals) · subsidy_agreement_reviews (22.9 performed-work records; populated by #1081). Rows are never edited in place: a term revision or status interval is CLOSED (its effective_until set) by its successor — nothing else about it ever changes.

Scope honesty: this is current-known business history with close-only mutation, not a bitemporal store. created_at/created_by record transaction time, but the model cannot reconstruct "what the system believed on date X" after a correction, and a correction/amendment protocol is deliberately deferred until a real consumer needs it (tracked at that consumer, not pre-built).

Windows are half-open [effective_from, effective_until); the as-of predicate is from ⇐ d AND (until IS NULL OR d < until). Terminal statuses (terminated/withdrawn/declined) hold an open-ended head interval so status_as_of stays truthful after closure — but terminal intervals are EXCLUDED from the coverage predicate: an agreement’s coverage is the union of its non-terminal intervals ([first_from, terminal_head.from) once closed). The overlap guard and the blocking invariant share this predicate, so a successor agreement after closure is legal while same-program double-coverage is impossible.

craig_financial::subsidy::store is the only legal writer. Compound primitives take &mut PgConnection (a caller-held transaction — a pool executor would autocommit between the close-head/insert/projection steps) and serialize on the parent row (FOR UPDATE) plus a per-(child, program) advisory lock (two fresh creates have no parent row to lock). Transitions CAS on the open interval’s row id — status-based expectations have an ABA hole (active → suspended → active). Business dates are explicit parameters, strictly after the open head’s start and never in the future (the current_status projection must never report a future state; scheduled transitions are a non-goal here). Term revisions are server-numbered (head.revision + 1).

#1067 ships NO mutation API: creation lands with the eligibility-bearing flows (#1069 ERR, #1070 SG, #1071 import), reviews and suspend/reinstate/terminate with #1081 — nothing payable can exist unvalidated. The module compiles into the lib target (deliberate deviation from the binary-private store convention) so the temporal tests can drive the primitives directly.

subsidy_agreements.current_status is a projection of the interval head, updated in the same transaction as every interval write. Eight blocking invariants (subsidy_* in crates/craig-test-lib/sql/invariants/craig-financial/, registered in BLOCKING_INVARIANTS) verify projection==head, exactly-one-head (LEFT JOIN cardinality), window/revision contiguity, party rules, and cross-agreement coverage non-overlap — they hold by construction, so any violation means a raw write bypassed the store.

In-place reinstatement (22.8) is a new active interval on the SAME identity (terminated → active in the machine; cause-specific approval enforced by #1081). A post-closure re-application is a NEW identity row with predecessor_agreement_id set — predecessor must be terminal at link time, self-links are CHECK-rejected, and UNIQUE(predecessor_agreement_id) forbids branching (cycles are impossible given terminal-at-link + unique successor).

import_agreement_history inserts a complete historical chain as recorded — no fabricated pending head, terminal tails never touch the open-agreement index. Provenance (source_system/external_reference/import_batch_id/imported_at) is required by construction with an all-or-none CHECK and a UNIQUE(source_system, external_reference) replay key (idempotent re-import → 409).