Carry SNAP eligibility and exemption inputs through Populace US outputs

[daphnehanse11]

Closes #244; advances #248.

Summary

Adds an eligibility_inputs source stage that carries the SNAP eligibility and exemption inputs through Populace US outputs, following the hours_worked (#293) template: manifest entry, runtime handler, frame transform, release signal gate, builder wiring, and parity-register cleanup.

Five PolicyEngine-facing person inputs, each a direct mapping of measured CPS ASEC variables — the same mappings the retired enhanced-CPS pipeline used, so parity with the retired surface is by construction:

Output	Source	Rule
is_disabled	PEDISDRS/PEDISEAR/PEDISEYE/PEDISOUT/PEDISPHY/PEDISREM, SSI_VAL, A_AGE	any difficulty item == 1, then the retired align_reported_ssi_disability rule (under-65 reported-SSI recipients are disabled)
is_blind	PEDISEYE	== 1
is_full_time_college_student	A_HSCOL, A_FTPT	college enrollment (== 2) and full-time (== 1)
own_children_in_household	PEPAR1/PEPAR2 within PH_SEQ	count of household members whose parent pointers resolve to the person (the retired children_per_parent construction)
veterans_benefits	VET_VAL	direct, floored at zero

Nothing is imputed. Without this stage every input takes its engine default (False/0), silently erasing the SNAP disability, student, parent/child, and veteran exemption channels — the #244/#248 failure mode.

Ownership notes

• is_veteran is formula-owned in PolicyEngine-US (derived from veterans_benefits), so the stage exports the input dollars and deliberately not the derived flag (avoiding the Certified populace-us persists 18 formula-owned variables eCPS doesn't (formula_owned_export gate never wired into the build) #24 over-export failure).
• immigration_status_str from Carry SNAP eligibility and exemption inputs through Populace US outputs #244's list is already owned by the immigration_status stage and is not duplicated here.
• The five entries for these variables are removed from ecps_parity_known_gaps.json (each producing PR removes its own register lines, per Derive hours-worked inputs from ASEC reported hours #293/Assign SNAP take-up from reported receipt and the FNS participation rate #294 review guidance).

Gates

us_eligibility_inputs_signal_gate fails the release when any column is missing or constant, or when weighted shares leave plausibility bands: disabled share [0.05, 0.20] (ASEC six-item battery ≈ 10% of all persons), full-time college share [0.01, 0.08], parent share [0.12, 0.40], positive veterans'-payment share [0.002, 0.04]. Healing mirrors the hours stage: a surface carrying constant engine defaults is recomputed from raw columns rather than trusted.

Testing

• New test_us_eligibility_inputs.py: 20 tests over manifest declaration, each mapping rule (including the SSI-alignment age boundary, both parent pointers, cross-household pointer isolation, negative-value flooring), frame integration (idempotence, constant-default healing, missing-raw-column errors), and gate pass/fail behavior.
• Builder test patches the new stage alongside hours/snap; l0-refit export fixture extended with the five columns (they join US_RELEASE_REQUIRED_PERSON_SOURCE_COLUMNS).
• Full populace-build suite passes locally.

🤖 Generated with Claude Code

[MaxGhenis]

Review — column persistence verified; the "parity by construction" claim is overstated on two of five mappings

Reviewed with a column-manifest lens (does the surface actually reach the persisted H5, not just pass a weights-side gate) plus a source check on each mapping. The persistence machinery is right. Two mappings are refinements over the retired pipeline rather than reproductions of it, which is worth documenting explicitly rather than folding into a blanket parity claim.

Persistence is enforced end-to-end — this is the right fix for the #340/#244 mechanism

Confirmed all five outputs are genuine PolicyEngine-US person input variables with no formula (is_disabled, is_blind, is_full_time_college_student bool; own_children_in_household int; veterans_benefits float). Input variables with no formula fall back to their broadcast default (False/0) when absent from the H5 — exactly the #244/#340 silent-erasure path. So persistence is what makes this stage matter, and it is enforced at two independent points:

• The stage produces the columns into the base frame (with_us_eligibility_inputs → derive_us_eligibility_inputs_from_manifest), and the build tool runs us_eligibility_inputs_signal_gate, which raises RuntimeError if any column is missing/constant or its weighted share leaves the plausibility band.
• US_ELIGIBILITY_INPUTS_NONCONSTANT_PERSON_COLUMNS (all five) is spliced into US_RELEASE_REQUIRED_PERSON_SOURCE_COLUMNS, so assert_required_us_release_source_columns(export_frame) — called in export_us_l0_refit_h5 immediately before write_dataset — hard-fails the export if any of the five is missing or constant in the frame that gets written.

That is precisely #340's requested action ("fail release when a PolicyEngine input variable consumed by any validation-suite reform/backtest is absent from the persisted H5"), and it is invisible to weights-side gates by construction. The _disabled_carries_signal idempotence guard (recompute a constant-default surface rather than trust it) is the correct handling of the healing case. Good.

Mapping sources — three are exact parity, two are refinements presented as parity

Checked each mapping against the retired enhanced-CPS cps.py:

• is_blind ← PEDISEYE == 1: matches retired cps.py exactly. Parity. ✓
• own_children_in_household: the PEPAR1/PEPAR2-within-PH_SEQ parent-pointer count matches the retired children_per_parent construction. Parity. ✓
• veterans_benefits ← max(VET_VAL, 0): direct mapping, floored. Parity in substance. ✓
• is_full_time_college_student ← (A_HSCOL == 2) & (A_FTPT == 1): the retired pipeline used A_HSCOL == 2 alone and never read A_FTPT. This is a divergence, not parity. I verified against the Census ASEC 2024 data dictionary that A_FTPT is school enrollment intensity ("Is ... enrolled in school as a full-time or part-time student"; 1 = full time, 2 = part time; universe A_ENRLW=1) — not employment — so the added filter is a legitimate refinement that makes the flag truer to its name (it correctly drops part-time college students the retired mapping swept in). But it is a behavioral change to the retired surface: PolicyEngine-US reads is_full_time_college_student in is_snap_higher_ed_student and meets_snap_parent_exception, so narrowing it moves who is subject to the SNAP higher-ed-student restriction.
• is_disabled ← any PEDIS* == 1 OR (under-65 reported SSI_VAL > 0): the retired cps.py construction is the six-item battery alone. The added SSI alignment is attributed to a "retired align_reported_ssi_disability rule", but I couldn't find that named rule in the retired code (local clone or archived-repo code search). Either it was ported faithfully from a retired stage I couldn't locate, or it's a new (defensible) refinement — please confirm which, and cite it, rather than asserting parity.

Recommendation

The persistence design is solid and I'd be comfortable with the mappings on their merits — both refinements arguably improve accuracy. The single ask is honesty about scope: #352 documents its one pregnancy-rate divergence from the retired pipeline cleanly in the module and manifest notes; do the same for the is_full_time_college_student full-time filter and the is_disabled SSI alignment, so "parity by construction" isn't claimed for mappings that are supersets/refinements. That also gives the SNAP student-surface change an audit trail.

Tests are thorough (the full/part-time split, both SSI-alignment paths, cross-household pointer isolation, negative flooring, gate pass/fail, idempotent pass-through). CI is green on test/wheels for 3.13 and 3.14. Not merging — review only.

[MaxGhenis]

Follow-up on the is_veteran / #24 boundary and the downstream plumbing, since both are load-bearing for this stage's purpose.

The is_veteran boundary is correct. Confirmed is_veteran is formula-owned in PolicyEngine-US (formula returns person("veterans_benefits", period) > 0), so exporting veterans_benefits (the measured input dollars) and not is_veteran is exactly right — persisting a formula-owned flag is the #24 over-export failure, because the engine would then read the stale persisted value instead of recomputing. Exporting the input that drives the formula is the correct lever.

And that lever actually reaches the work requirement. veterans_benefits → is_veteran is read directly in meets_snap_abawd_work_requirements (the pre-HR1 exemption branch: is_veteran = person("is_veteran", period)), and is_disabled is read at exemption (B) (7 U.S.C. 2015(o)(3)(B)). So the two channels this stage most affects are live in the pinned pe-us ABAWD formula, not just nominally present. Before this stage they default (False/0) and those exemptions never fire, over-stating ABAWD ineligibility — which is the concrete reason the persistence fix matters for the pre-OBBBA §10102 counterfactual becoming scoreable.

This doesn't change the review above: the persistence design is sound and the #293 template is followed cleanly. The one open item remains documenting the two mapping refinements (is_full_time_college_student's A_FTPT == 1 filter and is_disabled's SSI alignment) as deliberate divergences rather than parity.

[daphnehanse11]

Thanks — the persistence-lens review caught exactly the right question, and chasing it turned up receipts: both mappings are retired-pipeline constructions, so I've replaced the blanket parity claim with per-mapping citations rather than reframing them as divergences (pushed in 0371324, plus a follow-up: the manifest's incumbent-dependency guard forbids naming the retired package in stage text, so the file/line citations live in the stage module docstring).

is_disabled SSI alignment — align_reported_ssi_disability is defined in the retired repo at datasets/cps/takeup.py#L38-L45 (is_disabled | (reported_ssi & (ages < 65))), imported in cps.py#L33-L37 and applied to is_disabled in the take-up block at cps.py#L751-L757. History reaches back to at least 2026-03-19 ("Fix PR 607 SSI alignment"), well before the 2026-07-02 archival — it likely hid from the search because it lives in takeup.py, not cps.py.

is_full_time_college_student A_FTPT filter — the retired cps.py applies (A_HSCOL == 2) & (A_FTPT == 1) whenever A_FTPT is loaded (cps.py#L1222-L1228), and census_cps.py includes A_FTPT in the raw person load (census_cps.py#L323) — so the published surface ran the strict form, and I agree your data-dictionary read confirms it's also the semantically correct one. The one true divergence, now documented in the docstring: the retired A_HSCOL-only fallback (for loads without A_FTPT) is deliberately not reproduced — this stage requires A_FTPT and fails loudly.

CI is re-running on the citation commits.

[daphnehanse11]

Addendum for the final state of the branch: the citation form went through one more revision — the incumbent-independence rule turns out to be enforced at two layers, and the receipts comment above only reflects the first.

1. The source-manifest loader rejects stage JSON containing the retired package name (caught locally, fixed in 0371324 by keeping citations out of the manifest).
2. The behavioral-contract suite (test_us_plan.py) sweeps all build source text for the literal, allowlisting only the pinned parity-reference machinery (parity_reference.py / ecps_parity_reference.json) — which is why the docstring citation failed CI even after the manifest fix.

Final form (0c3d890): the module docstring cites "the retired enhanced-CPS repo @ 42ed5d45c5" plus in-repo file paths (datasets/cps/takeup.py, cps.py's take-up block, census_cps.py's raw load list) per mapping, and the full GitHub permalinks live in the receipts comment above for the review record. All four checks green on 0c3d890.

Net diff vs what you reviewed: docstring citation wording only — no behavioral change to any mapping, gate, or test.