Draft: Integrate modeled state unemployment insurance into income flows

[daphnehanse11]

Tracks #8301.

Purpose

This is the draft umbrella PR for wiring modeled state unemployment insurance benefits into unemployment_compensation and downstream income flows.

Keep this PR as a draft until the relevant state rules and policyengine-us-data pipelines are ready. State UI rule implementations can still merge separately when they are calculator-safe; this PR is for the baseline microsimulation integration step.

Why draft

The current PA wiring is conceptually right for household calculations, but it should not enter baseline aggregation until enhanced CPS can populate or impute the required wage-history and unemployment inputs. Otherwise, the integration would be partial: modeled UI would depend on inputs that are not yet available in the microsim data pipeline, and could mix calculator-only logic into baseline income flows prematurely.

Scope

• Add modeled state UI variables to unemployment_compensation only after each state has usable data inputs.
• Coordinate with policyengine-us-data for extraction/imputation of required variables.
• Add microsimulation regressions that protect reported unemployment compensation and validate nonzero modeled UI where expected.
• Use this branch as the collection point for aggregator wiring across states.

Current contents

• PA UC aggregator wiring and an income-flow test. This is kept here as the first candidate integration, but it is not merge-ready until the data pipeline prerequisites are met.

Checklist

• Inventory state UI variables and required inputs for each modeled state.
• Keep state UI rule/calculator PRs separate where they can safely merge without baseline aggregation.
• Add or impute required inputs in policyengine-us-data.
• Bump policyengine-us-data minimum policyengine-us version after any new model variables are released.
• Validate enhanced CPS has nonzero modeled UI for expected state populations.
• Add a microsim regression confirming unemployment_compensation does not drop relative to the reported baseline.
• Add state UI variables to unemployment_compensation.adds once data-backed.
• Re-run targeted UI, household income-flow, TaxSIM, and full CI checks.
• Undraft only after the data pipeline and microsim validation are complete.

Tests so far

These passed for the current PA-only wiring, but they are not sufficient to merge this PR:

• uv run python -m policyengine_core.scripts.policyengine_command test policyengine_us/tests/policy/baseline/gov/states/pa/dli/unemployment_compensation -c policyengine_us
• uv run python -m policyengine_core.scripts.policyengine_command test policyengine_us/tests/policy/contrib/taxsim/taxsim_v11.yaml -c policyengine_us
• uv run python -m policyengine_core.scripts.policyengine_command test policyengine_us/tests/policy/baseline/household/income/spm_unit/spm_unit_benefits.yaml -c policyengine_us
• uv run --extra dev ruff check policyengine_us/variables/gov/states/unemployment_compensation.py
• uv run --extra dev ruff format --check policyengine_us/variables/gov/states/unemployment_compensation.py

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (8cb60e7) to head (6198da9).
⚠️ Report is 21 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #8303   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         1    -2     
  Lines           63        10   -53     
=========================================
- Hits            63        10   -53     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[MaxGhenis]

Converted this to a draft umbrella PR for modeled state UI income-flow integration. The PA UC wiring is a useful first candidate, but we should not merge it into baseline unemployment_compensation until the corresponding policyengine-us-data inputs/imputations and microsim regression are in place. That avoids shipping a partial calculator-only aggregation path before enhanced CPS can support it.