Materialize Medicaid take-up via anchored count-calibration to CMS state snapshots

[daphnehanse11]

Summary

Implements #331 (and the doctrine half of #332): takes_up_medicaid_if_eligible is now materialized by a medicaid_take_up source stage instead of shipping at the engine's all-True default, healing the #170 enrollment == eligibility degeneracy (72.30M == 72.30M in the published 2024 release) and stopping weight calibration from absorbing take-up error into the eligible population.

No administrative participation rate clears the #315 provenance bar for Medicaid (us-data's state rates were MACPAC enrollment over modeled eligibility — a model-relative ratio), so this stage cites no rate. It follows the native ACA stage pattern instead, recorded as a new contract treatment:

• count_calibrated contract treatment: anchored assignment calibrated to administrative enrollment counts (Ledger facts). Loader validation requires a calibration block naming the anchor and target fact families, and refuses a sourced rate (that would be seed misclassified).
• Anchor: eligible reporters of has_medicaid_health_coverage_at_interview (CPS ASEC, point-in-time) always take up. CPS undercounts Medicaid, so the anchor is a floor.
• Fill: everyone else draws at an in-build state fill rate (CMS count over weighted modeled eligibles — computed transparently, never cited as provenance), then calibrate_binary_assignment greedily hits the CMS December 2024 state snapshot among eligible non-anchored persons.
• Point-in-time semantics (Declare point-in-time (average-month) semantics for enrollment take-up flags and snapshot-month provenance #332): anchor, targets, and concept all sit at a representative month — the Urban HIPSM convention ("a point-in-time snapshot … rather than an annual average"), now contract doctrine. Ever-enrolled counts would overstate spending against per-FYE cost denominators.

Mechanics

• Builder mirrors the ACA stage: batched engine simulation materializes person-level is_medicaid_eligible, the medicaid_enrollment target role compiles the state target table, and the stage output writes back to the person table.
• Gate: fails on the all-True landmine (unsaturated state with enrollment == eligibility), a missed CMS count beyond 2% relative, a dropped anchor, or a state missing its target row. Saturated states (CMS count ≥ modeled eligible weight — Add Medicaid and CHIP eligibility-to-enrollment diagnostics #170's −2.4% combined shortfall) are classified and reported, not failed: full enrollment is the calibrated answer there, and the shortfall is an eligibility-undercount question out of scope here.
• Off-domain propensity: the assign op deliberately carries no eligibility mask, so persons outside today's modeled eligibility keep a draw-based flag at the state fill rate. Invisible at baseline (the engine gates on is_medicaid_eligible), but eligibility-expanding reforms enroll newly eligible people at a plausible propensity instead of a hard-coded zero. Not a behavioral model — that is future utility-layer work.
• Removes takes_up_medicaid_if_eligible from the reviewed degenerate-input exclusions (that registry fails when a listed column becomes non-degenerate).
• Diagnostics artifact us_medicaid_take_up.json written beside the take-up participation diagnostics; the participation diagnostics now report count_calibrated programs' live surface instead of "ships at engine default".

Deliberately out of scope

• CHIP: blocked on CHIP enrollment targets are concept-mismatched: CMS total_chip_enrollment includes M-CHIP; model materializes separate CHIP only (20 states zero-support) #321 — CMS total_chip_enrollment mixes M-CHIP into a concept the model does not materialize (20 states zero-support). The contract entry records the dependency; CHIP follows this pattern once the ledger splits the concepts.
• Within-year churn / ever-enrolled semantics (longitudinal frame direction).

Tests

• 23 new tests in test_us_medicaid_take_up.py: contract validation (calibration block required, sourced rate refused), anchor preservation (including model-ineligible reporters), unsaturated states hitting the CMS count to unit-weight granularity, saturation classification, bit-reproducible reruns, source-identity draw keying, off-domain propensity, gate failure modes (landmine, missing target, dropped anchor, anchor-above-count floor), and builder helpers (target-role filtering, person state mapping).
• Updated: contract treatment enum test, builder main() end-to-end stubs, US_DONORS/stage-order plan alignment.
• Full workspace suite green (uv run pytest), ruff check clean.

Closes #331. Refs #332, #170, #321, #323, #315.

🤖 Generated with Claude Code

[daphnehanse11]

Ran an adversarial multi-angle review of this branch (8 finder angles, per-finding verification) before marking ready. Outcome, for reviewer context:

Confirmed and fixed in 2cb7f97:

• Checkpoint staleness: the target-frame checkpoint identity hashes the on-disk base dataset, not the staged frame, so a pre-branch checkpoint would have silently calibrated weights against all-True medicaid_enrolled. TARGET_FRAME_CHECKPOINT_MATERIALIZER_VERSION bumped to 2.
• Gate landmine false-positives: full enrollment explained by anchor mass (all eligibles reported coverage) or by greedy overshoot within one person weight of the count is a legitimate outcome; the check now exempts both instead of aborting the build.
• Anchor preservation is now a person-level invariant (anchored_not_taking_up_count) checked in every state including saturated ones — aggregates can't see a dropped anchor once calibration back-fills to the count.
• Stale eCPS parity exemption for takes_up_medicaid_if_eligible deleted (its "Populace does not yet produce it" reason is false as of this PR; parity_gate has no staleness check so it would have exempted the layer forever).
• Duplicate per-state target rows now refuse to compile (calibrate op is last-row-wins; rate/diagnostics/gate sum them).
• Export-frame re-check: a count-calibrated column shipping at the engine default on the export frame now fails the release rather than being recorded observationally.
• Participation diagnostics keep the scope_owner debt pointer on count_calibrated rows and label the share's universe (the flag deliberately carries off-domain propensity Trues).
• Reuse: draws now delegate to take_up._stable_unit_draws, person state codes use Frame.broadcast; empty targets refuse early; dead knobs removed.

Refuted in verification (no change): NaN CMS targets can't reach the stage — ledger compilation enforces math.isfinite at both entry points.

Known accepted interplay: if literally every state saturated (CMS count ≥ modeled eligibles everywhere), the flag would be constant-True — this stage's gate passes by saturation doctrine while the degenerate-input gate fails the build. That's treated as the intended loud backstop for a pathological feed, not a contradiction to engineer away; mechanics verified, trigger judged improbable (mixed saturation map expected).

Deferred (chips filed): sharing the ACA batch sims instead of a second full-population eligibility pass (~15–45 min/build); generalizing the ACA-branded error labels in the shared binary ops; parity-gate staleness enforcement.

[daphnehanse11]

Marking ready and requesting review. One decision here is genuinely doctrine-level and yours to bless: the count_calibrated contract treatment (amends the #315 enum) — used when no administrative participation rate exists but administrative counts do, per the native ACA stage pattern your contract note describes. Your #294 approval covered the same mechanical family (reported anchor, identity-keyed draws, constant-True healing, gate); the deltas here are count-calibration in place of a cited rate, the unmasked anchor, and the off-domain propensity, all flagged in the PR body with rationale. #331/#332 carry the full design record, including the HIPSM point-in-time precedent. The register line for this flag is removed in-PR per your #294 guidance, and #339 (stacked on this branch) holds the batch-sim sharing follow-up.