Store marginal National Insurance schedules as scales

changelog.d/222-ni-scale-parameters.changed.md

@@ -0,0 +1,4 @@
+- Store marginal National Insurance schedules as parameter scales while preserving contribution calculations and existing scalar reform paths.
+- Reject unsupported changes to the fixed zero-rate, zero-threshold NI scale sentinel with a targeted error.
+- Direct YAML readers must migrate the ten removed scalar files to the canonical scale files; parameter-tree readers retain the legacy compatibility paths.
+- Retain incoming savings indexation, director and liability rules while migrating NI readers; hide legacy and fixed-zero discovery controls without removing their IDs or update contracts.

docs/book/index.md

@@ -67,3 +67,7 @@ revenue = (
 )
 f"Revenue: £{round(revenue / 1e9, 1)}bn"
 ```
+
+## Model reference
+
+- [National Insurance parameter scales](programs/gov/hmrc/national-insurance-scales.md)

docs/book/policy/model-baseline.md

@@ -8,15 +8,15 @@ PolicyEngine UK models the UK tax and benefit system as of 2025, incorporating m
 
 ### Budget 2025 threshold freezes
 
-Budget 2025 keeps the income tax personal allowance and basic rate limit, and the equivalent National Insurance thresholds, at their current levels until April 2031. Finance Act 2021 s.5, as amended by Finance Act 2023 s.5 and Finance Act 2026 s.10, fixes the [personal allowance](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/income_tax/allowances/personal_allowance/amount.yaml) at £12,570 and the [basic rate limit](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/income_tax/rates/uk.yaml) at £37,700 for 2022-23 to 2030-31. The model holds the [primary threshold](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/primary_threshold.yaml) and [lower profits limit](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/national_insurance/class_4/thresholds/lower_profits_limit.yaml) at £12,570, the [upper earnings limit](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/upper_earnings_limit.yaml) and [upper profits limit](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/national_insurance/class_4/thresholds/upper_profits_limit.yaml) at £50,270, and the [secondary threshold](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/secondary_threshold.yaml) at £5,000 a year through 2030-31. For Class 1, regulations set only the 2026-27 amounts; the later years are announced policy. The Class 4 limits are standing figures in SSCBA 1992 s.15(3). The [lower earnings limit](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/lower_earnings_limit.yaml) is not frozen: it rose with CPI to £129 a week in 2026-27.
+Budget 2025 keeps the income tax personal allowance and basic rate limit, and the equivalent National Insurance thresholds, at their current levels until April 2031. Finance Act 2021 s.5, as amended by Finance Act 2023 s.5 and Finance Act 2026 s.10, fixes the [personal allowance](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/income_tax/allowances/personal_allowance/amount.yaml) at £12,570 and the [basic rate limit](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/income_tax/rates/uk.yaml) at £37,700 for 2022-23 to 2030-31. The model holds the [primary threshold](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/primary_threshold.yaml) and [lower profits limit](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_4/thresholds/lower_profits_limit.yaml) at £12,570, the [upper earnings limit](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/upper_earnings_limit.yaml) and [upper profits limit](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_4/thresholds/upper_profits_limit.yaml) at £50,270, and the [secondary threshold](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/secondary_threshold.yaml) at £5,000 a year through 2030-31. For Class 1, regulations set only the 2026-27 amounts; the later years are announced policy. The Class 4 limits are standing figures in SSCBA 1992 s.15(3). The [lower earnings limit](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/lower_earnings_limit.yaml) is not frozen: it rose with CPI to £129 a week in 2026-27.
 
 From 2031-32 the model indexes these thresholds by September CPI, in [`create_threshold_indexation.py`](https://github.com/PolicyEngine/policyengine-uk/blob/main/policyengine_uk/parameters/gov/hmrc/create_threshold_indexation.py). The personal allowance and basic rate limit follow Income Tax Act 2007 ss.57 and 21 year by year: each rises by the CPI increase to the previous September, with the allowance's increase rounded up to a multiple of £10 and the limit rounded up to a multiple of £100. The government says the National Insurance thresholds will also be uprated by September CPI after 2030-31 (Explanatory Memorandum to SI 2026/231, para 5.1), and it has kept them aligned with income tax through the freeze (HMRC's Budget 2025 policy paper on the threshold freeze; Explanatory Memorandum to SI 2026/231, paras 5.14 and 5.15). The model assumes the alignment continues, round-ups included: the primary threshold and lower profits limit equal the personal allowance, and the upper earnings and profits limits equal the higher rate threshold (the personal allowance plus the basic rate limit). It also assumes the secondary threshold rises by September CPI, unrounded; the Autumn Budget 2024 policy paper says only that it will be increased in line with CPI. None of these National Insurance rules after 2030-31 is law.
 
 ## 2025 reforms
 
 ### Autumn Budget 2024
 
-The government increased the [employer National Insurance rate from 13.8% to 15%](https://github.com/PolicyEngine/policyengine-uk/blob/master/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/rates/employer.yaml#L30-L35) and reduced the [employer secondary threshold from £9,100 to £5,000 annually](https://github.com/PolicyEngine/policyengine-uk/blob/master/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/secondary_threshold.yaml#L26-L30), both taking effect in fiscal year 2025-26.
+The government increased the [employer National Insurance rate from 13.8% to 15%](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/rates/employer.yaml) and reduced the [employer secondary threshold from £9,100 to £5,000 annually](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/secondary_threshold.yaml), both taking effect in fiscal year 2025-26.
 
 ### Universal Credit rebalancing
 
@@ -30,7 +30,7 @@ Annual benefit uprating applied 4.1% increases to state pensions and 1.7% to wor
 
 ### Autumn Statement 2023
 
-The government announced further National Insurance cuts, reducing the [employee main rate from 10% to 8%](https://github.com/PolicyEngine/policyengine-uk/blob/master/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/rates/employee/main.yaml#L24-L29) and the [self-employed Class 4 rate from 9% to 6%](https://github.com/PolicyEngine/policyengine-uk/blob/master/policyengine_uk/parameters/gov/hmrc/national_insurance/class_4/rates/main.yaml#L26-L33) in fiscal year 2024-25. [Class 2 National Insurance contributions were abolished](https://github.com/PolicyEngine/policyengine-uk/blob/master/policyengine_uk/parameters/gov/hmrc/national_insurance/class_2/flat_rate.yaml#L51-L56) for self-employed people, with the flat rate set to £0 in fiscal year 2024-25.
+The government announced further National Insurance cuts, reducing the [employee main rate from 10% to 8%](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/rates/employee/main.yaml) and the [self-employed Class 4 rate from 9% to 6%](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_4/rates/main.yaml) in fiscal year 2024-25. [Class 2 National Insurance contributions were abolished](https://github.com/PolicyEngine/policyengine-uk/blob/master/policyengine_uk/parameters/gov/hmrc/national_insurance/class_2/flat_rate.yaml#L51-L56) for self-employed people, with the flat rate set to £0 in fiscal year 2024-25.
 
 ### Capital gains tax changes (Autumn Budget 2024)
 
@@ -42,7 +42,7 @@ The government increased the [child benefit high income tax charge threshold fro
 
 ### Autumn Statement 2023 (Employee NI cut)
 
-An initial National Insurance cut reduced the [employee main rate from 12% to 10%](https://github.com/PolicyEngine/policyengine-uk/blob/master/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/rates/employee/main.yaml#L18-L23) in fiscal year 2024-25.
+An initial National Insurance cut reduced the [employee main rate from 12% to 10%](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/rates/employee/main.yaml) in fiscal year 2024-25.
 
 ## 2023 reforms
 
@@ -54,11 +54,11 @@ The government reduced the [additional rate income tax threshold from £150,000
 
 ### Spring Statement 2022
 
-The government announced an increase in the [National Insurance primary threshold from £9,880 to £12,570](https://github.com/PolicyEngine/policyengine-uk/blob/master/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/primary_threshold.yaml#L17-L22), aligning it with the personal allowance in fiscal year 2022-23.
+The government announced an increase in the [National Insurance primary threshold from £9,880 to £12,570](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/thresholds/primary_threshold.yaml), aligning it with the personal allowance in fiscal year 2022-23.
 
 ### Autumn Budget 2021 (Health and Social Care Levy)
 
-The Health and Social Care Levy Act 2021 raised the [employee main rate from 12% to 13.25%](https://github.com/PolicyEngine/policyengine-uk/blob/master/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/rates/employee/main.yaml#L4-L17) and the [employer rate from 13.8% to 15.05%](https://github.com/PolicyEngine/policyengine-uk/blob/master/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/rates/employer.yaml#L18-L29) for fiscal year 2022-23. The Health and Social Care Levy (Repeal) Act 2022 restored 12% and 13.8% for earnings paid from 6 November 2022. The model reads each fiscal year's rates at 30 April, so 2022-23 carries the levy rates for the whole year ([#1807](https://github.com/PolicyEngine/policyengine-uk/issues/1807)).
+The Health and Social Care Levy Act 2021 raised the [employee main rate from 12% to 13.25%](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/rates/employee/main.yaml) and the [employer rate from 13.8% to 15.05%](https://github.com/PolicyEngine/policyengine-uk/blob/e1601dbe4feb15e71d0d59b7a57f9d860741c068/policyengine_uk/parameters/gov/hmrc/national_insurance/class_1/rates/employer.yaml) for fiscal year 2022-23. The Health and Social Care Levy (Repeal) Act 2022 restored 12% and 13.8% for earnings paid from 6 November 2022. The model reads each fiscal year's rates at 30 April, so 2022-23 carries the levy rates for the whole year ([#1807](https://github.com/PolicyEngine/policyengine-uk/issues/1807)).
 
 ### Mini-Budget 2022 (September)
 

docs/book/programs/gov/hmrc/national-insurance-scales.md

@@ -0,0 +1,93 @@
+# National Insurance parameter scales
+
+PolicyEngine UK stores three marginal National Insurance (NI) schedules as
+parameter scales. Each schedule holds its contribution rates and the thresholds
+at which they apply. The schedules retain their dated values and units.
+
+All paths below start with `gov.hmrc.national_insurance.`. Bracket indices start
+at zero. Bracket zero supplies the fixed zero-threshold, zero-rate sentinel.
+Contribution reforms use brackets 1 and 2 below. Any nonzero, missing or null
+threshold or rate in bracket zero is rejected with a targeted error naming the
+canonical leaf. Validation covers its full dated history, including future
+entries; an explicit update to zero leaves calculations unchanged.
+
+| Scale | Contribution bands | Threshold period in the parameter files |
+| --- | --- | --- |
+| `class_1.employee_scale` | Primary rate in bracket 1; additional rate in bracket 2 | Week |
+| `class_1.employer_scale` | Employer rate in bracket 1 | Week |
+| `class_4.contribution_scale` | Main rate in bracket 1; additional rate in bracket 2 | Year |
+
+The contribution formulas retain their period conversions. Changing the
+parameter layout does not make a weekly threshold an annual amount. Class 2's
+flat contribution amount and its eligibility thresholds remain scalar
+parameters.
+
+## Reform paths
+
+Use the following canonical paths when specifying new rate or threshold reforms.
+The old scalar paths remain live views of the corresponding scale components.
+Updating either path changes the same dated parameter history.
+
+| Existing scalar path | Canonical scale component |
+| --- | --- |
+| `class_1.rates.employee.main` | `class_1.employee_scale[1].rate` |
+| `class_1.rates.employee.additional` | `class_1.employee_scale[2].rate` |
+| `class_1.thresholds.primary_threshold` | `class_1.employee_scale[1].threshold` |
+| `class_1.thresholds.upper_earnings_limit` | `class_1.employee_scale[2].threshold` |
+| `class_1.rates.employer` | `class_1.employer_scale[1].rate` |
+| `class_1.thresholds.secondary_threshold` | `class_1.employer_scale[1].threshold` |
+| `class_4.rates.main` | `class_4.contribution_scale[1].rate` |
+| `class_4.rates.additional` | `class_4.contribution_scale[2].rate` |
+| `class_4.thresholds.lower_profits_limit` | `class_4.contribution_scale[1].threshold` |
+| `class_4.thresholds.upper_profits_limit` | `class_4.contribution_scale[2].threshold` |
+
+The bracket syntax above identifies a leaf in a reform path. Python callables
+access a raw scale through its `brackets` list, for example
+`parameters.gov.hmrc.national_insurance.class_1.employee_scale.brackets[1].rate`.
+Existing scalar attribute chains and leaf updates remain supported. The model's
+scalar views expose the old names, current dated values, descriptions and units.
+
+Apply scalar changes through the rate or threshold leaf. The compatibility views
+do not provide a second editable copy of the NI schedules. Replacing, deleting or
+reparenting legacy subtrees requires an explicit structural migration using the
+canonical scales; conflicting legacy replacements raise a migration error.
+
+## Contribution outputs
+
+The scales preserve the model's contribution components. Employee Class 1 NI
+still adds `ni_class_1_employee_primary` and
+`ni_class_1_employee_additional`. These outputs retain their separate input
+overrides. Class 4 still calculates its main and additional contributions and
+applies the existing annual-maximum rules. Employer NI retains its existing
+pension-contribution switch.
+
+The parameter migration preserves the existing calculation rules, liability
+conditions and rounding.
+
+## Maintaining the schedules
+
+Edit the canonical scale components when changing the model. Their dated values,
+references, units and uprating metadata supply the legacy scalar views. The NI
+threshold generator writes to these canonical leaves. Parameter processing visits
+each numerical history once; metadata discovery also exposes the legacy names.
+
+Metadata retains both primitive IDs and their histories and units. Discovery
+marks the ten legacy scalar views and the six fixed-zero leaves with
+`household: false` and `economy: false`; the ten canonical contribution rate and
+threshold leaves remain visible. Direct legacy lookup still resolves the same
+canonical metadata and values, while enumeration supplies presentation-only
+views. Hiding a fixed-zero control does not change its input-validation rule.
+
+The pinned, source-extracted API contract tests cover these flags, all other
+record fields and update routes. They do not verify a deployed API or the app's
+tree, search and control presentation. Consumer owners must check those surfaces
+before relying on the migration in a UI.
+
+The separate full-year Category A director scale and factual-input gate for
+2022–23 retain their constrained annual calculation and monthly allocation.
+They are not replaced by the ordinary employee schedule. The savings starting
+rate remains an annual limit, indexed alongside the five canonical NI threshold
+writers without treating it as a weekly amount.
+
+For NI rate reforms in behavioural scenarios, see
+[Labour supply dynamics](../../../usage/dynamics.md).