Merge main into #2573's branch (resolves a comment-only conflict)

changelog.d/2572-bonus-sacrifice.added.md

@@ -0,0 +1 @@
+- Added `pension_contributions_via_bonus_sacrifice`, an input for employer pension contributions made in place of a bonus. It is read summed with `pension_contributions_via_salary_sacrifice`, so the £2,000 NICs exemption cap from April 2029 and the annual allowance threshold income cover both routes, and datasets can keep the two apart.

changelog.d/2572-heating-fuels.added.md

@@ -0,0 +1 @@
+- Added `liquid_fuel_consumption` and `solid_fuel_consumption`, household spending on heating oil, LPG, coal and wood (COICOP 04.5.3 and 04.5.4). They default to zero, are already part of `housing_water_and_electricity_consumption` so add nothing to `consumption`, and dataset projection uprates them by CPI like other LCFS spending, since Ofgem's price cap does not cover them.

changelog.d/2572-spousal-maintenance.added.md

@@ -0,0 +1 @@
+- Added `spousal_maintenance_income`, maintenance paid by a spouse, civil partner, former spouse or former civil partner. It is Universal Credit unearned income, Pension Credit income (but not savings credit qualifying income) and Housing Benefit income, less £15 a week where the family includes a child or young person, as well as market and HBAI income. `maintenance_income` is documented as child maintenance, which counts in none of the means tests.

changelog.d/2572-student-loan-plans.fixed.md

@@ -0,0 +1 @@
+- Fixed `uprate_student_loan_plans` in dataset projection: it takes the base year from the dataset instead of assuming 2023, compares the data's fixed ages with the base year's oldest holder of each plan (so new Plan 2 holders above the 2012 intake now appear, and new Plan 1 holders come only from the 1998 and later intakes, with loans first paid before September 2006 written off at 65), and keys each person's take-up draw on `person_id`, so the same people hold a loan in every year and in any row order.

changelog.d/2572-widowed-parents-allowance.added.md

@@ -0,0 +1 @@
+- Added `widowed_parents_allowance_reported` (CPI-uprated) and `widowed_parents_allowance`, so datasets can separate Widowed Parent's Allowance from Bereavement Support Payment. Unlike Bereavement Support Payment, the allowance is taxable, Universal Credit unearned income, a welfare benefit for the benefit cap and an overlapping benefit for Carer's Allowance and Carer Support Payment. Housing Benefit counts it less £15 a week and Income Support less £10 a week.

changelog.d/fix-2573-council-tax-reduction.fixed.md

@@ -0,0 +1 @@
+- Count claimant and partner spousal maintenance and Widowed Parent’s Allowance in Council Tax Reduction income across Great Britain, with the statutory £15 weekly disregards and Pension Credit routing.

changelog.d/fix-2573-income-support.fixed.md

@@ -0,0 +1 @@
+- Count the claimant's and partner's spousal maintenance in Income Support while continuing to disregard child maintenance.

changelog.d/fix-2573-non-dependants.fixed.md

@@ -0,0 +1 @@
+- Included spousal maintenance in Housing Benefit and Council Tax Reduction non-dependant income bands while preserving its income-tax exemption.

changelog.d/fix-2573-student-loans.fixed.md

@@ -0,0 +1 @@
+- Correct newly assigned projected student loan plans by funding nation, using household region as a proxy: Plan 4 for Scotland, Plan 1 for Northern Ireland, Plan 2 for Wales, and Plan 2 or 5 by entry cohort for England.

docs/book/assumptions/growthfactors.md

@@ -18,9 +18,9 @@ We apply CPI to these variables:
 - All reported benefits– `carers_allowance_reported`, `child_benefit_reported`, `child_tax_credit_reported`, `esa_contrib_reported`, `esa_income_reported`, `housing_benefit_reported`, `iidb_reported`, `incapacity_benefit_reported`, `income_support_reported`, `jsa_contrib_reported`, `jsa_income_reported`, `maternity_allowance_reported`, `pension_credit_reported`, `sda_reported`, `state_pension_reported`, `universal_credit_reported`, `winter_fuel_allowance_reported`, `working_tax_credit_reported`
 - All consumption categories EXCEPT energy– `alcohol_and_tobacco_consumption`, `clothing_and_footwear_consumption`, `communication_consumption`, `education_consumption`, `food_and_non_alcoholic_beverages_consumption`, `health_consumption`, `household_furnishings_consumption`, `housing_water_and_electricity_consumption`, `miscellaneous_consumption`, `recreation_consumption`, `restaurants_and_hotels_consumption`, `transport_consumption`
 
-`domestic_energy_consumption`, `electricity_consumption` and `gas_consumption` are deliberately excluded. The data build calibrates them to NEED mean kWh and converts to pounds at Ofgem Q2 2026 unit rates, so the stored values already carry FY26/27 price levels; uprating them from the dataset's data year would re-apply price changes that are already included. See PolicyEngine/policyengine-uk#1867.
+`domestic_energy_consumption`, `electricity_consumption` and `gas_consumption` are deliberately excluded. The data build calibrates them to NEED mean kWh and converts to pounds at Ofgem Q2 2026 unit rates, so the stored values already carry FY26/27 price levels; uprating them from the dataset's data year would re-apply price changes that are already included. See PolicyEngine/policyengine-uk#1867. `liquid_fuel_consumption` and `solid_fuel_consumption` (heating oil, LPG, coal and wood) are not covered by Ofgem's price cap, so they are CPI-uprated from the data year like other LCFS spending.
 
-- Other variables– `afcs_reported`, `bsp_reported`, `childcare_expenses`, `free_school_fruit_veg`, `free_school_meals`, `free_school_milk`, `maintenance_expenses`, `statutory_maternity_pay`, `statutory_paternity_pay`, `statutory_sick_pay`, `state_pension`, `war_widows_pension_reported`
+- Other variables– `afcs_reported`, `bsp_reported`, `childcare_expenses`, `free_school_fruit_veg`, `free_school_meals`, `free_school_milk`, `maintenance_expenses`, `statutory_maternity_pay`, `statutory_paternity_pay`, `statutory_sick_pay`, `state_pension`, `war_widows_pension_reported`, `widowed_parents_allowance_reported`
 
 ## Road fuel volume
 
@@ -46,6 +46,29 @@ We apply the OBR's wage growth forecasts to employment-related variables.
 
 We use average earnings for these variables: `employee_pension_contributions`, `employer_pension_contributions`, `employment_income`, `employment_income_before_lsr`, `personal_pension_contributions`, `student_loan_repayments`
 
+### Newly assigned student loan plans
+
+Dataset projection holds ages fixed, so a person of a given age represents a
+later university intake in each projected year. When projection adds a loan
+to a tertiary-educated person without one, it uses current household region
+as a proxy for the funding nation, because the dataset does not record the
+funding agency. This proxy cannot identify people who moved between nations.
+
+The [official repayment-plan rules](https://www.gov.uk/repaying-your-student-loan/which-repayment-plan-you-are-on)
+give SAAS borrowers Plan 4 and Student Finance Northern Ireland borrowers
+Plan 1. For undergraduate loans, England uses Plan 1 before the 2012 intake,
+Plan 2 for 2012–2022, and Plan 5 from 2023; Wales uses Plan 1 before 2012 and
+Plan 2 from 2012. New assignments follow these routes; an unknown region
+leaves the person without an assigned loan. New holders from the 2023 and
+later intakes are added only in England: Plan 5 is the only plan that did not
+exist in the base year, while the other nations' plans for those intakes are
+already in the data. Plan 1 loans first paid before September 2006 (the 2005
+and earlier intakes) are written off at 65, later ones about 29 years after
+the course started. Take-up remains a fixed 40%
+probability with a draw keyed on person ID. This funding-nation routing
+applies to newly assigned loans; the existing-holder relabelling and
+write-off approximations are unchanged.
+
 ## Lagged average earnings
 
 We lag earnings growth by one year and use that to uprate housing service charges (including ground rent).
@@ -62,7 +85,7 @@ We derive these rates from OBR GDP growth and ONS population projections.
 |-------------|------|------|------|------|------|------|------|------|
 | Growth rate | 9.2% | 5.0% | 3.8% | 2.8% | 2.8% | 3.1% | 3.3% | 3.3% |
 
-We use per capita GDP for these variables: `benunit_reported_capital`, `capital_gains`, `capital_gains_badr`, `capital_gains_before_response`, `capital_gains_carried_interest`, `capital_gains_residential_property`, `cash_isa`, `corporate_wealth`, `directly_held_shares`, `dividend_income`, `gross_financial_wealth`, `household_lifetime_isa_balance`, `lifetime_isa_balance`, `lump_sum_income`, `main_residence_value`, `maintenance_income`, `miscellaneous_income`, `mortgage_capital_repayment`, `net_financial_wealth`, `non_residential_property_value`, `other_investment_income`, `other_residential_property_value`, `owned_land`, `pension_credit_reported_capital`, `pension_income`, `private_pension_wealth`, `private_transfer_income`, `property_income`, `property_rental_income`, `savings`, `savings_interest_income`, `stocks_and_shares_isa`, `sublet_income`, `uc_reported_capital`, `unit_and_investment_trusts`
+We use per capita GDP for these variables: `benunit_reported_capital`, `capital_gains`, `capital_gains_badr`, `capital_gains_before_response`, `capital_gains_carried_interest`, `capital_gains_residential_property`, `cash_isa`, `corporate_wealth`, `directly_held_shares`, `dividend_income`, `gross_financial_wealth`, `household_lifetime_isa_balance`, `lifetime_isa_balance`, `lump_sum_income`, `main_residence_value`, `maintenance_income`, `miscellaneous_income`, `mortgage_capital_repayment`, `net_financial_wealth`, `non_residential_property_value`, `other_investment_income`, `other_residential_property_value`, `owned_land`, `pension_credit_reported_capital`, `pension_income`, `private_pension_wealth`, `private_transfer_income`, `property_income`, `property_rental_income`, `savings`, `savings_interest_income`, `spousal_maintenance_income`, `stocks_and_shares_isa`, `sublet_income`, `uc_reported_capital`, `unit_and_investment_trusts`
 
 ## Council tax
 

docs/book/programs/gov/cms/child-maintenance.md

@@ -1,25 +1,33 @@
 # Child maintenance (planned)
 
 ```{warning}
-**Not yet modelled in detail.** PolicyEngine UK has two generic person-level
-inputs, `maintenance_income` and `maintenance_expenses`. They do not tell
-child maintenance apart from maintenance between former partners, and the
-model does not calculate a Child Maintenance Service (CMS) award. This page
-sets out the scope for doing that, tracked in
-[#669](https://github.com/PolicyEngine/policyengine-uk/issues/669) (still
-open, October 2026).
+**Not yet modelled in detail.** The model does not calculate a Child
+Maintenance Service (CMS) award. This page sets out the scope for doing that,
+tracked in [#669](https://github.com/PolicyEngine/policyengine-uk/issues/669)
+(still open, October 2026).
 ```
 
 ## What the model does today
 
-- `maintenance_income` is added to `market_income`, `household_market_income`
-  and `hbai_household_net_income`.
-- `maintenance_expenses` is subtracted in `market_income` and
-  `hbai_household_net_income`.
-- Neither variable feeds any means test. Universal Credit unearned income is
-  the list in `gov.dwp.universal_credit.means_test.income_definitions.unearned`,
-  which contains no maintenance, and UC earned income does not net off
-  maintenance paid.
+- `maintenance_income` holds child maintenance received. Datasets fill it
+  from the Family Resources Survey child maintenance module.
+- `spousal_maintenance_income` holds maintenance paid by a spouse, civil
+  partner, former spouse or former civil partner
+  ([#2572](https://github.com/PolicyEngine/policyengine-uk/issues/2572)).
+- Both are added to `market_income`, `household_market_income` and
+  `hbai_household_net_income`. `maintenance_expenses` (maintenance paid) is
+  subtracted in `market_income` and `hbai_household_net_income`.
+- Only `spousal_maintenance_income` feeds the means tests:
+  - Universal Credit unearned income
+    ([UC Regulations 2013 reg. 66(1)(d)](https://www.legislation.gov.uk/uksi/2013/376/regulation/66));
+  - Pension Credit income
+    ([State Pension Credit Regulations 2002 reg. 15(5)(d)](https://www.legislation.gov.uk/uksi/2002/1792/regulation/15)),
+    but not savings credit qualifying income (reg. 9(f));
+  - Housing Benefit income, less £15 a week where the family includes a child
+    or young person
+    ([HB Regulations 2006 Sch. 5 para. 47](https://www.legislation.gov.uk/uksi/2006/213/schedule/5/paragraph/47);
+    [HB (SPC) Regulations 2006 reg. 29(1)(o) and Sch. 5 para. 20](https://www.legislation.gov.uk/uksi/2006/214/regulation/29)).
+- UC earned income does not net off maintenance paid.
 - `uc_deductions` does cover child maintenance collected from a paying
   parent's UC award, but only in aggregate: it sits in the above-cap excess
   of `uc_deduction_rate` with last resort deductions, estimated from DWP
@@ -35,35 +43,19 @@ For **child** maintenance that is the right answer for UC:
 
 This asymmetry is the work-incentive problem described by the Centre for Social
 Justice in [*The Hidden Parent Poverty Trap: Child Maintenance and Universal
-Credit*][csj]. The model already reproduces it, because neither input reaches
-UC.
-
-The gap is **maintenance between former spouses or civil partners**.
-Reg. 66(1)(d) counts it as unearned income in UC, but the model cannot see it,
-because it shares `maintenance_income` with child maintenance. Those
-recipients' UC is overstated.
+Credit*][csj]. The model reproduces it, because neither child maintenance
+variable reaches UC.
 
 ## Scope
 
-### Phase 1: separate the inputs
-
-- New input `child_maintenance_received` (Person, GBP, annual).
-- New input `child_maintenance_paid` (Person, GBP, annual).
-- Keep `maintenance_income` and `maintenance_expenses` for maintenance
-  between former partners, and say so in their documentation.
-- In the data pipeline
-  ([Microcosm UK](https://github.com/PolicyEngine/microcosm)), route the FRS
-  child-maintenance items to the new inputs and the spousal items to the
-  existing ones.
-- HBAI income keeps both kinds, received and paid.
-
-### Phase 2: count spousal maintenance in UC
-
-- Add `maintenance_income` (now spousal only) to the UC unearned income list
-  from 2013-04-29, citing reg. 66(1)(d).
-- Leave `child_maintenance_received` and `child_maintenance_paid` out of UC.
-- Check the legacy benefits and Pension Credit the same way before adding
-  either input to their income definitions.
+### Phases 1 and 2: separate the inputs and count spousal maintenance
+
+Done in the engine by #2572. What remains is in the data: datasets that put
+the FRS payments from an absent partner in `private_transfer_income` should
+move them to `spousal_maintenance_income`
+([policyengine-uk-data#627](https://github.com/PolicyEngine/policyengine-uk-data/issues/627);
+[Microcosm UK](https://github.com/PolicyEngine/microcosm)). Datasets that do
+not supply it keep today's results.
 
 ### Phase 3: model the CMS calculation
 

docs/book/programs/gov/dwp/bereavement-support-plan.md

@@ -36,7 +36,7 @@ That means:
 - Reform analyses changing BSP rates have no household-level surface.
 - Anyone bereaved after the FRS reference week never appears as a BSP
   recipient even if eligible.
-- The legacy WPA has no variable of its own. Both the Enhanced FRS
+- Both the Enhanced FRS
   ([`frs.py`](https://github.com/PolicyEngine/policyengine-uk-data/blob/main/policyengine_uk_data/datasets/frs.py))
   and Microcosm UK fill `bsp_reported` from FRS benefit codes 6 and 9
   ([`frs_spine.py`](https://github.com/PolicyEngine/microcosm/blob/75167a68/packages/microcosm-build/src/microcosm/build/uk_runtime/frs_spine.py#L825)),
@@ -52,6 +52,18 @@ That means:
   [microcosm#1222](https://github.com/PolicyEngine/microcosm/issues/1222));
   [#2381](https://github.com/PolicyEngine/policyengine-uk/issues/2381)
   tracks freezing it after that.
+- Since [#2572](https://github.com/PolicyEngine/policyengine-uk/issues/2572),
+  WPA also has its own variables, `widowed_parents_allowance_reported`
+  (CPI-uprated) and `widowed_parents_allowance`. Unlike BSP, WPA is taxable
+  ([ITEPA 2003 s. 577](https://www.legislation.gov.uk/ukpga/2003/1/section/577)),
+  Universal Credit unearned income
+  ([UC Regulations 2013 reg. 66(1)(b)(vi)](https://www.legislation.gov.uk/uksi/2013/376/regulation/66)),
+  Housing Benefit income less £15 a week, a welfare benefit for the benefit
+  cap and an overlapping benefit for Carer's Allowance and Carer Support
+  Payment. It ends at State Pension age and while the recipient lives with a
+  partner ([SSCBA 1992 s. 39A(4) and (5)][sscba-39a]), so it never reaches
+  Pension Credit. The datasets still put it in `bsp_reported` until they
+  split FRS code 6.
 
 ## Proposed scope
 
@@ -125,15 +137,16 @@ For historical analyses the model should:
 - Add `wpa_eligible` (Person, YEAR): partner died between April 2001
   and 5 April 2017, the survivor is under State Pension age and is
   entitled to Child Benefit.
-- Add `widowed_parents_allowance` (Person, YEAR) as a derived
-  formula reading the WPA rate parameter (which would need
+- Replace the `adds` of `widowed_parents_allowance` (Person, YEAR) with
+  a formula reading the WPA rate parameter (which would need
   backfilling under `gov/dwp/wpa/rate.yaml`).
 
 WPA has no new awards, but existing awards continue while the
 surviving parent has a dependent child, so some recipients remain. In
 the current data they sit inside `bsp_reported` (see above), so they
-are already counted in income; the gap is that they can't be told
-apart from BSP or reformed separately.
+are already counted in income. Once datasets fill
+`widowed_parents_allowance_reported`, they are told apart from BSP; the
+gap left is a rule-based amount for reforms.
 
 ### Phase 3: data-side bereavement inputs
 

docs/book/validation/hbai.md

@@ -27,7 +27,7 @@ The table below shows how the HBAI income components map to PolicyEngine variabl
 | State support - all benefits and tax credits |`hbai_benefits`|
 | Income from occupational and private pensions |`private_pension_income` (includes occupational pension income)|
 | Investment income |`dividend_income`, `savings_interest_income`, `property_income_after_finance_costs`|
-| Maintenance payments |`maintenance_income`|
+| Maintenance payments |`maintenance_income`, `spousal_maintenance_income`|
 | Income from educational grants and scholarships (including, for students, student loans and parental contributions) |`student_payments`|
 | The cash value of certain forms of income in kind (free school meals, free school breakfast, free school milk, free school fruit and vegetables, Healthy Start vouchers and free TV licences for those aged 75 and over who receive Pension Credit) |`free_school_meals`, `free_school_fruit_veg`, `free_school_milk`, `healthy_start_vouchers`, `free_tv_licence_value`|
 | **Subtractions** | |
@@ -98,6 +98,7 @@ Each of the variables above is either derived from other variables, or is a dire
 | `savings_interest_income` | gov.economic_assumptions.indices.obr.per_capita.gdp | Uprated based on OBR per capita GDP projections |
 | `property_income` | gov.economic_assumptions.indices.obr.per_capita.gdp | Uprated based on OBR per capita GDP projections |
 | `maintenance_income` | gov.economic_assumptions.indices.obr.per_capita.gdp | Uprated based on OBR per capita GDP projections |
+| `spousal_maintenance_income` | gov.economic_assumptions.indices.obr.per_capita.gdp | Uprated based on OBR per capita GDP projections |
 | `student_payments` | Not uprated directly | Currently no specific uprating for student payments |
 | `free_school_meals` |gov.obr.consumer_price_index | Uprated based on CPI inflation |
 | `free_school_fruit_veg` | gov.obr.consumer_price_index | Uprated based on CPI inflation |

docs/engineering/pension-annual-allowance.md

@@ -112,6 +112,9 @@ because the survey does not record arrangement dates. Supply
 `pension_contributions_via_salary_sacrifice_pre_2015` for the part attributable
 to earlier arrangements. Its exclusion is limited to full salary sacrifice
 before the NICs exemption cap: that cap does not limit the s. 228ZA add-back.
+Bonus sacrifice (`pension_contributions_via_bonus_sacrifice`) is a relevant
+flexible remuneration arrangement under the same subsection and is added back
+with salary sacrifice; the pre-2015 input is a share of their sum.
 Flexible remuneration not
 represented by these contribution inputs needs an explicit threshold-income
 override.