@casomoltd/nhs-pay 0.32.0 → 0.33.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 (115) hide show
  1. package/README.md +23 -21
  2. package/dist/afc-scales.d.ts +43 -10
  3. package/dist/afc-scales.js +50 -16
  4. package/dist/afc-scales.js.map +1 -1
  5. package/dist/allowances.js +11 -11
  6. package/dist/allowances.js.map +1 -1
  7. package/dist/award.d.ts +3 -3
  8. package/dist/award.js +21 -21
  9. package/dist/award.js.map +1 -1
  10. package/dist/circulars/england-md-1-2026-r2.d.ts +13 -0
  11. package/dist/circulars/england-md-1-2026-r2.js +13 -0
  12. package/dist/circulars/england-md-1-2026-r2.js.map +1 -1
  13. package/dist/circulars/ni-hsc-tc8-05-2025.d.ts +22 -0
  14. package/dist/circulars/ni-hsc-tc8-05-2025.js +22 -0
  15. package/dist/circulars/ni-hsc-tc8-05-2025.js.map +1 -1
  16. package/dist/circulars/scotland-pcs-dd-2025-01.d.ts +20 -0
  17. package/dist/circulars/scotland-pcs-dd-2025-01.js +20 -0
  18. package/dist/circulars/scotland-pcs-dd-2025-01.js.map +1 -1
  19. package/dist/circulars/scotland-pcs-dd-2026-01.d.ts +19 -0
  20. package/dist/circulars/scotland-pcs-dd-2026-01.js +30 -10
  21. package/dist/circulars/scotland-pcs-dd-2026-01.js.map +1 -1
  22. package/dist/circulars/scotland-pcs-dd-2026-02.d.ts +10 -0
  23. package/dist/circulars/scotland-pcs-dd-2026-02.js +10 -0
  24. package/dist/circulars/scotland-pcs-dd-2026-02.js.map +1 -1
  25. package/dist/circulars/wales-mdw-01-2025.d.ts +17 -0
  26. package/dist/circulars/wales-mdw-01-2025.js +17 -0
  27. package/dist/circulars/wales-mdw-01-2025.js.map +1 -1
  28. package/dist/circulars/wales-mdw-01-2026.d.ts +20 -0
  29. package/dist/circulars/wales-mdw-01-2026.js +20 -0
  30. package/dist/circulars/wales-mdw-01-2026.js.map +1 -1
  31. package/dist/commutation.js +3 -2
  32. package/dist/commutation.js.map +1 -1
  33. package/dist/dental-grades.d.ts +25 -0
  34. package/dist/dental-grades.js +25 -0
  35. package/dist/dental-grades.js.map +1 -0
  36. package/dist/dental-scales.d.ts +5 -21
  37. package/dist/dental-scales.js +73 -72
  38. package/dist/dental-scales.js.map +1 -1
  39. package/dist/format.js +3 -2
  40. package/dist/format.js.map +1 -1
  41. package/dist/hcas-pcts.d.ts +1 -1
  42. package/dist/hcas-zone.d.ts +23 -0
  43. package/dist/hcas-zone.js +17 -0
  44. package/dist/hcas-zone.js.map +1 -0
  45. package/dist/hcas.d.ts +26 -18
  46. package/dist/hcas.js +45 -24
  47. package/dist/hcas.js.map +1 -1
  48. package/dist/index.d.ts +23 -14
  49. package/dist/index.js +13 -9
  50. package/dist/index.js.map +1 -1
  51. package/dist/medical-grades.d.ts +33 -0
  52. package/dist/medical-grades.js +33 -0
  53. package/dist/medical-grades.js.map +1 -0
  54. package/dist/medical-scales.d.ts +10 -33
  55. package/dist/medical-scales.js +104 -158
  56. package/dist/medical-scales.js.map +1 -1
  57. package/dist/member/input-period.d.ts +18 -5
  58. package/dist/member/input-period.js +24 -13
  59. package/dist/member/input-period.js.map +1 -1
  60. package/dist/pay-round.js +3 -3
  61. package/dist/pay-round.js.map +1 -1
  62. package/dist/pay-year.d.ts +17 -0
  63. package/dist/pay-year.js +20 -0
  64. package/dist/pay-year.js.map +1 -0
  65. package/dist/pension/ledger.d.ts +7 -0
  66. package/dist/pension/ledger.js +18 -11
  67. package/dist/pension/ledger.js.map +1 -1
  68. package/dist/pension.js +2 -1
  69. package/dist/pension.js.map +1 -1
  70. package/dist/post.d.ts +20 -21
  71. package/dist/post.js +54 -53
  72. package/dist/post.js.map +1 -1
  73. package/dist/published/england-afc.d.ts +29 -0
  74. package/dist/published/england-afc.js +142 -0
  75. package/dist/published/england-afc.js.map +1 -0
  76. package/dist/published/hcas-zones.d.ts +18 -0
  77. package/dist/published/hcas-zones.js +46 -0
  78. package/dist/published/hcas-zones.js.map +1 -0
  79. package/dist/published/wales-living-wage.d.ts +36 -0
  80. package/dist/published/wales-living-wage.js +30 -0
  81. package/dist/published/wales-living-wage.js.map +1 -0
  82. package/dist/regions.d.ts +25 -14
  83. package/dist/regions.js +61 -71
  84. package/dist/regions.js.map +1 -1
  85. package/dist/resolver.d.ts +46 -41
  86. package/dist/resolver.js +70 -142
  87. package/dist/resolver.js.map +1 -1
  88. package/dist/role.d.ts +3 -3
  89. package/dist/scale-point.d.ts +11 -7
  90. package/dist/scale-point.js +29 -1
  91. package/dist/scale-point.js.map +1 -1
  92. package/dist/scale-tables.d.ts +42 -60
  93. package/dist/scale-tables.js +65 -105
  94. package/dist/scale-tables.js.map +1 -1
  95. package/dist/scale-translators.d.ts +90 -0
  96. package/dist/scale-translators.js +97 -0
  97. package/dist/scale-translators.js.map +1 -0
  98. package/dist/scales.d.ts +138 -101
  99. package/dist/scales.js +221 -457
  100. package/dist/scales.js.map +1 -1
  101. package/dist/sources.d.ts +8 -12
  102. package/dist/sources.js +9 -15
  103. package/dist/sources.js.map +1 -1
  104. package/dist/take-home.js +1 -2
  105. package/dist/take-home.js.map +1 -1
  106. package/dist/values.d.ts +10 -3
  107. package/dist/values.js +11 -4
  108. package/dist/values.js.map +1 -1
  109. package/dist/working-week.d.ts +23 -8
  110. package/dist/working-week.js +55 -25
  111. package/dist/working-week.js.map +1 -1
  112. package/package.json +3 -3
  113. package/dist/bands.d.ts +0 -63
  114. package/dist/bands.js +0 -78
  115. package/dist/bands.js.map +0 -1
package/dist/scales.js CHANGED
@@ -1,43 +1,24 @@
1
1
  /**
2
- * NHS Agenda for Change pay scales by tax year.
2
+ * NHS Agenda for Change pay scales by pay year, for every nation, and the
3
+ * lookups over them.
3
4
  *
4
5
  * Pure salary data — no metadata (labels, slugs, role
5
6
  * descriptions); presentation copy is a consumer concern.
6
7
  *
7
- * ── Two layers, and which nation is in which ──
8
+ * ── Where each nation's figures come from ──
8
9
  *
9
10
  * Scotland, Wales and Northern Ireland each publish an AfC pay
10
11
  * CIRCULAR, so each is transcribed verbatim in `src/circulars/*` and
11
12
  * translated to canonical points by `afc-scales.ts`. This module holds
12
13
  * the result, not the transcription.
13
14
  *
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:
25
- * - "NHS Employers — AfC pay scales 2025/26"
26
- * - "NHS Employers — AfC pay scales 2026/27" (note its hourly
27
- * table has printing errors; this file reads the ANNUAL
28
- * column, so they cannot reach us — see the manifest)
29
- * - "NHS Employers, 2026 AfC pay scales poster" — the same award
30
- * rendered a second time by the same publisher, which is what
31
- * confirms the annual column above is untouched by those errors
32
- * - "Health Careers — AfC pay rates"
33
- * - NLW: "GOV.UK — national minimum wage rates"
34
- * - Wales floor: "Wales, AFC(W) 01/2026 living wage"
35
- * - HCAS rates: "NHS Terms and Conditions of Service
36
- * Handbook, amendment 62" (#sa-41), Annex 9
37
- *
38
- * The other three nations' sources are cited in their own circular
39
- * files, beside the data they justify — including the warning that
40
- * Scotland's MSG consolidated table prints superseded 4.25% rates and
15
+ * England publishes no AfC circular, so its tables are transcribed from
16
+ * the publisher's page in `src/published/england-afc.ts` (the README's
17
+ * AfC pay scales rule). The HCAS zones and the Welsh living-wage floor sit beside it
18
+ * in `src/published/`, each citing its own
19
+ * source. The other three nations' sources are cited in their own
20
+ * circular files, beside the data they justify — including the warning
21
+ * that Scotland's MSG consolidated table prints superseded 4.25% rates and
41
22
  * must not be read instead of the circular.
42
23
  *
43
24
  * POINT LABELS — one convention, all four nations. A point's label is
@@ -46,406 +27,135 @@
46
27
  * past it. No publisher prints such a label; every one is our reading
47
28
  * of an interval the publisher does print. For the three circular
48
29
  * nations the year is derived in `afc-scales.ts` from the transcribed
49
- * interval; England's are authored here as years. All four go through
30
+ * interval; England's are authored as years in `published/`. All four go through
50
31
  * `afcPoint`, which writes the label and the year from one number, so
51
32
  * a label and the timing a pay path reads from it cannot disagree.
52
33
  *
53
34
  * Labels are lookup keys for `afcResolver.fromScalePoint`, so changing
54
35
  * one is an API change, and the fixtures assert them.
36
+ *
37
+ * Pension tiers are a separate read (`getPensionTiers`), since a nation
38
+ * can publish a scale for a year with no tier table.
55
39
  */
56
- import { NATION_KEYS, TAX_YEARS, CURRENT_TAX_YEAR, } from '@casomoltd/paye-calc';
40
+ import { NATION_KEYS, YEAR_LABELS, closingYearOf, } from '@casomoltd/paye-calc';
57
41
  import { ScaleUnavailable, invariant } from './errors.js';
58
42
  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';
43
+ import { onlyPointLabelled } from './scale-point.js';
44
+ import { salaryRangeOf } from './values.js';
59
45
  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
- import { afcPoint } from './afc-scales.js';
61
- import { hoursPerYear } from './working-week.js';
62
- // The band registry lives in its own module so the translation layer
63
- // can name a band without importing this one — see `afc-band.ts`.
64
- export { AFC_BANDS, AFC_BAND_IDS } from './afc-band.js';
65
- // ── HCAS zone rates, per year ───────────────────
66
- //
67
- // The PERCENTAGES hold from year to year; the cash floor and
68
- // ceiling do not — NHS Employers uprates them with each pay
69
- // award and prints one table per year. Sharing a single table
70
- // across years therefore pays the current year's ceiling on
71
- // last year's salary, which is why these are separate.
72
- //
73
- // Source: NHS TCS Handbook (amendment 62, 1 June 2026), Annex 9
74
- // "High cost area supplements", Table 1 (from 1 April 2026) and
75
- // Table 2 (from 1 April 2025).
76
- const HCAS_2025_26 = {
77
- innerLondon: {
78
- rate: 20, min: 5609, max: 8466,
79
- },
80
- outerLondon: {
81
- rate: 15, min: 4714, max: 5941,
82
- },
83
- fringe: {
84
- rate: 5, min: 1303, max: 2198,
85
- },
86
- };
87
- const HCAS_2026_27 = {
88
- innerLondon: {
89
- rate: 20, min: 5794, max: 8746,
90
- },
91
- outerLondon: {
92
- rate: 15, min: 4870, max: 6137,
93
- },
94
- fringe: {
95
- rate: 5, min: 1346, max: 2270,
96
- },
97
- };
98
- // ── 2025-26 ─────────────────────────────────────
99
- const AFC_SCALES_2025_26 = {
100
- hcas: HCAS_2025_26,
101
- scales: {
102
- // Two points, both 24465. The publisher prints Band 2 with an
103
- // entry point, a 2-year progression interval and a top point,
104
- // and the wage floor has compressed the two to the same cash
105
- // figure — so the structure is published and the equality is
106
- // the fact, not a reason to collapse it. Wales's Band 2 is the
107
- // same shape and is modelled the same way.
108
- '2': [
109
- afcPoint(1, false, 24465),
110
- afcPoint(3, true, 24465),
111
- ],
112
- '3': [
113
- afcPoint(1, false, 24937),
114
- afcPoint(3, true, 26598),
115
- ],
116
- '4': [
117
- afcPoint(1, false, 27485),
118
- afcPoint(4, true, 30162),
119
- ],
120
- '5': [
121
- afcPoint(1, false, 31049),
122
- afcPoint(3, false, 33487),
123
- afcPoint(5, true, 37796),
124
- ],
125
- '6': [
126
- afcPoint(1, false, 38682),
127
- afcPoint(3, false, 40823),
128
- afcPoint(6, true, 46580),
129
- ],
130
- '7': [
131
- afcPoint(1, false, 47810),
132
- afcPoint(3, false, 50273),
133
- afcPoint(6, true, 54710),
134
- ],
135
- '8a': [
136
- afcPoint(1, false, 55690),
137
- afcPoint(3, false, 58487),
138
- afcPoint(6, true, 62682),
139
- ],
140
- '8b': [
141
- afcPoint(1, false, 64455),
142
- afcPoint(3, false, 68631),
143
- afcPoint(6, true, 74896),
144
- ],
145
- '8c': [
146
- afcPoint(1, false, 76965),
147
- afcPoint(3, false, 81652),
148
- afcPoint(6, true, 88682),
149
- ],
150
- '8d': [
151
- afcPoint(1, false, 91342),
152
- afcPoint(3, false, 96941),
153
- afcPoint(6, true, 105337),
154
- ],
155
- '9': [
156
- afcPoint(1, false, 109179),
157
- afcPoint(3, false, 115763),
158
- afcPoint(6, true, 125637),
159
- ],
160
- },
161
- };
162
- // ── 2026-27 ─────────────────────────────────────
163
- const AFC_SCALES_2026_27 = {
164
- hcas: HCAS_2026_27,
165
- scales: {
166
- // Two points, both 25272. The publisher prints Band 2 with an
167
- // entry point, a 2-year progression interval and a top point,
168
- // and the wage floor has compressed the two to the same cash
169
- // figure — so the structure is published and the equality is
170
- // the fact, not a reason to collapse it. Wales's Band 2 is the
171
- // same shape and is modelled the same way.
172
- '2': [
173
- afcPoint(1, false, 25272),
174
- afcPoint(3, true, 25272),
175
- ],
176
- '3': [
177
- afcPoint(1, false, 25760),
178
- afcPoint(3, true, 27476),
179
- ],
180
- '4': [
181
- afcPoint(1, false, 28392),
182
- afcPoint(4, true, 31157),
183
- ],
184
- '5': [
185
- afcPoint(1, false, 32073),
186
- afcPoint(3, false, 34592),
187
- afcPoint(5, true, 39043),
188
- ],
189
- '6': [
190
- afcPoint(1, false, 39959),
191
- afcPoint(3, false, 42170),
192
- afcPoint(6, true, 48117),
193
- ],
194
- '7': [
195
- afcPoint(1, false, 49387),
196
- afcPoint(3, false, 51932),
197
- afcPoint(6, true, 56515),
198
- ],
199
- '8a': [
200
- afcPoint(1, false, 57528),
201
- afcPoint(3, false, 60417),
202
- afcPoint(6, true, 64750),
203
- ],
204
- '8b': [
205
- afcPoint(1, false, 66582),
206
- afcPoint(3, false, 70896),
207
- afcPoint(6, true, 77368),
208
- ],
209
- '8c': [
210
- afcPoint(1, false, 79504),
211
- afcPoint(3, false, 84346),
212
- afcPoint(6, true, 91609),
213
- ],
214
- '8d': [
215
- afcPoint(1, false, 94356),
216
- afcPoint(3, false, 100140),
217
- afcPoint(6, true, 108814),
218
- ],
219
- '9': [
220
- afcPoint(1, false, 112782),
221
- afcPoint(3, false, 119583),
222
- afcPoint(6, true, 129783),
223
- ],
224
- },
225
- };
226
- // ── Scotland 2025-26 ─────────────────────────────
227
- // Scotland negotiates its own AfC award. The 2025-26
228
- // settlement was 4.25%, but carried an inflation
229
- // guarantee: at least one percentage point above average
230
- // CPI for the calendar year of the uplift. 2025 CPI
231
- // confirmed at 3.4%, so the guarantee bit and the rate
232
- // became 4.4%, backdated to 1 April 2025 with arrears.
233
- // Band structures differ from England (Band 2 has 2
234
- // points, Bands 8a–9 have 2 points each).
235
- // Source: "Scotland, PCS(AFC)2026/1" (#sa-13), Annex B,
236
- // the revised 4.4% column.
237
- const AFC_SCALES_2025_26_SCOTLAND = {
238
- hcas: HCAS_2025_26,
239
- // Points come from the verbatim circular via the
240
- // translation layer, so the labels are DERIVED from the
241
- // publisher's own progression column rather than typed
242
- // beside the salaries where the two could disagree.
243
- scales: SCOTLAND_SCALES_2025_26,
244
- };
245
- // ── Scotland 2026-27 ─────────────────────────────
246
- // 3.75% on the REVISED 2025-26 base, so the inflation
247
- // guarantee reaches this year too.
248
- // Source: "Scotland, PCS(AFC)2026/1" (#sa-13), Annex B,
249
- // effective 1 April 2026.
250
- const AFC_SCALES_2026_27_SCOTLAND = {
251
- hcas: HCAS_2026_27,
252
- // Points come from the verbatim circular via the
253
- // translation layer, so the labels are DERIVED from the
254
- // publisher's own progression column rather than typed
255
- // beside the salaries where the two could disagree.
256
- scales: SCOTLAND_SCALES_2026_27,
257
- };
258
- // ── Wales ────────────────────────────────────────
259
- //
260
- // Wales runs its OWN pay ladder, transcribed here rather
261
- // than derived from the England table. Both years are read
262
- // from the Welsh circular's Annex 1: the ladders differ at
263
- // every band from 4 upward, so England's figures plus a
264
- // living-wage floor reproduce neither year. The floor lifts
265
- // the bottom of a ladder and cannot raise its top.
266
- //
267
- // Structure differs from England too: Band 2 carries two
268
- // points where England's has one.
269
- //
270
- // Band 1 is published in both years and closed to new
271
- // entrants. It is absent from this ladder because
272
- // AFC_BANDS starts at B2, and reachable through
273
- // `afcBand1`, which reads it off the circular.
274
- //
275
- // Sources: "Wales, AfC(W) 02/2025" (#sa-44) and "Wales,
276
- // AfC(W) 02/2026" (#sa-45), Annex 1 of each.
277
- const AFC_SCALES_2025_26_WALES = {
278
- hcas: HCAS_2025_26,
279
- // Points come from the verbatim circular via the
280
- // translation layer, so the labels are DERIVED from the
281
- // publisher's own progression column rather than typed
282
- // beside the salaries where the two could disagree.
283
- scales: WALES_SCALES_2025_26,
284
- };
285
- const AFC_SCALES_2026_27_WALES = {
286
- hcas: HCAS_2026_27,
287
- // Points come from the verbatim circular via the
288
- // translation layer, so the labels are DERIVED from the
289
- // publisher's own progression column rather than typed
290
- // beside the salaries where the two could disagree.
291
- scales: WALES_SCALES_2026_27,
292
- };
293
- const AFC_SCALES_WALES = {
294
- [TAX_YEARS.Y2025_26]: AFC_SCALES_2025_26_WALES,
295
- [TAX_YEARS.Y2026_27]: AFC_SCALES_2026_27_WALES,
296
- };
297
- // ── National Living Wage (statutory, 21+) ────────
298
- //
299
- // Hourly rate set by the Low Pay Commission, keyed by the
300
- // TAX year the rate runs in — the NLW changes on 1 April,
301
- // so a tax year carries exactly one rate and the two line
302
- // up. Rates move every April, so a year's entry is the
303
- // rate announced FOR that April, never the one in force
304
- // when the entry was written.
305
- // Source: "GOV.UK — national minimum wage rates" (#sa-30).
306
- export const NLW_HOURLY = {
307
- [TAX_YEARS.Y2025_26]: 12.21,
308
- [TAX_YEARS.Y2026_27]: 12.71,
46
+ import { AFC_BAND_IDS } from './afc-band.js';
47
+ import { ENGLAND_AFC_2025_26, ENGLAND_AFC_2026_27 } from './published/england-afc.js';
48
+ import { schemeYearOfPayYear } from './pay-year.js';
49
+ /** What {@link afcPayYearFor} finds for a scheme year. */
50
+ export const AFC_PAY_YEAR_KINDS = {
51
+ /** This library holds the nation's scale for the year. */
52
+ held: 'held',
53
+ /** The year is before the earliest scale this library holds for the
54
+ * nation. */
55
+ notHeld: 'notHeld',
56
+ /** The year is after the latest scale this library holds for the
57
+ * nation, and no later than the round after the tax year given: its
58
+ * award is awaited. A year further on is refused. */
59
+ awaited: 'awaited',
309
60
  };
310
61
  /**
311
- * Annualise an hourly rate at given weekly hours.
62
+ * Every nation's published AfC scales, by pay year. Total over Nation, so
63
+ * adding a nation is a compile error here rather than a silent fall-through
64
+ * to England's. Each nation is its own even where the figures coincide.
312
65
  *
313
- * `weeklyHours` is required: the standard week varies by
314
- * nation and year (`afcWeeklyHours`), so defaulting it
315
- * would silently return an rUK answer for a Scottish rate.
316
- * Pass `afcWeeklyHours(year, nation)`.
66
+ * Held per (nation, year), source included: a year-blind citation puts the
67
+ * 2026/27 pay-scales page beneath a 2025-26 table, which reads as a claim
68
+ * the reader cannot check. England and Northern Ireland share a salary
69
+ * TABLE and do not share a SOURCE: NI publishes its own circular, and its
70
+ * figures matching England's is a fact about the two publishers rather
71
+ * than a licence to cite one for the other.
317
72
  *
318
- * The inverse of dividing by `hoursPerYear`, which it reads, so the two
319
- * agree up to the rounding of the hourly rate and of the result.
73
+ * Scotland, Wales and Northern Ireland take their points from their
74
+ * verbatim circulars through `afc-scales.ts`, which also holds each
75
+ * circular's notes; England's are transcribed in `published/`.
320
76
  */
321
- export function annualiseHourly(hourly, weeklyHours) {
322
- return Math.round(hourly * hoursPerYear(weeklyHours));
323
- }
324
- export const WALES_LIVING_WAGE = {
325
- [TAX_YEARS.Y2026_27]: { annual: 26300, hourly: 13.45 },
326
- };
327
- // ── Lookup by tax year ──────────────────────────
328
- const AFC_SCALES = {
329
- [TAX_YEARS.Y2025_26]: AFC_SCALES_2025_26,
330
- [TAX_YEARS.Y2026_27]: AFC_SCALES_2026_27,
331
- };
332
- const AFC_SCALES_SCOTLAND = {
333
- [TAX_YEARS.Y2025_26]: AFC_SCALES_2025_26_SCOTLAND,
334
- [TAX_YEARS.Y2026_27]: AFC_SCALES_2026_27_SCOTLAND,
335
- };
336
- /** Every nation's published scale family — each nation its own, even
337
- * where the figures coincide. Total over Nation, so adding a nation
338
- * is a compile error here rather than a silent fall-through to
339
- * England's. */
340
- /**
341
- * Northern Ireland's ladder: England's salaries, and NOT England's
342
- * shape at Band 2.
343
- *
344
- * HSC (AfC) 06/2025 prints Bands 1 and 2 in its Basic Pay block as
345
- * single flat figures; its entry/interval/top table starts at Band 3.
346
- * England's publisher prints Band 2 with an entry point, a two-year
347
- * interval and a top point. Same cash, different published structure —
348
- * so NI cannot simply alias England's table, which is the whole reason
349
- * the two nations' SOURCES are held apart.
350
- *
351
- * Every other band is England's, transcribed from a document that
352
- * prints the same figures.
353
- */
354
- /**
355
- * Northern Ireland's ladder, from HSC (AfC) 06/2025 (3 December 2025,
356
- * effective 1 April 2025).
357
- *
358
- * ONE year. NI has issued no 2026-27 AfC pay circular: the Health
359
- * Minister stated a desire to proceed with 3.3% on 12 February 2026
360
- * "subject to my budgetary position", and as at the most recent
361
- * Assembly answer (AQW 49635/22-27, 15 July 2026) he "cannot" pay it
362
- * "until I have clarity on my Department's budget". HSC staff are
363
- * still on these rates. The 3.3% is still recorded in `award.ts` —
364
- * announced and published are different things.
365
- *
366
- * The figures are England's for every band, because NI's circular
367
- * prints the same numbers; they are AUTHORED here rather than derived
368
- * from `AFC_SCALES` so that NI can diverge without a code change, and
369
- * so that Band 2 does not depend on an unasserted property of
370
- * England's table. NI's Basic Pay block prints Bands 1 and 2 as single
371
- * flat figures and starts its entry/interval/top table at Band 3, so
372
- * Band 2 is ONE point where England's is two.
373
- *
374
- * All 29 values are pinned against the circular in
375
- * `tests/fixtures/pay-scales.csv`.
376
- */
377
- const AFC_SCALES_NI = {
378
- [TAX_YEARS.Y2025_26]: {
379
- // NI operates no high cost area supplement; the field is shared
380
- // with England's table because the type carries it for every
381
- // nation, and no NI region resolves an HCAS zone.
382
- hcas: AFC_SCALES_2025_26.hcas,
383
- // From NI's OWN circular now, not England's table with Band 2
384
- // patched over it. The figures still coincide — HSC (AfC) 06/2025
385
- // prints the same numbers — but they coincide as a fact about the
386
- // two documents rather than as a construction, so NI can diverge
387
- // without a code change and Band 2's flat shape comes from the
388
- // page that prints it flat.
389
- scales: NI_SCALES_2025_26,
390
- },
391
- };
392
- const SCALE_FAMILIES = {
393
- [NATION_KEYS.england]: AFC_SCALES,
394
- [NATION_KEYS.northernIreland]: AFC_SCALES_NI,
395
- [NATION_KEYS.scotland]: AFC_SCALES_SCOTLAND,
396
- [NATION_KEYS.wales]: AFC_SCALES_WALES,
397
- };
398
- /**
399
- * The document that PUBLISHES each nation's AfC scales for a year.
400
- *
401
- * Held per (nation, year), not per nation: a year-blind citation puts
402
- * the 2026/27 pay-scales page beneath a 2025-26 table, which reads as
403
- * a claim the reader cannot check.
404
- *
405
- * England and Northern Ireland share a salary TABLE and do not share a
406
- * SOURCE. NI publishes its own circular, with its own issuer, reference
407
- * and date, and its figures matching England's is a fact about the two
408
- * publishers rather than a licence to cite one for the other.
409
- *
410
- * Northern Ireland has one row, not two: it has published no 2026-27
411
- * scales, so there is no 2026-27 table to cite.
412
- */
413
- const AFC_SCALE_SOURCES = {
77
+ const AFC_SCALE_YEARS = {
414
78
  [NATION_KEYS.england]: {
415
- [TAX_YEARS.Y2025_26]: AFC_ENGLAND_SCALES_2025,
416
- [TAX_YEARS.Y2026_27]: AFC_ENGLAND_SCALES_2026,
79
+ [YEAR_LABELS.Y2025_26]: { scales: ENGLAND_AFC_2025_26, source: AFC_ENGLAND_SCALES_2025 },
80
+ [YEAR_LABELS.Y2026_27]: { scales: ENGLAND_AFC_2026_27, source: AFC_ENGLAND_SCALES_2026 },
417
81
  },
418
82
  [NATION_KEYS.northernIreland]: {
419
- // One year, matching the scales. There is no 2026-27 entry because
420
- // there are no 2026-27 NI scales to cite — a source for a table
421
- // that does not exist would be the false claim this map exists to
422
- // prevent.
423
- [TAX_YEARS.Y2025_26]: AFC_NI_2025,
83
+ // One year: NI has issued no 2026-27 circular (see NI_SCALES_2025_26).
84
+ [YEAR_LABELS.Y2025_26]: { scales: NI_SCALES_2025_26, source: AFC_NI_2025 },
424
85
  },
425
86
  [NATION_KEYS.scotland]: {
426
87
  // One circular restates both years: PCS(AFC)2026/1 revised the
427
- // 2025-26 figure when the inflation guarantee triggered and
428
- // restates 2026-27, so it is current for each.
429
- [TAX_YEARS.Y2025_26]: AFC_SCOTLAND,
430
- [TAX_YEARS.Y2026_27]: AFC_SCOTLAND,
88
+ // 2025-26 figure when the inflation guarantee triggered and restates
89
+ // 2026-27, so it is current for each.
90
+ [YEAR_LABELS.Y2025_26]: { scales: SCOTLAND_SCALES_2025_26, source: AFC_SCOTLAND },
91
+ [YEAR_LABELS.Y2026_27]: { scales: SCOTLAND_SCALES_2026_27, source: AFC_SCOTLAND },
431
92
  },
432
93
  [NATION_KEYS.wales]: {
433
- [TAX_YEARS.Y2025_26]: AFC_W_02_2025,
434
- [TAX_YEARS.Y2026_27]: AFC_W_02_2026,
94
+ [YEAR_LABELS.Y2025_26]: { scales: WALES_SCALES_2025_26, source: AFC_W_02_2025 },
95
+ [YEAR_LABELS.Y2026_27]: { scales: WALES_SCALES_2026_27, source: AFC_W_02_2026 },
435
96
  },
436
97
  };
98
+ /**
99
+ * England's latest AfC PAY year.
100
+ *
101
+ * Read from England's scale table, so it moves when a round is
102
+ * transcribed rather than by hand. Typed as a `PayYear`: an unbranded
103
+ * literal assigns to `TaxYear` and `PayYear` alike, and would pass into a
104
+ * tax-year parameter silently.
105
+ *
106
+ * NOT a site-wide "current year": Northern Ireland is a round behind.
107
+ * A consumer resolving figures for a reader's nation wants
108
+ * `latestAfcYear(nation)`; a consumer applying deductions wants the tax
109
+ * year in force, which it reads from its own clock.
110
+ */
111
+ export const AFC_CURRENT_YEAR = latestAfcYear(NATION_KEYS.england);
112
+ /** The previous AfC pay year, for a year-on-year comparison: the one
113
+ * before {@link AFC_CURRENT_YEAR} in England's table. */
114
+ export const AFC_PREVIOUS_YEAR = previousAfcYear(NATION_KEYS.england);
115
+ /** The most rounds a pay year may sit from the tax year it is priced in:
116
+ * one, either way ({@link payRoundLag}). */
117
+ const MOST_ROUNDS_APART = 1;
118
+ /** A nation's AfC bands for a year, each with its ladder, salary range
119
+ * and source — synchronous, no file I/O. Every nation's ladder is
120
+ * transcribed from its own instrument, Northern Ireland's included
121
+ * though its figures match England's, so no nation's scale is computed
122
+ * from another's. `year` and `nation` are both required — the accessor
123
+ * never defaults a locale, since a forgotten `nation` would silently
124
+ * return England figures for every region. */
125
+ export function getAfcScales(year, nation) {
126
+ const { scales, source } = getScalesForYear(year, nation);
127
+ return AFC_BAND_IDS.map((band) => ({
128
+ band,
129
+ points: scales[band],
130
+ salary: salaryRangeOf(scales[band]),
131
+ source,
132
+ }));
133
+ }
134
+ /** One band's published ladder for a pay year and nation. Every band is
135
+ * on every ladder (a nation-year's scales are total over the bands), so
136
+ * only the year and nation can be unpublished, which throws
137
+ * {@link ScaleUnavailable}. */
138
+ export function afcBandPoints(year, nation, band) {
139
+ return getScalesForYear(year, nation).scales[band];
140
+ }
141
+ /**
142
+ * The point labelled `label` on an AfC band, with the band's points, for
143
+ * a pay year and nation, read from {@link getAfcScales}. Throws
144
+ * `ScaleUnavailable` where the year and nation publish no scale or the
145
+ * band has no such point, and `AmbiguousScalePoint` where the label names
146
+ * more than one, so a caller never prices a point it did not ask for.
147
+ */
148
+ export function afcPointOf(year, nation, band, label) {
149
+ const points = afcBandPoints(year, nation, band);
150
+ const current = onlyPointLabelled(points, label, band, () => new ScaleUnavailable(nation, year, band, label));
151
+ return { points, current };
152
+ }
437
153
  /** The circular or page that publishes a nation's AfC scales for a
438
154
  * year. Throws for a combination that has no published scale, in step
439
155
  * with {@link getScalesForYear} — a scale we cannot cite is a scale we
440
156
  * should not be serving. */
441
157
  export function afcScaleSource(year, nation) {
442
- // The tables key on the label; the signature carries the basis.
443
- const key = year;
444
- const source = AFC_SCALE_SOURCES[nation][key];
445
- if (!source) {
446
- throw new ScaleUnavailable(nation, year);
447
- }
448
- return source;
158
+ return getScalesForYear(year, nation).source;
449
159
  }
450
160
  /** PAY years a given nation publishes AfC scales for, oldest
451
161
  * first. Nations do not move in lockstep — a year one has
@@ -458,19 +168,18 @@ export function afcScaleSource(year, nation) {
458
168
  * one pay year while every nation shares the same tax year. */
459
169
  export function afcPayYears(nation) {
460
170
  // Sorted, not authoring order: the "oldest first" above is a
461
- // guarantee callers rely on (`resolver.ts` reverses it to find the
462
- // latest year), and object-literal order would silently break it if
463
- // a new year were authored above an old one. Year labels sort
464
- // lexicographically because they are zero-padded ISO-style.
465
- return Object.keys(SCALE_FAMILIES[nation]).sort();
171
+ // guarantee callers rely on (`latestAfcYear` and `previousAfcYear` read
172
+ // the last two), and object-literal order would silently break it if
173
+ // a new year were authored above an old one. Year labels collate in year
174
+ // order because they are fixed-width and zero-padded.
175
+ return Object.keys(AFC_SCALE_YEARS[nation]).sort((a, b) => a.localeCompare(b));
466
176
  }
467
177
  /**
468
178
  * The most recent year a nation has actually published AfC scales for.
469
179
  *
470
- * Nations do not move together. Northern Ireland has issued no 2026-27
471
- * pay circular — its 3.3% is announced, unfunded and undated — so its
472
- * latest published year is 2025-26 while the other three are on
473
- * 2026-27. A consumer that asks for a site-wide "current year" gets
180
+ * Nations do not move together: Northern Ireland's latest is a round
181
+ * behind the others (see `NI_SCALES_2025_26` in `afc-scales.ts`). A
182
+ * consumer that asks for a site-wide "current year" gets
474
183
  * `ScaleUnavailable` there, which is correct but is not an answer; this
475
184
  * is the answer.
476
185
  *
@@ -478,9 +187,21 @@ export function afcPayYears(nation) {
478
187
  * this library holds. A consumer deriving it would be re-computing,
479
188
  * from the outside, something only these tables know.
480
189
  */
190
+ export function latestAfcYear(nation) {
191
+ const years = afcPayYears(nation);
192
+ const latest = years[years.length - 1];
193
+ if (!latest) {
194
+ // A plain Error, not ScaleUnavailable: that type's `year` is a
195
+ // TaxYear, and there is no year to name here. Casting a filler
196
+ // string into the union would make `error.year` lie to any caller
197
+ // that reads it.
198
+ throw new Error(`latestAfcYear: ${nation} publishes no AfC scale in any year`);
199
+ }
200
+ return latest;
201
+ }
481
202
  /**
482
- * How far a nation's newest published pay scales sit from the tax year
483
- * in force. Positive means the pay scales are BEHIND.
203
+ * How many rounds `payYear` sits behind `taxYear`. Positive means the pay
204
+ * round is BEHIND the tax year; negative means it is ahead.
484
205
  *
485
206
  * ## The domain rule this exists to state
486
207
  *
@@ -492,9 +213,9 @@ export function afcPayYears(nation) {
492
213
  *
493
214
  * They diverge in exactly one way. An AfC round is agreed and
494
215
  * implemented by each nation separately, and a nation whose award is
495
- * not yet funded keeps paying last year's scales into this tax year;
496
- * this function says which nations are. Tax never waits: the thresholds
497
- * change on 6 April whatever the employer has settled.
216
+ * not yet funded keeps paying last year's scales into this tax year.
217
+ * Tax never waits: the thresholds change on 6 April whatever the
218
+ * employer has settled.
498
219
  *
499
220
  * So the legitimate values are:
500
221
  *
@@ -502,26 +223,43 @@ export function afcPayYears(nation) {
502
223
  * |---|---|
503
224
  * | `0` | the award is implemented; pay year and tax year agree |
504
225
  * | `1` | the award for this year is not yet in payment |
505
- * | `-1` | next year's circular is out but its tax year has not begun |
226
+ * | `-1` | next year's round is out but its tax year has not begun |
506
227
  *
507
- * Anything else is a defect in THIS library's data, not a fact about
508
- * the world: a lag of 2 means a whole round was never transcribed.
509
- * {@link assertPayYearLagIsSane} is where that is enforced.
228
+ * Anything else is a round that was never transcribed or a caller pricing
229
+ * a stale round, not a fact about the world ({@link isPayRoundInReach}).
510
230
  *
511
- * What this cannot catch is a pay year passed where a tax year was
512
- * wanted: the values here would look perfectly legal. The distinct
513
- * `PayYear` and `TaxYear` types are what stop that.
231
+ * Counted in years from each label's closing year, not by position in a
232
+ * list of labels, so it holds however the labels are ordered. What this
233
+ * cannot catch is a pay year passed where a tax year was wanted: the
234
+ * distinct `PayYear` and `TaxYear` types are what stop that.
514
235
  */
515
- export function payYearLag(nation) {
516
- const order = Object.values(TAX_YEARS);
517
- const pay = order.indexOf(latestAfcYear(nation));
518
- const tax = order.indexOf(CURRENT_TAX_YEAR);
519
- invariant(pay >= 0 && tax >= 0, `payYearLag: ${nation} resolves a year outside TAX_YEARS`);
520
- return tax - pay;
236
+ export function payRoundLag(payYear, taxYear) {
237
+ return closingYearOf(taxYear) - closingYearOf(payYear);
521
238
  }
522
239
  /**
523
- * True while a nation is still paying an older round than the tax year
524
- * in force — its award is announced or awaited, but not in payment.
240
+ * True where `payYear` is a round this library will price under
241
+ * `taxYear`'s deductions: at most one round from it, either way
242
+ * ({@link payRoundLag}). One rule for every reader, so a caller refusing
243
+ * a stale round and this library checking its own tables cannot disagree
244
+ * about what "too far apart" means.
245
+ */
246
+ export function isPayRoundInReach(payYear, taxYear) {
247
+ return Math.abs(payRoundLag(payYear, taxYear)) <= MOST_ROUNDS_APART;
248
+ }
249
+ /**
250
+ * How far a nation's newest published pay scales sit from `taxYear`:
251
+ * {@link payRoundLag} of {@link latestAfcYear}. Positive means the pay
252
+ * scales are BEHIND, which is the nations still paying an earlier round.
253
+ *
254
+ * `taxYear` is the caller's: this library holds no clock, so the tax year
255
+ * in force is a fact the consumer brings, read at its own build or run.
256
+ */
257
+ export function latestRoundLag(nation, taxYear) {
258
+ return payRoundLag(latestAfcYear(nation), taxYear);
259
+ }
260
+ /**
261
+ * True while a nation is still paying an older round than `taxYear` — its
262
+ * award is announced or awaited, but not in payment.
525
263
  *
526
264
  * The domain question ("is this nation behind?") rather than a
527
265
  * comparison against some particular year, so a consumer cannot get
@@ -529,51 +267,77 @@ export function payYearLag(nation) {
529
267
  * "is it exactly 2025-26" and quietly says no for a nation two rounds
530
268
  * behind, which is the case that most needs saying yes.
531
269
  */
532
- export function isAwaitingPayAward(nation) {
533
- return payYearLag(nation) > 0;
270
+ export function isAwaitingPayAward(nation, taxYear) {
271
+ return latestRoundLag(nation, taxYear) > 0;
534
272
  }
535
273
  /**
536
- * Fail loudly if any nation's pay scales have drifted further from the
537
- * tax year than the domain allows. See {@link payYearLag}.
274
+ * Fail loudly if any nation's newest scale is out of reach of `taxYear`
275
+ * ({@link isPayRoundInReach}).
538
276
  *
539
277
  * A function rather than a module-scope check: this library is
540
278
  * published, and a throw at import time would take down every consumer
541
279
  * over a data problem they cannot fix. It runs in this repo's tests,
542
- * which is where a transcription gap should surface.
280
+ * which is where a transcription gap should surface, and a consumer can
281
+ * run it against the tax year it prices in.
543
282
  */
544
- export function assertPayYearLagIsSane() {
545
- for (const nation of Object.keys(SCALE_FAMILIES)) {
546
- const lag = payYearLag(nation);
547
- invariant(lag >= -1 && lag <= 1, `${nation} is ${lag} years from the tax year in force `
548
- + `(${CURRENT_TAX_YEAR}): its newest published scale is `
549
- + `${latestAfcYear(nation)}. A gap beyond one year means a pay `
550
- + 'round was never transcribed, not that a nation skipped one.');
283
+ export function assertLatestRoundsInReach(taxYear) {
284
+ for (const nation of Object.keys(AFC_SCALE_YEARS)) {
285
+ const latest = latestAfcYear(nation);
286
+ invariant(isPayRoundInReach(latest, taxYear), `${nation} is ${payRoundLag(latest, taxYear)} rounds from the `
287
+ + `${taxYear} tax year: its newest published scale is ${latest}. A `
288
+ + `gap beyond ${MOST_ROUNDS_APART} round means a pay round was never `
289
+ + 'transcribed, not that a nation skipped one.');
551
290
  }
552
291
  }
553
- export function latestAfcYear(nation) {
292
+ /**
293
+ * The AfC pay year whose round runs over one scheme year, where this
294
+ * library holds its scale for the nation, and otherwise which side of the
295
+ * held years the scheme year falls ({@link AFC_PAY_YEAR_KINDS}). A pay year
296
+ * is one scheme year (`pay-year.ts`). `taxYear` is the tax year in force,
297
+ * which bounds how far ahead a round can be awaited.
298
+ *
299
+ * The round a scheme year names is not always the scale staff were paid
300
+ * on in it: a nation whose award is late still pays the previous round's
301
+ * scale (`latestRoundLag`, `latestAfcYear`). Ask those for that.
302
+ */
303
+ export function afcPayYearFor(end, nation, taxYear) {
554
304
  const years = afcPayYears(nation);
555
- const latest = years[years.length - 1];
556
- if (!latest) {
557
- // A plain Error, not ScaleUnavailable: that type's `year` is a
558
- // TaxYear, and there is no year to name here. Casting a filler
559
- // string into the union would make `error.year` lie to any caller
560
- // that reads it.
561
- throw new Error(`latestAfcYear: ${nation} publishes no AfC scale in any year`);
305
+ const year = years.find((y) => schemeYearOfPayYear(y) === end);
306
+ if (year !== undefined)
307
+ return { kind: AFC_PAY_YEAR_KINDS.held, year };
308
+ if (end > schemeYearOfPayYear(latestAfcYear(nation))) {
309
+ // A round can be awaited up to the one after `taxYear`; a year beyond
310
+ // that has no round to wait for, which this cannot answer.
311
+ const lastAwaitable = closingYearOf(taxYear) + MOST_ROUNDS_APART;
312
+ invariant(end <= lastAwaitable, `afcPayYearFor: the scheme year ending ${end} is past the next pay `
313
+ + `round (${lastAwaitable})`);
314
+ return { kind: AFC_PAY_YEAR_KINDS.awaited };
562
315
  }
563
- return latest;
316
+ // Below the latest and not found, so before the earliest: a nation's
317
+ // years run unbroken, and a gap among them is a round never
318
+ // transcribed.
319
+ invariant(years.every((y) => schemeYearOfPayYear(y) > end), `afcPayYearFor: ${nation} has no AfC scale for the scheme year ending `
320
+ + `${end}, between years it does hold`);
321
+ return { kind: AFC_PAY_YEAR_KINDS.notHeld };
322
+ }
323
+ /** The AfC year a nation published before its latest, for a year-on-year
324
+ * comparison. Throws where the nation holds only one year. */
325
+ function previousAfcYear(nation) {
326
+ const years = afcPayYears(nation);
327
+ const previous = years.slice(0, -1).at(-1);
328
+ invariant(previous !== undefined, `previousAfcYear: ${nation} holds one AfC year only`);
329
+ return previous;
564
330
  }
565
331
  /** Resolve a nation's published scale table for a year.
566
332
  * Every figure returned is transcribed from that nation's
567
- * own instrument. Where two nations' circulars print the
568
- * same numbers the tables share an object literal for
569
- * brevity, and each nation's fixture rows pin its values
570
- * against its OWN document, so a divergence fails rather
571
- * than propagating. Throws {@link ScaleUnavailable} for a
333
+ * own instrument, and each nation's fixture rows pin its
334
+ * values against its OWN document, so a divergence fails
335
+ * rather than propagating. Throws {@link ScaleUnavailable} for a
572
336
  * year that nation has not published, rather than silently
573
337
  * substituting another year's or nation's figures. */
574
- export function getScalesForYear(year, nation) {
338
+ function getScalesForYear(year, nation) {
575
339
  const key = year;
576
- const base = SCALE_FAMILIES[nation][key];
340
+ const base = AFC_SCALE_YEARS[nation][key];
577
341
  if (!base) {
578
342
  throw new ScaleUnavailable(nation, year);
579
343
  }