Plan: Monthly Subsidy Payment Generator (#1068)

payments.agreement_id UUID NULL REFERENCES subsidy_agreements(id) ON DELETE RESTRICT
payments.term_id UUID NULL with table-level composite FOREIGN KEY (agreement_id, term_id) REFERENCES subsidy_agreement_terms (agreement_id, id) ON DELETE NO ACTION — pricing provenance (which revision priced the row; mismatch detection).

Trio placement_id/foster_home_id/case_id → nullable; CHECK payments_origin_exclusive: placement rows keep the NOT-NULL trio + NULL agreement/term; subsidy rows have agreement_id + term_id NOT NULL + NULL placement/home (case optional — post-case SG/RCS episodes still pay). Pre-1.0 breaking nullability → CHANGELOG Changed.

Subsidy shape CHECKs (conditional on agreement_id IS NOT NULL): EXTRACT(DAY FROM period_start) = 1; period_end = (period_start + INTERVAL '1 month' - INTERVAL '1 day')::date; day_count = 1 AND daily_rate = gross_amount (unit-month); payments_subsidy_never_ive: NOT ive_eligible AND ffp_rate = 0 (TANF-funded per 22.8: 542 TANF-MOE, 552/553 TANF; enhanced-cohort funding confirmation on #1073’s list) — the STRUCTURAL never-IV-E guarantee.

Idempotency: partial UNIQUE payments_one_subsidy_per_agreement_month (agreement_id, period_start) WHERE agreement_id IS NOT NULL AND status <> 'voided' — voided rows free the key (regeneration path). No separate agreement index (the unique leads on agreement_id).

Payment model + contracts PaymentResponse: + agreement_id/term_id: Option<Uuid>, trio → Option (test-lib lifecycle clients rely on the mirror). Payment LIST/count gain agreement_id + child_id filters and an id tie-break on the current single-column sort.

CreatePaymentParams gains agreement_id, term_id, assigned_worker_sub (no assignment field exists today; the placement caller passes None, preserving NULL-then-backfill).

Events: publish_payment_created + the lifecycle payloads (events.rs:43) OMIT case_id when None (conditional key insert — json! would emit an explicit null that stops the audit fallback #1090 fixed).

Generator: ONE tx PER CHILD covering reconcile-then-generate for all that child’s agreements (the xact lock spans the pass): lock → re-evaluate INSIDE the tx (TOCTOU kill) — agreement_for_update (new lib read, SELECT … FOR UPDATE), status_as_of(month_start) == Active, terms_as_of(month_start) (capture term_id), per-diem overlap check (EXISTS … WHERE child_id = $1 AND agreement_id IS NULL AND status <> 'voided' AND period_start ⇐ $3 AND period_end >= $2) — THEN insert + publish_payment_created staged same-tx → commit. Lock ordering is acyclic vs the #1067 history lock (distinct keyspaces; generator never takes the history lock; transition_status takes agreement-row then history — never pay-excl).

handle_placement_activated gains the same lock + the reciprocal check: on subsidy-row overlap, per-diem STILL wins (a foster family is never starved; the 22.8 handoff is #1069’s flow) — WARN + REPORT-ONLY invariant subsidy_perdiem_same_month_overlap (the transitional handoff month is legal until the correction voids it; the invariant is the operator queue).

Cross-program guard: candidates grouped by child; >1 active program for a child+month → generate NOTHING for that child (skipped_multi_program + WARN) — fail-closed pending #1073’s coexistence confirmation; report-only invariant multiple_subsidy_payments_same_child_month watches the data.

Jurisdiction gate: subsidy payment policy is GEORGIA-DEFINED ONLY — the scheduler spawns only when settings.jurisdiction == "georgia"; the endpoint returns 400 typed UNSUPPORTED_JURISDICTION (new craig-common constant) elsewhere. TX generation = future policy work (ADR-053).

Correction protocol (ADR-052’s named deferred consumer, now defined):

Terms-coverage hardening (store): native create_agreement rejects terms.effective_from > initial_status_effective_from — with the guard, generator-time terms_as_of == None on an active agreement is a hard per-agreement error (errors + WARN), not a quiet skip. Import path untouched.

Core in the LIB: craig_financial::subsidy::generator (#1067 lib-module precedent; tests reach it). Owns insert_subsidy_payment (its own subsidy-shaped INSERT incl. term_id/origin — distinct from the bin’s placement-shaped create_payment; B8-watched) and generate_for_month(pool, month_start, scope, initiator) with GenerateScope { All, Child(Uuid) } (test-determinism seam) and Initiator { Scheduled, Manual { sub, name } } (manual runs stamped with the CALLER, not "system").

GenerationReport { month, run_id, generated, already_existed, derivation_mismatch, skipped_exclusivity, skipped_multi_program, skipped_not_active, errors, voided_stale } (contracts; Serialize+Deserialize+ToSchema). Per-agreement errors continue the batch (errors++); endpoint returns 200 with the report (WARN logs keyed run_id + agreement_id); fatal candidate-query error → 500. One financial.subsidy_generation_completed event (run_id, month, initiator kind, counts — no PII) staged in its own tx after the batch; ADR-003 + implementation-guide + security parsing rows.

Run lease: pg_try_advisory_lock(hashtext('subsidy-gen')) as a SESSION lock on a connection the run HOLDS for its duration (dedicated pool.acquire() guard or standalone PgConnection); session locks release only via same-connection pg_advisory_unlock or connection close — unlock-or-close on ALL paths (a still-locked pooled connection would silently 409 every future run), and connection-drop-releases IS the crash-safety property. Second concurrent run → endpoint 409 GENERATION_ALREADY_RUNNING (new problem_types constant) / scheduler skips the tick. Batching: keyset ordered (child_id, id), page boundaries only BETWEEN children (the cross-program guard needs each child whole).

Scheduler (bin spawn_workers): typed settings subsidy_generator_interval_seconds, serde-default 0 = disabled (explicit deployment consent); devstack/CI enablement = CRAIG_FINANCIAL__SUBSIDY_GENERATOR_INTERVAL_SECONDS: 3600 in docker-compose.yml’s craig-financial block AND docker-compose.scale.yml (no separate CI compose exists). Loop = detection.rs shape BUT the FIRST tick runs immediately under the lease. Business clock: UTC month boundaries (documented v1 approximation; #1092 owns the timezone decision); injected now: fn() → NaiveDate seam for tests.

Trigger POST /v1/financial/subsidy-payments/generate in NEW api/subsidy_generation.rs (B1 + authz-coverage/evil-corpus gate visibility): authz = authz.check(claims, ResourceRef { resource_type: SubsidyAgreement, resource_id: Uuid::nil(), assigned_worker_sub: None, supervisor_sub: None, attrs: {} }, Action::Approve) — the collection-appropriate capability: GA admin+supervisor; TX ADMIN-ONLY (regional + service DENIED by the subsidy_agreement ruleset’s leading rows). Request { month: Option<String> } via ONE typed YearMonth garde-custom parser (contracts; proptests: never-panics + roundtrip
canonical-form); malformed → 422 VALIDATION_FAILED, valid-but-out-of-range → 400 INVALID_DATE; bound [current − 12 months, current]. Registered routes + ApiDoc + evil corpus.

Metrics: craig_common::metrics family (generated/voided_stale/derivation_mismatch/skipped_*/errors) — jws-worker precedent.

Read-surface acceptance (ADR-053): generated rows are FINANCIAL artifacts under Payment policy (exposure identical to per-diem rows); the agreement LEDGER stays behind SubsidyAgreement policy; the TX-regional/service breadth of Payment policy is the pre-existing documented hazard (noted on #1086).

Seed: FOUR collections with SqlRow impls rendered BEFORE payments (sql.rs order): SeedSubsidyAgreement, SeedSubsidyParty (caregiver ≠ child — blocking invariants), SeedSubsidyTerms, SeedSubsidyInterval (pending→active chains); + 3 months of unit-month history per agreement ENDING AT AND INCLUDING the current month (the immediate first tick lands already_existed no-ops on every boot — no count contamination); statuses PENDING only (claiming aggregation untouched); SeedPayment.payment_type → String (old tokens byte-identical); manifest.rs Option rendering fix; dedicated fixture ids. Churn: sql_byte_identity re-bless, payments COLUMNS, rate-consistency test scoped to placement-origin + a new subsidy↔term assertion, downstream snapshots enumerated at implementation.

Tests — taxonomy-placed (conc/fault/invariant/property in their named dirs for cargo xtask reliability):

Unit-month presentation: origin-aware BFF payment-detail labels ("Monthly amount"; day-count hidden for subsidy rows); contracts doc-comments de-daily-fied; api-docs
data-model-financial document the convention; day_count_gross_consistent remediation text gains the subsidy note.

Docs: ADR-053 (+nav) — shared-table nullable origins, unit-month accounting, correction/freeze protocol, child/month locking, funding CHECK, capability choice, read-surface acceptance, jurisdiction gate, UTC-clock approximation; ADR-003
implementation-guide (2 events + voided reshape); ADR-052 pointer line; shared-crates (contracts); cross-service-reconciliation.adoc ("every payment has a case and placement" now false — reword; from_queries already NULL-filter, verify); state-machines void note; configuration-reference (knob + PAYMENT_PERIOD backfill); runbook guidance (disable/recover/partial-error/metrics) in developer-guide; CHANGELOG (Changed + Added).