Read HMRC's joint distribution of capital gains by taxable income

[MaxGhenis]

Part one of #552: the source surface. The imputation stage and band-level UK_CGT_TARGET_SPECS facts follow in a second PR built on this one.

Why

Populace has no capital gains source stage — cgt_calibration.py reads capital_gains as a persisted input that arrives with the certified candidate, and the two declared HMRC facts are aggregates (total gains, taxpayer count). The distribution underneath was imputed from a percentile table that stops at the 99th income percentile with a p95 of £1.16m, so it holds effectively nothing above £2m — against roughly 5,000 taxpayers there in HMRC's statistics, including 2,000 above £5m holding £22.7bn of gains. Measured on the current candidate, the two top bands carry 54.6% of UK CGT and 0.2% of the modelled tax.

Populace builds from raw sources, so the stage gets written once, from the primary publication. HMRC table 3 gives the joint distribution directly — individuals and gains by size of gain crossed with taxable income, eleven gain bands to £5m+ by six income bands — which is the surface an income-conditioned imputation needs, and it reconciles with table 2.1a at 359,000 individuals and £62.9bn for 2023-24. Four published years (2020-21 through 2023-24), so the stage can fit per year rather than aging one forward. The top two bands hold 50.7%, 52.2%, 54.8% and 54.9% of gains across those years — the concentration is not a one-year artifact.

What this adds

• uk_runtime/ods_tables.py — stdlib ODS reader taking the artifact label as an argument, so errors name their source. Repeat-run expansion is bounded, and suppressed cells arrive as their marker text rather than being coerced or dropped. hmrc_income keeps its own reader with SPI-specific messages; migrating it onto this is deliberately out of scope so a certified surface does not move inside a feature.
• uk_runtime/hmrc_capital_gains.py — the joint distribution as typed cells with pinned provenance (URL, sha256, size), checked before parsing so a wrong artifact fails on its identity. Counts convert from thousands, amounts from £ millions.
• 27 tests: synthetic sheets for the parsing logic, and a skipif class against the real pinned ODS (inputs/hmrc/, an optional local input like the SPI one) covering the fingerprint, the published totals, all four years, and the top-tail presence that motivates the module.

What the published data forced

Two things assumption would have gotten wrong. Amounts are suppressed as well as counts — 2022-23 withholds one — so both come back as None, with a suppressed count meaning "fewer than 500 people" rather than zero, and the result reports how much published mass sits inside suppressed cells (±£4m across the four years: rounding, not real mass). And the number of note rows above the header varies by year, so the header is located by its column heading rather than a fixed row index.

Basis notes for the follow-up stage

Gains are after losses and attributed gains but before the AEA; taxable income is after reliefs and the personal allowance; trusts are excluded; and only individuals with a CGT liability appear. The existing two UK_CGT_TARGET_SPECS facts come from table 1, which includes trusts (378,000 / £65.9bn), so band facts from this surface need declaring on the individuals-only basis rather than mixed with them. Sub-AEA gainers are outside this table entirely and need a separate decision.

Tests

uv run pytest packages/populace-build/tests: exit 0, all green (the repo's -q addopts plus a command-line -q suppress the count line; the progress lines reach 100% with no failures). ruff check and ruff format --check pass on the changed files.

🤖 Generated with Claude Code