Reviewed CMS Medicaid enrollment substitution register for the take-up gate (#386)

[MaxGhenis]

For the Medicaid stage owner's review

This implements the conductor recommendation on #386: a reviewed-substitution register at the Medicaid take-up gate, rather than relaxing the gate. It is deliberately staged for the Medicaid stage owner's review before merge — the substitution touches what the release calibrates state Medicaid enrollment to.

The problem (#386)

The #334 Medicaid take-up gate fails closed on the first full-release run (#368 Build J): Rhode Island's December 2024 CMS snapshot is unreported at source. Both RI 202412 rows in the pinned pi-dataset-april-2026-release.csv carry Total Medicaid Enrollment = 0 under the footnote "Unable to Provide Data due to System Limitations", so the point-in-time snapshot compiles to no FIPS-44 medicaid_enrollment spec and the count-calibration gate fails on states without CMS enrollment targets: ['44'].

The fix

A reviewed-substitution register maps RI to its nearest-prior reported month. No Ledger fact is synthesized — the substitution lives at the registry-compile/gate layer, where it is auditable per release:

• Substituted fact: cms_medicaid.month2024_11.state_enrollment.ri.total_medicaid_enrollment
• Value: 273,400 (RI November 2024 Total Medicaid Enrollment)

Verified against the pinned ledger source: the RI 202411 final (U/Y) row reports Total Medicaid Enrollment = 273400 with no footnote (and 273,400 Medicaid + 32,761 CHIP = 306,161 total, internally consistent), while RI 202412 is the footnoted 0.

The register injects a medicaid_enrollment TargetSpec for RI, cloning an existing state spec's calibration/materialization shape and re-pointing its identity and value, stamping the substitution provenance (the CMS footnote, the substituted-for month, the tracking issue) into the spec metadata.

Wiring

• Applied once after the target-registry compile, before the dense/sparse split, so the injected spec flows through target_specs into the materialized calibration registry that both the dense (calibrate) and sparse (calibrate_l0_refit) arms consume, and into the take-up target table.
• Take-up diagnostics: the substitution records ride with_us_medicaid_take_up into the take-up diagnostics and the us_medicaid_take_up.json release artifact.
• Manifest: the applied records land in build_manifest.json alongside the target-registry version that carries the injected spec's provenance metadata, and the metadata survives compilation into the calibration TargetSet (the diagnostics target surface). So release artifacts show exactly which point-in-time counts were substituted, and why.

Cannot-rot semantics

The register cannot outlive its justification. A substitution applies only while its substituted-for month is genuinely absent. The moment CMS backfills a real RI December-2024 count, the natural FIPS-44 spec reappears, the register marks the entry stale and injects nothing, and the take-up gate fails — forcing the entry's removal (the #286 stale-exclusion doctrine, applied to a substitution register).

Alternatives considered

• T-MSIS cross-source for the same month: heavier lift, different concept basis — better as the durable fix if CMS never backfills.
• Ship RI anchored-only with a caveat: rejected — exactly the silent-degradation class the gate exists to stop.

Tests

packages/populace-build/tests/test_us_medicaid_take_up.py::TestReviewedSubstitutionRegister:

• test_pass_with_substitution — the gate fails closed on FIPS 44 without the register and passes once RI gains its substituted target.
• test_fails_without_substitution_on_a_genuinely_missing_state — a genuinely-missing state with no register entry still fails, so the register is not a blanket bypass.
• test_cannot_rot_fails_when_the_backfilled_ri_fact_appears — a backfilled RI December fact marks the entry stale, injects nothing, and fails the gate.
• test_substitution_metadata_reaches_the_compiled_spec — the provenance survives into the compiled TargetSet the solver and diagnostics consume.
• test_register_pins_rhode_island_to_the_ledger_value — pins the single reviewed entry against silent drift.
• test_registry_without_medicaid_family_is_a_no_op — a registry with no medicaid_enrollment family at all records every entry inapplicable and injects nothing (the register is not the owner of Medicaid-absence; the take-up stage's empty-target guard is).

uv run pytest is clean — 1,622 passed / 54 skipped in a CI-identical venv (no us extra), and 37 passed in test_us_medicaid_take_up.py with policyengine-us installed — and ruff check / ruff format --check are clean on the changed files.

Refs #386, #334, #368.

🤖 Generated with Claude Code