US Medicare IRMAA: enrollee-gated Part B premium target and held-out IRMAA validation rows (#1206)

changelog.d/us-medicare-irmaa-holdout-1206.added.md

@@ -0,0 +1 @@
+Report held-out Medicare Part B and Part D IRMAA payers and income-related premiums against the 2026 Trustees Report Tables V.E3 and V.E4 in `us_medicare_irmaa_holdout.json`; validation only, never a calibration target or release gate. With no weighted payer (as on the locked policyengine-us 2.2.1 for 2024) it reports `no_payers` and withholds the comparisons (#1206).

changelog.d/us-medicare-part-b-premium-target-enrollees-1206.fixed.md

@@ -0,0 +1 @@
+Bind the CMS Part B premiums-from-enrollees target to `gross_medicare_part_b_premium_if_enrolled`, the enrollment-gated gross premium, instead of `gross_medicare_part_b_premium`, which also charged eligible non-enrollees (#1206). On the locked policyengine-us 2.2.1 the bound premium carries no 2024 income-related premium, so the row reads the standard premium alone, and its calibration miss widens, until Microcosm's engine includes PolicyEngine/policyengine-us#10106.

docs/agent-guide.md

@@ -224,6 +224,23 @@ SSA's SSI Annual Statistical Report 2024, Table 9. This held-out diagnostic
 never feeds calibration or refuses a release; unavailable measurements are
 reported explicitly. The report records the difference between SSA's December
 2024 recipient snapshot and the model's positive annual benefits.
+It also writes `us_medicare_irmaa_holdout.json`: weighted Medicare Part B and
+Part D income-related premium (IRMAA) payers and annual amounts, compared with
+the 2026 Medicare Trustees Report's calendar-year rows in Tables V.E3 and V.E4
+(microcosm#1206). Both Parts count `medicare_enrolled` people only (Part A
+and/or Part B). Part B is
+`gross_medicare_part_b_premium_if_enrolled - base_part_b_premium`, because the
+base premium is defined for every eligible person. Part D is
+`income_adjusted_part_d_premium_surcharge`, which policyengine-us charges every
+Medicare enrollee above the thresholds until PolicyEngine/policyengine-us#10115
+gates it on Part D enrollment. IRMAA rests on income from two years before
+the period. The locked policyengine-us 2.2.1 reads that year's inputs, and a
+single-year release H5 has none, so a 2024 release on that engine reports
+`status: no_payers` (the batched scorer gives exactly that on the certified
+`populace-us-2024-spm-20260915` file) until the engine includes
+PolicyEngine/policyengine-us#10106. A Part with no weighted payer never reports
+a Trustees comparison. It is held out the same way: no calibration row, no
+release refusal.
 Before a release rerun, run the small-H5 guard sweep described in
 [the release build rule](us-release-build-rule.md#post-export-scoring).
 That fixture check is separate from full-export timing and release

packages/microcosm-build/src/microcosm/build/us_runtime/fiscal_targets.py

@@ -452,8 +452,18 @@ def _us_hierarchy_seed(
             ),
         },
     ),
+    # 2025 Trustees Report Table III.C3 Part B premiums from enrollees.
+    # gross_medicare_part_b_premium is defined for is_medicare_eligible, so
+    # it also charges eligible people who never enrolled. PolicyEngine-US
+    # documents the enrollment-gated gross_medicare_part_b_premium_if_enrolled
+    # for CMS premiums-from-enrollees targets (microcosm#1206).
+    # The target includes income-related premiums (IRMAA). On the locked
+    # policyengine-us 2.2.1 a 2024 release has none, because IRMAA rests on
+    # income two years earlier and the H5 carries 2024 inputs only, so this
+    # row reads the standard premium alone until Microcosm's engine includes
+    # PolicyEngine/policyengine-us#10106 (see microcosm#1206 for the sums).
     ("cms_medicare", "actual_amount", "premiums_from_enrollees"): (
-        "gross_medicare_part_b_premium",
+        "gross_medicare_part_b_premium_if_enrolled",
         "cms_medicare",
         {"target_role": "medicare_part_b_premium_total"},
     ),