@casomoltd/nhs-pay 0.15.2 → 0.16.1

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
@@ -0,0 +1,180 @@
1
+ /**
2
+ * AfC cash allowances — the per-session payments that sit beside the
3
+ * pay scales and are uplifted by the same award.
4
+ *
5
+ * Separate from {@link getAfcScales} because an allowance is not a
6
+ * scale point: it is not annual, not banded, and not pensionable pay
7
+ * in the way a salary is, so folding it into a scale year would put
8
+ * two different kinds of money behind one lookup.
9
+ *
10
+ * Recorded as cited constants for the same reason awards are — the
11
+ * publisher states the cash figure, and the uplifted rate is rounded
12
+ * by the publisher rather than by us. Scotland's 2026-27 rate is
13
+ * £27.51, where 26.51 × 1.0375 is £27.504.
14
+ *
15
+ * Coverage is deliberately partial, and absence means UNTRANSCRIBED,
16
+ * not unpaid. England's medical & dental circular sets an on-call
17
+ * availability allowance of its own — annual by nodal point, not per
18
+ * session — transcribed verbatim in `src/circulars/` and outside this
19
+ * lookup entirely, so a missing row here does not mean no such
20
+ * allowance is paid in that nation. Scotland has no sleep-in row
21
+ * for the same reason: its circular uplifts the on-call
22
+ * availability allowance and is silent on them, where Wales's
23
+ * prints a sleeping-in rate.
24
+ *
25
+ * Northern Ireland's two rates ARE transcribed — HSC (AfC) 06/2025
26
+ * Section 2 prints a sleep-in and an on-call rate, and
27
+ * `ni-hsc-afc-06-2025.ts` carries both — but they are not surfaced
28
+ * here, so `afcSessionAllowances(year, 'northern-ireland')` returns
29
+ * empty. That is a gap in this module, not in the transcription.
30
+ */
31
+ import { payYear } from '@casomoltd/paye-calc';
32
+ import { isoDate } from './iso-date.js';
33
+ import { NATION_KEYS, TAX_YEARS } from '@casomoltd/paye-calc';
34
+ import { AFC_SCOTLAND, AFC_W_02_2025, AFC_W_02_2026, } from './sources.js';
35
+ /**
36
+ * Identifiers for the per-session allowances transcribed here.
37
+ *
38
+ * Prefixed by nation because these are NOT the same payment under
39
+ * different names: Scotland's on-call availability allowance and
40
+ * Wales's three rates are set by different instruments, on
41
+ * different footings, and an unprefixed `onCall` would let one be
42
+ * passed where the other is meant and still compile.
43
+ */
44
+ export const SESSION_ALLOWANCES = {
45
+ scotlandOnCallAvailability: 'scotland-on-call-availability',
46
+ walesSleepingIn: 'wales-sleeping-in',
47
+ walesOnCallWeekday: 'wales-on-call-weekday-weekend',
48
+ walesOnCallPublicHoliday: 'wales-on-call-public-holiday',
49
+ };
50
+ /**
51
+ * The nation whose instrument sets each allowance. Derived from the
52
+ * id rather than written beside it: the two are not independent
53
+ * facts, and a row free to say `walesSleepingIn` for Scotland is a
54
+ * disagreement waiting to be written.
55
+ */
56
+ const ALLOWANCE_NATION = {
57
+ [SESSION_ALLOWANCES.scotlandOnCallAvailability]: NATION_KEYS.scotland,
58
+ [SESSION_ALLOWANCES.walesSleepingIn]: NATION_KEYS.wales,
59
+ [SESSION_ALLOWANCES.walesOnCallWeekday]: NATION_KEYS.wales,
60
+ [SESSION_ALLOWANCES.walesOnCallPublicHoliday]: NATION_KEYS.wales,
61
+ };
62
+ // ── Per-session allowance rates ──────────────────
63
+ //
64
+ // Scotland pays a flat rate per on-call session, uplifted with the
65
+ // AfC award under PCS(AFC)2015/3 para 7.2. Both rates below come from
66
+ // the 2026 circular: it revised the 2025-26 rate from £26.47 to
67
+ // £26.51 when the inflation guarantee lifted that year's award to
68
+ // 4.4%, and set the 2026-27 rate in the same document.
69
+ // Source: "Scotland, PCS(AFC)2026/1" (#sa-13).
70
+ const RATES = [
71
+ // Scotland, PCS(AFC)2026/1 (#sa-13). The 2026 circular revised
72
+ // the 2025-26 rate from £26.47 to £26.51 when the inflation
73
+ // guarantee lifted that year's award to 4.4%, and set the
74
+ // 2026-27 rate in the same document.
75
+ {
76
+ id: SESSION_ALLOWANCES.scotlandOnCallAvailability,
77
+ label: 'On-call availability allowance',
78
+ year: payYear(TAX_YEARS.Y2025_26),
79
+ perSession: 26.51,
80
+ effectiveFrom: isoDate('2025-04-01'),
81
+ source: AFC_SCOTLAND,
82
+ },
83
+ {
84
+ id: SESSION_ALLOWANCES.scotlandOnCallAvailability,
85
+ label: 'On-call availability allowance',
86
+ year: payYear(TAX_YEARS.Y2026_27),
87
+ perSession: 27.51,
88
+ effectiveFrom: isoDate('2026-04-01'),
89
+ source: AFC_SCOTLAND,
90
+ },
91
+ // Wales, AfC(W) 02/2025 and 02/2026, the allowance table on the
92
+ // last page of each. Transcribed, not derived: 02/2026 uplifts
93
+ // by 3.3%, but 25.21 x 1.033 is 26.042 where it prints £26.05,
94
+ // so computing the weekday rate lands a penny out.
95
+ {
96
+ id: SESSION_ALLOWANCES.walesSleepingIn,
97
+ label: 'Sleeping in',
98
+ year: payYear(TAX_YEARS.Y2025_26),
99
+ perSession: 43.38,
100
+ effectiveFrom: isoDate('2025-04-01'),
101
+ source: AFC_W_02_2025,
102
+ },
103
+ {
104
+ id: SESSION_ALLOWANCES.walesOnCallWeekday,
105
+ label: 'On call, weekday or weekend',
106
+ year: payYear(TAX_YEARS.Y2025_26),
107
+ perSession: 25.21,
108
+ effectiveFrom: isoDate('2025-04-01'),
109
+ source: AFC_W_02_2025,
110
+ },
111
+ {
112
+ id: SESSION_ALLOWANCES.walesOnCallPublicHoliday,
113
+ label: 'On call, public holiday',
114
+ year: payYear(TAX_YEARS.Y2025_26),
115
+ perSession: 50.41,
116
+ effectiveFrom: isoDate('2025-04-01'),
117
+ source: AFC_W_02_2025,
118
+ },
119
+ {
120
+ id: SESSION_ALLOWANCES.walesSleepingIn,
121
+ label: 'Sleeping in',
122
+ year: payYear(TAX_YEARS.Y2026_27),
123
+ perSession: 44.82,
124
+ effectiveFrom: isoDate('2026-04-01'),
125
+ source: AFC_W_02_2026,
126
+ },
127
+ {
128
+ id: SESSION_ALLOWANCES.walesOnCallWeekday,
129
+ label: 'On call, weekday or weekend',
130
+ year: payYear(TAX_YEARS.Y2026_27),
131
+ perSession: 26.05,
132
+ effectiveFrom: isoDate('2026-04-01'),
133
+ source: AFC_W_02_2026,
134
+ },
135
+ {
136
+ id: SESSION_ALLOWANCES.walesOnCallPublicHoliday,
137
+ label: 'On call, public holiday',
138
+ year: payYear(TAX_YEARS.Y2026_27),
139
+ perSession: 52.08,
140
+ effectiveFrom: isoDate('2026-04-01'),
141
+ source: AFC_W_02_2026,
142
+ },
143
+ ];
144
+ function withNation(rate) {
145
+ return { ...rate, nation: ALLOWANCE_NATION[rate.id] };
146
+ }
147
+ /**
148
+ * Every per-session allowance transcribed for a nation and year,
149
+ * in the order its instrument prints them. Empty where none has
150
+ * been transcribed — see this module's header on what absence
151
+ * means.
152
+ */
153
+ export function afcSessionAllowances(year, nation) {
154
+ return RATES
155
+ .filter((r) => r.year === year
156
+ && ALLOWANCE_NATION[r.id] === nation)
157
+ .map(withNation);
158
+ }
159
+ /**
160
+ * One named allowance for a tax year, or `undefined` where that
161
+ * year has none transcribed.
162
+ *
163
+ * Keyed by allowance id, not by (nation, year): each id belongs to
164
+ * exactly one nation's instrument, so the nation is implied. A
165
+ * `(year, nation)` signature would take an argument it could not
166
+ * honour — asked for Wales it could only ever answer for whichever
167
+ * single allowance the function had been written around, and
168
+ * return `undefined` for the rest as though none were published.
169
+ *
170
+ * Undefined rather than a throw: unlike the AfC award, which every
171
+ * nation settles every year, most (allowance, year) pairs have no
172
+ * transcription and absence is the normal answer rather than an
173
+ * error. Callers branch on it; routing that through an exception
174
+ * would be an `if` written as a throw.
175
+ */
176
+ export function sessionAllowance(id, year) {
177
+ const rate = RATES.find((r) => r.id === id && r.year === year);
178
+ return rate && withNation(rate);
179
+ }
180
+ //# sourceMappingURL=allowances.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"allowances.js","sourceRoot":"","sources":["../src/allowances.ts"],"names":[],"mappings":"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"}
package/dist/award.d.ts CHANGED
@@ -1,37 +1,176 @@
1
1
  /**
2
- * Agenda for Change headline pay awards (consolidated % uplift) by
3
- * nation and year.
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.
12
- *
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.
29
- */
30
- import type { Nation, TaxYear } from '@casomoltd/paye-calc';
31
- /**
32
- * The AfC headline pay award for a nation and year, as a percentage
33
- * (e.g. `3.75` for 3.75%). Throws {@link AwardUnavailable} for an
34
- * unrecorded combination rather than defaulting — the caller must
35
- * name the nation (no silent fallback).
36
- */
37
- export declare function afcAward(year: TaxYear, nation: Nation): number;
2
+ * NHS headline pay awards by nation, year and staff family, for both
3
+ * pay frameworks: Agenda for Change, and medical & dental.
4
+ *
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.
13
+ *
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.
38
+ */
39
+ import type { Nation, PayYear } from '@casomoltd/paye-calc';
40
+ import type { IsoDate, IsoMonth } from './iso-date.js';
41
+ import { DocumentSource } from './document-source.js';
42
+ import type { AfcBandId } from './scales.js';
43
+ import type { MedicalGradeId } from './medical-scales.js';
44
+ import type { DentalGradeId } from './dental-scales.js';
45
+ /**
46
+ * Every identifier that names a pay scale, across both frameworks —
47
+ * 11 AfC bands, 22 medical grades, 13 dental. The three sets are
48
+ * disjoint, so the union is safe to key a total Record by.
49
+ */
50
+ export type PayScaleId = AfcBandId | MedicalGradeId | DentalGradeId;
51
+ /**
52
+ * The staff groups an award is announced for. These are the AWARD's
53
+ * own groupings, coarser than a reader-facing role: one figure covers
54
+ * consultants, SAS and salaried GPs alike.
55
+ *
56
+ * The VALUES are prefixed because the bare words collide with three
57
+ * other identifier unions — `resident` and `salaried-dental` are grade
58
+ * ids, and `medical` is a `RoleKind`. Without the prefix a grade id
59
+ * would compile where a family is required and return a plausible but
60
+ * wrong answer. The keys are unprefixed, so call sites read normally.
61
+ */
62
+ export declare const AWARD_FAMILIES: {
63
+ /** Every AfC band. One award covers all of them, which is a family
64
+ * of one group — not the absence of a family. */
65
+ readonly afc: "award-afc";
66
+ /** Consultants, SAS doctors & dentists, and salaried GPs. */
67
+ readonly medical: "award-medical";
68
+ /** Doctors & dentists in training. */
69
+ readonly resident: "award-resident";
70
+ /** Salaried dentists in community & public dental services. */
71
+ readonly salariedDental: "award-salaried-dental";
72
+ };
73
+ export type AwardFamily = (typeof AWARD_FAMILIES)[keyof typeof AWARD_FAMILIES];
74
+ /** One nation's settled award, for one family in one year. */
75
+ export interface PayAward {
76
+ readonly kind: 'settled';
77
+ readonly nation: Nation;
78
+ readonly year: PayYear;
79
+ readonly family: AwardFamily;
80
+ /**
81
+ * Headline consolidated uplift — `3.5` means 3.5%.
82
+ *
83
+ * The AWARD, which is not always the whole movement in the scales. A
84
+ * round can carry a restructure alongside its percentage: England's
85
+ * 2026-27 resident scale moved by more than this figure, because
86
+ * PC(M&D) 1/2026 R2 applied the award and re-cut the nodal points in
87
+ * the same circular. Rendering this as "the pay rise" understates
88
+ * such a round; compare the published scales where that matters.
89
+ */
90
+ readonly pct: number;
91
+ /**
92
+ * The date the award takes effect, which pay is backdated to. Held
93
+ * per row rather than derived from the tax year: an award need not
94
+ * start on 6 April, and a new contract within a round can start
95
+ * mid-year.
96
+ */
97
+ readonly effectiveFrom: IsoDate;
98
+ /**
99
+ * The month (`YYYY-MM`) the announcement expected the money to reach
100
+ * salaries, where it said so. An expectation the source published,
101
+ * not a guarantee and not a payroll date.
102
+ *
103
+ * MONTH precision, and typed as such: a consumer that needs a Date
104
+ * from it must go through `firstOfMonth`, not splice a day on.
105
+ */
106
+ readonly expectedInPay?: IsoMonth;
107
+ readonly source: DocumentSource;
108
+ /** The scales this award reaches. Derived from {@link AWARD_COVERAGE}
109
+ * at load, never authored, so the two cannot disagree. */
110
+ readonly covers: readonly PayScaleId[];
111
+ }
112
+ /**
113
+ * An agreed change to pay that CANNOT yet be stated as a percentage
114
+ * against a published scale — a sibling of {@link PayAward}, not a
115
+ * state of one. Everything in the award table is already accepted;
116
+ * what differs here is that no headline figure applies.
117
+ *
118
+ * It carries NO `pct`, and that absence is the design: a consumer
119
+ * cannot render a figure that does not exist, because there is nowhere
120
+ * to read one from. Anything quantitative stays prose beside the cited
121
+ * instrument until a circular makes it an award.
122
+ */
123
+ export interface ForthcomingChange {
124
+ readonly kind: 'forthcoming';
125
+ readonly nation: Nation;
126
+ readonly family: AwardFamily;
127
+ /** When the change starts. Where it is staged, this is the earliest
128
+ * phase NOT yet reflected in the published scales — England's row
129
+ * moved to April 2027 once R2 put the April 2026 phase in the
130
+ * circular, because a forthcoming record describes what has not
131
+ * landed. */
132
+ readonly effectiveFrom: IsoDate;
133
+ readonly source: DocumentSource;
134
+ readonly covers: readonly PayScaleId[];
135
+ }
136
+ /**
137
+ * What the library knows about a scale's pay movement. A caller must
138
+ * narrow on `kind` before rendering, which is the point: quoting a
139
+ * percentage that only a settled award carries becomes a compile error
140
+ * rather than a review catch.
141
+ */
142
+ export type PayChange = PayAward | ForthcomingChange;
143
+ /**
144
+ * Every award recorded for a pay scale in a nation, newest year first
145
+ * — the "which awards affect this role?" direction, and the same
146
+ * question whichever framework the scale belongs to. Empty where none
147
+ * has been announced; absence is a normal state, not an error, because
148
+ * a partly-settled round is the usual mid-year position.
149
+ *
150
+ * A list rather than a single award, because the question is about a
151
+ * history, not just this year's figure.
152
+ */
153
+ export declare function awardsFor(nation: Nation, scale: PayScaleId): readonly PayAward[];
154
+ /**
155
+ * Everything the library knows about a scale's pay movement in a
156
+ * nation. Settled awards first, newest year first, then any
157
+ * forthcoming changes — NOT one merged chronology, because the two
158
+ * arms are not comparable: a settled award is dated by the year it
159
+ * belongs to, a forthcoming change only by when it starts.
160
+ *
161
+ * Callers narrow on `kind`; those that only ever quote a percentage
162
+ * should use {@link awardsFor} and never see the other arm.
163
+ */
164
+ export declare function changesFor(nation: Nation, scale: PayScaleId): readonly PayChange[];
165
+ /**
166
+ * The AfC award for a nation and year. Throws {@link AwardUnavailable}
167
+ * rather than returning undefined — unlike the medical & dental
168
+ * families, every nation settles an AfC award every year, so a missing
169
+ * one is a real error and not the normal mid-year state.
170
+ *
171
+ * A convenience over the same table {@link awardsFor} reads: the AfC
172
+ * headline needs no band, because one award covers every band, and
173
+ * that fact is stated in AWARD_COVERAGE rather than implied by this
174
+ * signature taking no band.
175
+ */
176
+ export declare function afcAward(year: PayYear, nation: Nation): PayAward;