Assign SNAP take-up from reported receipt and the FNS participation rate

[daphnehanse11]

Summary

Closes #243. Second half of the SNAP work-requirements input surface (#248), alongside #293 (hours).

The published dataset ships takes_up_snap_if_eligible constant True (or omits it — same engine default), so PolicyEngine-US pays SNAP to 100% of eligible units. FNS measures participation among the eligible at ~82%. Universal take-up misstates who receives SNAP and overstates the reach of any eligibility-side reform.

This adds a snap_take_up source stage following the #266/#293 template: manifest entry + shared runtime handler + frame transform + release gate + builder wiring.

Semantics (identical to the retired enhanced-CPS pipeline)

1. Reported recipients always take up — SPM units with positive raw ASEC SPM_SNAPSUB reported receiving SNAP; survey measurement wins unconditionally.
2. Non-reporters fill to the published rate — seeded draws grant take-up at exactly the fill rate needed for the overall weighted share to land on the manifest's cited FNS rate (0.82). When reporters alone exceed the rate, nothing is forced — the share is emergent.
3. Eligibility stays the engine's job — the flag is assigned across all units and PE-US intersects it with modeled eligibility, matching the retired pipeline.

Draws are blake2b hashes keyed by stable source identity (source_year/source_household_id/min source_person_id), so support-channel clones of one source unit always agree and reruns are bit-reproducible. The rate lives in the manifest with its FNS citation — a rate without a citation refuses to run.

Healing + gate

• The frame transform is idempotent on a signal-carrying column and recomputes when the column is constant — the published all-True landmine is repaired, not trusted.
• Release gate (snap_take_up_signal): column nonconstant, every reporting unit takes up (anchor preserved), weighted share within [0.70, 0.95]. Threaded through release gate failures, calibration diagnostics, and both manifests, mirroring the immigration and hours gates.

Verification

• 18 new tests (manifest declaration, anchor/fill/overflow semantics, seed stability, clone consistency, citation enforcement, healing path, gate failure modes); full populace-build suite green.
• End-to-end against the current 233,716-SPM-unit base: take-up share 0.821 (target 0.82), reported share 0.107 (CPS underreporting is exactly why the fill exists), zero reporters denied, gate green.

Follow-up (not in this PR)

State-calibrated take-up (greedy fill against FNS state household counts, the calibrate_binary_assignment machinery) is deliberately deferred: FNS state counts are average-monthly while the flag is annual-ever, and that bridge deserves its own reviewed decision — see the discussion on #292. National-rate + reported-anchor matches the retired pipeline's published behavior.

Merge-order notes

• Same anchor-point conflicts with Derive hours-worked inputs from ASEC reported hours #293 (both insert after the immigration stage in the manifest, stage order, and builder) — trivial resolution whichever lands second.
• After this merges, the takes_up_snap_if_eligible reviewed exclusion in Gate releases on input columns stuck at the engine default #286's degenerate-input gate becomes stale and should be removed.

🤖 Generated with Claude Code

[daphnehanse11]

Rebased onto current main (8b1795a, was 14 behind) and squashed the two commits, mirroring the #293 rebase.

Conflict resolutions were the same 11 additive anchor points as #293 — main's TANF/EITC take-up (#315) and eCPS-parity (#316) wiring interleaved with this PR's SNAP wiring. In main() the TANF/EITC seeding + gate now run first, then SNAP take-up + gate; snap_take_up_gate threads through _release_gate_failures/_build_manifests alongside degenerate_input_gate/ecps_parity_gate.

Intended changes beyond conflict resolution:

• Dropped the stale takes_up_snap_if_eligible reviewed exclusion from US_DEGENERATE_INPUT_REVIEWED_EXCLUSIONS — the merge-order follow-up this PR's description flagged (Gate releases on input columns stuck at the engine default #286 merged first; this stage makes the column non-degenerate, and the cannot-rot gate fails on a listed column that carries signal).
• Reconciled the Seed TANF and EITC take-up from administrative rates; engine-asserted take-up contract (#312) #315 take-up contract inventory: SNAP stays populace_treatment: "out_of_scope" (flipping it to seed would make with_us_take_up_inputs double-seed it), but the scope_owner/notes now say the stage has landed rather than "in-flight", and clarify that out_of_scope means out of scope for the Bernoulli module, not unseeded. Same doc fix in take_up.py's module docstring.
• One incidental ruff format hunk in take_up.py (pre-existing three-line ternary collapsed to one).

Verified the rebased net diff against the original with interdiff — no other semantic drift. Full populace-build suite green locally; ruff check + format clean.

Note for merge order with #293: both PRs insert at the same manifest/builder anchor points; whichever merges second gets the same-shape trivial conflict both descriptions anticipate.

🤖 Generated with Claude Code

[daphnehanse11]

Heads-up from the medicaid take-up workstream (#334/#337): once #337 lands, parity_gate fails on stale known-gap exemptions — any register entry whose layer the candidate now populates. This branch's SNAP stage will make takes_up_snap_if_eligible exactly that: the entry still sits in ecps_parity_known_gaps.json with reason "Populace does not yet produce it", so the first release build off a rebased #294 will fail the parity gate until that entry is deleted. When rebasing, (1) remove the takes_up_snap_if_eligible entry from the register, and (2) note the take-up contract landed in #315 marks SNAP out_of_scope pointing at this PR — the contract entry's treatment/notes should be updated to reflect the stage actually landing (same pattern #334 used for Medicaid: the stage owns the flag, the contract records how). Also expect small rebase friction in us_runtime/__init__.py and the builder wiring where #334 added its stage alongside where this PR adds SNAP's.

[MaxGhenis]

Approving (agent-assisted review; I verified the load-bearing pieces). The logic is right and the tests are thorough — reported-receipt anchor, weighted fill to the FNS rate, blake2b seeding keyed on source identity for clone-consistency, constant-True healing, and a gate that mirrors the immigration one. 0.82 checks out as the FY2018 FNS national participation rate.

One thing I fixed on the branch rather than bouncing back: this stage makes takes_up_snap_if_eligible a produced layer, but the parity register still exempted it with reason "Populace does not yet produce it." #337 removes the four entries rotted by already-merged work but not this one (it only rots once this merges), and because SNAP stays out_of_scope, it sits outside #337's seeded_take_up_programs() static guard — so the failure would only surface on the first release build after both land. I pushed a commit deleting the entry here; it's safe under current CI (the register only shrinks, nothing asserts presence) and under the pre-#337 gate (the candidate populates the column). Same pattern applies to #293's hours entries — cleanest if each producing PR removes its own register line.

Two nits, neither blocking:

• The manifest labels the FNS artifact vintage "latest_available" but 0.82 is FY2018 (latest published is FY2022 at 88%) — either pin the vintage to FY2018 in the notes or refresh the rate.
• The fill target is computed on person "first" weights per SPM unit while the gate measures on resolve_weights("spm_unit"); they coincide today (0.821 achieved vs 0.820 target) but computing the target on the spm_unit basis would keep them locked together if weight resolution ever changes.