Fix disable_simulated_benefits and read one claimant-or-partner award

[MaxGhenis]

Summary

Fixes the disable_simulated_benefits reform (gov.contrib.policyengine.disable_simulated_benefits), which raised an error before setting any benefit, and gives the claimant's and partner's income-related ESA and income-based JSA one reading, shared by the claimant_or_partner_* variables and both income-related limbs of income_support_eligible.

Stacked on #2027, with #2025 merged in (both are stacked on #2013). The diff against #2027 therefore also shows #2025's changes. This PR's own change is commit 1f68925; the merge commits only bring in #2025 and #2027's later head.

What was wrong

The reform raised for three separate reasons, each hiding the next:

1. Simulation.__init__ does not call core's constructor, so tax_benefit_system.simulation was never set and the reform's self.simulation raised AttributeError. The public service budget reform (adjust_budgets) reads the same attribute.
2. The dataset year is text for a situation's dataset and a number for a multi-year dataset, and range(time_period, time_period + 10) raised TypeError on text.
3. Five listed benefits have no <name>_reported variable: Attendance Allowance, both DLA components and both PIP components. Since Move disability benefit reported amount mapping to UK data #1656 the data gives their receipt as a rate category and the model pays that category's rate, so there is no reported amount to copy.

Once it runs, a second defect appears in later years. The reform holds each benefit at its dataset-year amount for ten years, while the *_reported variables are uprated. claimant_or_partner_esa_income, claimant_or_partner_jsa_income (#2027) and the Income Support limbs (#2013, #2025) decide whose award esa_income / jsa_income holds by comparing it with the award on the current period's reports and with their plain total. In a later year neither comparison holds, so the whole award, another member's included, was taken to be the claimant's or partner's.

What changes

• Simulation: sets tax_benefit_system.simulation before applying structural reforms, as core's constructor does.
• Reform:
  • reads the dataset year as a number from either dataset type;
  • drops the five benefits with no reported amount;
  • sets claimant_or_partner_esa_income and claimant_or_partner_jsa_income for each of the ten years, from the claimant's and partner's reports in the dataset year (is_claimant_or_partner);
  • sets income_support from the claimant's and partner's reports alone. In the model income_support is the claimant's family's award, and the passports read it as theirs, so another member's report would otherwise passport the claimant.
• One formula: claimant_or_partner_award in policyengine_uk/utils/benefit_unit.py is the formula of both claimant_or_partner_* variables.
• Income Support gate: the income-related ESA limb (s.124(1)(h)) is claimant_or_partner_esa_income > 0 and the income-based JSA limb (s.124(1)(f)) is claimant_or_partner_jsa_income > 0. The gate now reads what the means tests and passports read, including an award entered for those variables directly or set by the reform.

Why the limbs read the variables and do not call the helper

A helper recomputes the claimant's and partner's award from esa_income and the reports. It cannot see a value the reform set on claimant_or_partner_esa_income, so limbs that called it would keep the later-year defect. Reading the variable gives the same result as the old limb convention (award > 0) & (~as_reported | scoped > 0): the variable is zero when the award is, the scoped award when the reports explain it, and the award itself otherwise. With the limbs reading the variables, nothing needs the as-reported masks, so the helper returns the award alone.

Behaviour changes to note

• Plain total of the reports. When esa_income / jsa_income equals the plain total of everyone's reports but not the formula's award, the gate used to read the claimant's and partner's award after the capital screen. It now reads the plain total of their reports, as Count only the claimant's and partner's legacy awards in means tests and passports #2027's variables already did. Three existing tests pinned the old reading and now state the new one.
• Directly entered claimant-or-partner awards now reach the Income Support gate.
• Caching. The gate reads a calculated variable, so code that changes esa_income / jsa_income after calculating the gate has to clear claimant_or_partner_* as well as income_support_eligible. The three test helpers that recalculate the gate do so.
• Reform amounts. As before, the reform holds amounts at their dataset-year level; it does not uprate them.

Invariants

For every benefit unit and each of the reform's ten years:

• esa_income and jsa_income equal the sum of every member's dataset-year report, and claimant_or_partner_* equals the sum of the claimant's and partner's (conservation);
• 0 <= claimant_or_partner_* <= esa_income / jsa_income (bounds), in the reform and in the formula (to the rule's half penny);
• the values are the same in every year (the reform does not uprate);
• income_support_eligible is false whenever either claimant-or-partner award is positive (the limbs only bar);
• the council tax reduction passport equals "Income Support, or either claimant-or-partner award, is positive".

Differential: in formula mode, and for awards entered directly, set later, set on a branch or recalculated after deletion, the new limbs and gate equal the code they replace (copied from #2025 at 081ec14), except in the plain-total case above, which is checked against its own expectation.

Overlap with #2047

#2047 (PAWHP in household income, on #2038) carries the same simulation link and AA/DLA/PIP removal so its own stack works. Whichever lands second keeps both PRs' rules: this PR's claimant-or-partner scoping, and #2047's winter-heating split. Under that split, winter_fuel_allowance is not in BENEFITS, and the one dataset-year Winter Fuel Payment report is set as pawhp in Scotland while PAWHP is active and as winter_fuel_allowance otherwise. Without it, Scottish households would be counted twice.

Enhanced FRS

Real runs on a private copy of the Enhanced FRS 2024-25, 2025-2030. Base 2cb91b036 (#2027 at f551e54 with #2025 at 081ec14 merged, without this PR) against this PR's head 9e88021a4. Aggregates only.

• Reform off (the default): £0. All 113 compared benefit-unit, person and household arrays are identical in every year, including income_support_eligible, both claimant-or-partner awards, every passport and household net income. No benefit unit holds a plain-total esa_income or jsa_income, and no member other than the claimant or partner reports ESA, JSA or Income Support (74 benefit units have such a member).
• Reform on. On the base it still raises AttributeError: 'CountryTaxBenefitSystem' object has no attribute 'simulation'; on this branch it runs. In each year 2025-2030:
  • the claimant-or-partner ESA and JSA awards equal the stored awards in every benefit unit (1,084 with ESA, 38 with JSA), as they must when no other member reports them;
  • the stored awards are the same in every year;
  • no benefit unit is Income Support eligible while either claimant-or-partner award is positive.

As before the fix, the reform holds each amount at its dataset-year cash level, so its later-year totals fall behind the baseline's. Whether it should use each year's reported amounts instead is a separate question (follow-up task).

Tests

• New test_disable_simulated_benefits.py (30 with the file below):
  • a six-family situation over 2025, 2026 and 2027, with an adult outside the couple reporting ESA and JSA, and the claimant's own ESA, JSA, screened-out ESA and another member's Income Support;
  • it checks the stored and claimant-or-partner awards, both Income Support limbs, the council tax reduction passport and each person's is_on_* status in each year, and shows that a value-only reading would take the excluded adult's ESA as the couple's in later years;
  • a multi-year dataset;
  • a conservation and bounds property over random families.
• New test_income_support_gate_reads_claimant_or_partner_awards.py, the differential test against the replaced code:
  • examples: formula mode, awards entered in the situation, set after calculating, set on a branch and on a nested branch, and recalculated after deletion;
  • a property over stored values at and around both readings (±£0.004, ±£0.006);
  • the full old and new gates on the eligibility property families.
• Existing pytest files for the gate, the direct inputs, the lifecycle and the legacy readers (85): pass.
• YAML: tests/policy/baseline/finance/benefit/family and .../gov/local_authorities/council_tax_reduction, 509 passed.
• Mutants, each caught by the new reform test:
  • the old gate;
  • no per-year claimant-or-partner awards;
  • Income Support summed over all members;
  • the old Simulation (no link);
  • attendance_allowance back in the list.

axiom: n/a: model reform

🤖 Generated with Claude Code