Add private_pension_wealth as an explicit capital disregard; corporate_wealth keeps the share-like holdings

[MaxGhenis]

Part of PolicyEngine/policyengine-uk-data#452 (mechanism M2) and PolicyEngine/microcosm#750. Draft — held for Max's go.

What

Makes the means-test treatment of pension wealth explicit on the model side, ahead of the data pipelines splitting it out of corporate_wealth:

• private_pension_wealth — new Household STOCK input (GBP, per-capita-GDP uprating, default 0): the value of private pension rights other than current-employment defined-benefit entitlements (DC pots, AVCs, current personal pensions, retained DB/DC rights, pensions in payment, pension-sharing rights), imputed from the Wealth and Assets Survey. It is not a capital source in any means test — the value of a right to receive a pension under an occupational or personal pension scheme is disregarded capital — and pension income actually drawn still counts through private_pension_income.
• corporate_wealth — documentation now describes what the data carries (UK shares, employee shares and options, unit and investment trusts, stocks-and-shares ISAs); no "private pensions", no "corporate bonds". It names the separately exported stocks_and_shares_isa fold (Add cash ISA and stocks and shares ISA holdings variables #1791) so nobody sums both.
• total_wealth adds private_pension_wealth, so wealth taxes, wealth deciles and net_wealth (Add net_wealth variable and mortgage_debt / consumer_debt inputs #1761) keep the pre-split base.
• corporate_sector_wealth = corporate_wealth + private_pension_wealth is the new allocation key for shareholding (corporate-tax incidence: business rates, corporate SDLT, carbon tax, corporate-incident revenue), corporate_land_value (the LVT input) and employer_ni_response_capital_incidence. Pension funds hold corporate equity; keeping the key whole means the split moves nothing but the capital tests.
• The six capital sources.yaml parameters cite the disregard paragraph and explain why private_pension_wealth is absent from the list; data/uprating_indices.yaml and docs/book/assumptions/growthfactors.md register the new stock.

Why

corporate_wealth = WAS total pensions − current DB + shares/ISAs/trusts in both data builds, and it is a countable capital source everywhere. On enhanced_frs_2024_25.h5 (uk-data 1.56.14) at 2025, 2,983 of 6,447 benefit-unit records that report Universal Credit fail the £16,000 test, 96% of them on corporate_wealth alone (mean imputed corporate wealth among them £250k) — the largest single mechanism behind the UC caseload shortfall in policyengine-uk-data#452.

Statute (all fetched 2026-08-23): UC Regs 2013 Sch 10 ¶10; Housing Benefit Regs 2006 Sch 6 ¶31–32 and the pension-age HB Regs 2006 Sch 6 ¶24; JSA Regs 1996 Sch 8 ¶28–29; ESA Regs 2008 Sch 9 ¶28–29; Income Support Regs 1987 Sch 10 ¶23–23A; State Pension Credit Regs 2002 Sch V ¶22–23 (Part I). Not modelled (stated in the docstring): the notional-income rule for claimants over SPC qualifying age with undrawn money-purchase pots, and the capital treatment of withdrawn lump sums.

Inert on today's data, whole on tomorrow's

• Existing datasets carry no private_pension_wealth column → default 0 → every consumer is bit-identical to main on enhanced_frs_2024_25.h5 v1.56.16 at 2025 and 2029 (independent check: total_wealth, shareholding, corporate_land_value, land_value, LVT, wealth_tax, non_primary_residence_wealth_tax, household_wealth_decile, employer_ni_response_capital_incidence, corporate_sdlt, business_rates, carbon_tax, corporate_incident_tax_revenue_change, uc_assessable_capital, household_net_income, universal_credit — all byte-equal).
• A dataset built with the split (microcosm#750) loads private_pension_wealth; total_wealth and corporate_sector_wealth equal the pre-split values by construction (float32 rounding), and only the means tests move. The measured effect on the microcosm machinery (weights unchanged, 2025): UC benefit units 5.19m → 6.27m, eligible benefit units 9.8m → 16.3m; receipt in microcosm experiments/452-uk-pension-wealth-split.md.
• Sequencing: this PR lands first (inert). Consumers of a split dataset must run an engine ≥ this release, otherwise the loader drops the pension column and total_wealth / the exposure keys silently narrow.

Consumer check (every reader of corporate_wealth / total_wealth)

consumer	treatment
UC / HB / JSA / ESA / IS / PC capital sources	unchanged lists; private_pension_wealth documented as disregarded
uc_unearned_income dividend gate (corporate_wealth > 0)	keys on share-like holdings (dividends come from shares); unchanged on current data
total_wealth → wealth_tax, non_primary_residence_wealth_tax, household_wealth_decile, net_wealth (#1761)	re-sums the pension component
shareholding → business rates, corporate SDLT, carbon tax, corporate-incident revenue	key = corporate_sector_wealth
corporate_land_value → land_value → land_value_tax (LVT paper inputs)	key = corporate_sector_wealth
employer_ni_response_capital_incidence	key = corporate_sector_wealth
household/wealth/land/intensity.yaml: corporate_wealth	parameter unread by any formula; untouched
test fixtures setting corporate_wealth (8 YAML files, 2 Python tests)	unaffected

Tests

policyengine-core test policyengine_uk/tests/policy -c policyengine_uk   # 1126 passed
pytest policyengine_uk/tests/ -m "not microsimulation"                   # 155 passed, 15 skipped
ruff format --check . && ruff check .                                    # clean

New: tests/policy/baseline/household/wealth/private_pension_wealth.yaml; disregard cases in the UC, HB, ESA, JSA, IS and PC capital YAMLs; test_corporate_land_value_key_is_unchanged_by_the_pension_split.

Out of scope

Current-employment DB entitlements (WAS DVValDBT_SCAPE, £1.15tn on the donor) are not carried by either data build — a future current_db_pension_wealth would complete private pension wealth and change total_wealth. Cash ISAs (cash_isa, #1791) are capital for the means tests but the model's savings maps WAS savings accounts only — the opposite-direction gap, registered on microcosm#750.

Authored by Claude (Fable) from the #452 diagnosis; six-refuter adversarial verification of the design (statute, chain, model consumers, gates, measurement, completeness) with the model-side claims re-verified bit-for-bit on the licensed artifact.

🤖 Generated with Claude Code