@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.
- package/README.md +48 -0
- package/dist/award.d.ts +8 -8
- package/dist/award.js +8 -8
- package/dist/circulars/england-md-1-2026r.d.ts +2 -3
- package/dist/circulars/england-md-1-2026r.js +2 -3
- package/dist/circulars/england-md-1-2026r.js.map +1 -1
- package/dist/circulars/ni-hsc-tc8-05-2025.d.ts +2 -2
- package/dist/circulars/ni-hsc-tc8-05-2025.js +2 -2
- package/dist/circulars/scotland-pcs-dd-2025-01.d.ts +2 -3
- package/dist/circulars/scotland-pcs-dd-2025-01.js +2 -3
- package/dist/circulars/scotland-pcs-dd-2025-01.js.map +1 -1
- package/dist/circulars/scotland-pcs-dd-2026-01.d.ts +2 -2
- package/dist/circulars/scotland-pcs-dd-2026-01.js +2 -2
- package/dist/circulars/wales-mdw-01-2025.d.ts +2 -2
- package/dist/circulars/wales-mdw-01-2025.js +2 -2
- package/dist/circulars/wales-mdw-01-2026.d.ts +2 -2
- package/dist/circulars/wales-mdw-01-2026.js +2 -2
- package/dist/format.d.ts +8 -0
- package/dist/format.js +14 -0
- package/dist/format.js.map +1 -1
- package/dist/gad/erf-2023-06-30.d.ts +39 -3
- package/dist/gad/erf-2023-06-30.js +39 -3
- package/dist/gad/erf-2023-06-30.js.map +1 -1
- package/dist/gad/factor-table.d.ts +10 -0
- package/dist/gad/factor-table.js.map +1 -1
- package/dist/gad/lrf-2023-06-30.d.ts +39 -3
- package/dist/gad/lrf-2023-06-30.js +39 -3
- package/dist/gad/lrf-2023-06-30.js.map +1 -1
- package/dist/hcas-pcts.js +3 -1
- package/dist/hcas-pcts.js.map +1 -1
- package/dist/index.d.ts +15 -4
- package/dist/index.js +17 -5
- package/dist/index.js.map +1 -1
- package/dist/npa.d.ts +28 -0
- package/dist/npa.js +60 -0
- package/dist/npa.js.map +1 -0
- package/dist/pension/history.d.ts +105 -0
- package/dist/pension/history.js +115 -0
- package/dist/pension/history.js.map +1 -0
- package/dist/pension/ledger.d.ts +146 -0
- package/dist/pension/ledger.js +193 -0
- package/dist/pension/ledger.js.map +1 -0
- package/dist/pension/prices.d.ts +125 -0
- package/dist/pension/prices.js +108 -0
- package/dist/pension/prices.js.map +1 -0
- package/dist/pension/seed.d.ts +75 -0
- package/dist/pension/seed.js +82 -0
- package/dist/pension/seed.js.map +1 -0
- package/dist/pension/uplift.d.ts +151 -0
- package/dist/pension/uplift.js +135 -0
- package/dist/pension/uplift.js.map +1 -0
- package/dist/pension-projection.d.ts +249 -12
- package/dist/pension-projection.js +406 -101
- package/dist/pension-projection.js.map +1 -1
- package/dist/pension.js +9 -10
- package/dist/pension.js.map +1 -1
- package/dist/post.d.ts +24 -16
- package/dist/post.js +2 -3
- package/dist/post.js.map +1 -1
- package/dist/revaluation.d.ts +189 -0
- package/dist/revaluation.js +270 -0
- package/dist/revaluation.js.map +1 -0
- package/dist/scales.d.ts +17 -10
- package/dist/scales.js +17 -10
- package/dist/scales.js.map +1 -1
- package/dist/take-home.d.ts +9 -5
- package/dist/take-home.js +9 -5
- package/dist/take-home.js.map +1 -1
- 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 {
|
|
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
|
|
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 £
|
|
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
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
/** After ERF/LRF
|
|
94
|
-
|
|
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:
|
|
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)
|