Require state-level SNAP benefit hard targets

[daphnehanse11]

Summary

Closes #255.

SNAP currently calibrates to a single national hard target. This PR makes the 51 state-level SNAP benefit totals (50 states + DC) a required part of the US target profile, so a build can no longer silently ship national-only SNAP calibration.

Why the change is this small

Investigation for the 2026-07-01 SNAP research readout found the pipeline is already almost fully wired:

• The Ledger package usda-snap-fy69-to-current already ships per-state total_benefits facts (usda_snap.fy2024.state_benefits.<region> record sets, geography_level: state, all 53 state agencies).
• _direct_reference_from_fact already accepts state-geography facts for mapped families and stamps state_fips metadata — the same path per-state TANF targets use today.
• The release builder already materializes state_fips-scoped targets by masking households to the state.
• Territories (GU/VI) resolve no PolicyEngine state FIPS and are skipped automatically.

So with a current consumer_facts.jsonl, state SNAP hard targets activate with zero mapping changes. The only gap was enforcement.

Changes

• gates.py: add required_metadata_keys to TargetCoverageRequirement — presence-of-key matching, so a requirement can demand state-dimensioned rows (state_fips present) without enumerating 50 FIPS values. Validated non-empty in __post_init__.
• fiscal_targets.py: add the snap_state_benefits coverage requirement (family usda_snap, role snap_total, state_fips key required, min_matches=51).
• Tests: gate-level tests for required_metadata_keys (present/absent/empty-key rejection); compile test proving a state-level usda_snap fact becomes a state_fips-scoped spec while a Guam row is skipped; profile tests proving 50 state rows or a national-only surface fail the gate; state SNAP rows added to the complete-profile fixture.

Draft status / rollout note

This gate makes builds fail if the consumer-facts artifact lacks the state SNAP record sets. Before marking ready:

• Confirm the production consumer_facts.jsonl includes the state_benefits record sets (the source package parses them from the FNS FY24 workbook, but the deployed artifact vintage needs checking).
• Run a fiscal refresh build against a current artifact and review the per-state SNAP calibration diagnostics (zero-support states would need reviewed exclusions, TN-style).

Follow-up (not in this PR)

State participation counts (average_monthly_households/average_monthly_persons) as indicator targets — needs an explicit average-monthly vs annual-ever bridge before becoming a hard constraint.

Test plan

• uv run pytest packages/populace-build/tests — full suite passes (269 tests).
• ruff check / ruff format --check clean on changed files.

🤖 Generated with Claude Code

[daphnehanse11]

@PavelMakarchuk one open item for merge timing (not code review): this gate makes the 51 state SNAP rows mandatory, so it should land only once the production consumer_facts.jsonl is confirmed to include the usda_snap.fy2024.state_benefits.* record sets (they're in the Ledger source package, but I can't check the deployed artifact vintage from my side). One-line check against the artifact:

grep -c 'state_benefits' consumer_facts.jsonl   # expect >= 51

If the artifact predates the state record sets, merging this will (correctly) fail the next build until the artifact is refreshed — that's the gate doing its job, but better to sequence it deliberately.

[MaxGhenis]

Independent review verdict: the mechanism is sound (presence-of-key matching validated non-empty; state SNAP already maps to an active hard target on main, so this enforces an existing surface; orthogonal to #245's CD posture) and local gate/target tests pass. Two things block merge, matching the PR's own unchecked boxes: (1) run one fiscal-refresh build on a current artifact to confirm the deployed consumer_facts carries the state_benefits record sets, and (2) record any zero-support states as reviewed exclusions (TN-style). With per-state diagnostics from that run attached, this is merge-ready.

[MaxGhenis]

Gate-review evidence (independent review pass, 2026-07-06):

Code review: clean. The required_metadata_keys mechanism is presence-only as claimed (gates.py:297), validation rejects empty keys, and all touched suites pass locally (test_gates.py 84/84, test_us_fiscal_targets.py 86/86, spec-only enforcement 5/5, full package green, ruff clean).

Your first unresolved checklist item is now resolved with evidence: the current curated feed (the v6 surface used in tonight's Build F staging run) carries 53 state-level usda_snap total_benefits rows — 50 states + DC + GU/VI, with the territories dropping at reference compilation via the pre-existing _state_fips skip — so the compiled registry meets min_matches=51.

Second checklist item lands tomorrow: tonight's Build F staging run produces exactly the per-state SNAP calibration diagnostics you flagged as needed. Merge sequencing: once those diagnostics confirm no zero-support state (the TN-style case), this merges.

One design note for a follow-up (non-blocking): the failure message reports only the count ("has 50 match(es), needs 51") without naming the missing state, and the only exemption mechanism is requirement-wide — a per-state diagnostic in the failure line would make future breakage self-explaining.

[MaxGhenis]

Review — still valuable; do not close. Needs a rebase and its two rollout items resolved before it's merge-ready.

I checked whether the merged SNAP train (#350/#352/#353) or the state suites (#345/#319) already cover this. They don't:

• SNAP train (#350/#352/#353) is entirely about SNAP input columns — carrying eligibility/exemption inputs through outputs, seeding pregnancy, seeding ABAWD exemptions. Nothing about calibration-target coverage.
• State suites (#345 7 state-program benchmarks + EITC-by-state cross-check; #319 legislative-reform validation) are backtest/validation suites, not target-profile coverage requirements.
• Current main has neither piece of this PR: gates.py has no required_metadata_keys (only key-value required_metadata, line ~357), and fiscal_targets.py has no snap_state_benefits requirement — SNAP is still enforced only at the national snap_total. A build can still silently ship national-only SNAP calibration, which is exactly the gap this PR closes (#255).

The mechanism is genuinely needed, not redundant with the existing state coverage. The existing state_income_tax requirement gets away with bare min_matches=44 because that family has no national row. SNAP is different: the usda_snap/target_role=snap_total family carries both a national row and the per-state rows, so a plain count would let the national row (or a partial state surface) pass. required_metadata_keys=("state_fips",) is the right primitive — it demands state-dimensioned rows (state_fips present) without enumerating 50 FIPS values, and the matching logic is correct (AND of value-matches then key-presence; __post_init__ rejects empty keys). The two profile tests pin exactly the failure modes: a national row and a 50-of-51 surface both fail. min_matches=51 is right (50 states + DC; GU FIPS 66 / VI resolve no PE state FIPS and are skipped — the compile test proves CA→06 maps and Guam is dropped).

What remains before this can go ready (the PR's own checkboxes, still open, and correct):

1. Rebase — CONFLICTING/DIRTY. fiscal_targets.py now carries ~30 TargetCoverageRequirement blocks and has moved a lot since this branch's base; the changes here are additive (one dataclass field, one match clause, one requirement), so the rebase should be mechanical, but it's required.
2. Confirm the deployed consumer_facts.jsonl carries the usda_snap.fy2024.state_benefits.* record sets. This gate makes the build fail if they're absent, so this is a hard data dependency (same class as #334's Ledger-fact dependency) — merging it against an artifact that lacks the state rows would red the release build.
3. Run a fiscal-refresh build and review per-state SNAP diagnostics — any zero-support state needs a reviewed exclusion (the TN pattern) rather than a gate failure.

The deferred follow-up (state participation counts as indicator targets, pending an average-monthly vs annual-ever bridge) is correctly out of scope here.

Recommendation: keep open and pursue — rebase, tick the two data/rollout boxes, then it's a clean, self-contained hardening. Not closing (and not merging) — review-only per request.

[daphnehanse11]

Addressing the three items:

1. Rebase — done (e1e0911, CI running). The rebase surfaced one real interaction beyond the mechanical conflict: the complete-profile coverage tests that landed with the Build G work (test_soi_income_tax_liability_satisfies_total_tax and its seven siblings) synthesize a complete target surface and assert it passes — so snap_state_benefits immediately made 51 state-dimensioned SNAP rows part of "complete." Added complete_snap_state_rows() to the fixtures at all eight sites, mirroring complete_state_income_tax_rows. Full suite green.

2. Deployed-artifact confirmation — verified at the Ledger declaration level; the artifact-pin check remains. The usda_snap fy69-to-current source package in PolicyEngine/ledger declares the usda_snap.fy2024.state_benefits.{nero,maro,sero,mwro,swro,mpro,wro} record sets with per-state rows — 53 total: 50 states + DC + Guam (wro) + USVI (nero), which independently grounds both min_matches=51 and the requirement's territory-skip note. The state-level ETL (db/etl_snap.py, snap_states strata from the SNAP State Summary with state_fips constraints) produces exactly the rows this gate demands. What I could not check from here is the deployed consumer_facts.jsonl behind the current pin — that needs someone with artifact access to grep it for usda_snap.fy2024.state_benefits. before merge, per your point that this gate makes absence a build-red.

3. Per-state diagnostics / zero-support exclusions — open, needs a build run. Noting that the Build G per-run extra_support_exclusions mechanism (which landed in the same wave) is exactly the right vehicle if any state shows zero support: a reviewed, reason'd, per-artifact exclusion rather than a registry edit — arguably cleaner than the standing TN pattern for what may be artifact-specific gaps.

So: item 1 closed, item 2 four-fifths closed (declaration + ETL verified; pin grep outstanding), item 3 gated on the next fiscal-refresh run.

[MaxGhenis]

Review — the code is clean and merges green, but holding the merge: the required gate has no working escape hatch for a legitimately-missing or zero-support state, and rollout items 2 & 3 are still open.

I re-reviewed against current main. This branch is 6 commits behind and its green CI predates #384 (cross-register/take-up preflights), #387 (Medicaid substitution register), and #389 (Build J re-cert). Merging main in is conflict-free, and on that merged tree the touched suites pass locally (test_gates.py + test_us_fiscal_targets.py, 226 tests green; ruff clean), so the code itself is sound and would not red CI.

Genuinely resolved

• Item 1 (rebase + fixtures) is in the diff and holds on the merged tree: complete_snap_state_rows() is wired at all eight complete-profile sites and the profile-coverage suite passes with the new requirement active.
• Mechanism is correct: required_metadata_keys is presence-only, empty keys are rejected in __post_init__, and min_matches=51 is right (50 + DC; GU/VI resolve no PE state FIPS and drop at reference compilation).
• No interaction with the #387 reviewed-substitution register: that path is cms_medicaid / medicaid_enrollment; this requirement is usda_snap / snap_total. Different family — no double-handling of a state.

Why it is not merge-ready — the escape-hatch pincer (the substantive item)

The coverage gate runs on target_specs after support exclusions are applied. In tools/build_us_fiscal_refresh_release.py the registry is compiled with extra_support_exclusions=... (~L5667) and only then does target_profile_coverage_gate(target_specs, ...) run (~L5692). A source_record_id in extra_support_exclusions (or the standing US_FISCAL_TARGET_SUPPORT_EXCLUSIONS) makes _reference_from_ledger_fact return None (fiscal_targets.py ~L1983–1991) — the target is dropped from the registry, not zeroed.

So the per-run zero-support exclusion proposed in item 3 as the vehicle for a thin-support state is mutually exclusive with this requirement: excusing one SNAP-benefit state drops the usda_snap + state_fips count to 50 and fails snap_state_benefits (needs 51). There is no reviewed way to excuse a genuinely-unreported or zero-support SNAP-benefit state — the only remedy is to repopulate the feed. That is exactly the register-vs-register pincer register_consistency.py (#377) was built to forbid for input columns, reintroduced here for target rows. Contrast #387: the Medicaid gate injects a substitute spec so the count survives; SNAP-benefit rows have no equivalent, so this gate fails closed with only a bare count in the message (has 50 match(es), needs 51) rather than naming the missing state.

Two rollout items still open (per the latest PR comment)

2. Deployed feed not confirmed against the current pin. The Ledger source package declares 53 state_benefits rows and the ETL produces them, and the Build F feed was confirmed to carry 53 on 2026-07-06 — but nobody with artifact access has grepped the current pinned consumer_facts.jsonl (Build J vintage) for usda_snap.fy2024.state_benefits. >= 51. This gate makes absence a hard build-red, so that one-line check is a prerequisite.
3. No fiscal-refresh run under this gate has confirmed every SNAP-benefit state is support-expressible. The Build J zero-support register carries only TANF + SOI cells (no SNAP), which is encouraging, but that run predates this gate.

To make it merge-ready, either

• (a) confirm the current pinned consumer_facts.jsonl carries >= 51 usda_snap.fy2024.state_benefits.* rows and a fiscal-refresh build under this requirement shows zero SNAP-benefit states in the support-exclusion set — closing items 2 + 3 against the live pin and proving the pincer is unreachable on this artifact; or
• (b) give the requirement a reviewed escape hatch the coverage gate honors — e.g. subtract a named reviewed-exclusion set from the effective min_matches, or a substitution register in the #387 mold — so a genuinely-unreported or zero-support state degrades to a reviewed, reasoned exclusion instead of a red release.

Path (a) with the pin-grep and per-state diagnostics attached is the smaller step; (b) is the durable fix if the feed can ever legitimately lack a state. Either closes it out.

[MaxGhenis]

Merge-path (a) executed and verified — both conditions hold on the certified pin; merging.

Following up on my review comment: I ran the feed-completeness and support-expressibility verification directly against the artifacts the release build actually consumes.

1. The deployed feed carries the full state SNAP surface. The pinned consumer feed (consumer_facts_buildh_v8.jsonl, sha256 94b7155f…b1669 — byte-identical to the Build J scripts' pin) contains exactly 53 usda_snap.fy2024.state_benefits.* rows: all 50 states + DC + GU + VI (enumerated, not just counted). GU/VI resolve no PolicyEngine state FIPS and drop at reference compilation, exactly as the requirement's note describes.

2. No SNAP-benefit state is zero-support or excluded. No usda_snap record appears in the standing US_FISCAL_TARGET_SUPPORT_EXCLUSIONS register or in Build J's per-run sparse_zero_support_exclusions_buildj.json (24 entries, all TANF + SOI state-AGI cells). So the escape-hatch pincer I flagged is unreachable on the current certified artifacts: no state needs an exclusion, and the gate compiles against a complete surface.

3. The gate itself passes end-to-end. On this branch rebased onto current main, I compiled the registry exactly as the builder does — compile_us_fiscal_target_registry(feed, target_period=2024, age_targets=True, extra_support_exclusions=<Build J register>) — and ran target_profile_coverage_gate with the full requirement set including snap_state_benefits: the compiled registry carries 1 national + 51 state-FIPS snap_total targets (FIPS 01–56), and the gate passes with zero snap-related failures.

Also rebased the branch onto current main (content unchanged, +132/−5) so CI re-runs against the post-#371/#384/#389 tree — the prior green run predated those. The full populace-build suite passes locally on the rebased tree.

The design follow-up from my review stands as future work, now non-blocking: a reviewed exclusion/substitution hatch (the #387 mold) would make the gate degrade gracefully if a future feed vintage ever legitimately lacks a state, and the failure line could name the missing state rather than just the count.