UK pensions: resident State Pension, Pension Credit, contributions and salary-sacrifice relief (#1069)

[juaristi22]

Part of #1069 (UK pensions). It implements the approved plan's c1–c12 and the first review round; c0 waits for PolicyEngine/policyengine-uk#1899.

What this does

• Facts. It re-pins the Chronicle feed to 825406f, which carries the UK pension facts from UK pension facts for the 2025 calibration: DWP State Pension and Pension Credit caseloads from Stat-Xplore (UK residents), Northern Ireland pensions, workplace pension contributions, and the unported pension rows of files Chronicle already archives chronicle#302 via META: publication + validation portfolio to a well-validated populace launch #305, and adds the consumer operations those facts need.
• Resident State Pension.
  • It binds the resident level from Stat-Xplore (GB) and DfC (NI), with the age-by-sex-by-type, area and weekly-amount rows.
  • The OBR line and DWP's forecast lines become diagnostics.
  • The empty £40–60 band is signed out.
• State Pension age boundary.
  • SPI donor ages follow ONS single-year shares (c5).
  • The donor forest is queried at mid-year, which removes a zero-State-Pension artefact at 66 (c5 fix).
  • The SPI channel's prior mass is split by region and by whether a household has a member at State Pension age (c6), with a pension-age share σ_p = 0.2 (ruled 2026-10-02).
• SPI State Pension amounts by band. They now move to 2025 by their count rows' recipient growth times the State Pension rate, not the rate alone. The two rows of each band had described different numbers of recipients; this was the £50–70k band's residual (D6).
• Pension Credit (c7). Fourteen caseload targets, and a take-up stage that applies DWP's FYE2024 rates by component.
• Contributions (c8–c9).
  • Personal contributions are no longer clipped.
  • Employer contributions are drawn from ASHE rate bands instead of three times the employee contribution.
  • Converted salary-sacrifice records lose the sacrificed pay.
  • DWP's employer total (GB) is bound.
• Pension-age benefits (c10). Attendance Allowance in England and in Wales, and pension-age Housing Benefit, plus Winter Fuel recipients as a diagnostic.
• Salary-sacrifice relief (c11). The measure resolver runs a counterfactual simulation (the sacrifice returned to pay), and the income-tax and NICs relief rows from HMRC Table 6.2 bind through it.
• Clean-up.
  • Retires the stale D6 target-fit deferral.
  • The SPI allocation's reason is read from its declared shares everywhere.
  • Re-pins the gate digests.
  • Adds the receipts note experiments/1069-uk-pensions-receipts.md; Part J covers the review round.

Measurements (local, measurement-only builds; details in the receipts note)

• Build at 677336b (fix20; the head adds only the receipts note). Every gate passes. Loss 0.00742 on 1,170 targets, against 0.00836 on 1,090 for the 30 September main build. 98.0% of rows are within 10%, ESS is 5,007, and no row is above 25%.
• SPI State Pension bands. Every band is within 4%, except £20–30k at +13.1%, a headcount residual (8% too many recipients) that the uprating does not cause. Before the fix, £50–70k sat at +24.5%, or +25.6% at σ_p = 0.2.
• Engine, FY2025-26, on that build's H5.
  • State Pension £142.5bn and 12.41m recipients, against the £142.3bn resident level.
  • Pension Credit 1.46m benefit units and £6.16bn, against targets of 1.45m and £6.11bn. Realised take-up is 71.6% (Guarantee Credit) and 40.9% (Savings Credit only), against DWP's 69% and 37%.
• HBAI.
  • Pensioner quintile shares before housing costs are 21.5/27.9/21.1/16.7/12.7, against HBAI's 22/25/21/18/14.
  • Pensioner relative poverty is 15.2% BHC and 15.3% AHC, against HBAI FYE 2025's 16% and 14%.
• CPI-only State Pension probe. +£3.11bn by 2030 (bootstrap SE £0.07bn), within 0.5% of the σ_p = 0.5 build in every year.
• σ_p, 0.2 against 0.5 at 677336b. Both pass every gate. 0.5 fits single ages 62–63 and the pensioner quintiles better. 0.2 fits Pension Credit take-up after calibration, the pre-calibration benefit caseloads and the £20–30k State Pension band better. Details are in Part J.

For review (rulings owed)

• Table 3.8 and the DWP employee row. Both stay out of the fit: Table 3.8 splits contributions by relief mechanism, the engine's columns by provider. Vahid recommends binding the combined Table 3.8 amounts against employee plus personal contributions, with the DWP employee row as a diagnostic.
• The salary-sacrifice amount. The relief rows fit, but £34.3bn is sacrificed against the £24.6bn implied, because records paid under £9,100 hold about half of it. UK spine follow-ups after #1045: SPI band donors as a mass-conserving support channel, WAS tenure coherence, the residential draw's bound and Table 7 composition, then a national build #1063's earners-only fix resolves it. Vahid recommends keeping c9's amount row bound until then.
• The employer NICs relief is restated from HMRC's 13.8% to the statutory 15% (£3.70bn) by the rate only. On the fix20 H5 the engine-measured factor for earners is exactly 15/13.8; the threshold effect sits only on the records paid under £9,100.
• Single ages. 65 is −17%, 64 −6%, and 62 and 63 are +15% and +12%. Vahid recommends the R3 split (65, 66, 67–69) now.
• The income-tax relief bands, once the band test is fixed: bind the bands and make the total a diagnostic, or the reverse.

Not in this PR

• c0, the State Pension age migration (Set State Pension age from date of birth, including the rise to 67 policyengine-uk#1899).
• The engine follow-up (reform propagation, the 2025-26 Pension Credit rates and the April 2027 rate).
• The relief rate bands, which wait for a band-test fix.
• Winter Fuel binding (Model Winter Fuel Payment high-income recovery separately from entitlement policyengine-uk#1760).
• Scottish Attendance Allowance, which moved to Pension Age Disability Payment.

Verification

• CI passed every job at 004b5c9.
• At 677336b, the affected suites pass locally: the HMRC uprating, contract, target-reference, State Pension, Pension Credit, pension-age benefit, contribution, SPI and coverage tests, the shared spec and contract-pin tests (417), the CI test-plan check, lint and the integration-uk smoke build.
• Every derived surface was regenerated at its own commit: national references and membership, both national parity receipts, the coverage manifest and the charter-H2 fixture. No gate digest moved with the uprating fix.

🤖 Generated with Claude Code

[vahid-ahmadi]

Automated review pass (Claude Code, high effort) — round 1 at 004b5c9c

Verdict: nothing blocking in the code. The stages are deterministic and well receipted, the new target rows read the right facts, and the targeted suites pass locally. Three should-fixes: the DWP employer row is GB but binds a UK frame; the employer NICs restatement corrects the rate but not the secondary threshold; and Pension Credit take-up is set at prior weights with no post-calibration reading. Recommendations on the five rulings are below. Separately, and outside this PR: main's slc.borrowers.plan_2_* exclusions expire tomorrow (2026-10-03), and an expired entry raises in every build.

What the 32k lines are.

• About 26.6k are data: ons_single_year_age_populations.json (8.4k), uk_population_targets.json (6.6k), ashe_employer_pension_contribution_rates.json (4.1k), the target references and membership (5.6k), the parity signed differences (1.2k), and the fixtures, including job.tab.
• About 2.8k are tests and 2.7k code. The code is mostly spi_income.py, pension_credit_take_up.py, employer_pension_contributions.py, ledger_targets.py, spi_spine.py, target_materialization.py and measure_simulation.py.
• About 0.4k are docs (the receipts note).

Verified locally at this head.

• uv sync --all-packages, then 112 passed and 4 skipped across the nine new or changed pension test files: take-up, employer contributions, State Pension targets, Pension Credit targets, pension-age benefits, SPI pension age, the window consumers, SPI support, and test_ledger_monthly_count_x_mean.
• test_uk_battery_bindings, test_country_spec, test_uk_salary_sacrifice and test_uk_measure_simulation are green.
• tools/ci_test_plan.py verify is ok.
• CI: lint, wheels, engine-uk (both Pythons) and integration-uk pass; engine-free and engine-us were still running.

---

1. Should-fix: the DWP employer contributions row is GB, but its measurement has no country filter

dwp.workplace_pension.employer_contributions is labelled "Great Britain", and its notes say the source is ASHE, Great Britain (uk_population_targets.json:25678,25706). Its measurement.filters is null, so the engine sums employer contributions plus salary sacrifice over the UK frame, NI included.

Every other GB row in this PR filters on uk.geography.country: the State Pension amount, the Pension Credit caseload, and Attendance Allowance for England and Wales. NI is about 2.5–3% of UK employees, so the row asks GB's £104.2bn of UK records and pulls the GB employer draw down by roughly that much. Add uk.geography.country in [england, scotland, wales].

2. Should-fix: the employer NICs relief restatement corrects the rate, not the threshold

HMRC Table 6.2's 2024-25 £3.4bn is relief at 13.8% above a £9,100 secondary threshold. The counterfactual runs at the calibration year, at 15% above £5,000. The row's uprating_index (gov.hmrc.national_insurance.class_1.rates.employer) scales the fact by 15/13.8 to £3.70bn, which accounts for the rate only.

For a sacrificer whose pay is well above both thresholds, the returned pay is above both, so 15/13.8 is exact. But Part G of the receipts puts 52% of the final sacrificed amount (£18.8bn) on records with no pay. Their returned pay starts at £0. Under 2025 parameters the first £5,000 is relief-free, against £9,100 under 2024-25's. That is up to £4,100 a head more taxable at 15%, on about 1.24m people. So the engine's 2025 relief per pound is higher than the restated fact assumes, on exactly the records the solver leans on.

Two options:

• (a) Restate by an engine-measured factor: the employer NICs delta under 2024-25 parameters over the delta under 2025 parameters, on the same frame. It costs one extra counterfactual.
• (b) Keep HMRC's £3.4bn unrestated and record the parameter gap as a known residual, like the unuprated 2024-25 amounts (R1/R10).

Either is more honest than a rate-only factor. The point weakens a lot once #1063's earners-only fix removes the no-pay sacrificers (ruling 3).

3. Should-fix: Pension Credit take-up is set at prior weights and never read after calibration

assign_component_take_up (pension_credit_take_up.py:220-285) computes the residual rate on the stage's household weights, so realised take-up hits 69%/37% at prior. That is 69.4% and 39.1% on the c7 spine. Calibration then reweights to the 14 caseload rows while entitlement at prior is 36% short (Part D). Closing that gap by reweighting changes the entitled-to-claimant mix, so the take-up the final H5 implies can drift away from DWP's FYE2024 rates without anything noticing. The uk_stage_pension_credit_take_up gate reads the stage, not the calibrated population.

Report realised Guarantee Credit and Savings-Credit-only take-up on the final H5 (weighted claimants over weighted entitled) in Part H. If it lands well off 69/37, R9's fallback (solving take-up against the caseload) is worth reopening.

4. Nit: a licensed unit-record value sits in a committed rationale

The signed exclusion for the new State Pension £40–60 band (target_reference_signed_exclusions.json:162) quotes the two nearest FRS respondents' weekly amount, "£58.59 a week". That is an individual value from the licensed FRS. The rationale holds without it: "the two nearest restate above £60 at the 2025 rate".

5. Nit / question: the three income-tax band exclusions expire on 2026-11-25

hmrc.salary_sacrifice.it_relief_{basic,higher,additional}_rate stay excluded until 2026-11-25 (calibration_measure_exclusions.json). On expiry they fail closed: counterfactual_delta refuses banded bindings (measure_simulation.py), and an expired entry raises. When the band-test fix lands, the bands and it_relief_total both bind the same £8.8bn. Please say now which leaves the fit then (I'd keep the total and make the bands diagnostics, or the reverse), so the fix doesn't double-bind.

6. Note: D6's retirement is legitimate, but the band sits 0.5 points from the fence

Retiring the stale deferral is right: it expired on content and the row fits inside the bound. But the 50–70k State Pension band is at +24.5% against a 25% release-blocking fence. Any spine change can block the H5 on it, as σ_p = 0.2 already does (+25.6%). Worth a line in the body so the next blocked build isn't a surprise.

---

Rulings owed, with recommendations

1. Table 3.8 and the DWP employee row. Take option (1): bind the combined Table 3.8 amounts (net pay plus relief at source) by income band against employee plus personal contributions, and drop the counts.
   • The engine can't reproduce the relief-mechanism split, and option (2) leaves NEST-type trusts ambiguous anyway.
   • Keep the DWP employee row as a diagnostic. Its "employees' own £45.5bn" measures nearly the same total as the combined Table 3.8 (£44.1bn), so binding both pulls on one quantity twice.
   • The gross £66.2bn includes relief the engine doesn't hold in those columns, so it shouldn't bind.
2. σ_p: keep 0.5.
   • At 0.2 the H5 blocks (50–70k band +25.6%), single ages worsen (62 +15%, 63 +11%), and HBAI Q2 moves 2.9 points off.
   • Its gains are on prior gaps that calibration closes anyway.
   • The CPI-only probe's budget effect agrees within 0.5%, so the choice doesn't move the headline analysis.
   • Revisit after c0.
3. Salary-sacrifice amount: keep c9's amount row bound beside the relief rows until UK spine follow-ups after #1045: SPI band donors as a mass-conserving support channel, WAS tenure coherence, the residential draw's bound and Table 7 composition, then a national build #1063's earners-only fix lands. Two reasons beyond Part G's:
   • The DWP employer row binds employer contributions plus salary sacrifice, so the inflated £36.3bn (about £11.7bn over the £24.6bn implied) displaces genuine employer contributions inside that row's fit.
   • Relief on no-pay records' returned pay is mis-specified (see 2).
   • Bound, the amount anchors both until the forest stops predicting sacrifice for non-earners.
4. Employer NICs restated to 15%: not as a rate-only factor. See finding 2. Use (a) the engine-measured factor, or (b) HMRC's £3.4bn as published with the gap recorded.
5. Single ages (65 −19%, 64 +9%): take the R3 fallback now (65, 66 and 67–69).
   • Age 65 sits right at the State Pension age boundary that the SPI age draws, the pension-age stratum and Pension Credit eligibility all key on.
   • A −19% error there feeds those mechanisms directly.
   • The split costs three rows, and c0 doesn't remove the need for it.

Checked and correct

• State Pension resident level.
  • GB (Stat-Xplore, filtered to England, Scotland and Wales) and NI (DfC) are separate rows; each is count × mean weekly × 52, averaged over Feb/May/Aug/Nov 2025.
  • Each point is restated by the engine's new State Pension rate (221.20 → 230.25), so the February point isn't left at 2024-25 rates.
  • ledger_targets.py:2101-2132 refuses negative operands and records every member month.
• Pension Credit take-up draw.
  • It uses keyed stable_identity_uniforms on benunit_id with its own salt.
  • The residual rate is clipped to [0, 1], and reporters always claim.
  • The bands follow DWP's components: Guarantee Credit with or without Savings Credit, then Savings Credit only.
• Salary-sacrifice relief binds on hmrc.ss_* only. Every relief row's ledger_selector names hmrc.ss_income_tax_relief_* or hmrc.ss_nics_relief_*, not the generic relief concepts chronicle META: publication + validation portfolio to a well-validated populace launch #305 also emits. So the double emission I flagged there doesn't double-bind here.
• The counterfactual resolver.
  • One cached simulation per (zeroed, folded) pair.
  • The delta is per row, with the direction declared.
  • Banded bindings are refused.
  • The receipt records the route and non-zero rows.
• Converted salary-sacrifice records lose pay floored at £0 (salary_sacrifice.py:243), so pay can't go negative.
• The employer draw happens on the raw FRS spine (frs_hmrc_spine_leaves). SPI-channel rows take pension columns from the FRS-only fill, not from the donor household.
• HBAI FYE 2025 pensioner relative poverty is 16% BHC (CI 14–18) and 14% AHC (CI 12–16), as the body says. The final arm's 14.2% BHC sits at the bottom of that interval and 14.7% AHC inside it.
• The body's measurement figures match the receipts note: loss 0.00730 on 1,170; State Pension £142.5bn and 12.42m; Pension Credit 1.46m and £6.15bn; the quintiles.
• Privacy. Apart from 4, the committed evidence is aggregates and sample counts, with no unit records.

Outside this PR, time-critical

slc.borrowers.plan_2_liable and slc.borrowers.plan_2_above_threshold expire on 2026-10-03 on main too (calibration_measure_exclusions.json). From tomorrow every UK build and the certifier will raise on them. They need extending or retiring today, on main.

[juaristi22]

Thanks, Vahid. Round 1 is addressed at 677336b; details are in Part J of the receipts note. Point by point:

1. Employer row GB filter: done (677336b). The contract's measurement block now declares uk.geography.country in [england, scotland, wales]. The engine binding already restricted the row to GB households: its household_conditions list the nine English regions, Wales and Scotland. So the fit was GB-only before; the declared measurement now matches it.

2. Employer NICs threshold: measured. I ran the counterfactual under both parameter sets on the calibrated frame (the H5 built at 677336b, σ_p 0.2):

• Sacrificers paid at least £9,100: the engine's factor is 1.087, exactly the rate-only 15/13.8. Their returned pay sits above both thresholds, as you expected.
• Sacrificers paid under £9,100: 1.430. Overall: 1.171.
• The excess is entirely on records under £9,100, essentially the no-pay sacrificers from UK spine follow-ups after #1045: SPI band donors as a mass-conserving support channel, WAS tenure coherence, the residential draw's bound and Table 7 composition, then a national build #1063's non-earner defect. HMRC's real sacrificers are earners, so the rate-only factor is the right restatement of the real-world quantity. Option (a) would write the frame defect into the target, and once UK spine follow-ups after #1045: SPI band donors as a mass-conserving support channel, WAS tenure coherence, the residential draw's bound and Table 7 composition, then a national build #1063's earners-only fix lands the frame-wide factor converges to 1.087 anyway.
• So I recommend keeping the rate-only restatement, with these factors receipted. This is María's call (your ruling 4).

3. Pension Credit take-up after calibration: measured; now in Part H and Part J. Weighted claimants over weighted entitled, on the calibrated H5s (DWP FYE2024: 69% and 37%):

• Final build, σ_p 0.5: Guarantee Credit 74.7%, Savings Credit only 46.1%.
• σ_p 0.2: 71.6% and 40.7%.
• At 677336b, σ_p 0.2: 71.6% and 40.9%.
• Calibration fixes the claimants, so the drift is in the entitled pool behind them, and it is smallest at 0.2.

4. Unit value in the rationale: removed (677336b). The rationale now says the nearest records restate above £60 at the 2025 rate. The earlier text is still in the branch history (a2bfee0, below the #1063 stack's base). Rewriting that history is María's call.

5. Relief band exclusions after the band test. My proposal: bind the three bands and make the total a diagnostic, since the bands carry the distribution and the total is their sum. María to confirm; I'll record her choice next to the exclusions so the fix can't double-bind.

6. The £50–70k band and the fence: fixed at the root (677336b). The SPI State Pension amount rows moved to 2025 by the rate alone, while their count rows moved by HMRC's taxpayer growth in the band. So each band's amount kept the 2023-24 number of recipients while its count row grew them; in £50–70k the count grows by 1.217. The amount rows now move by their count row's factor times the rate ratio. After the fix the band is +3.8% at σ_p 0.2 and +3.0% at 0.5. Every SPI State Pension band: within 4% at 0.2, except £20–30k at +13.1%. Its count factor is about 1, so that is a headcount residual (8% too many recipients), not an uprating one.

On your rulings.

• σ_p: María ruled 0.2 (3a3fc10). The root fix removes the block at both shares, and I re-ran both at 677336b with fresh spines. Both pass every gate.
  • 0.5 is better on single ages 62–63 (+8% and +2%, against +15% and +12%) and on the pensioner quintiles (a 4.8-point total gap against 6.1). Its lower reported loss (0.00716 against 0.00742) is one row, ESA claimants.
  • 0.2 is better on Pension Credit take-up after calibration (71.6% and 40.9%, against 74.7% and 45.7%), the pre-calibration benefit caseloads, the £20–30k State Pension band (+13.1% against +18.7%), BHC poverty and ESS (5,007 against 4,937).
  • The probe's budget effect agrees within 0.5%.
  • So the prior gaps don't close for free: your point 3 is where they show up after calibration. Details are in Part J.
• 1, 3 and 5 are with María.
• 4 is point 2 above.

Outside this PR. slc.borrowers.plan_2_* still expire on main on 2026-10-03; I've flagged it to María.

[vahid-ahmadi]

Automated review pass (Claude Code, high effort) — round 2 at c78dff42

Verdict: nothing blocking; I'd approve once the four CI jobs still running (engine-free and engine-us, both Pythons) come back green. The round-1 items are closed or have a measured answer I agree with. Two of them carry a condition, stated below. The remaining open points are María's rulings.

R1 item	Status	Evidence
1 GB employer row has no country filter	Closed	The measurement block now declares uk.geography.country in [england, scotland, wales] (uk_population_targets.json:25648). The engine binding's household_conditions already listed the nine English regions, Wales and Scotland, so the fit was GB-only before and the declaration now matches it.
2 Employer NICs relief restated by rate only	Accepted, with a condition	Part J measures the counterfactual under both parameter sets: 1.087 for sacrificers paid at least £9,100 (exactly 15/13.8), 1.430 under £9,100, and 1.171 overall. For an earner above both thresholds, the relief per pound sacrificed is the rate alone, so the rate-only restatement is the right real-world quantity. The excess sits on records paid under £9,100, which #1089's c7 removes. Condition: after #1089 lands, re-measure the frame-wide factor and record that it converges towards 1.087. Until then the frame computes about 1.171 against a target restated at 1.087.
3 Pension Credit take-up not reported after calibration	Closed	Part H/J now reports it on the calibrated H5s. At σ_p 0.2 (fix20), Guarantee Credit is 71.6% and Savings Credit only 40.9%, against DWP's 69% and 37%. That's about 2.6 and 3.9 points high, with the entitled pool (1.81m and 0.41m) carrying the drift. It's acceptable as a recorded residual, since take-up isn't a bound row.
4 Single-record weekly amount in a rationale	Closed in the tree	The current text says "the nearest of them restate above £60" (target_reference_signed_exclusions.json:162), and the figure appears nowhere else in the tree. It's still in a2bfee0a, but that commit is on this PR's branch only, so a squash merge keeps it out of main's history. The PR's own commit list stays visible on GitHub. I'd treat that as de minimis rather than rewrite the branch; it's María's call.
5 Relief band and total rows double-binding after 25 November	Agree with the proposal	Bind the three bands and make the total a diagnostic. Please record the choice next to the exclusions in this PR, so the band-test fix can't re-bind both.
6 £50–70k band against the 25% fence	Closed at the root	align_hmrc_amount_by_recipient_growth_and_rate (hmrc_uprating.py) multiplies the count row's own taxpayer-growth factor by the engine's rate ratio, and writes both component receipts. That's the right decomposition: amount = recipients × amount per recipient. £50–70k now moves by 1.217 × 1.1295 = 1.375, and the band reads +3.8% at σ_p 0.2 (+3.0% at 0.5). The £20–30k band's +13.1% is a headcount residual (count factor 1.0025, 8.0% too many recipients), not an uprating one, as Part J says.

σ_p 0.2: noted, no objection. Part J lays out the trade-off fairly: 0.5 does better on single ages 62–63 and the pensioner quintiles, while 0.2 does better on take-up after calibration, the benefit caseloads, the £20–30k band and ESS.

Verification at this head: test_uk_hmrc_uprating, test_uk_spi_spine, test_uk_release_input_coverage_manifest and the shared test_contract all pass locally against this worktree's source (about 300 tests, no failures). In CI, lint, wheels, select-countries, both engine-uk jobs and integration-uk are green; the engine-free and engine-us jobs were still running.

Outside this PR, still urgent: slc.borrowers.plan_2_liable and plan_2_above_threshold still expire on main on 2026-10-03 (calibration_measure_exclusions.json:362 on main). The renewal exists only on #1089, which is stacked on this PR, and I found no PR to main carrying it. A one-line PR to main today avoids every UK build on main failing tomorrow.