T2-4 — FTI-bearing Determination Snapshots + Program Fan-out (tanf/medicaid/caps/wic) (#685)

(plan)

This execution plan + nav entry.

Done (2026-06-20) — 46117b0.

MR1 (shared)

canopy-contracts-eligibility — shared SnapshotStatus { Present, NoInputSnapshot } enum for the read wrappers; extend the snapshot proptest arb_program to all six Program variants.

Done (2026-06-20) — 0457849.

MR1 (caps)

canopy-caps — capture the single pre-loop evaluate’s corpus_hash (reuse for every child); caps_program_input + build_caps_policy_params; assemble + hash + bind + sign per child; DetermineOutput carrier (snapshot + signing_kid); create_determination_snapshot in the handler tx; caps_determinations.snapshot_hash column + immutable determination_snapshots table + trigger; CapsDeterminationRead marker on GET + list.

Done (2026-06-20) — 1a3d1ff7.

MR1 (wic)

canopy-wic — same pattern, per-participant (each participant’s evaluate corpus_hash); wic_program_input + build_wic_policy_params; carrier + storage + marker + migration.

Done (2026-06-20) — 4b9469c0.

MR1 (tests + docs)

caps/wic integration (re-hash == signed hash; marker; immutability; corpus_hash present incl. denial); insta .snapshot_hash redaction; api/+data-models/ for caps+wic; CHANGELOG; this plan’s MR1 cells; master-plan T2-4 row → In progress; regen caps/wic OpenAPI.

Done (2026-06-20) — the MR1 docs commit.

MR2 (canopy-common)

Extract insert_fti_chain_entry(&mut PgConnection, &FtiAuditEntry) from log_access (advisory-lock + chain-from + compute_fti_event_hash + INSERT … clock_timestamp()); pool-based log_access becomes a begin/insert/commit wrapper. Existing fti_audit_hash_chain_test.rs passes unchanged. (originating_system is read off the entry, so it is not a separate param.)

Done (2026-06-21) — 3abb9f9.

MR2 (tanf)

canopy-tanf — TanfRulesClient::evaluate_eligibility_with_corpus_hash (always Some); program_input/policy_params built inline via serde_json::json! (no B3a); facts incl. assets leaves (no person_id) + members parsed from MemberContext; accessed_by from handler claims; refactor create_determination → &mut PgConnection; persist det + snapshot + insert_fti_chain_entry (last, before commit) in one tx; column + table + trigger; TanfDeterminationRead marker.

Done (2026-06-21) — the MR2 implementation commit.

MR2 (tests + docs)

MR1 set + an fti_audit_log determination_snapshot entry is emitted and verify_fti_chain still passes; corpus_hash Some on a denial. tanf api/+data-models/; CHANGELOG; plan MR2 cells; regen tanf OpenAPI.

Done (2026-06-21) — the MR2 implementation commit.

MR3 (medicaid, FINAL)

canopy-medicaid — evaluate_cmd_cascade_priority_with_corpus_hash (always-run, reuse for all subjects; NOT hierarchy); medicaid_program_input (cascade order + per-COA evals + denial evals + countable_resources + SOLQ) + build_medicaid_policy_params; facts (income person_id, expenses + assets none); DetermineOutput carrier; accessed_by threaded to persist_determinations; N snapshots + N insert_fti_chain_entry appended LAST in the single all-or-nothing tx; column + table + trigger; MedicaidDeterminationRead marker. Closes #685.

Done (2026-06-21) — the MR3 implementation commit.

MR3 (tests + docs, FINAL)

Per-member re-hash == signed hash; one fti_audit_log entry per determination; chain verifies. medicaid api/+data-models/; CHANGELOG; this plan → Done + As-built; master-plan T2-4 row → Done; regen medicaid OpenAPI; close #685 + closing comment.

Done (2026-06-21) — the MR3 implementation commit.

Contract reuse

DeterminationSnapshot + canonical_hash() + SignableDetermination.snapshot_hash + jws_kid reused unchanged (program-agnostic since T1-10). Only shared addition: a SnapshotStatus { Present, NoInputSnapshot } enum in canopy-contracts-eligibility for the 4 read wrappers. SNAP’s existing canopy-contracts-snap::SnapshotStatus is left as-is (optional consolidation follow-up).

CAPS/WIC facts (no fact arrays)

facts.income/assets/expenses = vec![] (no itemized facts); the scalar gross_monthly_income + activity/participant attributes ride in program_input (the exact rules_input), where reproducibility lives. facts.household.members = the per-subject children/participants. No synthetic leaves.

TANF facts

income leaves (person_id) + assets leaves from ctx.assets (AssetItem has no person_id → person_id: None) + expenses leaves (person_id opt); all fact_id/provenance None; money .rescale(2); household.members from the context.

Medicaid facts

income leaves (wire IncomeItem has person_id) + expenses leaves (household-summed medical, no person_id); facts.assets = vec![] — wire assets are present but ignored by the determination (uses ctx.countable_resources, TODO #856), captured in program_input instead; household.members = whole household (self-contained). One snapshot per member determination.

Per-subject → N snapshots

medicaid/caps/wic emit N determinations → N DeterminationSnapshot`s keyed by `determination_id. Each assembled + hashed + bound into that subject’s envelope in the compute+sign phase, carried to persist. Medicaid persists ALL subjects in ONE all-or-nothing tx (persist_determinations, ADR-035 Slice 2); caps/wic persist in the handler tx.

program_input (STRUCTURAL-VALUE)

CAPS {rules_input, eligibility_type, activity_*, child:{person_id,age,special_needs}, outputs}; WIC {rules_input, participant:{category,infant_age_months,breastfeeding,adjunctive_program}, nutritional_risk_documented}; TANF {rules_input incl. time_limit/sanction/PR inputs, benefit i/o, deprivation, time_limit_exceeded}; Medicaid {cmd_cascade_priority_order, per-COA magi/non_magi/chip/tma + denial-reason evals, hierarchy result + assigned_coa, countable_resources, booleans, member SOLQ}. Each via a {prog}_program_input(…​) helper.

policy_params (STRUCTURAL-VALUE)

build_{prog}_policy_params(params) — the resolved thresholds verbatim. The named §39 federal-parameter version stamp is a follow-up (resolved values + corpus_hash are the v1 guarantee).

corpus_hash

CAPS: rules evaluate() runs once before the child loop → capture once, reuse for every child. WIC: per participant → each captures its own. TANF: evaluate_eligibility always runs (the time-limit branch is after it; sanction/PR are its inputs) → always Some. Medicaid: capture from evaluate_cmd_cascade_priority (in resolve_priority_order, runs unconditionally) — NOT hierarchy (skipped on the no-COA path). All calls share one engine corpus.

Wrapper-client plumbing

TanfRulesClient::evaluate_eligibility_with_corpus_hash + MedicaidRulesClient::evaluate_cmd_cascade_priority_with_corpus_hash return (…, String); the existing methods keep their signatures and delegate (.0) → no call-site fan-out.

FTI chain entry (tanf/medicaid)

New canopy_common::fti_audit::insert_fti_chain_entry(&mut PgConnection, originating_system, &FtiAuditEntry) (the advisory-lock + chain-from + compute_fti_event_hash + INSERT … clock_timestamp() body on the caller’s connection; pool-based log_access becomes a thin wrapper). Called as the LAST step inside the existing persist tx, after all det+snapshot inserts, before commit — TANF one entry; Medicaid appends all N at the end of its single tx. Entry: purpose=*Eligibility, action=Write, resource_type="determination_snapshot", resource_id=determination_id, accessed_by, data_elements_accessed = fact-class NAMES only (ADR-014 §2; the snapshot content is already covered by the signed snapshot_hash + the append-only guard). No fti_audit_log schema change.

FTI accessed_by

determine() receives only the outbound service token; the inbound Claims live in the handler. Pass an explicit accessed_by: &str (from claims.actor()/service_id()) from the handler into the persist path.

Carrier for pre-signed snapshot

caps/wic/medicaid sign in the compute phase but persist later → add snapshot: DeterminationSnapshot + signing_kid: Option<String> to DetermineOutput so the persist step inserts exactly what was hashed+signed. TANF persists in-line in determine() (no carrier).

Storage + tx

TANF: refactor create_determination(pool)→(&mut PgConnection), wrap det+snapshot+chain in db.begin(). caps/wic/medicaid: add create_determination_snapshot(&mut conn,…) (+ chain for medicaid) in the existing tx. tanf keeps writing tanf_household_snapshots (additive).

Migrations (ADR-016 expand)

Per service, next free slot ≥ 20260622000000 (own dir): ALTER TABLE {prog}_determinations ADD COLUMN IF NOT EXISTS snapshot_hash TEXT; + CREATE TABLE determination_snapshots (…) + a statement-level append-only trigger cloned from the SNAP guard (GUC canopy.snapshot_maintenance; INSERT unguarded). FTI services add no new chain table.

Supersession

Additive (expand only). tanf_household_snapshots kept (INSERT-only, read-nowhere). Medicaid’s magi_household_snapshots exists but has no active write/read path — untouched. The contract phase (drop dead tables) is a follow-up.

Legacy marker

{Prog}DeterminationRead { #[serde(flatten)] determination, snapshot_status } + ::new() from snapshot_hash.is_some(), on GET + list (all four services expose both). Signed {Prog}Determination untouched (the snapshot_hash field is additive + skip_serializing_if).

Byte-stability

.rescale(2) money; truncate_to_micros DateTime; DOB → NaiveDate. serde_jcs sorts object keys, so json! field order in the builders is irrelevant to the hash. Assemble → canonical_hash() → bind → sign; never mutate between hash and sign. Extend the proptest arb_program to all six variants.

Other services + verifier + orchestrator

No change. Tolerance via skip_serializing_if; the orchestrator already tolerates snapshot_hash (T1-10). But ProgramResult has no snapshot_hash field and the orchestrator builds its response without one — the hash is bound in the verified envelope only, NOT surfaced/persisted by the orchestrator until #879. T2-4’s durable storage is program-service-side.