Example notebook: federal vs. state fiscal impact of Medicaid reforms

[MaxGhenis]

Summary

Adds an example notebook demonstrating how to use the new federal_benefit_cost and state_benefit_cost aggregates (from PolicyEngine/policyengine-us#8076) to produce federal vs. state fiscal impact estimates.

Closes #131.

What it shows

Repealing the ACA expansion FMAP (90% → state regular FMAP) as a case study:

1. Baseline national totals for federal and state Medicaid+CHIP cost
2. Reform: set gov.hhs.medicaid.cost_share.expansion_fmap to 0 (defaults to regular FMAP for expansion adults)
3. Reform vs. baseline fiscal impact, partitioned federal/state
4. Per-state breakdown showing which states bear the largest share of shifted cost

The key pedagogical point: aggregate Medicaid cost is roughly unchanged, but federal cost falls and state cost rises by roughly equal amounts. Reporting only total budgetary impact would hide the entire policy story.

Dependencies

• Requires policyengine-us with PR #8076 merged (shipped 2026-04-18)
• No dependency on policyengine-api or policyengine.py — notebook uses Microsimulation directly

Related

• Add federal vs. state cost attribution for benefit programs (Medicaid FMAP, SNAP OBBBA, CHIP eFMAP, etc.) policyengine-us#8075 (scoping)
• Add Medicaid + CHIP federal/state cost attribution via FMAP policyengine-us#8076 (microsim variables, merged)
• Add federal vs. state budgetary impact to economic_impact_analysis policyengine.py#296 (SDK surface)
• Partition budgetary_impact into federal vs. state shares policyengine-api#3482 (API surface)
• Show federal vs. state budgetary impact on US reform reports policyengine-app-v2#1000 (UI)