@casomoltd/nhs-pay 0.15.2 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/README.md +66 -16
  2. package/dist/afc-band.d.ts +33 -0
  3. package/dist/afc-band.js +33 -0
  4. package/dist/afc-band.js.map +1 -0
  5. package/dist/afc-scales.d.ts +67 -0
  6. package/dist/afc-scales.js +238 -0
  7. package/dist/afc-scales.js.map +1 -0
  8. package/dist/allowances.d.ts +91 -0
  9. package/dist/allowances.js +180 -0
  10. package/dist/allowances.js.map +1 -0
  11. package/dist/award.d.ts +175 -36
  12. package/dist/award.js +370 -47
  13. package/dist/award.js.map +1 -1
  14. package/dist/bands.d.ts +34 -12
  15. package/dist/bands.js +26 -9
  16. package/dist/bands.js.map +1 -1
  17. package/dist/circulars/afc-shapes.d.ts +101 -0
  18. package/dist/circulars/afc-shapes.js +18 -0
  19. package/dist/circulars/afc-shapes.js.map +1 -0
  20. package/dist/circulars/{england-md-1-2026r.d.ts → england-md-1-2026-r2.d.ts} +198 -32
  21. package/dist/circulars/{england-md-1-2026r.js → england-md-1-2026-r2.js} +142 -76
  22. package/dist/circulars/england-md-1-2026-r2.js.map +1 -0
  23. package/dist/circulars/ni-hsc-afc-06-2025.d.ts +63 -0
  24. package/dist/circulars/ni-hsc-afc-06-2025.js +100 -0
  25. package/dist/circulars/ni-hsc-afc-06-2025.js.map +1 -0
  26. package/dist/circulars/ni-hsc-tc8-05-2025.d.ts +1 -1
  27. package/dist/circulars/ni-hsc-tc8-05-2025.js +1 -1
  28. package/dist/circulars/scotland-pcs-afc-2026-01.d.ts +82 -0
  29. package/dist/circulars/scotland-pcs-afc-2026-01.js +208 -0
  30. package/dist/circulars/scotland-pcs-afc-2026-01.js.map +1 -0
  31. package/dist/circulars/scotland-pcs-dd-2025-01.d.ts +1 -1
  32. package/dist/circulars/scotland-pcs-dd-2025-01.js +12 -4
  33. package/dist/circulars/scotland-pcs-dd-2025-01.js.map +1 -1
  34. package/dist/circulars/scotland-pcs-dd-2026-01.d.ts +2 -2
  35. package/dist/circulars/scotland-pcs-dd-2026-01.js +2 -2
  36. package/dist/circulars/scotland-pcs-dd-2026-02.d.ts +79 -0
  37. package/dist/circulars/scotland-pcs-dd-2026-02.js +185 -0
  38. package/dist/circulars/scotland-pcs-dd-2026-02.js.map +1 -0
  39. package/dist/circulars/wales-afc-w-02-2025.d.ts +53 -0
  40. package/dist/circulars/wales-afc-w-02-2025.js +85 -0
  41. package/dist/circulars/wales-afc-w-02-2025.js.map +1 -0
  42. package/dist/circulars/wales-afc-w-02-2026.d.ts +48 -0
  43. package/dist/circulars/wales-afc-w-02-2026.js +91 -0
  44. package/dist/circulars/wales-afc-w-02-2026.js.map +1 -0
  45. package/dist/circulars/wales-mdw-01-2025.d.ts +1 -1
  46. package/dist/circulars/wales-mdw-01-2025.js +1 -1
  47. package/dist/circulars/wales-mdw-01-2026.d.ts +1 -1
  48. package/dist/circulars/wales-mdw-01-2026.js +1 -1
  49. package/dist/dental-scales.d.ts +4 -4
  50. package/dist/dental-scales.js +30 -20
  51. package/dist/dental-scales.js.map +1 -1
  52. package/dist/document-source.d.ts +141 -0
  53. package/dist/document-source.js +80 -0
  54. package/dist/document-source.js.map +1 -0
  55. package/dist/errors.d.ts +31 -5
  56. package/dist/errors.js +32 -2
  57. package/dist/errors.js.map +1 -1
  58. package/dist/format.d.ts +2 -2
  59. package/dist/format.js.map +1 -1
  60. package/dist/gad/erf-2023-06-30.d.ts +1 -1
  61. package/dist/gad/erf-2023-06-30.js +2 -1
  62. package/dist/gad/erf-2023-06-30.js.map +1 -1
  63. package/dist/gad/factor-table.d.ts +2 -1
  64. package/dist/gad/factor-table.js.map +1 -1
  65. package/dist/gad/lrf-2023-06-30.d.ts +1 -1
  66. package/dist/gad/lrf-2023-06-30.js +2 -1
  67. package/dist/gad/lrf-2023-06-30.js.map +1 -1
  68. package/dist/hcas.d.ts +10 -14
  69. package/dist/hcas.js +13 -20
  70. package/dist/hcas.js.map +1 -1
  71. package/dist/index.d.ts +17 -9
  72. package/dist/index.js +17 -8
  73. package/dist/index.js.map +1 -1
  74. package/dist/iso-date.d.ts +87 -0
  75. package/dist/iso-date.js +97 -0
  76. package/dist/iso-date.js.map +1 -0
  77. package/dist/medical-scales.d.ts +19 -4
  78. package/dist/medical-scales.js +77 -20
  79. package/dist/medical-scales.js.map +1 -1
  80. package/dist/pension.d.ts +30 -0
  81. package/dist/pension.js +128 -8
  82. package/dist/pension.js.map +1 -1
  83. package/dist/post.d.ts +87 -2
  84. package/dist/post.js +112 -2
  85. package/dist/post.js.map +1 -1
  86. package/dist/regions.d.ts +1 -1
  87. package/dist/regions.js +1 -1
  88. package/dist/resolver.d.ts +57 -7
  89. package/dist/resolver.js +77 -25
  90. package/dist/resolver.js.map +1 -1
  91. package/dist/scale-point.d.ts +13 -4
  92. package/dist/scale-tables.d.ts +57 -10
  93. package/dist/scale-tables.js +58 -9
  94. package/dist/scale-tables.js.map +1 -1
  95. package/dist/scales.d.ts +169 -44
  96. package/dist/scales.js +462 -226
  97. package/dist/scales.js.map +1 -1
  98. package/dist/sources.d.ts +183 -0
  99. package/dist/sources.js +375 -0
  100. package/dist/sources.js.map +1 -0
  101. package/package.json +6 -4
  102. package/dist/circulars/england-md-1-2026r.js.map +0 -1
package/dist/scales.js CHANGED
@@ -2,10 +2,26 @@
2
2
  * NHS Agenda for Change pay scales by tax year.
3
3
  *
4
4
  * Pure salary data — no metadata (labels, slugs, role
5
- * descriptions); presentation copy is a hub-site concern.
5
+ * descriptions); presentation copy is a consumer concern.
6
6
  *
7
- * Sources, by the names they carry in docs/source-archive.md,
8
- * which holds every publisher URL and archived copy:
7
+ * ── Two layers, and which nation is in which ──
8
+ *
9
+ * Scotland, Wales and Northern Ireland each publish an AfC pay
10
+ * CIRCULAR, so each is transcribed verbatim in `src/circulars/*` and
11
+ * translated to canonical points by `afc-scales.ts`. This module holds
12
+ * the result, not the transcription.
13
+ *
14
+ * **England is the exception, and a documented one.** It publishes no
15
+ * AfC circular — its scales are an NHS Employers web page plus a
16
+ * poster — so there is nothing to transcribe and its tables are
17
+ * authored here directly. The rule: *where the publisher issues a
18
+ * circular, transcribe it verbatim; where it publishes a web table,
19
+ * cite it and pin it with fixtures.* Do NOT invent a pseudo-circular
20
+ * file for England to make the shapes match.
21
+ *
22
+ * Sources for what is authored HERE, by the names they carry in
23
+ * docs/source-archive.md, which holds every publisher URL and
24
+ * archived copy:
9
25
  * - "NHS Employers — AfC pay scales 2025/26"
10
26
  * - "NHS Employers — AfC pay scales 2026/27" (note its hourly
11
27
  * table has printing errors; this file reads the ANNUAL
@@ -18,30 +34,55 @@
18
34
  * - Wales floor: "Wales, AFC(W) 01/2026 living wage"
19
35
  * - HCAS rates: "NHS Terms and Conditions of Service
20
36
  * Handbook, amendment 62" (#sa-41), Annex 9
21
- * - Scotland (both years): "NHS Scotland, AfC pay scales 2025-26
22
- * and 2026-27 (MSG)" — 2025-26 rates revised by
23
- * "Scotland, PCS(AFC)2026/01"; 2026-27 in its Annex B
37
+ *
38
+ * The other three nations' sources are cited in their own circular
39
+ * files, beside the data they justify — including the qualification
40
+ * that used to live in this header, that Scotland's MSG consolidated
41
+ * table prints superseded 4.25% rates and must not be read instead of
42
+ * the circular.
43
+ *
44
+ * POINT LABELS — one convention, all four nations. A point's label is
45
+ * the year of service in which a member first reaches it: increment 1
46
+ * is `Year 1`, and the top point takes a `+` because service continues
47
+ * past it. No publisher prints such a label; every one is our reading
48
+ * of an interval the publisher does print. For the three circular
49
+ * nations that reading is now DERIVED in `afc-scales.ts` from the
50
+ * transcribed interval, so a label and its interval cannot disagree.
51
+ * England's are authored here, from the same convention.
52
+ *
53
+ * Labels are lookup keys for `afcResolver.fromScalePoint`, so changing
54
+ * one is an API change, and the fixtures assert them.
24
55
  */
25
- import { NATION_KEYS, TAX_YEARS } from '@casomoltd/paye-calc';
26
- import { ScaleUnavailable } from './errors.js';
27
- export const AFC_BANDS = {
28
- B2: '2',
29
- B3: '3',
30
- B4: '4',
31
- B5: '5',
32
- B6: '6',
33
- B7: '7',
34
- B8a: '8a',
35
- B8b: '8b',
36
- B8c: '8c',
37
- B8d: '8d',
38
- B9: '9',
56
+ import { NATION_KEYS, TAX_YEARS, CURRENT_TAX_YEAR, } from '@casomoltd/paye-calc';
57
+ import { ScaleUnavailable, invariant } from './errors.js';
58
+ import { AFC_ENGLAND_SCALES_2025, AFC_ENGLAND_SCALES_2026, AFC_NI_2025, AFC_SCOTLAND, AFC_W_02_2025, AFC_W_02_2026, } from './sources.js';
59
+ import { NI_SCALES_2025_26, SCOTLAND_SCALES_2025_26, SCOTLAND_SCALES_2026_27, WALES_SCALES_2025_26, WALES_SCALES_2026_27, } from './afc-scales.js';
60
+ // The band registry lives in its own module so the translation layer
61
+ // can name a band without importing this one — see `afc-band.ts`.
62
+ export { AFC_BANDS, AFC_BAND_IDS } from './afc-band.js';
63
+ // ── HCAS zone rates, per year ───────────────────
64
+ //
65
+ // The PERCENTAGES hold from year to year; the cash floor and
66
+ // ceiling do not — NHS Employers uprates them with each pay
67
+ // award and prints one table per year. Sharing a single table
68
+ // across years therefore pays the current year's ceiling on
69
+ // last year's salary, which is why these are separate.
70
+ //
71
+ // Source: NHS TCS Handbook (amendment 62, 1 June 2026), Annex 9
72
+ // "High cost area supplements", Table 1 (from 1 April 2026) and
73
+ // Table 2 (from 1 April 2025).
74
+ const HCAS_2025_26 = {
75
+ innerLondon: {
76
+ rate: 20, min: 5609, max: 8466,
77
+ },
78
+ outerLondon: {
79
+ rate: 15, min: 4714, max: 5941,
80
+ },
81
+ fringe: {
82
+ rate: 5, min: 1303, max: 2198,
83
+ },
39
84
  };
40
- /** Ordered band IDs — use for iteration. */
41
- export const AFC_BAND_IDS = Object.values(AFC_BANDS);
42
- // ── Shared HCAS zone rates ──────────────────────
43
- // Unchanged between 2025-26 and 2026-27.
44
- const HCAS_2025_ONWARDS = {
85
+ const HCAS_2026_27 = {
45
86
  innerLondon: {
46
87
  rate: 20, min: 5794, max: 8746,
47
88
  },
@@ -54,272 +95,252 @@ const HCAS_2025_ONWARDS = {
54
95
  };
55
96
  // ── 2025-26 ─────────────────────────────────────
56
97
  const AFC_SCALES_2025_26 = {
57
- hcas: HCAS_2025_ONWARDS,
98
+ hcas: HCAS_2025_26,
58
99
  scales: {
59
- '2': [{ label: 'Entry', salary: 24465 }],
100
+ // Two points, both 24465. The publisher prints Band 2 with an
101
+ // entry point, a 2-year progression interval and a top point,
102
+ // and the wage floor has compressed the two to the same cash
103
+ // figure — so the structure is published and the equality is
104
+ // the fact, not a reason to collapse it. Wales's Band 2 is the
105
+ // same shape and was already modelled this way.
106
+ '2': [
107
+ { label: 'Year 1', salary: 24465 },
108
+ { label: 'Year 3+', salary: 24465 },
109
+ ],
60
110
  '3': [
61
111
  { label: 'Year 1', salary: 24937 },
62
- { label: 'Year 2+', salary: 26598 },
112
+ { label: 'Year 3+', salary: 26598 },
63
113
  ],
64
114
  '4': [
65
115
  { label: 'Year 1', salary: 27485 },
66
- { label: 'Year 3+', salary: 30162 },
116
+ { label: 'Year 4+', salary: 30162 },
67
117
  ],
68
118
  '5': [
69
119
  { label: 'Year 1', salary: 31049 },
70
- { label: 'Year 2', salary: 33487 },
71
- { label: 'Year 4+', salary: 37796 },
120
+ { label: 'Year 3', salary: 33487 },
121
+ { label: 'Year 5+', salary: 37796 },
72
122
  ],
73
123
  '6': [
74
124
  { label: 'Year 1', salary: 38682 },
75
- { label: 'Year 2', salary: 40823 },
76
- { label: 'Year 5+', salary: 46580 },
125
+ { label: 'Year 3', salary: 40823 },
126
+ { label: 'Year 6+', salary: 46580 },
77
127
  ],
78
128
  '7': [
79
129
  { label: 'Year 1', salary: 47810 },
80
- { label: 'Year 2', salary: 50273 },
81
- { label: 'Year 5+', salary: 54710 },
130
+ { label: 'Year 3', salary: 50273 },
131
+ { label: 'Year 6+', salary: 54710 },
82
132
  ],
83
133
  '8a': [
84
134
  { label: 'Year 1', salary: 55690 },
85
- { label: 'Year 2', salary: 58487 },
86
- { label: 'Year 5+', salary: 62682 },
135
+ { label: 'Year 3', salary: 58487 },
136
+ { label: 'Year 6+', salary: 62682 },
87
137
  ],
88
138
  '8b': [
89
139
  { label: 'Year 1', salary: 64455 },
90
- { label: 'Year 2', salary: 68631 },
91
- { label: 'Year 5+', salary: 74896 },
140
+ { label: 'Year 3', salary: 68631 },
141
+ { label: 'Year 6+', salary: 74896 },
92
142
  ],
93
143
  '8c': [
94
144
  { label: 'Year 1', salary: 76965 },
95
- { label: 'Year 2', salary: 81652 },
96
- { label: 'Year 5+', salary: 88682 },
145
+ { label: 'Year 3', salary: 81652 },
146
+ { label: 'Year 6+', salary: 88682 },
97
147
  ],
98
148
  '8d': [
99
149
  { label: 'Year 1', salary: 91342 },
100
- { label: 'Year 2', salary: 96941 },
101
- { label: 'Year 5+', salary: 105337 },
150
+ { label: 'Year 3', salary: 96941 },
151
+ { label: 'Year 6+', salary: 105337 },
102
152
  ],
103
153
  '9': [
104
154
  { label: 'Year 1', salary: 109179 },
105
- { label: 'Year 2', salary: 115763 },
106
- { label: 'Year 5+', salary: 125637 },
155
+ { label: 'Year 3', salary: 115763 },
156
+ { label: 'Year 6+', salary: 125637 },
107
157
  ],
108
158
  },
109
159
  };
110
160
  // ── 2026-27 ─────────────────────────────────────
111
161
  const AFC_SCALES_2026_27 = {
112
- hcas: HCAS_2025_ONWARDS,
162
+ hcas: HCAS_2026_27,
113
163
  scales: {
114
- '2': [{ label: 'Entry', salary: 25272 }],
164
+ // Two points, both 25272. The publisher prints Band 2 with an
165
+ // entry point, a 2-year progression interval and a top point,
166
+ // and the wage floor has compressed the two to the same cash
167
+ // figure — so the structure is published and the equality is
168
+ // the fact, not a reason to collapse it. Wales's Band 2 is the
169
+ // same shape and was already modelled this way.
170
+ '2': [
171
+ { label: 'Year 1', salary: 25272 },
172
+ { label: 'Year 3+', salary: 25272 },
173
+ ],
115
174
  '3': [
116
175
  { label: 'Year 1', salary: 25760 },
117
- { label: 'Year 2+', salary: 27476 },
176
+ { label: 'Year 3+', salary: 27476 },
118
177
  ],
119
178
  '4': [
120
179
  { label: 'Year 1', salary: 28392 },
121
- { label: 'Year 3+', salary: 31157 },
180
+ { label: 'Year 4+', salary: 31157 },
122
181
  ],
123
182
  '5': [
124
183
  { label: 'Year 1', salary: 32073 },
125
- { label: 'Year 2', salary: 34592 },
126
- { label: 'Year 4+', salary: 39043 },
184
+ { label: 'Year 3', salary: 34592 },
185
+ { label: 'Year 5+', salary: 39043 },
127
186
  ],
128
187
  '6': [
129
188
  { label: 'Year 1', salary: 39959 },
130
- { label: 'Year 2', salary: 42170 },
131
- { label: 'Year 5+', salary: 48117 },
189
+ { label: 'Year 3', salary: 42170 },
190
+ { label: 'Year 6+', salary: 48117 },
132
191
  ],
133
192
  '7': [
134
193
  { label: 'Year 1', salary: 49387 },
135
- { label: 'Year 2', salary: 51932 },
136
- { label: 'Year 5+', salary: 56515 },
194
+ { label: 'Year 3', salary: 51932 },
195
+ { label: 'Year 6+', salary: 56515 },
137
196
  ],
138
197
  '8a': [
139
198
  { label: 'Year 1', salary: 57528 },
140
- { label: 'Year 2', salary: 60417 },
141
- { label: 'Year 5+', salary: 64750 },
199
+ { label: 'Year 3', salary: 60417 },
200
+ { label: 'Year 6+', salary: 64750 },
142
201
  ],
143
202
  '8b': [
144
203
  { label: 'Year 1', salary: 66582 },
145
- { label: 'Year 2', salary: 70896 },
146
- { label: 'Year 5+', salary: 77368 },
204
+ { label: 'Year 3', salary: 70896 },
205
+ { label: 'Year 6+', salary: 77368 },
147
206
  ],
148
207
  '8c': [
149
208
  { label: 'Year 1', salary: 79504 },
150
- { label: 'Year 2', salary: 84346 },
151
- { label: 'Year 5+', salary: 91609 },
209
+ { label: 'Year 3', salary: 84346 },
210
+ { label: 'Year 6+', salary: 91609 },
152
211
  ],
153
212
  '8d': [
154
213
  { label: 'Year 1', salary: 94356 },
155
- { label: 'Year 2', salary: 100140 },
156
- { label: 'Year 5+', salary: 108814 },
214
+ { label: 'Year 3', salary: 100140 },
215
+ { label: 'Year 6+', salary: 108814 },
157
216
  ],
158
217
  '9': [
159
218
  { label: 'Year 1', salary: 112782 },
160
- { label: 'Year 2', salary: 119583 },
161
- { label: 'Year 5+', salary: 129783 },
219
+ { label: 'Year 3', salary: 119583 },
220
+ { label: 'Year 6+', salary: 129783 },
162
221
  ],
163
222
  },
164
223
  };
165
224
  // ── Scotland 2025-26 ─────────────────────────────
166
- // Scotland negotiates its own AfC award (4.25% for
167
- // 2025-26). Band structures differ from England (Band 2
168
- // has 2 points, Bands 8a–9 have 2 points each).
169
- // Source: MSG consolidated AfC pay scales, "2025/26
170
- // Rates" (rates revised by PCS(AFC)2026/1, 23 Jan 2026).
225
+ // Scotland negotiates its own AfC award. The 2025-26
226
+ // settlement was 4.25%, but carried an inflation
227
+ // guarantee: at least one percentage point above average
228
+ // CPI for the calendar year of the uplift. 2025 CPI
229
+ // confirmed at 3.4%, so the guarantee bit and the rate
230
+ // became 4.4%, backdated to 1 April 2025 with arrears.
231
+ // Band structures differ from England (Band 2 has 2
232
+ // points, Bands 8a–9 have 2 points each).
233
+ // Source: "Scotland, PCS(AFC)2026/1" (#sa-13), Annex B,
234
+ // the revised 4.4% column.
171
235
  const AFC_SCALES_2025_26_SCOTLAND = {
172
- hcas: HCAS_2025_ONWARDS,
173
- scales: {
174
- '2': [
175
- { label: 'Year 1', salary: 25694 },
176
- { label: 'Year 2+', salary: 27900 },
177
- ],
178
- '3': [
179
- { label: 'Year 1', salary: 28011 },
180
- { label: 'Year 2+', salary: 30230 },
181
- ],
182
- '4': [
183
- { label: 'Year 1', salary: 30353 },
184
- { label: 'Year 3+', salary: 33016 },
185
- ],
186
- '5': [
187
- { label: 'Year 1', salary: 33247 },
188
- { label: 'Year 2', salary: 35525 },
189
- { label: 'Year 4+', salary: 41424 },
190
- ],
191
- '6': [
192
- { label: 'Year 1', salary: 41608 },
193
- { label: 'Year 2', salary: 43441 },
194
- { label: 'Year 5+', salary: 50702 },
195
- ],
196
- '7': [
197
- { label: 'Year 1', salary: 50861 },
198
- { label: 'Year 2', salary: 52804 },
199
- { label: 'Year 5+', salary: 59159 },
200
- ],
201
- '8a': [
202
- { label: 'Year 1', salary: 62681 },
203
- { label: 'Year 2+', salary: 67665 },
204
- ],
205
- '8b': [
206
- { label: 'Year 1', salary: 74003 },
207
- { label: 'Year 2+', salary: 79164 },
208
- ],
209
- '8c': [
210
- { label: 'Year 1', salary: 87400 },
211
- { label: 'Year 2+', salary: 93685 },
212
- ],
213
- '8d': [
214
- { label: 'Year 1', salary: 103764 },
215
- { label: 'Year 2+', salary: 108206 },
216
- ],
217
- '9': [
218
- { label: 'Year 1', salary: 122736 },
219
- { label: 'Year 2+', salary: 128051 },
220
- ],
221
- },
236
+ hcas: HCAS_2025_26,
237
+ // Points come from the verbatim circular via the
238
+ // translation layer, so the labels are DERIVED from the
239
+ // publisher's own progression column rather than typed
240
+ // beside the salaries where the two could disagree.
241
+ scales: SCOTLAND_SCALES_2025_26,
222
242
  };
223
243
  // ── Scotland 2026-27 ─────────────────────────────
224
- // 3.75% uplift on Scotland 2025-26 base.
225
- // Source: MSG consolidated AfC pay scales, "2026/27
226
- // Rates" (also PCS(AFC)2026/1 Annex B, eff. 1 Apr 2026).
244
+ // 3.75% on the REVISED 2025-26 base, so the inflation
245
+ // guarantee reaches this year too.
246
+ // Source: "Scotland, PCS(AFC)2026/1" (#sa-13), Annex B,
247
+ // effective 1 April 2026.
227
248
  const AFC_SCALES_2026_27_SCOTLAND = {
228
- hcas: HCAS_2025_ONWARDS,
229
- scales: {
230
- '2': [
231
- { label: 'Year 1', salary: 26658 },
232
- { label: 'Year 2+', salary: 28947 },
233
- ],
234
- '3': [
235
- { label: 'Year 1', salary: 29061 },
236
- { label: 'Year 2+', salary: 31364 },
237
- ],
238
- '4': [
239
- { label: 'Year 1', salary: 31492 },
240
- { label: 'Year 3+', salary: 34254 },
241
- ],
242
- '5': [
243
- { label: 'Year 1', salary: 34494 },
244
- { label: 'Year 2', salary: 36857 },
245
- { label: 'Year 4+', salary: 42977 },
246
- ],
247
- '6': [
248
- { label: 'Year 1', salary: 43169 },
249
- { label: 'Year 2', salary: 45070 },
250
- { label: 'Year 5+', salary: 52603 },
251
- ],
252
- '7': [
253
- { label: 'Year 1', salary: 52769 },
254
- { label: 'Year 2', salary: 54784 },
255
- { label: 'Year 5+', salary: 61377 },
256
- ],
257
- '8a': [
258
- { label: 'Year 1', salary: 65032 },
259
- { label: 'Year 2+', salary: 70202 },
260
- ],
261
- '8b': [
262
- { label: 'Year 1', salary: 76778 },
263
- { label: 'Year 2+', salary: 82133 },
264
- ],
265
- '8c': [
266
- { label: 'Year 1', salary: 90678 },
267
- { label: 'Year 2+', salary: 97199 },
268
- ],
269
- '8d': [
270
- { label: 'Year 1', salary: 107655 },
271
- { label: 'Year 2+', salary: 112264 },
272
- ],
273
- '9': [
274
- { label: 'Year 1', salary: 127338 },
275
- { label: 'Year 2+', salary: 132853 },
276
- ],
277
- },
249
+ hcas: HCAS_2026_27,
250
+ // Points come from the verbatim circular via the
251
+ // translation layer, so the labels are DERIVED from the
252
+ // publisher's own progression column rather than typed
253
+ // beside the salaries where the two could disagree.
254
+ scales: SCOTLAND_SCALES_2026_27,
255
+ };
256
+ // ── Wales ────────────────────────────────────────
257
+ //
258
+ // Wales runs its OWN pay ladder, transcribed here rather
259
+ // than derived from the England table. Both years are read
260
+ // from the Welsh circular's Annex 1: the ladders differ at
261
+ // every band from 4 upward, so England's figures plus a
262
+ // living-wage floor reproduce neither year. The floor lifts
263
+ // the bottom of a ladder and cannot raise its top.
264
+ //
265
+ // Structure differs from England too: Band 2 carries two
266
+ // points where England's has one.
267
+ //
268
+ // GAP: Band 1 is published in both years (£24,833, then
269
+ // £26,300) and is closed to new entrants. It is absent
270
+ // here only because AFC_BANDS starts at B2 — the same gap
271
+ // Scotland has, not a Wales-specific omission.
272
+ //
273
+ // Sources: "Wales, AfC(W) 02/2025" (#sa-44) and "Wales,
274
+ // AfC(W) 02/2026" (#sa-45), Annex 1 of each.
275
+ const AFC_SCALES_2025_26_WALES = {
276
+ hcas: HCAS_2025_26,
277
+ // Points come from the verbatim circular via the
278
+ // translation layer, so the labels are DERIVED from the
279
+ // publisher's own progression column rather than typed
280
+ // beside the salaries where the two could disagree.
281
+ scales: WALES_SCALES_2025_26,
282
+ };
283
+ const AFC_SCALES_2026_27_WALES = {
284
+ hcas: HCAS_2026_27,
285
+ // Points come from the verbatim circular via the
286
+ // translation layer, so the labels are DERIVED from the
287
+ // publisher's own progression column rather than typed
288
+ // beside the salaries where the two could disagree.
289
+ scales: WALES_SCALES_2026_27,
290
+ };
291
+ const AFC_SCALES_WALES = {
292
+ [TAX_YEARS.Y2025_26]: AFC_SCALES_2025_26_WALES,
293
+ [TAX_YEARS.Y2026_27]: AFC_SCALES_2026_27_WALES,
278
294
  };
279
295
  // ── National Living Wage (statutory, 21+) ────────
280
296
  //
281
- // Hourly rate set by the Low Pay Commission.
282
- // Source: gov.uk/national-minimum-wage-rates
297
+ // Hourly rate set by the Low Pay Commission, keyed by the
298
+ // TAX year the rate runs in — the NLW changes on 1 April,
299
+ // so a tax year carries exactly one rate and the two line
300
+ // up. Rates move every April, so a year's entry is the
301
+ // rate announced FOR that April, never the one in force
302
+ // when the entry was written.
303
+ // Source: "GOV.UK — national minimum wage rates" (#sa-30).
283
304
  export const NLW_HOURLY = {
284
- [TAX_YEARS.Y2026_27]: 12.21,
305
+ [TAX_YEARS.Y2025_26]: 12.21,
306
+ [TAX_YEARS.Y2026_27]: 12.71,
285
307
  };
286
308
  /** Standard rUK AfC weekly hours (Scotland differs from 2026-27). */
287
309
  const RUK_WEEKLY_HOURS = 37.5;
288
310
  /**
289
- * Standard AfC working hours per year (37.5 × 52).
311
+ * Standard AfC working hours per year (37.5 × 365/7 ≈ 1,955.4).
312
+ *
313
+ * The week-year is 365/7, not 52, matching every publisher that prints
314
+ * an hourly rate beside an annual salary, and matching NHS Employers'
315
+ * own ~1,955.4-hour year. A 52-week year gives 1,950, which no
316
+ * publisher prints.
317
+ *
290
318
  * @deprecated Use `hoursPerYear(config)` from
291
319
  * paye-calc for region-aware hours. This constant
292
320
  * assumes rUK 37.5h weeks and is wrong for Scotland
293
321
  * from 2026-27.
294
322
  */
295
- export const AFC_HOURS_PER_YEAR = RUK_WEEKLY_HOURS * 52;
323
+ export const AFC_HOURS_PER_YEAR = (RUK_WEEKLY_HOURS * 365) / 7;
296
324
  /**
297
325
  * Annualise an hourly rate at given weekly hours.
298
- * Defaults to 37.5 (rUK standard) for backward
299
- * compatibility. Pass config.standardWeeklyHours
300
- * for region-aware conversion.
326
+ *
327
+ * `weeklyHours` is required: the standard week is the
328
+ * axis that varies by nation (Scotland's AfC week is 37
329
+ * hours to 2025-26 and 36 from 2026-27, rUK's 37.5), so
330
+ * defaulting it would silently return an rUK answer for a
331
+ * Scottish rate. Pass `config.standardWeeklyHours`.
332
+ *
333
+ * The week-year is 365/7, the same basis `hoursPerYear`
334
+ * uses — the two are inverses of one another and a
335
+ * divisor that disagreed would round-trip a salary to a
336
+ * different number.
301
337
  */
302
- export function annualiseHourly(hourly, weeklyHours = RUK_WEEKLY_HOURS) {
303
- return Math.round(hourly * weeklyHours * 52);
338
+ export function annualiseHourly(hourly, weeklyHours) {
339
+ return Math.round((hourly * weeklyHours * 365) / 7);
304
340
  }
305
- // ── Wales living wage floor ─────────────────────
306
- //
307
- // The Welsh Government applies a Living Wage
308
- // Foundation floor (£13.45/hr) as an advance uplift,
309
- // stated as an annual figure of £26,300 (a set annual
310
- // value, not hourly × hours). Low spine points below it
311
- // (Band 2, Band 3 entry) are lifted to it.
312
- // Source: AfC(W) 01/2026 pay letter (6 Jan 2026).
313
- export const WALES_LW_FLOOR = {
314
- [TAX_YEARS.Y2026_27]: 26300,
341
+ export const WALES_LIVING_WAGE = {
342
+ [TAX_YEARS.Y2026_27]: { annual: 26300, hourly: 13.45 },
315
343
  };
316
- /** Apply the Wales living wage floor to a salary.
317
- * Returns the original salary if no floor exists
318
- * for the given tax year. */
319
- export function applyWalesFloor(salary, year) {
320
- const floor = WALES_LW_FLOOR[year];
321
- return floor ? Math.max(salary, floor) : salary;
322
- }
323
344
  // ── Lookup by tax year ──────────────────────────
324
345
  const AFC_SCALES = {
325
346
  [TAX_YEARS.Y2025_26]: AFC_SCALES_2025_26,
@@ -329,36 +350,251 @@ const AFC_SCALES_SCOTLAND = {
329
350
  [TAX_YEARS.Y2025_26]: AFC_SCALES_2025_26_SCOTLAND,
330
351
  [TAX_YEARS.Y2026_27]: AFC_SCALES_2026_27_SCOTLAND,
331
352
  };
332
- /** Tax years that have AFC scale data. */
333
- export const AFC_TAX_YEARS = Object.keys(AFC_SCALES);
334
- /** Apply the Wales living-wage floor to every point in a
335
- * scale year (a no-op where no floor applies for the year). */
336
- function floorScaleYear(scaleYear, year) {
337
- const scales = Object.fromEntries(AFC_BAND_IDS.map((band) => [
338
- band,
339
- scaleYear.scales[band].map((pt) => {
340
- const salary = applyWalesFloor(pt.salary, year);
341
- return salary !== pt.salary ? { ...pt, salary } : pt;
342
- }),
343
- ]));
344
- return { hcas: scaleYear.hcas, scales };
353
+ /** Every nation's published scale family — each nation its own, even
354
+ * where the figures coincide. Total over Nation, so adding a nation
355
+ * is a compile error here rather than a silent fall-through to
356
+ * England's. */
357
+ /**
358
+ * Northern Ireland's ladder: England's salaries, and NOT England's
359
+ * shape at Band 2.
360
+ *
361
+ * HSC (AfC) 06/2025 prints Bands 1 and 2 in its Basic Pay block as
362
+ * single flat figures; its entry/interval/top table starts at Band 3.
363
+ * England's publisher prints Band 2 with an entry point, a two-year
364
+ * interval and a top point. Same cash, different published structure —
365
+ * so NI cannot simply alias England's table, which is the whole reason
366
+ * the two nations' SOURCES are held apart.
367
+ *
368
+ * Every other band is England's, transcribed from a document that
369
+ * prints the same figures.
370
+ */
371
+ /**
372
+ * Northern Ireland's ladder, from HSC (AfC) 06/2025 (3 December 2025,
373
+ * effective 1 April 2025).
374
+ *
375
+ * ONE year. NI has issued no 2026-27 AfC pay circular: the Health
376
+ * Minister stated a desire to proceed with 3.3% on 12 February 2026
377
+ * "subject to my budgetary position", and as at the most recent
378
+ * Assembly answer (AQW 49635/22-27, 15 July 2026) he "cannot" pay it
379
+ * "until I have clarity on my Department's budget". HSC staff are
380
+ * still on these rates. The 3.3% is still recorded in `award.ts` —
381
+ * announced and published are different things.
382
+ *
383
+ * The figures are England's for every band, because NI's circular
384
+ * prints the same numbers; they are AUTHORED here rather than derived
385
+ * from `AFC_SCALES` so that NI can diverge without a code change, and
386
+ * so that Band 2 does not depend on an unasserted property of
387
+ * England's table. NI's Basic Pay block prints Bands 1 and 2 as single
388
+ * flat figures and starts its entry/interval/top table at Band 3, so
389
+ * Band 2 is ONE point where England's is two.
390
+ *
391
+ * All 29 values are pinned against the circular in
392
+ * `tests/fixtures/pay-scales.csv`.
393
+ */
394
+ const AFC_SCALES_NI = {
395
+ [TAX_YEARS.Y2025_26]: {
396
+ // NI operates no high cost area supplement; the field is shared
397
+ // with England's table because the type carries it for every
398
+ // nation, and no NI region resolves an HCAS zone.
399
+ hcas: AFC_SCALES_2025_26.hcas,
400
+ // From NI's OWN circular now, not England's table with Band 2
401
+ // patched over it. The figures still coincide — HSC (AfC) 06/2025
402
+ // prints the same numbers — but they coincide as a fact about the
403
+ // two documents rather than as a construction, so NI can diverge
404
+ // without a code change and Band 2's flat shape comes from the
405
+ // page that prints it flat.
406
+ scales: NI_SCALES_2025_26,
407
+ },
408
+ };
409
+ const SCALE_FAMILIES = {
410
+ [NATION_KEYS.england]: AFC_SCALES,
411
+ [NATION_KEYS.northernIreland]: AFC_SCALES_NI,
412
+ [NATION_KEYS.scotland]: AFC_SCALES_SCOTLAND,
413
+ [NATION_KEYS.wales]: AFC_SCALES_WALES,
414
+ };
415
+ /**
416
+ * The document that PUBLISHES each nation's AfC scales for a year.
417
+ *
418
+ * Held per (nation, year), not per nation: a year-blind citation puts
419
+ * the 2026/27 pay-scales page beneath a 2025-26 table, which reads as
420
+ * a claim the reader cannot check.
421
+ *
422
+ * England and Northern Ireland share a salary TABLE and do not share a
423
+ * SOURCE. NI publishes its own circular, with its own issuer, reference
424
+ * and date, and its figures matching England's is a fact about the two
425
+ * publishers rather than a licence to cite one for the other.
426
+ *
427
+ * Northern Ireland has one row, not two: it has published no 2026-27
428
+ * scales, so there is no 2026-27 table to cite.
429
+ */
430
+ const AFC_SCALE_SOURCES = {
431
+ [NATION_KEYS.england]: {
432
+ [TAX_YEARS.Y2025_26]: AFC_ENGLAND_SCALES_2025,
433
+ [TAX_YEARS.Y2026_27]: AFC_ENGLAND_SCALES_2026,
434
+ },
435
+ [NATION_KEYS.northernIreland]: {
436
+ // One year, matching the scales. There is no 2026-27 entry because
437
+ // there are no 2026-27 NI scales to cite — a source for a table
438
+ // that does not exist would be the false claim this map exists to
439
+ // prevent.
440
+ [TAX_YEARS.Y2025_26]: AFC_NI_2025,
441
+ },
442
+ [NATION_KEYS.scotland]: {
443
+ // One circular restates both years: PCS(AFC)2026/1 revised the
444
+ // 2025-26 figure when the inflation guarantee triggered and
445
+ // restates 2026-27, so it is current for each.
446
+ [TAX_YEARS.Y2025_26]: AFC_SCOTLAND,
447
+ [TAX_YEARS.Y2026_27]: AFC_SCOTLAND,
448
+ },
449
+ [NATION_KEYS.wales]: {
450
+ [TAX_YEARS.Y2025_26]: AFC_W_02_2025,
451
+ [TAX_YEARS.Y2026_27]: AFC_W_02_2026,
452
+ },
453
+ };
454
+ /** The circular or page that publishes a nation's AfC scales for a
455
+ * year. Throws for a combination that has no published scale, in step
456
+ * with {@link getScalesForYear} — a scale we cannot cite is a scale we
457
+ * should not be serving. */
458
+ export function afcScaleSource(year, nation) {
459
+ // The tables key on the label; the signature carries the basis.
460
+ const key = year;
461
+ const source = AFC_SCALE_SOURCES[nation][key];
462
+ if (!source) {
463
+ throw new ScaleUnavailable(nation, year);
464
+ }
465
+ return source;
466
+ }
467
+ /** PAY years a given nation publishes AfC scales for, oldest
468
+ * first. Nations do not move in lockstep — a year one has
469
+ * published may be outstanding for another — so a caller
470
+ * resolving figures for a nation must ask for that nation's
471
+ * years rather than assuming England's.
472
+ *
473
+ * Pay years, not tax years: this answers "which scale can I ask
474
+ * for", never "which tax rules apply". Northern Ireland publishes
475
+ * one pay year while every nation shares the same tax year. */
476
+ export function afcPayYears(nation) {
477
+ // Sorted, not authoring order: the "oldest first" above is a
478
+ // guarantee callers rely on (`resolver.ts` reverses it to find the
479
+ // latest year), and object-literal order would silently break it if
480
+ // a new year were authored above an old one. Year labels sort
481
+ // lexicographically because they are zero-padded ISO-style.
482
+ return Object.keys(SCALE_FAMILIES[nation]).sort();
483
+ }
484
+ /**
485
+ * The most recent year a nation has actually published AfC scales for.
486
+ *
487
+ * Nations do not move together. Northern Ireland has issued no 2026-27
488
+ * pay circular — its 3.3% is announced, unfunded and undated — so its
489
+ * latest published year is 2025-26 while the other three are on
490
+ * 2026-27. A consumer that asks for a site-wide "current year" gets
491
+ * `ScaleUnavailable` there, which is correct but is not an answer; this
492
+ * is the answer.
493
+ *
494
+ * Lives here rather than in a consumer because it is a fact about what
495
+ * this library holds. A consumer deriving it would be re-computing,
496
+ * from the outside, something only these tables know.
497
+ */
498
+ /**
499
+ * How far a nation's newest published pay scales sit from the tax year
500
+ * in force. Positive means the pay scales are BEHIND.
501
+ *
502
+ * ## The domain rule this exists to state
503
+ *
504
+ * A person's salary comes from an Agenda for Change round; the tax, NI
505
+ * and pension tiers applied to it come from the tax year they are
506
+ * being paid IN. Those are different facts, and they normally name the
507
+ * same year — which is why one value was long used for both, and why
508
+ * the day they diverge nothing complains.
509
+ *
510
+ * They diverge in exactly one way. An AfC round is agreed and
511
+ * implemented by each nation separately, and a nation whose award is
512
+ * not yet funded keeps paying last year's scales into this tax year.
513
+ * Northern Ireland is doing that now. Tax never waits: the thresholds
514
+ * change on 6 April whatever the employer has settled.
515
+ *
516
+ * So the legitimate values are:
517
+ *
518
+ * | lag | meaning |
519
+ * |---|---|
520
+ * | `0` | the award is implemented; pay year and tax year agree |
521
+ * | `1` | the award for this year is not yet in payment |
522
+ * | `-1` | next year's circular is out but its tax year has not begun |
523
+ *
524
+ * Anything else is a defect in THIS library's data, not a fact about
525
+ * the world: a lag of 2 means a whole round was never transcribed.
526
+ * {@link assertPayYearLagIsSane} is where that is enforced.
527
+ *
528
+ * The one thing this CANNOT catch is the mistake it was written after:
529
+ * passing a pay year where a tax year was wanted. Both are `TaxYear`,
530
+ * so both type-check, and the values here would look perfectly legal.
531
+ * Only distinct types would stop that.
532
+ */
533
+ export function payYearLag(nation) {
534
+ const order = Object.values(TAX_YEARS);
535
+ const pay = order.indexOf(latestAfcYear(nation));
536
+ const tax = order.indexOf(CURRENT_TAX_YEAR);
537
+ invariant(pay >= 0 && tax >= 0, `payYearLag: ${nation} resolves a year outside TAX_YEARS`);
538
+ return tax - pay;
539
+ }
540
+ /**
541
+ * True while a nation is still paying an older round than the tax year
542
+ * in force — its award is announced or awaited, but not in payment.
543
+ *
544
+ * The domain question ("is this nation behind?") rather than a
545
+ * comparison against some particular year, so a consumer cannot get
546
+ * the comparison subtly wrong: testing against a fixed year answers
547
+ * "is it exactly 2025-26" and quietly says no for a nation two rounds
548
+ * behind, which is the case that most needs saying yes.
549
+ */
550
+ export function isAwaitingPayAward(nation) {
551
+ return payYearLag(nation) > 0;
552
+ }
553
+ /**
554
+ * Fail loudly if any nation's pay scales have drifted further from the
555
+ * tax year than the domain allows. See {@link payYearLag}.
556
+ *
557
+ * A function rather than a module-scope check: this library is
558
+ * published, and a throw at import time would take down every consumer
559
+ * over a data problem they cannot fix. It runs in this repo's tests,
560
+ * which is where a transcription gap should surface.
561
+ */
562
+ export function assertPayYearLagIsSane() {
563
+ for (const nation of Object.keys(SCALE_FAMILIES)) {
564
+ const lag = payYearLag(nation);
565
+ invariant(lag >= -1 && lag <= 1, `${nation} is ${lag} years from the tax year in force `
566
+ + `(${CURRENT_TAX_YEAR}): its newest published scale is `
567
+ + `${latestAfcYear(nation)}. A gap beyond one year means a pay `
568
+ + 'round was never transcribed, not that a nation skipped one.');
569
+ }
570
+ }
571
+ export function latestAfcYear(nation) {
572
+ const years = afcPayYears(nation);
573
+ const latest = years[years.length - 1];
574
+ if (!latest) {
575
+ // A plain Error, not ScaleUnavailable: that type's `year` is a
576
+ // TaxYear, and there is no year to name here. Casting a filler
577
+ // string into the union would make `error.year` lie to any caller
578
+ // that reads it.
579
+ throw new Error(`latestAfcYear: ${nation} publishes no AfC scale in any year`);
580
+ }
581
+ return latest;
345
582
  }
346
- /** Resolve the published, nation-adjusted scale table for a
347
- * year — the single place a nation modifies the base scale:
348
- * Scotland swaps to its own family, Wales floors the
349
- * England/NI base, England/NI use the base as-is. Throws
350
- * {@link ScaleUnavailable} for an unpublished year rather
351
- * than silently substituting another year's figures. */
583
+ /** Resolve a nation's published scale table for a year.
584
+ * Every figure returned is transcribed from that nation's
585
+ * own instrument. Where two nations' circulars print the
586
+ * same numbers the tables share an object literal for
587
+ * brevity, and each nation's fixture rows pin its values
588
+ * against its OWN document, so a divergence fails rather
589
+ * than propagating. Throws {@link ScaleUnavailable} for a
590
+ * year that nation has not published, rather than silently
591
+ * substituting another year's or nation's figures. */
352
592
  export function getScalesForYear(year, nation) {
353
- const family = nation === NATION_KEYS.scotland
354
- ? AFC_SCALES_SCOTLAND
355
- : AFC_SCALES;
356
- const base = family[year];
593
+ const key = year;
594
+ const base = SCALE_FAMILIES[nation][key];
357
595
  if (!base) {
358
596
  throw new ScaleUnavailable(nation, year);
359
597
  }
360
- return nation === NATION_KEYS.wales
361
- ? floorScaleYear(base, year)
362
- : base;
598
+ return base;
363
599
  }
364
600
  //# sourceMappingURL=scales.js.map