PolicyEngine / PolicyEngine/policyengine-us
Refactor CA CalWORKs variables from YEAR to MONTH so July COLAs take effect mid-year
- Dominant language
- Python
- Stars
- 162
- Forks
- 212
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 97
Description
## Problem
Nearly all CA CalWORKs cash variables are YEAR-defined (19 of 22; `ca_tanf`, all eligibility variables, income variables, and resource variables). YEAR-defined formulas read parameters as of January 1, so CalWORKs parameter changes effective July 1 are inert for the calendar year in which they take effect — the model applies them starting the *following* January.
This affects every CalWORKs value that adjusts on July 1:
- **Vehicle value limit** (e.g., ACL 26-38: $33,626 effective 2026-07-01) — a household with a $33,550 vehicle passes the real vehicle test July–December 2026 but the model denies it for all of 2026.
- **MBSAC income limits** (e.g., ACL 26-39, effective 2026-07-01) — a Region 1 family of 4 with monthly income between the old and new MBSAC is denied for late 2026 despite the COLA.
- **MAP levels** (same July cycle).
The resource limits (ACLs 23-71/24-54/25-65) adjust January 1, so they happen to align with the YEAR-read convention — but everything else in the program is on the July cycle.
## Current state
```
ca_tanf.py YEAR
ca_tanf_max_benefit_standard.py MONTH <- already mixed
eligibility/* (10 variables) YEAR
income/ca_tanf_earned_income_person.py MONTH <- already mixed
income/ca_tanf_earned_income_after_disregard_person.py MONTH
income/* (5 more variables) YEAR
resources/* (2 variables) YEAR
```
The program already has mixed definition periods, which forces `period.this_year` bridging in several formulas.
## Proposed refactor
Convert the CA CalWORKs cash variable tree to MONTH definition periods, consistent with most other state TANF implementations (e.g., `tx_tanf`, `dc_tanf`, `il_tanf`). This makes July-effective ACL values bind in July and removes the mixed-period bridging.
Scope (why this is a big refactor, not a quick fix):
- ~19 variable definition-period changes plus period-access updates in each formula (`period` vs `period.this_year` semantics flip for income/stock reads).
- All CalWORKs YAML tests need period/value conversion (YEAR tests input annual amounts; MONTH tests change input/output conventions).
- Downstream dependents that read `ca_tanf` (CA county GA/GR programs, `tanf` aggregate) need auditing for period mismatches.
- Boundary tests should then cover both sides of each July transition (June vs July) per testing conventions.
Found by workflow-backed code review of #9029, which added July 2026 COLA values that currently cannot take effect until January 2027.
Contributor guide
Research direction
Start with ca_tanf.py, the eligibility/*, income/*, and resources/* variables, then compare their period handling with tx_tanf, dc_tanf, and il_tanf. Run the existing CalWORKs YAML tests and inspect downstream CA county GA/GR and tanf aggregate dependents. Done means the tree uses MONTH periods consistently, tests use monthly conventions, and June/July boundary cases pass for each July transition.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100