Seed TANF and EITC take-up from administrative rates; engine-asserted take-up contract (#312)

[MaxGhenis]

Fixes #312 (first tranche: contract inventory + the two provenance-clean seeds + release wiring).

Headline findings

• At the pinned engine (policyengine-us 1.752.2) all 13 takes_up_* variables are data-seeded: default=True, no formula, no *_seed/rate-parameter machinery. The model-side take-up migration referenced in the issue has not reached the pinned release, so every take-up-gated program ships at mechanical 100% participation unless the dataset seeds it (this generalizes Add Medicaid and CHIP eligibility-to-enrollment diagnostics #170's Medicaid finding to the whole class).
• One incumbent rate was fabricated: us-data's EITC 3+-children take-up (0.85) does not appear in the IRS/Census sources; the published figure is 0.82 (Census/NTA, TY2016 series). Seeded with the corrected value.

What ships

• us/take_up_contract.json + us_runtime/take_up_contract.py — engine-asserted contract inventory (same derive-from-metadata doctrine as Derive the formula-owned-output rejection set from engine metadata (blocklist can go stale) #301); adapter methods on the PE-US engine adapter; registered as a country-package resource.
• us_runtime/take_up.py — TANF + EITC seeding stages: deterministic draws keyed on source identity (clone-consistent), reported-receipt anchoring not available on the base spine (documented), calibrated Bernoulli at administratively sourced rates: TANF 0.219 (HHS ASPE 24th Report, Table 10, 2022), EITC by child count (Census/NTA + IRS corroboration). Signal gate (missing column / constant-true landmine / share-band) hard-fails the release; healing recomputes a constant-true landmine column.
• Release tool: stage + gate applied after the immigration block; standalone us_take_up_participation.json diagnostics artifact (per-program participation vs administrative rate, covering ALL 13 flags — unseeded rows record ships_at_engine_default honestly). Deliberately not threaded through the manifest gate-assembly (that is Wire the eCPS parity_gate into the US release with a pinned reference and a reason'd exemption register #313's zone).
• All other programs unseeded with recorded reasons: DC PTC (self-referential denominator), Head Start/Early HS (research-only rates, not admin), Medicaid/CHIP/SSI (ceiling artifact / no current standalone rate / scope mismatch), Housing (no rate ever), Medicare (near-universal by design), SNAP (in flight in Assign SNAP take-up from reported receipt and the FNS participation rate #294), ACA (native stage; Migrate ACA health-input gates after PE-US take-up contract changes #76/Jointly calibrate ACA take-up to CMS APTC people and SOI PTC returns #168). Follow-up: source these as Ledger facts.

Verification

• Engine-present run (before the env was re-synced to CI's leaner surface): all take-up, contract, and adapter tests pass.
• CI-mirror env (no policyengine_us): full workspace suite exit 0 with clean module-level skips; ruff check clean.
• Builder test extended with take-up fakes following the immigration idiom; spec-only country-package test satisfied by resource registration.

Provenance

Built by directed agents (inventory + provenance verification by two parallel primary-source checkers; stages + wiring) with the lead session performing the final test class, integration fixes, and PR. Squash-merge recommended (history carries WIP salvage checkpoints).

PROGRESS — take-up inputs (#312)

Branch: takeup-inputs off origin/main (7e9a32d).
Sibling: #313 ecps-parity-gate (gate/release wiring) — avoid gate-assembly region of release tool; rebase before PR.

Doctrine (from spec)

• Contract inventory FIRST (blocking): JSON table, engine-version-asserted (same as Derive the formula-owned-output rejection set from engine metadata (blocklist can go stale) #301).
• Class (b) seeding: reported-receipt-anchored (Assign SNAP take-up from reported receipt and the FNS participation rate #294 pattern) OR calibrated Bernoulli by admin rate.
• HARD RULE: every rate cites an administrative source (FNS/CMS/IRS/ACF, URL+vintage) in stage metadata. Rate-unsourced → leave unseeded, flag in report (stays Wire the eCPS parity_gate into the US release with a pinned reference and a reason'd exemption register #313 exemption; follow-up = source as Ledger fact).
• Exclusions: NO SNAP (Assign SNAP take-up from reported receipt and the FNS participation rate #294 in flight), NO ACA flag-seeding (model-simulated per Migrate ACA health-input gates after PE-US take-up contract changes #76), NO base-pool regen.
• Ambiguous classification → flag, do not decide (take-up semantics guardian-owned).

Steps

• 0. Setup + read Assign SNAP take-up from reported receipt and the FNS participation rate #294 pattern, source-stage machinery, Derive the formula-owned-output rejection set from engine metadata (blocklist can go stale) #301 metadata guard
• 1. Determine pinned PE-US version (1.752.2), install it
• 2. Contract inventory: enumerate takes_up_* / *_take_up_seed, classify by formula/default (13, all data_seeded)
• 3. Checked-in JSON table + test asserting it vs installed engine (COMMITTED+PUSHED)
• 4. Seeding stages for TANF + EITC (calibrated Bernoulli, source-id-keyed, Assign SNAP take-up from reported receipt and the FNS participation rate #294-style module)
• 5. Rate provenance: verified; only TANF (ASPE) + EITC (IRS NTA) clear the admin bar; rest rate_unsourced
• 6. Diagnostics: per-program participation vs admin count (extend Add Medicaid and CHIP eligibility-to-enrollment diagnostics #170) in release diagnostics
• 7. Tests: [x]inventory-vs-engine; [ ]per-stage seeding (deterministic/rate-reproduced/reported-anchor); [ ]prove-it-can-find-something on gate/diagnostic
• 8. Rebase onto origin/main, PR via --body-file (no merge)

Architecture decisions

• Seeding = dedicated take_up.py runtime module (like Assign SNAP take-up from reported receipt and the FNS participation rate #294 snap_take_up.py), NOT the generic ACA assign_binary_from_rate handler — because that handler keys draws on tax_unit_id, breaking the required source-identity clone-consistency. My module keys on source_year/source_household_id/source_person_id like Assign SNAP take-up from reported receipt and the FNS participation rate #294.
• TANF + EITC both = calibrated Bernoulli (no reported-receipt column threaded through populace base spine; ASEC PAW_VAL not carried, threading it = base-pool scope = out). EITC rate varies by num_children.
• Stay OUT of the gate-assembly region of build_us_fiscal_refresh_release.py (sibling Wire the eCPS parity_gate into the US release with a pinned reference and a reason'd exemption register #313). Add take-up gate/diagnostic wiring minimally, mirroring how SNAP Assign SNAP take-up from reported receipt and the FNS participation rate #294 threads (but Assign SNAP take-up from reported receipt and the FNS participation rate #294 not merged, so I wire independently and note rebase risk).

Log

• Setup: worktree created, read spec/DESIGN.md/PR#294 summary. Wire the eCPS parity_gate into the US release with a pinned reference and a reason'd exemption register #313 branch not yet pushed to origin.
• Installed pinned PE-US = 1.752.2 (pin >=1.745.0,<2).
• CONTRACT INVENTORY (engine-derived, rigorous): 13 takes_up_* vars. ZERO *_seed vars. ZERO model-simulated. ALL 13 have default=True + NO formula = class (b) data-seeded. NONE dead (all consumed via formula or adds).
  • BLOCKING FINDING for lead: the chip_take_up_seed/aca_take_up_seed model-side migration the spec references has NOT landed in the pinned engine. Classifying by installed engine per doctrine.
  • Consumers: snap→snap, tanf→tanf, eitc→eitc(+5 state), dc_ptc→dc_ptc, head_start→head_start, early_head_start→early_head_start, housing_assistance→housing_assistance, medicaid→medicaid_enrolled[adds], chip→chip_enrolled[adds], basic_health_program→bhp_enrolled[adds], medicare→medicare_enrolled[adds], ssi→ssi, aca→person_receives_aca+3.
• SCOPE: exclude SNAP(Assign SNAP take-up from reported receipt and the FNS participation rate #294), ACA(spec hard boundary, flag engine mismatch). Seed-candidates gated by PROVENANCE: TANF, EITC, DC PTC, Head Start, Early Head Start, Housing, Medicaid, CHIP, BHP, Medicare, SSI.
• NEXT: per-program admin-rate sourcing (decisive filter); ASEC reported-receipt availability (anchor vs Bernoulli).
• Adapter method take_up_contract() + take_up_variables() added to policyengine_us.py (+ _references_variable helper). Verified vs 1.752.2: all 13 = data_seeded.
• PROVENANCE VERIFICATION COMPLETE (2 parallel agents, primary-source-checked):
  • TANF 0.22 → SOURCED-ADMINISTRATIVE: HHS ASPE 24th Report Table 10 Ind.4 = 21.9% (2022). us-data mislabeled vintage 2018. SEED w/ correct vintage.
  • EITC by #children → SOURCED (IRS NTA/Census): NTA 2020 Fig A.7 TY2016: 0=0.65,1=0.86,2=0.85 MATCH; 3+=0.82 NOT 0.85 (us-data fabricated 0.85). IRS headline 78% corroborates. SEED w/ CORRECTED 3+=0.82.
  • DC PTC → MODEL-RELATIVE (37,133 real but ÷ PE-model denom; self-referential). rate-unsourced, unseeded.
  • Head Start 40/30 + Early HS 9 → SOURCED-RESEARCH-ONLY (NIEER=Rutgers, NOT ACF/federal); year-split is artifact. Fails admin-source bar → rate-unsourced, unseeded (follow-up: ACF Head Start Program Facts).
  • Medicaid (state) → UNSUPPORTED/MODEL-RELATIVE (0.99=ceiling artifact). CHIP → no standalone current rate. SSI 0.50 → aged-65+ only (49%), scope-mismatch to all-SSI. ALL rate-unsourced, unseeded (Add Medicaid and CHIP eligibility-to-enrollment diagnostics #170/Add Medicaid and CHIP eligibility-to-enrollment diagnostics #170 follow-up: source as Ledger facts).
  • Medicare → NEAR-UNIVERSAL-BY-DESIGN (~100% correct, seeding not meaningful). Document, unseeded.
  • Housing → no rate ever existed. rate-unsourced, unseeded.
  • ACA → OUT OF SCOPE (spec hard boundary; populace already has native ACA stage in source_stages.json).
• DECISION: seed exactly TANF + EITC (both verified administrative/IRS provenance). All others: rate-unsourced OR out-of-scope OR near-universal. This is the honest ledger#77-safe outcome.