@casomoltd/nhs-pay 0.10.4 → 0.12.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 (69) hide show
  1. package/README.md +48 -0
  2. package/dist/award.d.ts +8 -8
  3. package/dist/award.js +8 -8
  4. package/dist/circulars/england-md-1-2026r.d.ts +2 -3
  5. package/dist/circulars/england-md-1-2026r.js +2 -3
  6. package/dist/circulars/england-md-1-2026r.js.map +1 -1
  7. package/dist/circulars/ni-hsc-tc8-05-2025.d.ts +2 -2
  8. package/dist/circulars/ni-hsc-tc8-05-2025.js +2 -2
  9. package/dist/circulars/scotland-pcs-dd-2025-01.d.ts +2 -3
  10. package/dist/circulars/scotland-pcs-dd-2025-01.js +2 -3
  11. package/dist/circulars/scotland-pcs-dd-2025-01.js.map +1 -1
  12. package/dist/circulars/scotland-pcs-dd-2026-01.d.ts +2 -2
  13. package/dist/circulars/scotland-pcs-dd-2026-01.js +2 -2
  14. package/dist/circulars/wales-mdw-01-2025.d.ts +2 -2
  15. package/dist/circulars/wales-mdw-01-2025.js +2 -2
  16. package/dist/circulars/wales-mdw-01-2026.d.ts +2 -2
  17. package/dist/circulars/wales-mdw-01-2026.js +2 -2
  18. package/dist/format.d.ts +8 -0
  19. package/dist/format.js +14 -0
  20. package/dist/format.js.map +1 -1
  21. package/dist/gad/erf-2023-06-30.d.ts +39 -3
  22. package/dist/gad/erf-2023-06-30.js +39 -3
  23. package/dist/gad/erf-2023-06-30.js.map +1 -1
  24. package/dist/gad/factor-table.d.ts +10 -0
  25. package/dist/gad/factor-table.js.map +1 -1
  26. package/dist/gad/lrf-2023-06-30.d.ts +39 -3
  27. package/dist/gad/lrf-2023-06-30.js +39 -3
  28. package/dist/gad/lrf-2023-06-30.js.map +1 -1
  29. package/dist/hcas-pcts.js +3 -1
  30. package/dist/hcas-pcts.js.map +1 -1
  31. package/dist/index.d.ts +15 -4
  32. package/dist/index.js +17 -5
  33. package/dist/index.js.map +1 -1
  34. package/dist/npa.d.ts +28 -0
  35. package/dist/npa.js +60 -0
  36. package/dist/npa.js.map +1 -0
  37. package/dist/pension/history.d.ts +105 -0
  38. package/dist/pension/history.js +115 -0
  39. package/dist/pension/history.js.map +1 -0
  40. package/dist/pension/ledger.d.ts +146 -0
  41. package/dist/pension/ledger.js +193 -0
  42. package/dist/pension/ledger.js.map +1 -0
  43. package/dist/pension/prices.d.ts +125 -0
  44. package/dist/pension/prices.js +108 -0
  45. package/dist/pension/prices.js.map +1 -0
  46. package/dist/pension/seed.d.ts +75 -0
  47. package/dist/pension/seed.js +82 -0
  48. package/dist/pension/seed.js.map +1 -0
  49. package/dist/pension/uplift.d.ts +151 -0
  50. package/dist/pension/uplift.js +135 -0
  51. package/dist/pension/uplift.js.map +1 -0
  52. package/dist/pension-projection.d.ts +249 -12
  53. package/dist/pension-projection.js +406 -101
  54. package/dist/pension-projection.js.map +1 -1
  55. package/dist/pension.js +9 -10
  56. package/dist/pension.js.map +1 -1
  57. package/dist/post.d.ts +24 -16
  58. package/dist/post.js +2 -3
  59. package/dist/post.js.map +1 -1
  60. package/dist/revaluation.d.ts +189 -0
  61. package/dist/revaluation.js +270 -0
  62. package/dist/revaluation.js.map +1 -0
  63. package/dist/scales.d.ts +17 -10
  64. package/dist/scales.js +17 -10
  65. package/dist/scales.js.map +1 -1
  66. package/dist/take-home.d.ts +9 -5
  67. package/dist/take-home.js +9 -5
  68. package/dist/take-home.js.map +1 -1
  69. package/package.json +2 -2
@@ -26,29 +26,222 @@
26
26
  * → Deferred revaluation: CPI only
27
27
  * → In-payment revaluation: CPI (Pensions Increase Order)
28
28
  *
29
+ * ── Two projections, not one and a deflator ─────────
30
+ *
31
+ * Everything is computed in CASH — actual pounds at a stated
32
+ * date — because that is the ruler the scheme itself uses: its
33
+ * records, its uplifts and a member's statement are all cash
34
+ * figures.
35
+ *
36
+ * Today's money is NOT that divided by inflation. It is the
37
+ * SAME model run with the caller's assumption set to ZERO, so
38
+ * the pot grows 1.5% a year while a member is paying in and
39
+ * not at all once they are deferred, and pay stays the figure
40
+ * they gave. `projectPension` runs both and pairs them; every
41
+ * reported figure carries the two readings and its own date.
42
+ *
43
+ * **So today's money does not move with the CPI assumption**,
44
+ * and a deferred pension is exactly flat in it. Deflating
45
+ * instead leaves 1.5 / (1 + cpi) of real growth — 1.47% at 2% —
46
+ * which is defensible arithmetic and not what anyone means by
47
+ * ignoring inflation. A member checking by hand takes 1.5% a
48
+ * year on a flat salary; the tool's own two views are defined
49
+ * that way, so this is.
50
+ *
51
+ * It also means there is no anchor date, no face-value window,
52
+ * and no rule that a stated balance must never be restated: at a
53
+ * zero assumption there is nothing to restate, so that property
54
+ * holds by construction rather than by a clamp. An anchor is the
55
+ * tempting repair and there is no right placement for one —
56
+ * every candidate produces a defensible figure that disagrees
57
+ * with a real statement.
58
+ *
59
+ * **CPI + 1.5 is an ADDITION, never a multiplication.** 3.1% CPI
60
+ * gives 4.6%, which is what the Treasury Order made and what a
61
+ * member's statement shows — not the 4.6465% that 1.031 x 1.015
62
+ * produces. The multiplicative reading is tempting because it
63
+ * makes the scheme look CPI-free in real terms, so ONE
64
+ * projection serves both rulers and cannot disagree with itself.
65
+ * Read as the scheme writes it, the real rate is 1.5 / (1 + cpi)
66
+ * and DOES move with the assumption — so the two rulers can
67
+ * disagree, and the model says so rather than pretending
68
+ * otherwise. Two runs are what buy back a stable today's-money
69
+ * reading, at no cost in arithmetic the scheme does not do.
70
+ * Deferred and in payment are CPI exactly, so those phases are
71
+ * flat in real terms either way.
72
+ *
73
+ * Decided in the open at
74
+ * https://github.com/casomoltd/nhs-pay/issues/10
75
+ *
76
+ * ── Annual, and stepped ─────────────────────────────
77
+ *
78
+ * The scheme year is the unit. The pot moves once a year, on
79
+ * 6 April (1 April through 2022), and is unchanged in between —
80
+ * so the model steps rather than compounds continuously, and a
81
+ * figure read four months after an uplift is the same figure
82
+ * that uplift produced. `pension/ledger.ts` holds one row per
83
+ * scheme year; this module is the orchestrator over it.
84
+ *
29
85
  * NHSBSA Key Notes — 2015 Scheme Estimates (V2), March 2025
30
86
  * → Commutation rate: £12 lump sum per £1 pension
31
87
  * → HMRC 25% cap on lump sum
88
+ *
89
+ * ── One rate after the seed ─────────────────────────
90
+ *
91
+ * A projection reads no published Revaluation Order. Every
92
+ * uplift after the seed is the caller's assumption, whether or
93
+ * not an Order covers that year, and whether the member is
94
+ * still paying in or left a decade ago.
95
+ *
96
+ * An Order is a NOMINAL rate, and today's money is this same
97
+ * model at an assumption of ZERO. Applying one inside that run
98
+ * puts a whole year of CPI into a reading defined to contain
99
+ * none — 8.2 points for a member holding a 2024 statement, 3.2
100
+ * for a 2025 one — so the size of the error is not a property
101
+ * of the member at all, only of the piece of paper they
102
+ * happened to type in.
103
+ *
104
+ * Nor is the exactness collectable. The year-end figure an Order
105
+ * produces here also contains this library's guess at that
106
+ * year's pay, so there is nothing to check it against until a
107
+ * statement the member has not received. What IS checkable stays
108
+ * checkable: the stated figure itself is never restated.
109
+ *
110
+ * Decided in the open at
111
+ * https://github.com/casomoltd/nhs-pay/issues/13
112
+ *
113
+ * ── Checked against a real statement ────────────────
114
+ *
115
+ * Reconciled line by line against a member's NHS Annual
116
+ * Benefit Statement (2015 Section, updated to 31/03/2025;
117
+ * name and membership number redacted):
118
+ * Archived as "Annual Benefit Statement, 2015 Section,
119
+ * redacted" — see docs/source-archive.md.
120
+ *
121
+ * The accrual rate, the in-service revaluation, the HMRC
122
+ * lump-sum cap and the commutation residual all reproduced
123
+ * it. No figure from it is recorded here — the earnings
124
+ * beside those rates are the member's and stay out.
125
+ *
126
+ * It settled the ORDER of the accrual loop, previously an
127
+ * untested assumption: a year's slice is added AFTER the pot
128
+ * is revalued, never before, so a slice earns no revaluation
129
+ * in the scheme year it is earned. The other order overstated
130
+ * that statement by 3.2%, and every internal test still
131
+ * passed. `pension/ledger.ts` is written in that order and
132
+ * `revaluation never touches the year's own slice` holds it
133
+ * there.
134
+ *
135
+ * A ten-year projection built BY HAND from that statement is
136
+ * the golden oracle in `tests/golden-abs.test.ts` — reproduced
137
+ * to the penny on every row. It was hand-built before this
138
+ * code, which is the point of it: a fixture derived from the
139
+ * implementation agrees with whatever the implementation is
140
+ * changed to.
141
+ *
142
+ * ── Added, not compounded ───────────────────────────
143
+ *
144
+ * The scheme ADDS CPI and 1.5 PERCENTAGE POINTS: 3.1% CPI
145
+ * gives 4.6%, which is what the Treasury Order made and what
146
+ * the statement above shows. revaluation.ts carries every
147
+ * published year with its SI, and `pension/uplift.ts` derives
148
+ * the rate forward from the CPI figure — never backward, since
149
+ * back-computing CPI as rate − 1.5 would make the test of the
150
+ * +1.5 rule agree with itself.
151
+ *
152
+ * This module used to compound instead, at a flat real 1.5%:
153
+ * the multiplicative reading of the same rule, running about
154
+ * 0.6% high over a full career at 2% CPI. That is now fixed,
155
+ * at the cost described above.
32
156
  */
33
- import type { FactorTableKind } from './gad/factor-table.js';
157
+ import type { EstimatedHistory } from './pension/history.js';
158
+ import type { MemberLedger } from './pension/ledger.js';
159
+ import type { MemberPhase } from './pension/uplift.js';
160
+ import type { FactorProvenance, FactorTableKind } from './gad/factor-table.js';
161
+ /**
162
+ * One figure under BOTH projections.
163
+ *
164
+ * Every scalar reported here is a pair, so a consumer picks a
165
+ * reading rather than doing CPI arithmetic of its own.
166
+ *
167
+ * **Neither reading is derived from the other.** They are two
168
+ * runs of the same model: `nominal` at the caller's inflation
169
+ * assumption, `real` with that assumption set to zero. So
170
+ * `real` is not `nominal` deflated, and dividing one by the
171
+ * other does not give the assumption back.
172
+ *
173
+ * That distinction is the whole of a long-running disagreement
174
+ * about a third of a percent. Deflating a CPI + 1.5 projection
175
+ * leaves 1.5 / (1 + cpi) of real growth — 1.47% at 2% — because
176
+ * the 1.5 points are added before the growth and eaten into by
177
+ * the same year's inflation. Running the model at zero gives
178
+ * 1.5% flat, which is what "ignore inflation" means and what
179
+ * every member's own arithmetic does.
180
+ */
181
+ export interface ProjectionMoney {
182
+ /** Actual pounds at `asAt`, the pension revalued at CPI plus
183
+ * 1.5 points a year while accruing. */
184
+ readonly nominal: number;
185
+ /** Today's pounds: the same projection with inflation
186
+ * ignored, so 1.5% a year while accruing and flat once
187
+ * deferred. */
188
+ readonly real: number;
189
+ /** The date the figure falls on. Its absence is how a
190
+ * consumer once deflated an exit figure over the horizon to
191
+ * retirement: a figure that does not carry its own date
192
+ * cannot defend itself. */
193
+ readonly asAt: Date;
194
+ }
34
195
  /** A point on the projection curve */
35
196
  export interface ProjectionPoint {
36
197
  /** Age in years (can be fractional) */
37
198
  age: number;
38
- /** Annual pension in nominal £ */
199
+ /** Annual pension in actual £ of that year. Below today's
200
+ * age this is SMALLER than `real`: past pounds bought more. */
39
201
  nominal: number;
40
- /** Annual pension in today's £ (CPI-deflated) */
202
+ /** Annual pension in today's £ — what the projection
203
+ * computes; `nominal` is this scaled by CPI. */
41
204
  real: number;
42
- /** Whether this is accrued (known) or projected */
205
+ /** Whether this is accrued (known) or projected — i.e.
206
+ * whether the point falls on or before today. Deliberately
207
+ * NOT `phase === 'active'`: a consumer uses this to separate
208
+ * history from forecast, and a future working year is
209
+ * forecast. */
43
210
  accrued: boolean;
211
+ /** Which lifecycle phase the point falls in. Additive: the
212
+ * three fields above keep their names and meanings. */
213
+ phase: MemberPhase;
44
214
  }
45
215
  /** Input for statement path */
46
216
  export interface PensionStatementInput {
47
217
  kind: 'statement';
48
218
  /** Accrued pension from Annual Benefit Statement (£/yr) */
49
219
  accruedPension: number;
220
+ /**
221
+ * The date the statement valued that figure at — an ABS
222
+ * carries one ("updated to 31/03/2025"), and it is
223
+ * typically months behind whenever the member reads it.
224
+ * Omit only when the figure really is current: defaulting
225
+ * to `today` silently throws away every month of accrual
226
+ * and revaluation since the statement was issued.
227
+ */
228
+ statementDate?: Date;
50
229
  /** Current pensionable pay */
51
230
  currentSalary: number;
231
+ /**
232
+ * Date joined the 2015 scheme, if the member gave one.
233
+ *
234
+ * ILLUSTRATION ONLY. A statement states a balance, not a
235
+ * history, so the years before it are estimated — see
236
+ * `pension/history.ts` — and drawn so the built-up arm has a
237
+ * shape and a beginning. Nothing after the statement reads
238
+ * it, and the estimate is calibrated to land exactly on the
239
+ * stated balance rather than near it.
240
+ *
241
+ * Omit and the chart simply starts at the statement, which
242
+ * is what it did before this existed.
243
+ */
244
+ joinDate?: Date;
52
245
  dateOfBirth: Date;
53
246
  /** Date member stops accruing (leaves NHS) */
54
247
  exitDate: Date;
@@ -86,26 +279,70 @@ export interface CommutationResult {
86
279
  }
87
280
  /** Full projection result */
88
281
  export interface PensionProjectionResult {
89
- /** Accrued pension at exit date (nominal) */
90
- accruedAtExit: number;
91
- /** After revaluation, before ERF/LRF (nominal) */
92
- revaluedAtRetirement: number;
93
- /** After ERF/LRF (nominal) */
94
- annualPension: number;
282
+ /** Accrued pension at the close of the scheme year the exit
283
+ * falls in, dated at that close — see docs/how-it-works.md,
284
+ * "An exit date names a SCHEME YEAR, not a day". */
285
+ accruedAtExit: ProjectionMoney;
286
+ /** After revaluation, before ERF/LRF, at retirement */
287
+ revaluedAtRetirement: ProjectionMoney;
288
+ /** After ERF/LRF, at retirement */
289
+ annualPension: ProjectionMoney;
290
+ /** The balance in force TODAY — flat between the scheme's
291
+ * annual steps, so it is exact rather than interpolated.
292
+ *
293
+ * Reported here rather than left to a consumer reading the
294
+ * curve, because the curve is sampled at scheme year ends: a
295
+ * reader looking for "what have I got now" off the nearest
296
+ * plotted point gets a figure up to a year stale. One did,
297
+ * and showed a member the balance from before both the year
298
+ * end and the April uplift. */
299
+ accruedNow: ProjectionMoney;
95
300
  /** ERF or LRF factor applied */
96
301
  factor: number;
97
302
  factorType: FactorTableKind | 'none';
98
- /** Gap between revalued and drawn pension */
99
- adjustmentAmount: number;
303
+ /** Gap between revalued and drawn pension, at retirement */
304
+ adjustmentAmount: ProjectionMoney;
100
305
  /** Curve data for chart (both views) */
101
306
  curve: ProjectionPoint[];
102
307
  /** Whether estimation path was used */
103
308
  isEstimation: boolean;
309
+ /**
310
+ * The year-by-year record every figure above was read off.
311
+ *
312
+ * Additive, and the point of it is that a consumer showing
313
+ * its working cannot disagree with the headline: the rows ARE
314
+ * the derivation, not a re-derivation. A panel that recomputed
315
+ * "statement plus the Orders since" from the published CPI
316
+ * alone missed the in-service 1.5 points and the leaver's
317
+ * part-year blend, so it printed a sum that did not reach the
318
+ * number beside it.
319
+ */
320
+ /**
321
+ * The illustrative years before the statement, or null when
322
+ * there are none to draw. Its `impliedPay` is in TODAY'S
323
+ * money — the figure a reader can hold against the pay they
324
+ * entered, and the one to caption with.
325
+ */
326
+ estimatedHistory: EstimatedHistory | null;
327
+ ledger: MemberLedger;
328
+ /** The same walk with inflation ignored — the rows behind
329
+ * every `real` reading above, so a consumer showing its
330
+ * working in today's money reads them rather than
331
+ * recomputing and disagreeing with the headline. */
332
+ todaysMoneyLedger: MemberLedger;
104
333
  }
105
334
  /** 1/54 accrual rate — NHS 2015 CARE scheme */
106
335
  export declare const ACCRUAL_RATE: number;
107
336
  /** Commutation: £12 lump sum per £1 pension */
108
337
  export declare const COMMUTATION_FACTOR = 12;
338
+ /**
339
+ * Provenance of the in-force table behind a factor kind — the
340
+ * citation facts (table ref, guidance name, issue date, source
341
+ * PDF) consumers render instead of hand-typing them, so a page
342
+ * showing "GAD factors issued 30 June 2023" updates itself when
343
+ * a later issue supersedes the table above.
344
+ */
345
+ export declare function factorProvenance(kind: FactorTableKind): FactorProvenance;
109
346
  /**
110
347
  * Determine whether ERF or LRF applies and return the
111
348
  * factor. The rounding rules (ERF up §2.3, LRF down §3.4)