@casomoltd/nhs-pay 0.15.1 → 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 +24 -6
  102. package/dist/circulars/england-md-1-2026r.js.map +0 -1
package/dist/award.js CHANGED
@@ -1,64 +1,387 @@
1
1
  /**
2
- * Agenda for Change headline pay awards (consolidated % uplift) by
3
- * nation and year.
2
+ * NHS headline pay awards by nation, year and staff family, for both
3
+ * pay frameworks: Agenda for Change, and medical & dental.
4
4
  *
5
- * The negotiated award is published data, NOT derivable from the
6
- * scale points: per-point rounding diverges from the headline (e.g.
7
- * Scotland's 3.75% award computes as ~3.8% from a single band's
8
- * min-point delta), and staged awards have no single scale ratio. So
9
- * the award lives here as a cited constant, one per (nation, year),
10
- * each nation recorded independently because the four nations
11
- * negotiate separately.
5
+ * A negotiated award is published data, NOT derivable from the scale
6
+ * points. Per-point rounding diverges from the headline, and a staged
7
+ * award has no single scale ratio. For doctors the case is starker: a
8
+ * medical & dental circular prints salary scales and no percentage at
9
+ * all. Replaying an award onto the prior year's points reproduces the
10
+ * published figures only to within £1, and the error changes direction
11
+ * between publishers — so awards are recorded here as cited constants
12
+ * and the scales stay transcribed, never derived.
12
13
  *
13
- * Sources (also pinned per-row in tests/fixtures/afc-awards.csv).
14
- * Named as they appear in docs/source-archive.md, which holds
15
- * every publisher URL and archived copy:
16
- * - England & Wales: "NHS Employers — AfC pay scales 2025/26"
17
- * and "NHS Employers — AfC pay scales 2026/27"
18
- * - Scotland: "Scotland, PCS(AFC)2026/01" — 4.25% for 2025-26
19
- * (average 4.4% after the inflation guarantee) and 3.75%
20
- * for 2026-27
21
- * - Northern Ireland: Department of Health (NI) accepted the UK PRB
22
- * award, aligned with England (3.6% / 3.3%); 2026/27 subject to
23
- * local implementation. The award itself is the recommendation
24
- * in "NHS Pay Review Body, Thirty-Ninth Report 2026" (#sa-42).
25
- * The figures below still come from what each nation ACCEPTED,
26
- * never from the report: a recommendation can be modified,
27
- * staged or refused on the way in, and when it is, the circular
28
- * is right and the report is not.
14
+ * Each record is **self-describing**: it carries its nation, year and
15
+ * family as fields rather than relying on where it was found, so an
16
+ * award handed to a caller can say what it applies to. That is why the
17
+ * table is a flat list — a keyed cube would duplicate every coordinate
18
+ * in a field, and the two could disagree.
19
+ *
20
+ * Across both frameworks the figure is what a nation ACCEPTED, never
21
+ * what its review body recommended: a recommendation can be modified,
22
+ * staged or refused on the way in, and when it is, the acceptance is
23
+ * right and the report is not. A nation that has accepted nothing has
24
+ * no row — absence is the honest record of "not announced", which is
25
+ * why Northern Ireland has no 2026-27 medical entry.
26
+ *
27
+ * What this does NOT record is whether our own scale tables carry an
28
+ * award yet. That is already answered by the published scales: compare
29
+ * the year a scale resolved to against the year of the award. A stored
30
+ * flag would be a second source of truth, free to drift from the
31
+ * circulars the moment one publishes.
32
+ *
33
+ * Sources are pinned per row in tests/fixtures/, and every row carries
34
+ * its own {@link DocumentSource} so a consumer cites the instrument rather
35
+ * than hand-typing it. Employer-body summaries are deliberately not
36
+ * cited: accurate as they are, they restate an instrument rather than
37
+ * being one.
29
38
  */
39
+ import { payYear } from '@casomoltd/paye-calc';
40
+ import { isoDate, isoMonth } from './iso-date.js';
30
41
  import { NATION_KEYS, TAX_YEARS } from '@casomoltd/paye-calc';
31
42
  import { AwardUnavailable } from './errors.js';
32
- /** Headline consolidated AfC uplift (%), by nation and year. */
33
- const AFC_AWARDS = {
34
- [NATION_KEYS.england]: {
35
- [TAX_YEARS.Y2025_26]: 3.6,
36
- [TAX_YEARS.Y2026_27]: 3.3,
43
+ import { DocumentSource } from './document-source.js';
44
+ import { AFC_ENGLAND_2025, AFC_ENGLAND_2026, AFC_NI_2025, AFC_NI_2026, AFC_SCOTLAND, AFC_WALES_2025, AFC_WALES_2026, DDRB_54_ENGLAND, DDRB_54_SCOTLAND, DDRB_54_WALES, } from './sources.js';
45
+ import { AFC_BANDS, AFC_BAND_IDS } from './scales.js';
46
+ import { MEDICAL_GRADES, MEDICAL_GRADE_IDS } from './medical-scales.js';
47
+ import { DENTAL_GRADES, DENTAL_GRADE_IDS } from './dental-scales.js';
48
+ /**
49
+ * The staff groups an award is announced for. These are the AWARD's
50
+ * own groupings, coarser than a reader-facing role: one figure covers
51
+ * consultants, SAS and salaried GPs alike.
52
+ *
53
+ * The VALUES are prefixed because the bare words collide with three
54
+ * other identifier unions — `resident` and `salaried-dental` are grade
55
+ * ids, and `medical` is a `RoleKind`. Without the prefix a grade id
56
+ * would compile where a family is required and return a plausible but
57
+ * wrong answer. The keys are unprefixed, so call sites read normally.
58
+ */
59
+ export const AWARD_FAMILIES = {
60
+ /** Every AfC band. One award covers all of them, which is a family
61
+ * of one group — not the absence of a family. */
62
+ afc: 'award-afc',
63
+ /** Consultants, SAS doctors & dentists, and salaried GPs. */
64
+ medical: 'award-medical',
65
+ /** Doctors & dentists in training. */
66
+ resident: 'award-resident',
67
+ /** Salaried dentists in community & public dental services. */
68
+ salariedDental: 'award-salaried-dental',
69
+ };
70
+ // ── Coverage: which family covers each scale ─────
71
+ //
72
+ // Total over PayScaleId, so a new grade fails the build until someone
73
+ // says which award covers it — the compiler asks the question rather
74
+ // than a reviewer noticing. It states coverage at the granularity the
75
+ // ANNOUNCEMENTS state it: it claims a grade belongs to a staff group,
76
+ // never that a nation awarded that grade a percentage. Whether the
77
+ // group has an award in a given nation and year is the table below's
78
+ // answer, and is frequently "no".
79
+ //
80
+ // The eleven identical AfC rows are the point, not noise: the NHSPRB
81
+ // settles ONE award covering every band, and saying so here makes it a
82
+ // checkable claim rather than something implied by a lookup that takes
83
+ // no band.
84
+ const AWARD_COVERAGE = {
85
+ [AFC_BANDS.B2]: AWARD_FAMILIES.afc,
86
+ [AFC_BANDS.B3]: AWARD_FAMILIES.afc,
87
+ [AFC_BANDS.B4]: AWARD_FAMILIES.afc,
88
+ [AFC_BANDS.B5]: AWARD_FAMILIES.afc,
89
+ [AFC_BANDS.B6]: AWARD_FAMILIES.afc,
90
+ [AFC_BANDS.B7]: AWARD_FAMILIES.afc,
91
+ [AFC_BANDS.B8a]: AWARD_FAMILIES.afc,
92
+ [AFC_BANDS.B8b]: AWARD_FAMILIES.afc,
93
+ [AFC_BANDS.B8c]: AWARD_FAMILIES.afc,
94
+ [AFC_BANDS.B8d]: AWARD_FAMILIES.afc,
95
+ [AFC_BANDS.B9]: AWARD_FAMILIES.afc,
96
+ // Consultants, SAS and salaried GPs — DDRB recommendation 1's
97
+ // "consultants, SAS doctors and dentists, salaried GPs".
98
+ [MEDICAL_GRADES.consultant]: AWARD_FAMILIES.medical,
99
+ [MEDICAL_GRADES.specialtyDoctor]: AWARD_FAMILIES.medical,
100
+ [MEDICAL_GRADES.specialist]: AWARD_FAMILIES.medical,
101
+ [MEDICAL_GRADES.salariedGp]: AWARD_FAMILIES.medical,
102
+ [MEDICAL_GRADES.gpEducator]: AWARD_FAMILIES.medical,
103
+ [MEDICAL_GRADES.staffGrade]: AWARD_FAMILIES.medical,
104
+ [MEDICAL_GRADES.associateSpecialist]: AWARD_FAMILIES.medical,
105
+ [MEDICAL_GRADES.specialtyDoctor2008]: AWARD_FAMILIES.medical,
106
+ [MEDICAL_GRADES.associateSpecialist2008]: AWARD_FAMILIES.medical,
107
+ [MEDICAL_GRADES.hospitalPractitioner]: AWARD_FAMILIES.medical,
108
+ // The least certain entry: a locally-employed doctor holds a
109
+ // non-training post, so it sits with the other non-training grades —
110
+ // but no announcement names the group explicitly. Revisit if a round
111
+ // ever treats LEDs separately.
112
+ [MEDICAL_GRADES.locallyEmployedDoctor]: AWARD_FAMILIES.medical,
113
+ // Doctors in training — DDRB recommendation 1's "resident doctors".
114
+ [MEDICAL_GRADES.resident]: AWARD_FAMILIES.resident,
115
+ [MEDICAL_GRADES.fho1]: AWARD_FAMILIES.resident,
116
+ [MEDICAL_GRADES.fho2]: AWARD_FAMILIES.resident,
117
+ [MEDICAL_GRADES.sho]: AWARD_FAMILIES.resident,
118
+ [MEDICAL_GRADES.spr]: AWARD_FAMILIES.resident,
119
+ [MEDICAL_GRADES.str]: AWARD_FAMILIES.resident,
120
+ [MEDICAL_GRADES.specialtyRegistrarCore]: AWARD_FAMILIES.resident,
121
+ [MEDICAL_GRADES.specialtyRegistrarFixed]: AWARD_FAMILIES.resident,
122
+ [MEDICAL_GRADES.gpRegistrarSho]: AWARD_FAMILIES.resident,
123
+ [MEDICAL_GRADES.gpRegistrarSpr]: AWARD_FAMILIES.resident,
124
+ [MEDICAL_GRADES.gpRegistrarStr]: AWARD_FAMILIES.resident,
125
+ // Dentists in TRAINING take the resident award, not the salaried
126
+ // dental one — the split a reader-facing "dental" grouping loses.
127
+ [DENTAL_GRADES.dentalCoreTraining]: AWARD_FAMILIES.resident,
128
+ [DENTAL_GRADES.dentalSpecialtyTraining]: AWARD_FAMILIES.resident,
129
+ // A dental educator is an SAS dentist, so it takes the medical award.
130
+ [DENTAL_GRADES.dentalEducator]: AWARD_FAMILIES.medical,
131
+ // Salaried dentists in community & public dental services — DDRB
132
+ // recommendation 2, a separate and higher figure.
133
+ [DENTAL_GRADES.salariedDental]: AWARD_FAMILIES.salariedDental,
134
+ [DENTAL_GRADES.salariedDentist]: AWARD_FAMILIES.salariedDental,
135
+ [DENTAL_GRADES.seniorSalariedDentist]: AWARD_FAMILIES.salariedDental,
136
+ [DENTAL_GRADES.assistantClinicalDirectorDentist]: AWARD_FAMILIES.salariedDental,
137
+ [DENTAL_GRADES.clinicalDirectorDentist]: AWARD_FAMILIES.salariedDental,
138
+ [DENTAL_GRADES.communityDentalOfficer]: AWARD_FAMILIES.salariedDental,
139
+ [DENTAL_GRADES.seniorCommunityDentalOfficer]: AWARD_FAMILIES.salariedDental,
140
+ [DENTAL_GRADES.assistantCommunityDentalClinicalDirector]: AWARD_FAMILIES.salariedDental,
141
+ [DENTAL_GRADES.specialistCommunityDentist]: AWARD_FAMILIES.salariedDental,
142
+ [DENTAL_GRADES.communityDentalClinicalDirector]: AWARD_FAMILIES.salariedDental,
143
+ };
144
+ // ── The awards ───────────────────────────────────
145
+ const AWARD_ROWS = [
146
+ {
147
+ kind: 'settled',
148
+ nation: NATION_KEYS.england, year: payYear(TAX_YEARS.Y2026_27),
149
+ family: AWARD_FAMILIES.medical, pct: 3.5,
150
+ effectiveFrom: isoDate('2026-04-01'), expectedInPay: isoMonth('2026-06'),
151
+ source: DDRB_54_ENGLAND,
37
152
  },
38
- [NATION_KEYS.wales]: {
39
- [TAX_YEARS.Y2025_26]: 3.6,
40
- [TAX_YEARS.Y2026_27]: 3.3,
153
+ {
154
+ // `pct` is the DDRB award and nothing more, which for this one
155
+ // family is LESS than the scale actually moved: PC(M&D) 1/2026 R2
156
+ // applied the 3.5% and then restructured the nodal points under
157
+ // the BMA agreement, so a 2026-27 England resident point can be
158
+ // several percent above its 2025-26 counterpart. The award and the
159
+ // scale delta are different quantities here, and a consumer
160
+ // presenting this figure as the whole rise would understate it.
161
+ kind: 'settled',
162
+ nation: NATION_KEYS.england, year: payYear(TAX_YEARS.Y2026_27),
163
+ family: AWARD_FAMILIES.resident, pct: 3.5,
164
+ effectiveFrom: isoDate('2026-04-01'), expectedInPay: isoMonth('2026-06'),
165
+ source: DDRB_54_ENGLAND,
41
166
  },
42
- [NATION_KEYS.scotland]: {
43
- [TAX_YEARS.Y2025_26]: 4.25,
44
- [TAX_YEARS.Y2026_27]: 3.75,
167
+ {
168
+ kind: 'settled',
169
+ nation: NATION_KEYS.england, year: payYear(TAX_YEARS.Y2026_27),
170
+ family: AWARD_FAMILIES.salariedDental, pct: 3.75,
171
+ effectiveFrom: isoDate('2026-04-01'), expectedInPay: isoMonth('2026-06'),
172
+ source: DDRB_54_ENGLAND,
45
173
  },
46
- [NATION_KEYS.northernIreland]: {
47
- [TAX_YEARS.Y2025_26]: 3.6,
48
- [TAX_YEARS.Y2026_27]: 3.3,
174
+ {
175
+ kind: 'settled',
176
+ nation: NATION_KEYS.wales, year: payYear(TAX_YEARS.Y2026_27),
177
+ family: AWARD_FAMILIES.medical, pct: 3.5,
178
+ effectiveFrom: isoDate('2026-04-01'), source: DDRB_54_WALES,
49
179
  },
50
- };
180
+ {
181
+ kind: 'settled',
182
+ nation: NATION_KEYS.wales, year: payYear(TAX_YEARS.Y2026_27),
183
+ family: AWARD_FAMILIES.resident, pct: 3.5,
184
+ effectiveFrom: isoDate('2026-04-01'), source: DDRB_54_WALES,
185
+ },
186
+ {
187
+ kind: 'settled',
188
+ nation: NATION_KEYS.wales, year: payYear(TAX_YEARS.Y2026_27),
189
+ family: AWARD_FAMILIES.salariedDental, pct: 3.75,
190
+ effectiveFrom: isoDate('2026-04-01'), source: DDRB_54_WALES,
191
+ },
192
+ // Scotland records no `resident` row: its training grades were
193
+ // settled separately under the BMA agreement and promulgated through
194
+ // PCS(DD)2026/01, which prints scale points and no percentage.
195
+ {
196
+ kind: 'settled',
197
+ nation: NATION_KEYS.scotland, year: payYear(TAX_YEARS.Y2026_27),
198
+ family: AWARD_FAMILIES.medical, pct: 3.5,
199
+ effectiveFrom: isoDate('2026-04-01'), expectedInPay: isoMonth('2026-09'),
200
+ source: DDRB_54_SCOTLAND,
201
+ },
202
+ {
203
+ kind: 'settled',
204
+ nation: NATION_KEYS.scotland, year: payYear(TAX_YEARS.Y2026_27),
205
+ family: AWARD_FAMILIES.salariedDental, pct: 3.75,
206
+ effectiveFrom: isoDate('2026-04-01'), expectedInPay: isoMonth('2026-09'),
207
+ source: DDRB_54_SCOTLAND,
208
+ },
209
+ // Northern Ireland has accepted no 2026-27 medical & dental award.
210
+ // Its absence from this list IS the record of that.
211
+ // ── Agenda for Change ──
212
+ {
213
+ kind: 'settled', nation: NATION_KEYS.england,
214
+ year: payYear(TAX_YEARS.Y2025_26), family: AWARD_FAMILIES.afc,
215
+ pct: 3.6, effectiveFrom: isoDate('2025-04-01'), source: AFC_ENGLAND_2025,
216
+ },
217
+ {
218
+ kind: 'settled', nation: NATION_KEYS.england,
219
+ year: payYear(TAX_YEARS.Y2026_27), family: AWARD_FAMILIES.afc,
220
+ pct: 3.3, effectiveFrom: isoDate('2026-04-01'), source: AFC_ENGLAND_2026,
221
+ },
222
+ {
223
+ kind: 'settled', nation: NATION_KEYS.wales,
224
+ year: payYear(TAX_YEARS.Y2025_26), family: AWARD_FAMILIES.afc,
225
+ pct: 3.6, effectiveFrom: isoDate('2025-04-01'), source: AFC_WALES_2025,
226
+ },
227
+ {
228
+ kind: 'settled', nation: NATION_KEYS.wales,
229
+ year: payYear(TAX_YEARS.Y2026_27), family: AWARD_FAMILIES.afc,
230
+ pct: 3.3, effectiveFrom: isoDate('2026-04-01'), source: AFC_WALES_2026,
231
+ },
232
+ {
233
+ // 4.4, not the 4.25 the two-year deal originally set: its inflation
234
+ // guarantee (each year at least a point above that calendar year's
235
+ // average CPI) triggered when 2025 CPI confirmed at 3.4%, and
236
+ // PCS(AFC)2026/1 adjusted the rate backdated to 1 April 2025 with
237
+ // arrears. 4.4% is the headline in force, not an average.
238
+ kind: 'settled', nation: NATION_KEYS.scotland,
239
+ year: payYear(TAX_YEARS.Y2025_26), family: AWARD_FAMILIES.afc,
240
+ pct: 4.4, effectiveFrom: isoDate('2025-04-01'), source: AFC_SCOTLAND,
241
+ },
242
+ {
243
+ kind: 'settled', nation: NATION_KEYS.scotland,
244
+ year: payYear(TAX_YEARS.Y2026_27), family: AWARD_FAMILIES.afc,
245
+ pct: 3.75, effectiveFrom: isoDate('2026-04-01'), source: AFC_SCOTLAND,
246
+ },
247
+ {
248
+ kind: 'settled', nation: NATION_KEYS.northernIreland,
249
+ year: payYear(TAX_YEARS.Y2025_26), family: AWARD_FAMILIES.afc,
250
+ pct: 3.6, effectiveFrom: isoDate('2025-04-01'), source: AFC_NI_2025,
251
+ },
252
+ {
253
+ // Weaker instrument than every other row — see AFC_NI_2026.
254
+ kind: 'settled', nation: NATION_KEYS.northernIreland,
255
+ year: payYear(TAX_YEARS.Y2026_27), family: AWARD_FAMILIES.afc,
256
+ pct: 3.3, effectiveFrom: isoDate('2026-04-01'), source: AFC_NI_2026,
257
+ },
258
+ ];
259
+ /**
260
+ * Changes agreed but not yet expressible as an award. Two instances,
261
+ * both resident contracts:
262
+ * - England's April 2027 phase of the offer accepted July 2026, which
263
+ * moves pay by a RANGE across nodal points — a vector, not a
264
+ * headline, which is why no `pct` is recorded.
265
+ * - Wales replaces the 2002 resident contract with a 2026 one, phased
266
+ * by cohort. A contract replacement has no percentage at all.
267
+ *
268
+ * Each cites the instrument that agreed it, not commentary about it:
269
+ * the government's own offer document, and the Welsh pay circular that
270
+ * introduces the contract.
271
+ */
272
+ const FORTHCOMING_ROWS = [
273
+ {
274
+ // The offer's April 2026 phase is in the scales already, via
275
+ // PC(M&D) 1/2026 R2 (`england-md-1-2026-r2.ts`); April 2027 is the
276
+ // phase still to come, and a forthcoming row dates itself to what
277
+ // has NOT landed.
278
+ kind: 'forthcoming',
279
+ nation: NATION_KEYS.england,
280
+ family: AWARD_FAMILIES.resident,
281
+ effectiveFrom: isoDate('2027-04-01'),
282
+ source: new DocumentSource({
283
+ issuer: 'the UK government',
284
+ reference: 'offer to resident doctors June 2026',
285
+ url: 'https://www.gov.uk/government/publications'
286
+ + '/government-offer-to-resident-doctors-june-2026'
287
+ + '/offer-to-bma-uk-resident-doctors-committee-june-2026'
288
+ + '-accessible-version',
289
+ issued: isoDate('2026-06-17'),
290
+ }),
291
+ },
292
+ {
293
+ // The later cohorts (core trainees, then registrars) are phased
294
+ // across 2027 and 2028, which the circular gives as years rather
295
+ // than dates. A forthcoming row carries one date, so those stay
296
+ // prose on the page beside this citation.
297
+ kind: 'forthcoming',
298
+ nation: NATION_KEYS.wales,
299
+ family: AWARD_FAMILIES.resident,
300
+ effectiveFrom: isoDate('2026-08-01'),
301
+ source: new DocumentSource({
302
+ issuer: 'NHS Wales',
303
+ reference: 'circular M&D(W) 01/2026',
304
+ url: 'https://www.nhs.wales/files/pc-resources'
305
+ + '/md-w-0126-pay-award-02-04-26-version-2/',
306
+ issued: isoDate('2026-05-05'),
307
+ }),
308
+ },
309
+ ];
310
+ /** The scales a family reaches — the inverse of {@link AWARD_COVERAGE},
311
+ * computed once so the two directions cannot disagree. */
312
+ const ALL_SCALE_IDS = [
313
+ ...AFC_BAND_IDS,
314
+ ...MEDICAL_GRADE_IDS,
315
+ ...DENTAL_GRADE_IDS,
316
+ ];
317
+ /**
318
+ * Iterated from the canonical id arrays, NOT `Object.keys` — a Record
319
+ * lists integer-like keys first and in numeric order, which would put
320
+ * band 9 ahead of 8a and hand a consumer an order the authored table
321
+ * does not have.
322
+ */
323
+ function scalesCoveredBy(family) {
324
+ return ALL_SCALE_IDS.filter((scale) => AWARD_COVERAGE[scale] === family);
325
+ }
326
+ const AWARDS = AWARD_ROWS.map((row) => ({
327
+ ...row,
328
+ covers: scalesCoveredBy(row.family),
329
+ }));
330
+ const FORTHCOMING = FORTHCOMING_ROWS.map((row) => ({
331
+ ...row,
332
+ covers: scalesCoveredBy(row.family),
333
+ }));
334
+ /** One producer for "this nation's awards in this family, newest
335
+ * first" — both public lookups read it. */
336
+ function awardsInFamily(nation, family) {
337
+ return AWARDS
338
+ .filter((a) => a.nation === nation && a.family === family)
339
+ .sort((a, b) => b.year.localeCompare(a.year));
340
+ }
51
341
  /**
52
- * The AfC headline pay award for a nation and year, as a percentage
53
- * (e.g. `3.75` for 3.75%). Throws {@link AwardUnavailable} for an
54
- * unrecorded combination rather than defaulting — the caller must
55
- * name the nation (no silent fallback).
342
+ * Every award recorded for a pay scale in a nation, newest year first
343
+ * — the "which awards affect this role?" direction, and the same
344
+ * question whichever framework the scale belongs to. Empty where none
345
+ * has been announced; absence is a normal state, not an error, because
346
+ * a partly-settled round is the usual mid-year position.
347
+ *
348
+ * A list rather than a single award, because the question is about a
349
+ * history, not just this year's figure.
350
+ */
351
+ export function awardsFor(nation, scale) {
352
+ return awardsInFamily(nation, AWARD_COVERAGE[scale]);
353
+ }
354
+ /**
355
+ * Everything the library knows about a scale's pay movement in a
356
+ * nation. Settled awards first, newest year first, then any
357
+ * forthcoming changes — NOT one merged chronology, because the two
358
+ * arms are not comparable: a settled award is dated by the year it
359
+ * belongs to, a forthcoming change only by when it starts.
360
+ *
361
+ * Callers narrow on `kind`; those that only ever quote a percentage
362
+ * should use {@link awardsFor} and never see the other arm.
363
+ */
364
+ export function changesFor(nation, scale) {
365
+ const family = AWARD_COVERAGE[scale];
366
+ const forthcoming = FORTHCOMING.filter((c) => c.nation === nation && c.family === family);
367
+ return [...awardsFor(nation, scale), ...forthcoming];
368
+ }
369
+ /**
370
+ * The AfC award for a nation and year. Throws {@link AwardUnavailable}
371
+ * rather than returning undefined — unlike the medical & dental
372
+ * families, every nation settles an AfC award every year, so a missing
373
+ * one is a real error and not the normal mid-year state.
374
+ *
375
+ * A convenience over the same table {@link awardsFor} reads: the AfC
376
+ * headline needs no band, because one award covers every band, and
377
+ * that fact is stated in AWARD_COVERAGE rather than implied by this
378
+ * signature taking no band.
56
379
  */
57
380
  export function afcAward(year, nation) {
58
- const pct = AFC_AWARDS[nation][year];
59
- if (pct === undefined) {
381
+ const award = awardsInFamily(nation, AWARD_FAMILIES.afc).find((a) => a.year === year);
382
+ if (award === undefined) {
60
383
  throw new AwardUnavailable(year, nation);
61
384
  }
62
- return pct;
385
+ return award;
63
386
  }
64
387
  //# sourceMappingURL=award.js.map
package/dist/award.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"award.js","sourceRoot":"","sources":["../src/award.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAC,WAAW,EAAE,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAE7C,gEAAgE;AAChE,MAAM,UAAU,GAGZ;IACF,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE;QACrB,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,GAAG;QACzB,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,GAAG;KAC1B;IACD,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE;QACnB,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,GAAG;QACzB,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,GAAG;KAC1B;IACD,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE;QACtB,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI;QAC1B,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI;KAC3B;IACD,CAAC,WAAW,CAAC,eAAe,CAAC,EAAE;QAC7B,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,GAAG;QACzB,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,GAAG;KAC1B;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAa,EAAE,MAAc;IACpD,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
1
+ {"version":3,"file":"award.js","sourceRoot":"","sources":["../src/award.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,EAAC,OAAO,EAAC,MAAM,sBAAsB,CAAC;AAE7C,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAC,MAAM,eAAe,CAAC;AAChD,OAAO,EAAC,WAAW,EAAE,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AACpD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,SAAS,EAAE,YAAY,EAAC,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAC,cAAc,EAAE,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAEtE,OAAO,EAAC,aAAa,EAAE,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAanE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B;sDACkD;IAClD,GAAG,EAAE,WAAW;IAChB,6DAA6D;IAC7D,OAAO,EAAE,eAAe;IACxB,sCAAsC;IACtC,QAAQ,EAAE,gBAAgB;IAC1B,+DAA+D;IAC/D,cAAc,EAAE,uBAAuB;CAC/B,CAAC;AAiFX,oDAAoD;AACpD,EAAE;AACF,sEAAsE;AACtE,qEAAqE;AACrE,sEAAsE;AACtE,sEAAsE;AACtE,mEAAmE;AACnE,qEAAqE;AACrE,kCAAkC;AAClC,EAAE;AACF,qEAAqE;AACrE,uEAAuE;AACvE,uEAAuE;AACvE,WAAW;AAEX,MAAM,cAAc,GAAoC;IACtD,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,GAAG;IAClC,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,GAAG;IAClC,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,GAAG;IAClC,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,GAAG;IAClC,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,GAAG;IAClC,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,GAAG;IAClC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,GAAG;IACnC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,GAAG;IACnC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,GAAG;IACnC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,GAAG;IACnC,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,GAAG;IAElC,8DAA8D;IAC9D,yDAAyD;IACzD,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,OAAO;IACnD,CAAC,cAAc,CAAC,eAAe,CAAC,EAAE,cAAc,CAAC,OAAO;IACxD,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,OAAO;IACnD,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,OAAO;IACnD,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,OAAO;IACnD,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,OAAO;IACnD,CAAC,cAAc,CAAC,mBAAmB,CAAC,EAAE,cAAc,CAAC,OAAO;IAC5D,CAAC,cAAc,CAAC,mBAAmB,CAAC,EAAE,cAAc,CAAC,OAAO;IAC5D,CAAC,cAAc,CAAC,uBAAuB,CAAC,EAAE,cAAc,CAAC,OAAO;IAChE,CAAC,cAAc,CAAC,oBAAoB,CAAC,EAAE,cAAc,CAAC,OAAO;IAC7D,6DAA6D;IAC7D,qEAAqE;IACrE,qEAAqE;IACrE,+BAA+B;IAC/B,CAAC,cAAc,CAAC,qBAAqB,CAAC,EAAE,cAAc,CAAC,OAAO;IAE9D,oEAAoE;IACpE,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,QAAQ;IAClD,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,QAAQ;IAC9C,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,QAAQ;IAC9C,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,QAAQ;IAC7C,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,QAAQ;IAC7C,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,QAAQ;IAC7C,CAAC,cAAc,CAAC,sBAAsB,CAAC,EAAE,cAAc,CAAC,QAAQ;IAChE,CAAC,cAAc,CAAC,uBAAuB,CAAC,EAAE,cAAc,CAAC,QAAQ;IACjE,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC,QAAQ;IACxD,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC,QAAQ;IACxD,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC,QAAQ;IAExD,iEAAiE;IACjE,kEAAkE;IAClE,CAAC,aAAa,CAAC,kBAAkB,CAAC,EAAE,cAAc,CAAC,QAAQ;IAC3D,CAAC,aAAa,CAAC,uBAAuB,CAAC,EAAE,cAAc,CAAC,QAAQ;IAChE,sEAAsE;IACtE,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC,OAAO;IAEtD,iEAAiE;IACjE,kDAAkD;IAClD,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC,cAAc;IAC7D,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,cAAc,CAAC,cAAc;IAC9D,CAAC,aAAa,CAAC,qBAAqB,CAAC,EAAE,cAAc,CAAC,cAAc;IACpE,CAAC,aAAa,CAAC,gCAAgC,CAAC,EAC9C,cAAc,CAAC,cAAc;IAC/B,CAAC,aAAa,CAAC,uBAAuB,CAAC,EAAE,cAAc,CAAC,cAAc;IACtE,CAAC,aAAa,CAAC,sBAAsB,CAAC,EAAE,cAAc,CAAC,cAAc;IACrE,CAAC,aAAa,CAAC,4BAA4B,CAAC,EAC1C,cAAc,CAAC,cAAc;IAC/B,CAAC,aAAa,CAAC,wCAAwC,CAAC,EACtD,cAAc,CAAC,cAAc;IAC/B,CAAC,aAAa,CAAC,0BAA0B,CAAC,EACxC,cAAc,CAAC,cAAc;IAC/B,CAAC,aAAa,CAAC,+BAA+B,CAAC,EAC7C,cAAc,CAAC,cAAc;CAChC,CAAC;AAEF,oDAAoD;AAEpD,MAAM,UAAU,GAAwB;IACtC;QACE,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QAC9D,MAAM,EAAE,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG;QACxC,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,SAAS,CAAC;QACxE,MAAM,EAAE,eAAe;KACxB;IACD;QACE,+DAA+D;QAC/D,kEAAkE;QAClE,gEAAgE;QAChE,gEAAgE;QAChE,mEAAmE;QACnE,4DAA4D;QAC5D,gEAAgE;QAChE,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QAC9D,MAAM,EAAE,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG;QACzC,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,SAAS,CAAC;QACxE,MAAM,EAAE,eAAe;KACxB;IACD;QACE,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QAC9D,MAAM,EAAE,cAAc,CAAC,cAAc,EAAE,GAAG,EAAE,IAAI;QAChD,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,SAAS,CAAC;QACxE,MAAM,EAAE,eAAe;KACxB;IACD;QACE,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QAC5D,MAAM,EAAE,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG;QACxC,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,aAAa;KAC5D;IACD;QACE,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QAC5D,MAAM,EAAE,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG;QACzC,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,aAAa;KAC5D;IACD;QACE,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QAC5D,MAAM,EAAE,cAAc,CAAC,cAAc,EAAE,GAAG,EAAE,IAAI;QAChD,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,aAAa;KAC5D;IACD,+DAA+D;IAC/D,qEAAqE;IACrE,+DAA+D;IAC/D;QACE,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QAC/D,MAAM,EAAE,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG;QACxC,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,SAAS,CAAC;QACxE,MAAM,EAAE,gBAAgB;KACzB;IACD;QACE,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QAC/D,MAAM,EAAE,cAAc,CAAC,cAAc,EAAE,GAAG,EAAE,IAAI;QAChD,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,SAAS,CAAC;QACxE,MAAM,EAAE,gBAAgB;KACzB;IACD,mEAAmE;IACnE,oDAAoD;IAEpD,0BAA0B;IAC1B;QACE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO;QAC5C,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG;QAC7D,GAAG,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,gBAAgB;KACzE;IACD;QACE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO;QAC5C,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG;QAC7D,GAAG,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,gBAAgB;KACzE;IACD;QACE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,KAAK;QAC1C,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG;QAC7D,GAAG,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,cAAc;KACvE;IACD;QACE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,KAAK;QAC1C,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG;QAC7D,GAAG,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,cAAc;KACvE;IACD;QACE,oEAAoE;QACpE,mEAAmE;QACnE,8DAA8D;QAC9D,kEAAkE;QAClE,0DAA0D;QAC1D,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,QAAQ;QAC7C,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG;QAC7D,GAAG,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,YAAY;KACrE;IACD;QACE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,QAAQ;QAC7C,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG;QAC7D,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,YAAY;KACtE;IACD;QACE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,eAAe;QACpD,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG;QAC7D,GAAG,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,WAAW;KACpE;IACD;QACE,4DAA4D;QAC5D,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,eAAe;QACpD,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG;QAC7D,GAAG,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,WAAW;KACpE;CACF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,gBAAgB,GAA8B;IAClD;QACE,6DAA6D;QAC7D,mEAAmE;QACnE,kEAAkE;QAClE,kBAAkB;QAClB,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,WAAW,CAAC,OAAO;QAC3B,MAAM,EAAE,cAAc,CAAC,QAAQ;QAC/B,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC;QACpC,MAAM,EAAE,IAAI,cAAc,CAAC;YACzB,MAAM,EAAE,mBAAmB;YAC3B,SAAS,EAAE,qCAAqC;YAChD,GAAG,EAAE,4CAA4C;kBAC7C,iDAAiD;kBACjD,uDAAuD;kBACvD,qBAAqB;YACzB,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC;SAC9B,CAAC;KACH;IACD;QACE,gEAAgE;QAChE,iEAAiE;QACjE,gEAAgE;QAChE,0CAA0C;QAC1C,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,WAAW,CAAC,KAAK;QACzB,MAAM,EAAE,cAAc,CAAC,QAAQ;QAC/B,aAAa,EAAE,OAAO,CAAC,YAAY,CAAC;QACpC,MAAM,EAAE,IAAI,cAAc,CAAC;YACzB,MAAM,EAAE,WAAW;YACnB,SAAS,EAAE,yBAAyB;YACpC,GAAG,EAAE,0CAA0C;kBAC3C,0CAA0C;YAC9C,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC;SAC9B,CAAC;KACH;CACF,CAAC;AAEF;2DAC2D;AAC3D,MAAM,aAAa,GAA0B;IAC3C,GAAG,YAAY;IACf,GAAG,iBAAiB;IACpB,GAAG,gBAAgB;CACpB,CAAC;AAEF;;;;;GAKG;AACH,SAAS,eAAe,CAAC,MAAmB;IAC1C,OAAO,aAAa,CAAC,MAAM,CACzB,CAAC,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,MAAM,CAC5C,CAAC;AACJ,CAAC;AAED,MAAM,MAAM,GAAwB,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC3D,GAAG,GAAG;IACN,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC;CACpC,CAAC,CAAC,CAAC;AAEJ,MAAM,WAAW,GACf,gBAAgB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC7B,GAAG,GAAG;IACN,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC;CACpC,CAAC,CAAC,CAAC;AAEN;4CAC4C;AAC5C,SAAS,cAAc,CACrB,MAAc,EACd,MAAmB;IAEnB,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC;SACzD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CACvB,MAAc,EACd,KAAiB;IAEjB,OAAO,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,MAAc,EACd,KAAiB;IAEjB,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,WAAW,GAAG,WAAW,CAAC,MAAM,CACpC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAClD,CAAC;IACF,OAAO,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAa,EAAE,MAAc;IACpD,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,IAAI,CAC3D,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CACvB,CAAC;IACF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
package/dist/bands.d.ts CHANGED
@@ -4,30 +4,52 @@
4
4
  * tiers.
5
5
  *
6
6
  * Presentation copy (labels, slugs, role descriptions)
7
- * is a hub-site concern and lives there, not in this
7
+ * is a consumer's concern and lives there, not in this
8
8
  * domain library.
9
9
  */
10
- import type { TaxYear, Nation } from '@casomoltd/paye-calc';
10
+ import type { PayYear, Nation } from '@casomoltd/paye-calc';
11
11
  import type { AfcBandId, HcasZones } from './scales.js';
12
12
  import type { ScalePoint } from './scale-point.js';
13
+ import type { DocumentSource } from './document-source.js';
13
14
  import type { SalaryRange } from './values.js';
14
15
  export interface AfcBandMeta {
15
16
  band: AfcBandId;
16
17
  points: ScalePoint[];
17
18
  salary: SalaryRange;
19
+ /** The document that publishes these figures for this nation and
20
+ * year — the same value across a nation's bands, because one
21
+ * circular publishes the whole ladder. Carried per band anyway so a
22
+ * consumer reads a scale's source the same way whichever family it
23
+ * is rendering; medical and dental genuinely differ per grade. */
24
+ source: DocumentSource;
18
25
  }
19
26
  export interface AfcScaleData {
20
27
  bands: AfcBandMeta[];
21
28
  hcas: HcasZones;
22
29
  }
23
- /** Current financial year for band pages. */
24
- export declare const AFC_CURRENT_YEAR: "2026-27";
25
- /** Previous financial year for comparison. */
26
- export declare const AFC_PREVIOUS_YEAR: "2025-26";
30
+ /**
31
+ * The AfC PAY year England, Scotland and Wales are currently on.
32
+ *
33
+ * Typed as a `PayYear`, not left as a bare literal. An unbranded
34
+ * literal assigns to `TaxYear` and `PayYear` alike, so every consumer
35
+ * passing this into a tax-year parameter compiled silently — and
36
+ * several did, reading pension tiers and tax bands at a pay year.
37
+ * Annotating it turns that whole class into compile errors.
38
+ *
39
+ * NOT a site-wide "current year": Northern Ireland is a round behind.
40
+ * A consumer resolving figures for a reader's nation wants
41
+ * `latestAfcYear(nation)`; a consumer applying deductions wants
42
+ * `CURRENT_TAX_YEAR` from paye-calc.
43
+ */
44
+ export declare const AFC_CURRENT_YEAR: PayYear;
45
+ /** The previous AfC pay year, for a year-on-year comparison. */
46
+ export declare const AFC_PREVIOUS_YEAR: PayYear;
27
47
  /** Load AFC scale data — synchronous, no file I/O.
28
- * Scotland has its own scale tables; Wales applies a living wage
29
- * floor to the England/NI base. `year` and `nation` are both
30
- * required — the accessor never defaults a locale, since a
31
- * forgotten `nation` would silently return England figures for
32
- * every region (the exact bug this signature prevents). */
33
- export declare function getAfcScales(year: TaxYear, nation: Nation): AfcScaleData;
48
+ * Scotland and Wales each publish their own ladder; Northern
49
+ * Ireland adopts England's. Every figure is transcribed from the
50
+ * nation's own instrument, so no nation's scale is computed from
51
+ * another's. `year` and `nation` are both required — the accessor
52
+ * never defaults a locale, since a forgotten `nation` would
53
+ * silently return England figures for every region (the exact bug
54
+ * this signature prevents). */
55
+ export declare function getAfcScales(year: PayYear, nation: Nation): AfcScaleData;
package/dist/bands.js CHANGED
@@ -4,23 +4,39 @@
4
4
  * tiers.
5
5
  *
6
6
  * Presentation copy (labels, slugs, role descriptions)
7
- * is a hub-site concern and lives there, not in this
7
+ * is a consumer's concern and lives there, not in this
8
8
  * domain library.
9
9
  */
10
10
  import { TAX_YEARS } from '@casomoltd/paye-calc';
11
- import { AFC_BAND_IDS, getScalesForYear, } from './scales.js';
12
- /** Current financial year for band pages. */
11
+ import { AFC_BAND_IDS, afcScaleSource, getScalesForYear, } from './scales.js';
12
+ /**
13
+ * The AfC PAY year England, Scotland and Wales are currently on.
14
+ *
15
+ * Typed as a `PayYear`, not left as a bare literal. An unbranded
16
+ * literal assigns to `TaxYear` and `PayYear` alike, so every consumer
17
+ * passing this into a tax-year parameter compiled silently — and
18
+ * several did, reading pension tiers and tax bands at a pay year.
19
+ * Annotating it turns that whole class into compile errors.
20
+ *
21
+ * NOT a site-wide "current year": Northern Ireland is a round behind.
22
+ * A consumer resolving figures for a reader's nation wants
23
+ * `latestAfcYear(nation)`; a consumer applying deductions wants
24
+ * `CURRENT_TAX_YEAR` from paye-calc.
25
+ */
13
26
  export const AFC_CURRENT_YEAR = TAX_YEARS.Y2026_27;
14
- /** Previous financial year for comparison. */
27
+ /** The previous AfC pay year, for a year-on-year comparison. */
15
28
  export const AFC_PREVIOUS_YEAR = TAX_YEARS.Y2025_26;
16
29
  /** Load AFC scale data — synchronous, no file I/O.
17
- * Scotland has its own scale tables; Wales applies a living wage
18
- * floor to the England/NI base. `year` and `nation` are both
19
- * required — the accessor never defaults a locale, since a
20
- * forgotten `nation` would silently return England figures for
21
- * every region (the exact bug this signature prevents). */
30
+ * Scotland and Wales each publish their own ladder; Northern
31
+ * Ireland adopts England's. Every figure is transcribed from the
32
+ * nation's own instrument, so no nation's scale is computed from
33
+ * another's. `year` and `nation` are both required — the accessor
34
+ * never defaults a locale, since a forgotten `nation` would
35
+ * silently return England figures for every region (the exact bug
36
+ * this signature prevents). */
22
37
  export function getAfcScales(year, nation) {
23
38
  const scaleYear = getScalesForYear(year, nation);
39
+ const source = afcScaleSource(year, nation);
24
40
  const bands = AFC_BAND_IDS.map((band) => {
25
41
  const points = scaleYear.scales[band];
26
42
  const salaries = points.map((p) => p.salary);
@@ -31,6 +47,7 @@ export function getAfcScales(year, nation) {
31
47
  min: Math.min(...salaries),
32
48
  max: Math.max(...salaries),
33
49
  },
50
+ source,
34
51
  };
35
52
  });
36
53
  return {
package/dist/bands.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"bands.js","sourceRoot":"","sources":["../src/bands.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAC,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAM/C,OAAO,EACL,YAAY,EACZ,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAoBrB,6CAA6C;AAC7C,MAAM,CAAC,MAAM,gBAAgB,GAAG,SAAS,CAAC,QAAQ,CAAC;AAEnD,8CAA8C;AAC9C,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC,QAAQ,CAAC;AAEpD;;;;;4DAK4D;AAC5D,MAAM,UAAU,YAAY,CAC1B,IAAa,EACb,MAAc;IAEd,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAEjD,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACtC,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CACzB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAChB,CAAC;QACF,OAAO;YACL,IAAI;YACJ,MAAM;YACN,MAAM,EAAE;gBACN,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;gBAC1B,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;aAC3B;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK;QACL,IAAI,EAAE,SAAS,CAAC,IAAI;KACrB,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"bands.js","sourceRoot":"","sources":["../src/bands.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAC,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAM/C,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,aAAa,CAAC;AA2BrB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAY,SAAS,CAAC,QAAQ,CAAC;AAE5D,gEAAgE;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAY,SAAS,CAAC,QAAQ,CAAC;AAE7D;;;;;;;gCAOgC;AAChC,MAAM,UAAU,YAAY,CAC1B,IAAa,EACb,MAAc;IAEd,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAE5C,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACtC,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CACzB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAChB,CAAC;QACF,OAAO;YACL,IAAI;YACJ,MAAM;YACN,MAAM,EAAE;gBACN,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;gBAC1B,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;aAC3B;YACD,MAAM;SACP,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK;QACL,IAAI,EAAE,SAAS,CAAC,IAAI;KACrB,CAAC;AACJ,CAAC"}