Implement Alabama Unemployment Insurance (al_ui) (ref #8282)

[daphnehanse11]

Summary

Implements the Alabama Unemployment Insurance program (Code of Alabama Title 25, Chapter 4).
Closes #8282.

Regulatory Authority

• Code of Alabama § 25-4-72 (Weekly Benefit Amount)
• Code of Alabama § 25-4-74 (Maximum Duration & MBA)
• Code of Alabama § 25-4-75 (Total Amount Payable)
• Code of Alabama § 25-4-77 (Eligibility)
• Alabama UC Benefit Rights and Responsibilities handbook
• Ala. Admin. Code 480-4-3 (Benefits)
• USDOL 2023 Comparison of State UI Laws — Monetary chapter

Monetary Eligibility (§ 25-4-77(a)(4))

A claimant is monetarily eligible if ALL of the following are true:

1. Wages reported in at least 2 quarters of the base period
2. Total base-period wages ≥ 1.5 × the high-quarter wages
3. Unrounded weekly benefit amount > $44.50

Weekly Benefit Amount (§ 25-4-72(b))

• Formula: WBA = (High Quarter Wages + 2nd-High Quarter Wages) / 52
• Rounding: Nearest $1; ties round DOWN (Alabama-specific; implemented via np.ceil(x - 0.5))
• Min: $0 if unrounded ≤ $44.50; otherwise rounded amount
• Max: $275 (effective 2020-01-01; Act 2019-204)

Maximum Benefit Amount and Duration (§ 25-4-74(a))

• Duration: Sliding-scale tied to the state's unemployment rate (Act 2019-446):

State unemployment rate	Maximum weeks
≤ 6.5%	14
> 6.5% to ≤ 7.0%	15
> 7.0% to ≤ 7.5%	16
> 7.5% to ≤ 8.0%	17
> 8.0% to ≤ 8.5%	18
> 8.5% to ≤ 9.0%	19
> 9.0%	20

• MBA dual-cap: min(max_weeks × WBA, ¼ × base-period wages), rounded to nearest $1
• State unemployment rate is sourced from FRED ALUR (monthly values stored as a parameter)

Partial-Benefit Provisions (§ 25-4-72; NELP 2015 reform)

• A claimant is on partial unemployment if weekly earnings < WBA
• Earnings disregard: 1/3 × WBA (effective 2015-06-13 onward)
• Partial weekly benefit = max(WBA - max(weekly_earnings - WBA/3, 0), 0)

Waiting Week

• 1 non-compensable week subtracted from the duration of payable benefits
• Effective 2012-08-01 per BRR handbook p. 6 and Admin Code 480-4-3

Requirements Coverage

REQ	Description	Param	Variable	Test
REQ-001	≥2 base-period quarters	eligibility/quarters_with_wages.yaml	al_ui_monetarily_eligible.py	al_ui_monetarily_eligible.yaml
REQ-002	BPW ≥ 1.5 × HQW	eligibility/bpw_to_hqw_multiplier.yaml	al_ui_monetarily_eligible.py	al_ui_monetarily_eligible.yaml
REQ-003	Unrounded WBA > $44.50	wba/min_threshold.yaml	al_ui_monetarily_eligible.py, al_ui_weekly_benefit_amount.py	al_ui_weekly_benefit_amount.yaml
REQ-004	WBA = (HQW + 2HQW) / 52	—	al_ui_unrounded_wba.py	al_ui_unrounded_wba.yaml
REQ-005	Ties-down rounding	—	al_ui_weekly_benefit_amount.py	al_ui_weekly_benefit_amount.yaml
REQ-006	WBA = 0 when ≤ threshold	wba/min_threshold.yaml	al_ui_weekly_benefit_amount.py	al_ui_weekly_benefit_amount.yaml
REQ-007	WBA cap $275	wba/max.yaml	al_ui_weekly_benefit_amount.py	al_ui_weekly_benefit_amount.yaml
REQ-008	UR-bracket 14-20 weeks	mba/duration_weeks.yaml, state_unemployment_rate.yaml	al_ui_max_weeks.py	al_ui_max_weeks.yaml
REQ-010	MBA dual-cap	mba/bpw_fraction.yaml	al_ui_maximum_benefit_amount.py	al_ui_maximum_benefit_amount.yaml
REQ-011	MBA rounded to $1	—	al_ui_maximum_benefit_amount.py	al_ui_maximum_benefit_amount.yaml
REQ-012	Partial-week threshold	—	al_ui_partial_weekly_benefit.py	al_ui_partial_weekly_benefit.yaml
REQ-013	1/3 WBA disregard	partial/disregard_rate.yaml	al_ui_partial_weekly_benefit.py	al_ui_partial_weekly_benefit.yaml
REQ-014	1 waiting week	waiting_weeks.yaml	al_ui.py	al_ui.yaml, integration.yaml

Not Modeled

• Training-program +5-week extension (§ 25-4-74(b)) — opt-in, requires participation data not in CPS
• Extended Benefits (§ 25-4-75) — federally-triggered, transient
• Non-monetary eligibility (able/available/seeking work) — not simulatable
• Disqualifications (voluntary quit, misconduct, refusal, labor dispute) — requires reason-for-unemployment data
• Federal-conformity escalator on WBA max — programmatic, not in claimant calculations
• Alternative base period — Alabama has none
• Dependents' allowance — Alabama has none
• Pre-2020 history (uniform 26-week cap, pre-2015 $15 partial disregard) — out of scope per scope decision

Historical Notes

All AL UI parameters in this PR start at 2020-01-01, matching the effective date of Act 2019-204 which introduced:

• The current $275 WBA cap (previous: $265 from 2009; $255 from 2008)
• The unemployment-rate-tied duration bracket (replacing a flat 26-week cap)

The 1/3 partial-earnings disregard has been in effect since 2015-06-13 (prior was a flat $15) — using the 2020-01-01 effective date in the parameter is conservative (i.e., the rule was already in effect by then).

State unemployment rate values in state_unemployment_rate.yaml are approximate decimal-form FRED ALUR series values for 2020-01 through 2026-04. Reviewers should verify these against the authoritative FRED series before merge.

Test Coverage

• 76 YAML test cases across 8 unit-test files + 1 integration file
• All tests pass (verified by implementation-validator)
• Coverage includes: each formula variable's edge cases, all 7 duration brackets, both MBA caps binding, half-down rounding boundaries, monetary ineligibility scenarios, partial-week dynamics, full annual-benefit lifecycle, multi-person and cross-state cases

Files Added

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/
├── eligibility/
│   ├── bpw_to_hqw_multiplier.yaml
│   └── quarters_with_wages.yaml
├── index.yaml
├── mba/
│   ├── bpw_fraction.yaml
│   └── duration_weeks.yaml
├── partial/
│   └── disregard_rate.yaml
├── state_unemployment_rate.yaml
├── waiting_weeks.yaml
└── wba/
    ├── max.yaml
    └── min_threshold.yaml

policyengine_us/variables/gov/states/al/dol/unemployment_insurance/
├── al_ui.py
├── al_ui_base_period_wages.py
├── al_ui_high_quarter_wages.py
├── al_ui_max_weeks.py
├── al_ui_maximum_benefit_amount.py
├── al_ui_monetarily_eligible.py
├── al_ui_partial_weekly_benefit.py
├── al_ui_quarters_with_wages.py
├── al_ui_second_high_quarter_wages.py
├── al_ui_unrounded_wba.py
├── al_ui_weekly_benefit_amount.py
└── al_ui_weekly_earnings.py

policyengine_us/tests/policy/baseline/gov/states/al/dol/unemployment_insurance/
├── al_ui.yaml
├── al_ui_max_weeks.yaml
├── al_ui_maximum_benefit_amount.yaml
├── al_ui_monetarily_eligible.yaml
├── al_ui_partial_weekly_benefit.yaml
├── al_ui_unrounded_wba.yaml
├── al_ui_weekly_benefit_amount.yaml
├── integration.yaml
└── set_state_unemployment_rate.py (reform helper)

Modified: policyengine_us/variables/gov/states/unemployment_compensation.py — added al_ui to the adds list so it flows into the federal unemployment_compensation aggregator.

[codecov]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff             @@
##              main     #8283    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files            3        13    +10     
  Lines           63       168   +105     
==========================================
+ Hits            63       168   +105     

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.