glidepath 0.2.0__py3-none-any.whl

glidepath/regions/uk/data/age_rules.toml

@@ -0,0 +1,78 @@
+# UK age rules: durable, effective-dated policy parameters that are not
+# re-set each tax year (docs/planning.md §5.3, §6). The SPA timetable was
+# re-verified against the live gov.uk timetable page on 2026-08-02.
+
+schema_version = 2
+
+[meta]
+verified_on = 2026-08-02
+sources = [
+  "https://www.gov.uk/government/publications/state-pension-age-timetable/state-pension-age-timetable",
+  "https://www.gov.uk/government/publications/increasing-normal-minimum-pension-age",
+  "https://www.gov.uk/personal-pensions-your-rights/how-you-can-take-pension",
+  "https://www.gov.uk/lifetime-isa/who-can-open-a-lifetime-isa",
+  "https://www.gov.uk/lifetime-isa/withdrawing-money-from-your-lifetime-isa",
+  "https://www.gov.uk/deferring-state-pension/if-you-reach-state-pension-age-on-or-after-6-april-2016",
+]
+
+# Normal minimum pension age: 55 today, 57 from 6 April 2028. Protected
+# pension ages are out of scope for v1 (planning §6).
+[nmpa]
+steps = [
+  { age = 55 },
+  { age = 57, effective_from = 2028-04-06 },
+]
+
+# State pension age from date of birth (Pensions Act 2011: SPA 66 for
+# DOBs 1954-10-06 to 1960-04-05; Pensions Act 2014: 66 -> 67 bands as
+# ages; Pensions Act 2007: 67 -> 68 bands as fixed SPA dates, exactly
+# as legislated). Coverage deliberately starts at 1954-10-06: earlier
+# cohorts had lower, phased SPAs and different (pre-2016) deferral
+# rules that this forward-looking planner does not model. Age logic
+# must REJECT dates of birth before the first band, never guess.
+[state_pension_age]
+bands = [
+  { dob_from = 1954-10-06, dob_to = 1960-04-05, age = { years = 66 } },
+  { dob_from = 1960-04-06, dob_to = 1960-05-05, age = { years = 66, months = 1 } },
+  { dob_from = 1960-05-06, dob_to = 1960-06-05, age = { years = 66, months = 2 } },
+  { dob_from = 1960-06-06, dob_to = 1960-07-05, age = { years = 66, months = 3 } },
+  { dob_from = 1960-07-06, dob_to = 1960-08-05, age = { years = 66, months = 4 } },
+  { dob_from = 1960-08-06, dob_to = 1960-09-05, age = { years = 66, months = 5 } },
+  { dob_from = 1960-09-06, dob_to = 1960-10-05, age = { years = 66, months = 6 } },
+  { dob_from = 1960-10-06, dob_to = 1960-11-05, age = { years = 66, months = 7 } },
+  { dob_from = 1960-11-06, dob_to = 1960-12-05, age = { years = 66, months = 8 } },
+  { dob_from = 1960-12-06, dob_to = 1961-01-05, age = { years = 66, months = 9 } },
+  { dob_from = 1961-01-06, dob_to = 1961-02-05, age = { years = 66, months = 10 } },
+  { dob_from = 1961-02-06, dob_to = 1961-03-05, age = { years = 66, months = 11 } },
+  { dob_from = 1961-03-06, dob_to = 1977-04-05, age = { years = 67 } },
+  { dob_from = 1977-04-06, dob_to = 1977-05-05, reaches_on = 2044-05-06 },
+  { dob_from = 1977-05-06, dob_to = 1977-06-05, reaches_on = 2044-07-06 },
+  { dob_from = 1977-06-06, dob_to = 1977-07-05, reaches_on = 2044-09-06 },
+  { dob_from = 1977-07-06, dob_to = 1977-08-05, reaches_on = 2044-11-06 },
+  { dob_from = 1977-08-06, dob_to = 1977-09-05, reaches_on = 2045-01-06 },
+  { dob_from = 1977-09-06, dob_to = 1977-10-05, reaches_on = 2045-03-06 },
+  { dob_from = 1977-10-06, dob_to = 1977-11-05, reaches_on = 2045-05-06 },
+  { dob_from = 1977-11-06, dob_to = 1977-12-05, reaches_on = 2045-07-06 },
+  { dob_from = 1977-12-06, dob_to = 1978-01-05, reaches_on = 2045-09-06 },
+  { dob_from = 1978-01-06, dob_to = 1978-02-05, reaches_on = 2045-11-06 },
+  { dob_from = 1978-02-06, dob_to = 1978-03-05, reaches_on = 2046-01-06 },
+  { dob_from = 1978-03-06, dob_to = 1978-04-05, reaches_on = 2046-03-06 },
+  { dob_from = 1978-04-06, age = { years = 68 } },
+]
+
+# Lifetime ISA age gates: open 18-39, contribute to 50, charge-free
+# access at 60 (or first home / terminal illness / death).
+[lisa]
+open_age_min = 18
+open_age_max = 39
+contribute_until_age = 50
+access_age = 60
+
+# Post-2016 deferral: the weekly rate increases by 1% per 9 weeks
+# deferred, accruing at increment_rate/per_weeks for each whole week
+# once at least per_weeks weeks are deferred (~5.8% per 52 weeks).
+# The uplift applies to the rate payable at claim; increments are
+# CPI-uprated from then on.
+[state_pension_deferral]
+increment_rate = "0.01"
+per_weeks = 9

glidepath/regions/uk/data/assumptions_default.toml

@@ -0,0 +1,170 @@
+# Shipped default assumptions — the machine mirror of the §7 table in
+# docs/planning.md (recorded 2026-08-01). A doc-sync test keeps the two
+# aligned: same keys, same order, same numeric values. Every default is
+# user-overridable in the app; §6 announced-policy items are facts, these
+# are estimates.
+
+schema_version = 2
+
+[meta]
+verified_on = 2026-08-04
+sources = [
+  "https://obr.uk/efo/economic-and-fiscal-outlook-march-2026/",
+  "https://www.gov.scot/publications/scottish-budget-2026-2027/pages/4/",
+  "https://www.handbook.fca.org.uk/handbook/COBS/13/Annex2.html",
+  "https://www.ons.gov.uk/peoplepopulationandcommunity/healthandsocialcare/healthandlifeexpectancies/articles/lifeexpectancycalculator/2019-06-07",
+  "https://www.which.co.uk/money/pensions-and-retirement/accessing-your-pensions/annuities/annuity-rates-aQGfH6W5n2rm",
+  "https://www.hl.co.uk/retirement/annuities/best-buy-rates",
+]
+
+[[assumption]]
+key = "inflation.cpi"
+value = "0.02"
+basis = "OBR EFO March 2026: CPI at target from 2027"
+
+[[assumption]]
+key = "earnings.growth.real"
+value = "0.005"
+basis = "OBR EFO March 2026 medium-term real earnings growth"
+
+[[assumption]]
+key = "returns.equity.real"
+value = "0.04"
+basis = "Below long-run global equity history (~5% real); above the FCA intermediate rate (5% nominal - 2% CPI = 3% real) as a conservative cross-check (FCA COBS 13 Annex 2)"
+
+[[assumption]]
+key = "returns.bonds.real"
+value = "0.005"
+basis = "Consistent with current gilt real-yield ballpark and the FCA lower rate"
+
+[[assumption]]
+key = "returns.cash.real"
+value = "-0.005"
+basis = "Cash trails inflation over long horizons; cash-kind accounts bear no default fees, so this is their whole return - a cash slice inside a platform wrapper bears that wrapper's fees on top"
+
+[[assumption]]
+key = "volatility.equity"
+value = "0.18"
+basis = "Long-run global equity annual volatility (commonly cited 15-20%)"
+
+[[assumption]]
+key = "volatility.bonds"
+value = "0.07"
+basis = "Long-run gilt/IG portfolio volatility"
+
+[[assumption]]
+key = "volatility.cash"
+value = "0.01"
+basis = "Near-riskless nominal"
+
+[[assumption]]
+key = "correlation.equity_bonds"
+value = "0.2"
+basis = "Long-run average; regime-dependent (label prominently)"
+
+[[assumption]]
+key = "correlation.equity_cash"
+value = "0.0"
+basis = "Near-zero long-run historical correlation"
+
+[[assumption]]
+key = "correlation.bonds_cash"
+value = "0.2"
+basis = "Modest positive long-run historical correlation (short rates feed both)"
+
+[[assumption]]
+key = "fees.platform"
+value = "0.0025"
+basis = "Typical UK platform fee"
+
+[[assumption]]
+key = "fees.fund"
+value = "0.0015"
+basis = "Typical index-tracker OCF"
+
+[[assumption]]
+key = "yield.equity"
+value = "0.02"
+basis = "Long-run global equity dividend yield (~2%); consistent with the shipped 4% real return default as income plus real capital growth"
+
+[[assumption]]
+key = "yield.bonds"
+value = "0.025"
+basis = "Bond income approximates the nominal return for portfolios held near par: the shipped 0.5% real return default plus 2% CPI"
+
+[[assumption]]
+key = "yield.cash"
+value = "0.015"
+basis = "Cash return is wholly income: the shipped -0.5% real return default plus 2% CPI"
+
+[[assumption]]
+key = "horizon.planning_age"
+value = 95
+basis = "~1-in-4 longevity risk at 65 per ONS cohort life expectancy (exact values from 2024-based cohort tables at implementation)"
+
+[[assumption]]
+key = "glidepath.default_shape"
+value = { equity_start = "0.80", derisk_years_before_retirement = 15, equity_at_retirement = "0.40", transition = "linear", in_drawdown = "hold" }
+basis = "Typical UK target-date/lifestyling shape; a starting point only - per-person glide paths override it"
+
+[[assumption]]
+key = "policy.state_pension.uprating"
+value = { rule = "triple_lock", floor = "0.025", deterministic_cpi_margin = "0.005" }
+basis = "Triple lock = max(earnings, CPI, floor 2.5%), proxied as max(CPI + 0.5%, floor) - the margin stands in for the long-run earnings premium; alternative scenario: cpi. The proxy applies in every run mode: CPI is deterministic across Monte Carlo paths and no earnings series is modelled. Triple lock committed only to ~2029 (planning §6)"
+
+[[assumption]]
+key = "policy.tax.future_years"
+value = { mode = "frozen_then_cpi_indexed", frozen_until_tax_year = "2030/31", scotland = { lower_bands_frozen_until_tax_year = "2026/27", upper_bands_frozen_until_tax_year = "2028/29" } }
+basis = "rUK thresholds + PA/taper (reserved, both regimes) frozen to 2030/31 is legislated fact (planning §6); Scottish band uppers are set annually - lower bands uprate in practice (CPI proxy past the shipped year), Higher/Advanced/Top committed frozen to 2028/29 per Scottish Budget 2026-27 (announced policy, not legislation); post-freeze CPI indexation is assumption. Alternative: frozen indefinitely"
+
+[[assumption]]
+key = "annuity.level.single.65"
+value = "0.0775"
+basis = "Which? market table, snapshot 2026-07-27, retrieved 2026-08-01; best rate 7.946% - volatile market snapshot, refresh before relying on"
+
+[[assumption]]
+key = "annuity.escalating3.single.65"
+value = "0.0547"
+basis = "Which? market table, same snapshot"
+
+[[assumption]]
+key = "annuity.inflation_linked.single.65"
+value = "0.055"
+basis = "Indicative only - secondary source (IFA Magazine); weakest-sourced default here"
+
+# Per-age/type relativities to the single-life-at-65 base rates above,
+# plus the joint-life factor and the escalating product's fixed annual
+# increase. Derived from the Hargreaves Lansdown best-buy annuity tables
+# (annual income per GBP 100,000: single life level / RPI-linked / 3%
+# escalation, joint life 50% level), snapshot 2026-07-31, retrieved
+# 2026-08-03; the inflation-linked curve uses the RPI-linked product's
+# relativities. Ages between the knots interpolate linearly; ages
+# outside 55-75 are a modelling error, never an extrapolation.
+[[assumption]]
+key = "annuity.age_adjustment"
+basis = "Relativities from the Hargreaves Lansdown best-buy annuity tables, snapshot 2026-07-31, retrieved 2026-08-03; joint factor is joint-life 50% over single-life level at 65 (~0.92); escalation is the escalating product's fixed 3%/yr increase"
+
+[assumption.value]
+escalation = "0.03"
+joint_factor = "0.92"
+
+[assumption.value.level]
+"55" = "0.846"
+"60" = "0.897"
+"65" = "1.0"
+"70" = "1.072"
+"75" = "1.230"
+
+[assumption.value.escalating3]
+"55" = "0.797"
+"60" = "0.870"
+"65" = "1.0"
+"70" = "1.124"
+"75" = "1.333"
+
+[assumption.value.inflation_linked]
+"55" = "0.794"
+"60" = "0.874"
+"65" = "1.0"
+"70" = "1.144"
+"75" = "1.380"

glidepath/regions/uk/data/returns_history.toml

@@ -0,0 +1,150 @@
+# Historical annual return series for the backtest engine (roadmap 9.18;
+# conventions per docs/planning.md §5.3): world equity total returns in
+# GBP terms (GDP-weighted over the JST countries, currency moves
+# included), UK long gilt total returns, UK bills, and UK CPI inflation.
+# All rates are NOMINAL; real rates are derived in code as
+# (1 + nominal) / (1 + cpi) - 1. Derived from the Jordà-Schularick-Taylor
+# Macrohistory Database R6 by scripts/build_returns_history.py — never
+# edit a figure by hand; regenerate, re-verify, and update [meta].
+#
+# Data licence: unlike the code in this repository, the figures below are
+# a derived work of the JST Macrohistory Database (© Òscar Jordà, Moritz
+# Schularick, Alan M. Taylor and co-authors), distributed under
+# CC BY-NC-SA 4.0 (https://creativecommons.org/licenses/by-nc-sa/4.0/).
+# Cite Jordà, Schularick & Taylor (2017) and, for the return series,
+# Jordà, Knoll, Kuvshinov, Schularick & Taylor (2019).
+
+schema_version = 2
+
+[meta]
+verified_on = 2026-08-05
+sources = [
+  "https://www.macrohistory.net/database/",
+  "https://doi.org/10.1093/qje/qjz012",
+]
+
+# One entry per calendar year, contiguous.
+[returns]
+series = [
+  { year = 1900, equity = "0.089265", bonds = "-0.004351", cash = "0.036600", cpi = "0.051000" },
+  { year = 1901, equity = "0.083569", bonds = "-0.016046", cash = "0.031600", cpi = "0.005000" },
+  { year = 1902, equity = "0.064752", bonds = "0.019486", cash = "0.029700", cpi = "0.000000" },
+  { year = 1903, equity = "-0.014222", bonds = "-0.027631", cash = "0.034100", cpi = "0.004000" },
+  { year = 1904, equity = "0.183341", bonds = "0.041458", cash = "0.026800", cpi = "-0.002000" },
+  { year = 1905, equity = "0.148694", bonds = "0.035830", cash = "0.025600", cpi = "0.004000" },
+  { year = 1906, equity = "0.096150", bonds = "-0.010846", cash = "0.039900", cpi = "0.000000" },
+  { year = 1907, equity = "-0.121251", bonds = "0.000132", cash = "0.044700", cpi = "0.012000" },
+  { year = 1908, equity = "0.204636", bonds = "0.035945", cash = "0.023200", cpi = "0.005000" },
+  { year = 1909, equity = "0.145710", bonds = "0.018180", cash = "0.022900", cpi = "0.005000" },
+  { year = 1910, equity = "0.001891", bonds = "-0.013062", cash = "0.031600", cpi = "0.009000" },
+  { year = 1911, equity = "0.047476", bonds = "0.002250", cash = "0.029100", cpi = "0.001000" },
+  { year = 1912, equity = "0.063221", bonds = "0.007547", cash = "0.036200", cpi = "0.030000" },
+  { year = 1913, equity = "-0.038684", bonds = "-0.013174", cash = "0.043700", cpi = "-0.004000" },
+  { year = 1914, equity = "-0.057368", bonds = "0.044682", cash = "0.029100", cpi = "-0.003000" },
+  { year = 1915, equity = "0.179977", bonds = "0.034000", cash = "0.036600", cpi = "0.125000" },
+  { year = 1916, equity = "0.095367", bonds = "-0.202986", cash = "0.052000", cpi = "0.181000" },
+  { year = 1917, equity = "-0.054226", bonds = "0.030637", cash = "0.047900", cpi = "0.252000" },
+  { year = 1918, equity = "0.152737", bonds = "0.127967", cash = "0.035700", cpi = "0.220000" },
+  { year = 1919, equity = "0.090777", bonds = "-0.084263", cash = "0.034800", cpi = "0.101000" },
+  { year = 1920, equity = "-0.133812", bonds = "-0.073387", cash = "0.062100", cpi = "0.154000" },
+  { year = 1921, equity = "0.023880", bonds = "0.164649", cash = "0.045800", cpi = "-0.086000" },
+  { year = 1922, equity = "0.116231", bonds = "0.159672", cash = "0.025700", cpi = "-0.140000" },
+  { year = 1923, equity = "0.209454", bonds = "0.042221", cash = "0.026200", cpi = "-0.060000" },
+  { year = 1924, equity = "0.152745", bonds = "0.073520", cash = "0.033900", cpi = "-0.007000" },
+  { year = 1925, equity = "0.082649", bonds = "0.003139", cash = "0.040900", cpi = "0.003000" },
+  { year = 1926, equity = "0.205101", bonds = "0.028755", cash = "0.045100", cpi = "-0.008000" },
+  { year = 1927, equity = "0.281417", bonds = "0.071688", cash = "0.042500", cpi = "-0.024000" },
+  { year = 1928, equity = "0.288268", bonds = "0.059311", cash = "0.041500", cpi = "-0.003000" },
+  { year = 1929, equity = "-0.072253", bonds = "-0.015965", cash = "0.052600", cpi = "-0.009000" },
+  { year = 1930, equity = "-0.210017", bonds = "0.131428", cash = "0.024800", cpi = "-0.028000" },
+  { year = 1931, equity = "-0.283587", bonds = "-0.005443", cash = "0.035900", cpi = "-0.043000" },
+  { year = 1932, equity = "0.212621", bonds = "0.403182", cash = "0.014900", cpi = "-0.026000" },
+  { year = 1933, equity = "0.270342", bonds = "0.031661", cash = "0.005900", cpi = "-0.021000" },
+  { year = 1934, equity = "-0.031001", bonds = "0.276968", cash = "0.007300", cpi = "0.000000" },
+  { year = 1935, equity = "0.291837", bonds = "-0.031190", cash = "0.005500", cpi = "0.007000" },
+  { year = 1936, equity = "0.252380", bonds = "0.002684", cash = "0.005800", cpi = "0.007000" },
+  { year = 1937, equity = "-0.184306", bonds = "-0.092034", cash = "0.005600", cpi = "0.034000" },
+  { year = 1938, equity = "0.065716", bonds = "-0.021813", cash = "0.006100", cpi = "0.016000" },
+  { year = 1939, equity = "0.146198", bonds = "0.009540", cash = "0.013200", cpi = "0.028000" },
+  { year = 1940, equity = "0.226479", bonds = "0.159367", cash = "0.010300", cpi = "0.168000" },
+  { year = 1941, equity = "0.009918", bonds = "0.105643", cash = "0.010100", cpi = "0.108000" },
+  { year = 1942, equity = "0.122409", bonds = "0.027593", cash = "0.010000", cpi = "0.071000" },
+  { year = 1943, equity = "0.175061", bonds = "-0.004982", cash = "0.010000", cpi = "0.034000" },
+  { year = 1944, equity = "0.134137", bonds = "0.057250", cash = "0.010000", cpi = "0.027000" },
+  { year = 1945, equity = "0.242946", bonds = "0.148149", cash = "0.009000", cpi = "0.028000" },
+  { year = 1946, equity = "0.171915", bonds = "0.107610", cash = "0.005000", cpi = "0.031000" },
+  { year = 1947, equity = "0.214035", bonds = "-0.143347", cash = "0.005100", cpi = "0.070000" },
+  { year = 1948, equity = "-0.138832", bonds = "0.006970", cash = "0.005100", cpi = "0.077000" },
+  { year = 1949, equity = "0.491191", bonds = "-0.089347", cash = "0.005200", cpi = "0.028000" },
+  { year = 1950, equity = "0.161823", bonds = "0.040642", cash = "0.005200", cpi = "0.039185" },
+  { year = 1951, equity = "0.357201", bonds = "-0.096837", cash = "0.005600", cpi = "0.090498" },
+  { year = 1952, equity = "0.071894", bonds = "-0.006850", cash = "0.022000", cpi = "0.106501" },
+  { year = 1953, equity = "0.078079", bonds = "0.138610", cash = "0.023000", cpi = "0.036250" },
+  { year = 1954, equity = "0.518630", bonds = "0.060638", cash = "0.017900", cpi = "0.022919" },
+  { year = 1955, equity = "0.240524", bonds = "-0.101183", cash = "0.037500", cpi = "0.050708" },
+  { year = 1956, equity = "0.026371", bonds = "-0.029814", cash = "0.049500", cpi = "0.051627" },
+  { year = 1957, equity = "-0.070412", bonds = "-0.063057", cash = "0.048100", cpi = "0.038420" },
+  { year = 1958, equity = "0.361389", bonds = "0.170271", cash = "0.045600", cpi = "0.028777" },
+  { year = 1959, equity = "0.279276", bonds = "0.009832", cash = "0.033800", cpi = "0.005994" },
+  { year = 1960, equity = "0.054619", bonds = "-0.071032", cash = "0.048900", cpi = "0.007944" },
+  { year = 1961, equity = "0.202969", bonds = "-0.079440", cash = "0.051400", cpi = "0.032512" },
+  { year = 1962, equity = "-0.089243", bonds = "0.247768", cash = "0.041700", cpi = "0.041985" },
+  { year = 1963, equity = "0.157864", bonds = "0.036340", cash = "0.036700", cpi = "0.021062" },
+  { year = 1964, equity = "0.085160", bonds = "-0.023652", cash = "0.045900", cpi = "0.032287" },
+  { year = 1965, equity = "0.068515", bonds = "0.043927", cash = "0.059100", cpi = "0.042572" },
+  { year = 1966, equity = "-0.056785", bonds = "0.042149", cash = "0.061200", cpi = "0.040000" },
+  { year = 1967, equity = "0.365652", bonds = "0.023494", cash = "0.058100", cpi = "0.022436" },
+  { year = 1968, equity = "0.195415", bonds = "-0.023348", cash = "0.070300", cpi = "0.039969" },
+  { year = 1969, equity = "0.008073", bonds = "-0.002488", cash = "0.076300", cpi = "0.051997" },
+  { year = 1970, equity = "-0.014822", bonds = "0.034527", cash = "0.070200", cpi = "0.065186" },
+  { year = 1971, equity = "0.096383", bonds = "0.269080", cash = "0.055800", cpi = "0.094149" },
+  { year = 1972, equity = "0.373878", bonds = "-0.041294", cash = "0.055200", cpi = "0.071911" },
+  { year = 1973, equity = "-0.001318", bonds = "-0.087871", cash = "0.093800", cpi = "0.093463" },
+  { year = 1974, equity = "-0.206434", bonds = "-0.157680", cash = "0.113800", cpi = "0.157315" },
+  { year = 1975, equity = "0.509732", bonds = "0.361257", cash = "0.101800", cpi = "0.227005" },
+  { year = 1976, equity = "0.298244", bonds = "0.138826", cash = "0.111500", cpi = "0.156573" },
+  { year = 1977, equity = "-0.054435", bonds = "0.455556", cash = "0.076600", cpi = "0.149425" },
+  { year = 1978, equity = "0.168867", bonds = "-0.025752", cash = "0.085100", cpi = "0.074722" },
+  { year = 1979, equity = "0.005701", bonds = "0.041836", cash = "0.130000", cpi = "0.113724" },
+  { year = 1980, equity = "0.124930", bonds = "0.191252", cash = "0.151200", cpi = "0.151543" },
+  { year = 1981, equity = "0.192427", bonds = "0.099868", cash = "0.129800", cpi = "0.118098" },
+  { year = 1982, equity = "0.252504", bonds = "0.535222", cash = "0.113800", cpi = "0.081110" },
+  { year = 1983, equity = "0.371905", bonds = "0.078283", cash = "0.095900", cpi = "0.049350" },
+  { year = 1984, equity = "0.321407", bonds = "0.037561", cash = "0.093000", cpi = "0.042580" },
+  { year = 1985, equity = "0.210940", bonds = "0.199184", cash = "0.116000", cpi = "0.049223" },
+  { year = 1986, equity = "0.424598", bonds = "0.125390", cash = "0.103400", cpi = "0.033261" },
+  { year = 1987, equity = "-0.062390", bonds = "0.178991", cash = "0.092300", cpi = "0.032049" },
+  { year = 1988, equity = "0.211144", bonds = "0.068684", cash = "0.098000", cpi = "0.037592" },
+  { year = 1989, equity = "0.391700", bonds = "0.082100", cash = "0.132800", cpi = "0.052376" },
+  { year = 1990, equity = "-0.201779", bonds = "0.082109", cash = "0.140900", cpi = "0.069727" },
+  { year = 1991, equity = "0.141957", bonds = "0.184824", cash = "0.108200", cpi = "0.075326" },
+  { year = 1992, equity = "0.181181", bonds = "0.200163", cash = "0.089400", cpi = "0.042615" },
+  { year = 1993, equity = "0.253227", bonds = "0.227906", cash = "0.052100", cpi = "0.025065" },
+  { year = 1994, equity = "0.011726", bonds = "-0.104130", cash = "0.051500", cpi = "0.019785" },
+  { year = 1995, equity = "0.170583", bonds = "0.175601", cash = "0.063300", cpi = "0.026565" },
+  { year = 1996, equity = "0.072023", bonds = "0.077644", cash = "0.057800", cpi = "0.024003" },
+  { year = 1997, equity = "0.194018", bonds = "0.167595", cash = "0.064800", cpi = "0.018246" },
+  { year = 1998, equity = "0.206531", bonds = "0.211694", cash = "0.068200", cpi = "0.015574" },
+  { year = 1999, equity = "0.265622", bonds = "-0.041475", cash = "0.050400", cpi = "0.013287" },
+  { year = 2000, equity = "0.016360", bonds = "0.097945", cash = "0.058000", cpi = "0.007965" },
+  { year = 2001, equity = "-0.167235", bonds = "0.029549", cash = "0.047600", cpi = "0.012335" },
+  { year = 2002, equity = "-0.245099", bonds = "0.102087", cash = "0.038600", cpi = "0.012589" },
+  { year = 2003, equity = "0.176649", bonds = "0.021114", cash = "0.035600", cpi = "0.013616" },
+  { year = 2004, equity = "0.119649", bonds = "0.066381", cash = "0.044400", cpi = "0.013435" },
+  { year = 2005, equity = "0.209706", bonds = "0.085014", cash = "0.045500", cpi = "0.020569" },
+  { year = 2006, equity = "0.108019", bonds = "-0.005020", cash = "0.046500", cpi = "0.023287" },
+  { year = 2007, equity = "0.098177", bonds = "0.062061", cash = "0.055300", cpi = "0.023228" },
+  { year = 2008, equity = "-0.165409", bonds = "0.159729", cash = "0.043200", cpi = "0.036019" },
+  { year = 2009, equity = "0.129192", bonds = "-0.015164", cash = "0.005300", cpi = "0.021653" },
+  { year = 2010, equity = "0.129113", bonds = "0.101185", cash = "0.005000", cpi = "0.032982" },
+  { year = 2011, equity = "-0.045778", bonds = "0.184079", cash = "0.004800", cpi = "0.044637" },
+  { year = 2012, equity = "0.114294", bonds = "0.038486", cash = "0.003130", cpi = "0.028282" },
+  { year = 2013, equity = "0.244511", bonds = "-0.061271", cash = "0.003020", cpi = "0.025648" },
+  { year = 2014, equity = "0.088731", bonds = "0.155964", cash = "0.003800", cpi = "0.014610" },
+  { year = 2015, equity = "0.069384", bonds = "0.007676", cash = "0.004400", cpi = "0.000401" },
+  { year = 2016, equity = "0.234059", bonds = "0.071265", cash = "0.002024", cpi = "0.006597" },
+  { year = 2017, equity = "0.129036", bonds = "0.037439", cash = "0.004123", cpi = "0.027000" },
+  { year = 2018, equity = "0.047819", bonds = "0.022330", cash = "0.006998", cpi = "0.025000" },
+  { year = 2019, equity = "0.118576", bonds = "0.057202", cash = "0.007098", cpi = "0.018000" },
+  { year = 2020, equity = "0.089930", bonds = "0.057524", cash = "0.000394", cpi = "0.009000" },
+]

glidepath/regions/uk/data/tax_year_2026_27.toml

@@ -0,0 +1,98 @@
+# UK tax year 2026/27 policy figures (docs/planning.md §5.3, §6).
+# Income tax, pension and ISA figures verified 2026-08-01/02; savings,
+# dividend, AA carry-forward and DB valuation figures 2026-08-04; the
+# scheme-pays minimum 2026-08-06 — all from the primary sources below;
+# never edit a figure without re-verifying and updating [meta].
+
+schema_version = 2
+
+[meta]
+tax_year    = "2026/27"
+start_date  = 2026-04-06
+end_date    = 2027-04-05
+verified_on = 2026-08-06
+sources = [
+  "https://www.gov.uk/hmrc-internal-manuals/pensions-tax-manual/ptm056410",
+  "https://www.legislation.gov.uk/ukpga/2004/12/section/237B",
+  "https://www.gov.uk/income-tax-rates",
+  "https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027",
+  "https://www.gov.uk/scottish-income-tax",
+  "https://www.gov.uk/government/publications/rates-and-allowances-pension-schemes/pension-schemes-rates",
+  "https://www.gov.uk/tax-on-your-private-pension/pension-tax-relief",
+  "https://www.legislation.gov.uk/ukpga/2004/12/section/190",
+  "https://www.gov.uk/hmrc-internal-manuals/pensions-tax-manual/ptm044100",
+  "https://www.gov.uk/guidance/check-if-you-have-unused-annual-allowances-on-your-pension-savings",
+  "https://www.gov.uk/hmrc-internal-manuals/pensions-tax-manual/ptm056510",
+  "https://www.gov.uk/hmrc-internal-manuals/pensions-tax-manual/ptm053301",
+  "https://www.legislation.gov.uk/ukpga/2004/12/section/234",
+  "https://www.gov.uk/individual-savings-accounts",
+  "https://www.gov.uk/lifetime-isa",
+  "https://www.gov.uk/tax-on-dividends",
+  "https://www.gov.uk/apply-tax-free-interest-on-savings",
+  "https://www.gov.uk/government/publications/budget-2025-overview-of-tax-legislation-and-rates-ootlar/budget-2025-overview-of-tax-legislation-and-rates-ootlar",
+]
+
+[income_tax.ruk]
+personal_allowance = "12570"
+pa_taper_threshold = "100000"  # adjusted net income; PA -£1 per £2 above
+pa_taper_rate      = "0.5"
+# Band widths are TAXABLE income above the personal allowance, ascending.
+bands = [
+  { name = "basic", rate = "0.20", upper = "37700" },
+  { name = "higher", rate = "0.40", upper = "125140" },
+  { name = "additional", rate = "0.45" },  # no upper = unbounded
+]
+
+[income_tax.scotland]  # non-savings/non-dividend income only
+personal_allowance = "12570"
+pa_taper_threshold = "100000"
+pa_taper_rate      = "0.5"
+bands = [
+  { name = "starter", rate = "0.19", upper = "3967" },
+  { name = "basic", rate = "0.20", upper = "16956" },
+  { name = "intermediate", rate = "0.21", upper = "31092" },
+  { name = "higher", rate = "0.42", upper = "62430" },
+  { name = "advanced", rate = "0.45", upper = "125140" },
+  { name = "top", rate = "0.48" },
+]
+
+[pension]
+annual_allowance           = "60000"
+aa_taper_threshold_income  = "200000"
+aa_taper_adjusted_income   = "260000"
+aa_taper_rate              = "0.5"
+aa_taper_floor             = "10000"
+mpaa                       = "10000"
+aa_carry_forward_years     = 3  # unused AA carries from the previous 3 tax years
+scheme_pays_min_charge     = "2000"  # mandatory scheme pays above this charge (FA 2004 s237B)
+member_relief_basic_amount = "3600"  # low/no-earner relief floor, RAS only
+member_relief_max_age      = 75  # no relief on contributions from age 75 (FA 2004 s188)
+relief_at_source_rate      = "0.20"
+tax_free_lump_sum_fraction = "0.25"
+lump_sum_allowance         = "268275"
+lump_sum_death_benefit_allowance = "1073100"
+db_valuation_factor        = 16  # FA 2004 s234 relevant valuation factor (PIA = 16 x pension)
+
+[isa]
+annual_allowance = "20000"
+lisa_allowance   = "4000"  # counts within the overall ISA allowance
+lisa_bonus_rate  = "0.25"
+lisa_withdrawal_charge = "0.25"
+
+# Nil rates consume band width (§6); savings above them are taxed at the
+# rUK band rates until the separate savings rates land in the 2027/28 file.
+[savings]
+starting_rate_limit = "5000"  # reduced £1 per £1 of non-savings income above the PA
+psa_basic      = "1000"
+psa_higher     = "500"
+psa_additional = "0"
+
+# Rates align positionally with the rUK bands (dividends are UK-wide).
+# 2026/27 figures include the Budget 2025 +2ppt change, in force.
+[dividend]
+allowance = "500"  # a nil rate, not a deduction
+rates = [
+  { name = "ordinary", rate = "0.1075" },
+  { name = "upper", rate = "0.3575" },
+  { name = "additional", rate = "0.3935" },
+]