@casomoltd/nhs-pay 0.32.0 → 0.34.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 (125) hide show
  1. package/README.md +24 -22
  2. package/dist/afc-band.d.ts +4 -4
  3. package/dist/afc-band.js +4 -4
  4. package/dist/afc-scales.d.ts +89 -60
  5. package/dist/afc-scales.js +166 -182
  6. package/dist/afc-scales.js.map +1 -1
  7. package/dist/allowances.js +11 -11
  8. package/dist/allowances.js.map +1 -1
  9. package/dist/award.d.ts +3 -3
  10. package/dist/award.js +21 -21
  11. package/dist/award.js.map +1 -1
  12. package/dist/circulars/afc-shapes.d.ts +41 -21
  13. package/dist/circulars/afc-shapes.js +9 -8
  14. package/dist/circulars/afc-shapes.js.map +1 -1
  15. package/dist/circulars/england-md-1-2026-r2.d.ts +13 -0
  16. package/dist/circulars/england-md-1-2026-r2.js +13 -0
  17. package/dist/circulars/england-md-1-2026-r2.js.map +1 -1
  18. package/dist/circulars/ni-hsc-afc-06-2025.d.ts +3 -2
  19. package/dist/circulars/ni-hsc-afc-06-2025.js +3 -2
  20. package/dist/circulars/ni-hsc-afc-06-2025.js.map +1 -1
  21. package/dist/circulars/ni-hsc-tc8-05-2025.d.ts +22 -0
  22. package/dist/circulars/ni-hsc-tc8-05-2025.js +22 -0
  23. package/dist/circulars/ni-hsc-tc8-05-2025.js.map +1 -1
  24. package/dist/circulars/scotland-pcs-dd-2025-01.d.ts +20 -0
  25. package/dist/circulars/scotland-pcs-dd-2025-01.js +20 -0
  26. package/dist/circulars/scotland-pcs-dd-2025-01.js.map +1 -1
  27. package/dist/circulars/scotland-pcs-dd-2026-01.d.ts +19 -0
  28. package/dist/circulars/scotland-pcs-dd-2026-01.js +30 -10
  29. package/dist/circulars/scotland-pcs-dd-2026-01.js.map +1 -1
  30. package/dist/circulars/scotland-pcs-dd-2026-02.d.ts +10 -0
  31. package/dist/circulars/scotland-pcs-dd-2026-02.js +10 -0
  32. package/dist/circulars/scotland-pcs-dd-2026-02.js.map +1 -1
  33. package/dist/circulars/wales-mdw-01-2025.d.ts +17 -0
  34. package/dist/circulars/wales-mdw-01-2025.js +17 -0
  35. package/dist/circulars/wales-mdw-01-2025.js.map +1 -1
  36. package/dist/circulars/wales-mdw-01-2026.d.ts +20 -0
  37. package/dist/circulars/wales-mdw-01-2026.js +20 -0
  38. package/dist/circulars/wales-mdw-01-2026.js.map +1 -1
  39. package/dist/commutation.js +3 -2
  40. package/dist/commutation.js.map +1 -1
  41. package/dist/dental-grades.d.ts +25 -0
  42. package/dist/dental-grades.js +25 -0
  43. package/dist/dental-grades.js.map +1 -0
  44. package/dist/dental-scales.d.ts +5 -21
  45. package/dist/dental-scales.js +73 -72
  46. package/dist/dental-scales.js.map +1 -1
  47. package/dist/format.js +3 -2
  48. package/dist/format.js.map +1 -1
  49. package/dist/hcas-pcts.d.ts +1 -1
  50. package/dist/hcas-pcts.js +1 -1
  51. package/dist/hcas-pcts.js.map +1 -1
  52. package/dist/hcas-zone.d.ts +23 -0
  53. package/dist/hcas-zone.js +17 -0
  54. package/dist/hcas-zone.js.map +1 -0
  55. package/dist/hcas.d.ts +26 -18
  56. package/dist/hcas.js +45 -24
  57. package/dist/hcas.js.map +1 -1
  58. package/dist/index.d.ts +25 -16
  59. package/dist/index.js +14 -10
  60. package/dist/index.js.map +1 -1
  61. package/dist/medical-grades.d.ts +33 -0
  62. package/dist/medical-grades.js +33 -0
  63. package/dist/medical-grades.js.map +1 -0
  64. package/dist/medical-scales.d.ts +10 -33
  65. package/dist/medical-scales.js +104 -158
  66. package/dist/medical-scales.js.map +1 -1
  67. package/dist/member/input-period.d.ts +18 -5
  68. package/dist/member/input-period.js +24 -13
  69. package/dist/member/input-period.js.map +1 -1
  70. package/dist/pay-round.js +3 -3
  71. package/dist/pay-round.js.map +1 -1
  72. package/dist/pay-year.d.ts +17 -0
  73. package/dist/pay-year.js +20 -0
  74. package/dist/pay-year.js.map +1 -0
  75. package/dist/pension/ledger.d.ts +7 -0
  76. package/dist/pension/ledger.js +18 -11
  77. package/dist/pension/ledger.js.map +1 -1
  78. package/dist/pension.js +2 -1
  79. package/dist/pension.js.map +1 -1
  80. package/dist/post.d.ts +20 -21
  81. package/dist/post.js +54 -53
  82. package/dist/post.js.map +1 -1
  83. package/dist/published/england-afc.d.ts +72 -0
  84. package/dist/published/england-afc.js +86 -0
  85. package/dist/published/england-afc.js.map +1 -0
  86. package/dist/published/hcas-zones.d.ts +18 -0
  87. package/dist/published/hcas-zones.js +46 -0
  88. package/dist/published/hcas-zones.js.map +1 -0
  89. package/dist/published/wales-living-wage.d.ts +36 -0
  90. package/dist/published/wales-living-wage.js +30 -0
  91. package/dist/published/wales-living-wage.js.map +1 -0
  92. package/dist/regions.d.ts +25 -14
  93. package/dist/regions.js +61 -71
  94. package/dist/regions.js.map +1 -1
  95. package/dist/resolver.d.ts +46 -41
  96. package/dist/resolver.js +70 -142
  97. package/dist/resolver.js.map +1 -1
  98. package/dist/role.d.ts +3 -3
  99. package/dist/scale-point.d.ts +11 -7
  100. package/dist/scale-point.js +29 -1
  101. package/dist/scale-point.js.map +1 -1
  102. package/dist/scale-tables.d.ts +42 -60
  103. package/dist/scale-tables.js +65 -105
  104. package/dist/scale-tables.js.map +1 -1
  105. package/dist/scale-translators.d.ts +90 -0
  106. package/dist/scale-translators.js +97 -0
  107. package/dist/scale-translators.js.map +1 -0
  108. package/dist/scales.d.ts +164 -102
  109. package/dist/scales.js +242 -462
  110. package/dist/scales.js.map +1 -1
  111. package/dist/sources.d.ts +8 -12
  112. package/dist/sources.js +9 -15
  113. package/dist/sources.js.map +1 -1
  114. package/dist/take-home.js +1 -2
  115. package/dist/take-home.js.map +1 -1
  116. package/dist/values.d.ts +10 -3
  117. package/dist/values.js +11 -4
  118. package/dist/values.js.map +1 -1
  119. package/dist/working-week.d.ts +23 -8
  120. package/dist/working-week.js +55 -25
  121. package/dist/working-week.js.map +1 -1
  122. package/package.json +3 -3
  123. package/dist/bands.d.ts +0 -63
  124. package/dist/bands.js +0 -78
  125. package/dist/bands.js.map +0 -1
package/dist/scales.d.ts CHANGED
@@ -1,101 +1,144 @@
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) and translated by `afc-scales.ts` like the
18
+ * others. The HCAS zones and the Welsh living-wage floor sit beside it
19
+ * in `src/published/`, each citing its own
20
+ * source. The other three nations' sources are cited in their own
21
+ * circular files, beside the data they justify — including the warning
22
+ * that Scotland's MSG consolidated table prints superseded 4.25% rates and
41
23
  * must not be read instead of the circular.
42
24
  *
43
25
  * POINT LABELS — one convention, all four nations. A point's label is
44
26
  * the year of service in which a member first reaches it: increment 1
45
27
  * is `Year 1`, and the top point takes a `+` because service continues
46
28
  * past it. No publisher prints such a label; every one is our reading
47
- * of an interval the publisher does print. For the three circular
48
- * 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
50
- * `afcPoint`, which writes the label and the year from one number, so
29
+ * of an interval the publisher does print. For all four nations the
30
+ * year is derived in `afc-scales.ts`, from the transcribed interval
31
+ * (England, Wales, Northern Ireland) or Annex C's yearly increment
32
+ * (Scotland), through `afcPoint`, which writes the label and the year
33
+ * from one number, so
51
34
  * a label and the timing a pay path reads from it cannot disagree.
52
35
  *
53
36
  * Labels are lookup keys for `afcResolver.fromScalePoint`, so changing
54
37
  * one is an API change, and the fixtures assert them.
38
+ *
39
+ * Pension tiers are a separate read (`getPensionTiers`), since a nation
40
+ * can publish a scale for a year with no tier table.
55
41
  */
56
- import type { Nation, PayYear, YearLabel } from '@casomoltd/paye-calc';
42
+ import type { Nation, PayYear, TaxYear } from '@casomoltd/paye-calc';
57
43
  import type { DocumentSource } from './document-source.js';
58
- import type { SteppedPoint } from './scale-point.js';
44
+ import type { PayLadder, SteppedPoint } from './scale-point.js';
45
+ import type { SalaryRange } from './values.js';
46
+ import type { PrintedBand1 } from './afc-scales.js';
59
47
  import type { AfcBandId } from './afc-band.js';
60
- export { AFC_BANDS, AFC_BAND_IDS } from './afc-band.js';
61
- export type { AfcBandId } from './afc-band.js';
62
- export interface HcasZone {
63
- rate: number;
64
- min: number;
65
- max: number;
48
+ import type { SchemeYearEnd } from './pension/scheme-year.js';
49
+ /** What {@link afcPayYearFor} finds for a scheme year. */
50
+ export declare const AFC_PAY_YEAR_KINDS: {
51
+ /** This library holds the nation's scale for the year. */
52
+ readonly held: "held";
53
+ /** The year is before the earliest scale this library holds for the
54
+ * nation. */
55
+ readonly 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
+ readonly awaited: "awaited";
60
+ };
61
+ /** A scheme year's AfC pay year, or why there is none to read. */
62
+ export type AfcPayYearLookup = {
63
+ readonly kind: typeof AFC_PAY_YEAR_KINDS.held;
64
+ readonly year: PayYear;
65
+ } | {
66
+ readonly kind: typeof AFC_PAY_YEAR_KINDS.notHeld;
67
+ } | {
68
+ readonly kind: typeof AFC_PAY_YEAR_KINDS.awaited;
69
+ };
70
+ /** Band 1 for a nation and pay year: the figure and status its publisher
71
+ * prints, with the year and source it is held under. */
72
+ export interface AfcBand1 extends PrintedBand1 {
73
+ readonly year: PayYear;
74
+ readonly source: DocumentSource;
66
75
  }
67
- export interface HcasZones {
68
- innerLondon: HcasZone;
69
- outerLondon: HcasZone;
70
- fringe: HcasZone;
76
+ /** A band's nation, attached from the key it is stored under rather
77
+ * than stored beside it — one fact, one producer. */
78
+ export interface AfcBand1Published extends AfcBand1 {
79
+ readonly nation: Nation;
71
80
  }
72
- interface AfcScaleYear {
73
- hcas: HcasZones;
74
- scales: Record<AfcBandId, SteppedPoint[]>;
81
+ /** One AfC band's published ladder for a nation and year. */
82
+ export interface AfcBandMeta {
83
+ band: AfcBandId;
84
+ points: SteppedPoint[];
85
+ salary: SalaryRange;
86
+ /** The document that publishes these figures for this nation and
87
+ * year — the same value across a nation's bands, because one
88
+ * circular publishes the whole ladder. Carried per band anyway so a
89
+ * consumer reads a scale's source the same way whichever family it
90
+ * is rendering; medical and dental genuinely differ per grade. */
91
+ source: DocumentSource;
75
92
  }
76
- export declare const NLW_HOURLY: Partial<Record<YearLabel, number>>;
77
93
  /**
78
- * Annualise an hourly rate at given weekly hours.
94
+ * England's latest AfC PAY year.
79
95
  *
80
- * `weeklyHours` is required: the standard week varies by
81
- * nation and year (`afcWeeklyHours`), so defaulting it
82
- * would silently return an rUK answer for a Scottish rate.
83
- * Pass `afcWeeklyHours(year, nation)`.
96
+ * Read from England's scale table, so it moves when a round is
97
+ * transcribed rather than by hand. Typed as a `PayYear`: an unbranded
98
+ * literal assigns to `TaxYear` and `PayYear` alike, and would pass into a
99
+ * tax-year parameter silently.
84
100
  *
85
- * The inverse of dividing by `hoursPerYear`, which it reads, so the two
86
- * agree up to the rounding of the hourly rate and of the result.
101
+ * NOT a site-wide "current year": Northern Ireland is a round behind.
102
+ * A consumer resolving figures for a reader's nation wants
103
+ * `latestAfcYear(nation)`; a consumer applying deductions wants the tax
104
+ * year in force, which it reads from its own clock.
87
105
  */
88
- export declare function annualiseHourly(hourly: number, weeklyHours: number): number;
89
- /** The Welsh living-wage floor for a year, as its pay
90
- * letter states it. */
91
- export interface WalesLivingWage {
92
- /** The floor applied to low spine points. */
93
- readonly annual: number;
94
- /** The Living Wage Foundation rate the floor is set
95
- * against — quotable, never a divisor. */
96
- readonly hourly: number;
97
- }
98
- export declare const WALES_LIVING_WAGE: Partial<Record<YearLabel, WalesLivingWage>>;
106
+ export declare const AFC_CURRENT_YEAR: PayYear;
107
+ /** The previous AfC pay year, for a year-on-year comparison: the one
108
+ * before {@link AFC_CURRENT_YEAR} in England's table. */
109
+ export declare const AFC_PREVIOUS_YEAR: PayYear;
110
+ /** A nation's AfC bands for a year, each with its ladder, salary range
111
+ * and source — synchronous, no file I/O. Every nation's ladder is
112
+ * transcribed from its own instrument, Northern Ireland's included
113
+ * though its figures match England's, so no nation's scale is computed
114
+ * from another's. `year` and `nation` are both required — the accessor
115
+ * never defaults a locale, since a forgotten `nation` would silently
116
+ * return England figures for every region. */
117
+ export declare function getAfcScales(year: PayYear, nation: Nation): AfcBandMeta[];
118
+ /**
119
+ * Band 1 for a nation and pay year. Throws {@link ScaleUnavailable} for a
120
+ * year that nation has not published, as {@link getAfcScales} does, so
121
+ * the two reads of one ladder fail the same way.
122
+ *
123
+ * Deliberately NOT part of `AFC_BANDS` or the scale list. Band 1 joining
124
+ * either shifts every index that reads the list by position, and this
125
+ * needs to shift nothing — it is a lookup beside the ladder, not a rung
126
+ * added to it.
127
+ */
128
+ export declare function afcBand1(year: PayYear, nation: Nation): AfcBand1Published;
129
+ /** One band's published ladder for a pay year and nation. Every band is
130
+ * on every ladder (a nation-year's scales are total over the bands), so
131
+ * only the year and nation can be unpublished, which throws
132
+ * {@link ScaleUnavailable}. */
133
+ export declare function afcBandPoints(year: PayYear, nation: Nation, band: AfcBandId): SteppedPoint[];
134
+ /**
135
+ * The point labelled `label` on an AfC band, with the band's points, for
136
+ * a pay year and nation, read from {@link getAfcScales}. Throws
137
+ * `ScaleUnavailable` where the year and nation publish no scale or the
138
+ * band has no such point, and `AmbiguousScalePoint` where the label names
139
+ * more than one, so a caller never prices a point it did not ask for.
140
+ */
141
+ export declare function afcPointOf(year: PayYear, nation: Nation, band: AfcBandId, label: string): PayLadder;
99
142
  /** The circular or page that publishes a nation's AfC scales for a
100
143
  * year. Throws for a combination that has no published scale, in step
101
144
  * with {@link getScalesForYear} — a scale we cannot cite is a scale we
@@ -114,10 +157,9 @@ export declare function afcPayYears(nation: Nation): PayYear[];
114
157
  /**
115
158
  * The most recent year a nation has actually published AfC scales for.
116
159
  *
117
- * Nations do not move together. Northern Ireland has issued no 2026-27
118
- * pay circular — its 3.3% is announced, unfunded and undated — so its
119
- * latest published year is 2025-26 while the other three are on
120
- * 2026-27. A consumer that asks for a site-wide "current year" gets
160
+ * Nations do not move together: Northern Ireland's latest is a round
161
+ * behind the others (see `NI_TABLES_2025_26` in `afc-scales.ts`). A
162
+ * consumer that asks for a site-wide "current year" gets
121
163
  * `ScaleUnavailable` there, which is correct but is not an answer; this
122
164
  * is the answer.
123
165
  *
@@ -125,9 +167,10 @@ export declare function afcPayYears(nation: Nation): PayYear[];
125
167
  * this library holds. A consumer deriving it would be re-computing,
126
168
  * from the outside, something only these tables know.
127
169
  */
170
+ export declare function latestAfcYear(nation: Nation): PayYear;
128
171
  /**
129
- * How far a nation's newest published pay scales sit from the tax year
130
- * in force. Positive means the pay scales are BEHIND.
172
+ * How many rounds `payYear` sits behind `taxYear`. Positive means the pay
173
+ * round is BEHIND the tax year; negative means it is ahead.
131
174
  *
132
175
  * ## The domain rule this exists to state
133
176
  *
@@ -139,9 +182,9 @@ export declare function afcPayYears(nation: Nation): PayYear[];
139
182
  *
140
183
  * They diverge in exactly one way. An AfC round is agreed and
141
184
  * implemented by each nation separately, and a nation whose award is
142
- * not yet funded keeps paying last year's scales into this tax year;
143
- * this function says which nations are. Tax never waits: the thresholds
144
- * change on 6 April whatever the employer has settled.
185
+ * not yet funded keeps paying last year's scales into this tax year.
186
+ * Tax never waits: the thresholds change on 6 April whatever the
187
+ * employer has settled.
145
188
  *
146
189
  * So the legitimate values are:
147
190
  *
@@ -149,20 +192,37 @@ export declare function afcPayYears(nation: Nation): PayYear[];
149
192
  * |---|---|
150
193
  * | `0` | the award is implemented; pay year and tax year agree |
151
194
  * | `1` | the award for this year is not yet in payment |
152
- * | `-1` | next year's circular is out but its tax year has not begun |
195
+ * | `-1` | next year's round is out but its tax year has not begun |
153
196
  *
154
- * Anything else is a defect in THIS library's data, not a fact about
155
- * the world: a lag of 2 means a whole round was never transcribed.
156
- * {@link assertPayYearLagIsSane} is where that is enforced.
197
+ * Anything else is a round that was never transcribed or a caller pricing
198
+ * a stale round, not a fact about the world ({@link isPayRoundInReach}).
157
199
  *
158
- * What this cannot catch is a pay year passed where a tax year was
159
- * wanted: the values here would look perfectly legal. The distinct
160
- * `PayYear` and `TaxYear` types are what stop that.
200
+ * Counted in years from each label's closing year, not by position in a
201
+ * list of labels, so it holds however the labels are ordered. What this
202
+ * cannot catch is a pay year passed where a tax year was wanted: the
203
+ * distinct `PayYear` and `TaxYear` types are what stop that.
161
204
  */
162
- export declare function payYearLag(nation: Nation): number;
205
+ export declare function payRoundLag(payYear: PayYear, taxYear: TaxYear): number;
163
206
  /**
164
- * True while a nation is still paying an older round than the tax year
165
- * in force — its award is announced or awaited, but not in payment.
207
+ * True where `payYear` is a round this library will price under
208
+ * `taxYear`'s deductions: at most one round from it, either way
209
+ * ({@link payRoundLag}). One rule for every reader, so a caller refusing
210
+ * a stale round and this library checking its own tables cannot disagree
211
+ * about what "too far apart" means.
212
+ */
213
+ export declare function isPayRoundInReach(payYear: PayYear, taxYear: TaxYear): boolean;
214
+ /**
215
+ * How far a nation's newest published pay scales sit from `taxYear`:
216
+ * {@link payRoundLag} of {@link latestAfcYear}. Positive means the pay
217
+ * scales are BEHIND, which is the nations still paying an earlier round.
218
+ *
219
+ * `taxYear` is the caller's: this library holds no clock, so the tax year
220
+ * in force is a fact the consumer brings, read at its own build or run.
221
+ */
222
+ export declare function latestRoundLag(nation: Nation, taxYear: TaxYear): number;
223
+ /**
224
+ * True while a nation is still paying an older round than `taxYear` — its
225
+ * award is announced or awaited, but not in payment.
166
226
  *
167
227
  * The domain question ("is this nation behind?") rather than a
168
228
  * comparison against some particular year, so a consumer cannot get
@@ -170,25 +230,27 @@ export declare function payYearLag(nation: Nation): number;
170
230
  * "is it exactly 2025-26" and quietly says no for a nation two rounds
171
231
  * behind, which is the case that most needs saying yes.
172
232
  */
173
- export declare function isAwaitingPayAward(nation: Nation): boolean;
233
+ export declare function isAwaitingPayAward(nation: Nation, taxYear: TaxYear): boolean;
174
234
  /**
175
- * Fail loudly if any nation's pay scales have drifted further from the
176
- * tax year than the domain allows. See {@link payYearLag}.
235
+ * Fail loudly if any nation's newest scale is out of reach of `taxYear`
236
+ * ({@link isPayRoundInReach}).
177
237
  *
178
238
  * A function rather than a module-scope check: this library is
179
239
  * published, and a throw at import time would take down every consumer
180
240
  * over a data problem they cannot fix. It runs in this repo's tests,
181
- * which is where a transcription gap should surface.
241
+ * which is where a transcription gap should surface, and a consumer can
242
+ * run it against the tax year it prices in.
182
243
  */
183
- export declare function assertPayYearLagIsSane(): void;
184
- export declare function latestAfcYear(nation: Nation): PayYear;
185
- /** Resolve a nation's published scale table for a year.
186
- * Every figure returned is transcribed from that nation's
187
- * own instrument. Where two nations' circulars print the
188
- * same numbers the tables share an object literal for
189
- * brevity, and each nation's fixture rows pin its values
190
- * against its OWN document, so a divergence fails rather
191
- * than propagating. Throws {@link ScaleUnavailable} for a
192
- * year that nation has not published, rather than silently
193
- * substituting another year's or nation's figures. */
194
- export declare function getScalesForYear(year: PayYear, nation: Nation): AfcScaleYear;
244
+ export declare function assertLatestRoundsInReach(taxYear: TaxYear): void;
245
+ /**
246
+ * The AfC pay year whose round runs over one scheme year, where this
247
+ * library holds its scale for the nation, and otherwise which side of the
248
+ * held years the scheme year falls ({@link AFC_PAY_YEAR_KINDS}). A pay year
249
+ * is one scheme year (`pay-year.ts`). `taxYear` is the tax year in force,
250
+ * which bounds how far ahead a round can be awaited.
251
+ *
252
+ * The round a scheme year names is not always the scale staff were paid
253
+ * on in it: a nation whose award is late still pays the previous round's
254
+ * scale (`latestRoundLag`, `latestAfcYear`). Ask those for that.
255
+ */
256
+ export declare function afcPayYearFor(end: SchemeYearEnd, nation: Nation, taxYear: TaxYear): AfcPayYearLookup;