@casomoltd/nhs-pay 0.11.0 → 0.12.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 (63) 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/gad/erf-2023-06-30.d.ts +39 -3
  19. package/dist/gad/erf-2023-06-30.js +39 -3
  20. package/dist/gad/erf-2023-06-30.js.map +1 -1
  21. package/dist/gad/factor-table.d.ts +10 -0
  22. package/dist/gad/factor-table.js.map +1 -1
  23. package/dist/gad/lrf-2023-06-30.d.ts +39 -3
  24. package/dist/gad/lrf-2023-06-30.js +39 -3
  25. package/dist/gad/lrf-2023-06-30.js.map +1 -1
  26. package/dist/hcas-pcts.js +3 -1
  27. package/dist/hcas-pcts.js.map +1 -1
  28. package/dist/index.d.ts +11 -3
  29. package/dist/index.js +9 -2
  30. package/dist/index.js.map +1 -1
  31. package/dist/pension/history.d.ts +105 -0
  32. package/dist/pension/history.js +115 -0
  33. package/dist/pension/history.js.map +1 -0
  34. package/dist/pension/ledger.d.ts +146 -0
  35. package/dist/pension/ledger.js +193 -0
  36. package/dist/pension/ledger.js.map +1 -0
  37. package/dist/pension/prices.d.ts +125 -0
  38. package/dist/pension/prices.js +108 -0
  39. package/dist/pension/prices.js.map +1 -0
  40. package/dist/pension/seed.d.ts +75 -0
  41. package/dist/pension/seed.js +82 -0
  42. package/dist/pension/seed.js.map +1 -0
  43. package/dist/pension/uplift.d.ts +151 -0
  44. package/dist/pension/uplift.js +135 -0
  45. package/dist/pension/uplift.js.map +1 -0
  46. package/dist/pension-projection.d.ts +217 -48
  47. package/dist/pension-projection.js +394 -202
  48. package/dist/pension-projection.js.map +1 -1
  49. package/dist/pension.js +9 -10
  50. package/dist/pension.js.map +1 -1
  51. package/dist/post.d.ts +24 -16
  52. package/dist/post.js +2 -3
  53. package/dist/post.js.map +1 -1
  54. package/dist/revaluation.d.ts +119 -30
  55. package/dist/revaluation.js +175 -29
  56. package/dist/revaluation.js.map +1 -1
  57. package/dist/scales.d.ts +17 -10
  58. package/dist/scales.js +17 -10
  59. package/dist/scales.js.map +1 -1
  60. package/dist/take-home.d.ts +9 -5
  61. package/dist/take-home.js +9 -5
  62. package/dist/take-home.js.map +1 -1
  63. package/package.json +1 -1
@@ -26,42 +26,97 @@
26
26
  * → Deferred revaluation: CPI only
27
27
  * → In-payment revaluation: CPI (Pensions Increase Order)
28
28
  *
29
- * ── Which ruler this projects in ────────────────────
30
- *
31
- * Everything here is computed in TODAY'S MONEY, and cash
32
- * terms are that figure scaled by CPI. This is not a
33
- * presentation choice: every promise the 2015 scheme makes is
34
- * expressed RELATIVE to CPI (in service CPI + 1.5%, deferred
35
- * and in payment CPI exactly), so with pay holding its value
36
- * the scheme's real behaviour is CPI-free — +1.5% a year
37
- * while you pay in, flat once you stop. Only the translation
38
- * to cash reads `assumedCpi`.
39
- *
40
- * Projecting in cash instead requires growing pay at CPI to
41
- * stay self-consistent. Holding pay flat in CASH while
42
- * revaluing the pot at CPI + 1.5% — the shape this module
43
- * used to have — counts inflation twice on historic service:
44
- * it treats a salary from ten years ago as worth today's
45
- * number in today's prices, then revalues the pension it
46
- * bought as though it were not.
47
- *
48
- * The scaling between the two rulers is exact, not an
49
- * approximation. In service the cash pot grows (1+cpi)(1.015)
50
- * while the slice it adds grows (1+cpi); deferred and in
51
- * payment both grow at CPI. The (1+cpi)^t factor therefore
52
- * divides out of every term, so ONE projection serves both
53
- * rulers and the two can never disagree.
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.
54
84
  *
55
85
  * NHSBSA Key Notes — 2015 Scheme Estimates (V2), March 2025
56
86
  * → Commutation rate: £12 lump sum per £1 pension
57
87
  * → HMRC 25% cap on lump sum
58
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
+ *
59
113
  * ── Checked against a real statement ────────────────
60
114
  *
61
115
  * Reconciled line by line against a member's NHS Annual
62
116
  * Benefit Statement (2015 Section, updated to 31/03/2025;
63
117
  * name and membership number redacted):
64
- * https://drive.google.com/file/d/1UJ8FIXC-6JbLOHIHZ3fbvqBLyTG-noL3/view
118
+ * Archived as "Annual Benefit Statement, 2015 Section,
119
+ * redacted" — see docs/source-archive.md.
65
120
  *
66
121
  * The accrual rate, the in-service revaluation, the HMRC
67
122
  * lump-sum cap and the commutation residual all reproduced
@@ -73,27 +128,39 @@
73
128
  * is revalued, never before, so a slice earns no revaluation
74
129
  * in the scheme year it is earned. The other order overstated
75
130
  * that statement by 3.2%, and every internal test still
76
- * passed. `simulateAccrual` is written in that order and
131
+ * passed. `pension/ledger.ts` is written in that order and
77
132
  * `revaluation never touches the year's own slice` holds it
78
133
  * there.
79
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
+ *
80
142
  * ── Added, not compounded ───────────────────────────
81
143
  *
82
144
  * The scheme ADDS CPI and 1.5 PERCENTAGE POINTS: 3.1% CPI
83
145
  * gives 4.6%, which is what the Treasury Order made and what
84
146
  * the statement above shows. revaluation.ts carries every
85
- * published year with its SI.
86
- *
87
- * This module compounds — a flat real rate of 1.5%, which is
88
- * the multiplicative reading of the same rule and runs about
89
- * 0.6% high over a full career at 2% CPI. Correcting it makes
90
- * the real rate cpi-dependent and so costs the property this
91
- * whole module rests on, which is why it is a decision rather
92
- * than a fix, taken in the open at
93
- * https://github.com/casomoltd/nhs-pay/issues/10
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.
94
156
  */
95
157
  import { invariant } from './errors.js';
96
158
  import { npaDate, periodInYearsMonths, yearsBetween, } from './dates.js';
159
+ import { createPrices } from './pension/prices.js';
160
+ import { buildLedger } from './pension/ledger.js';
161
+ import { estimateHistory } from './pension/history.js';
162
+ import { openingUpliftFor } from './pension/uplift.js';
163
+ import { schemeYearClosedBy, schemeYearEndDate, schemeYearEndFor, seedFromJoinDate, seedFromStatement, } from './pension/seed.js';
97
164
  import { FactorTable } from './gad/factor-table.js';
98
165
  import { ERF_0_420 } from './gad/erf-2023-06-30.js';
99
166
  import { LRF_0_421 } from './gad/lrf-2023-06-30.js';
@@ -102,22 +169,18 @@ import { LRF_0_421 } from './gad/lrf-2023-06-30.js';
102
169
  export const ACCRUAL_RATE = 1 / 54;
103
170
  /** Commutation: £12 lump sum per £1 pension */
104
171
  export const COMMUTATION_FACTOR = 12;
105
- /** In-service revaluation bonus above CPI */
106
- const ACTIVE_REVAL_BONUS = 0.015;
107
172
  /**
108
- * The scheme's promises in today's money. Each is the headline
109
- * rate MINUS the CPI it is quoted against, which is why none
110
- * of them mentions `assumedCpi`:
111
- * - paying in: CPI + 1.5% ⇒ 1.5% real
112
- * - deferred: CPI ⇒ flat
113
- * - in payment: CPI ⇒ flat
114
- * The two flat rates are named rather than inlined because
115
- * "the pension holds its value" is the scheme's actual
116
- * guarantee, and a bare 0 reads like an omission.
173
+ * The most of a member's benefits HMRC lets them take as a
174
+ * tax-free lump sum, as a percentage.
175
+ *
176
+ * Exported because it is the only part of the commutation rule
177
+ * a member can be told directly — {@link maxLumpSum} is the cap
178
+ * in pounds, which answers "how much" but never "why that
179
+ * much". A consumer explaining the swap needs this figure, and
180
+ * a consumer that writes its own copy of it is one that can
181
+ * drift from the library that applies it.
117
182
  */
118
- const ACTIVE_REAL_RATE = ACTIVE_REVAL_BONUS;
119
- const DEFERRED_REAL_RATE = 0;
120
- const IN_PAYMENT_REAL_RATE = 0;
183
+ export const HMRC_LUMP_SUM_CAP_PCT = 25;
121
184
  // ── Factor Tables ───────────────────────────────────
122
185
  // Which issue is in force is exactly these two constructions —
123
186
  // swap the import when GAD supersedes a table (the two tables
@@ -172,11 +235,27 @@ export function revalue(pension, annualRate, years) {
172
235
  }
173
236
  // ── Commutation ─────────────────────────────────────
174
237
  /**
175
- * Maximum tax-free lump sum under HMRC 25% rule.
176
- * Formula: (20 × pension) / (3 + 20/commutationFactor)
238
+ * Maximum tax-free lump sum under the HMRC cap.
239
+ *
240
+ * The cap is on the lump sum as a share of the CAPITAL VALUE of
241
+ * the benefits, and taking a lump sum lowers the pension that
242
+ * value is measured from — so the answer is a fixed point, not
243
+ * a percentage of anything the caller already holds. With `c`
244
+ * the cap and `f` the commutation factor, capital value is
245
+ * `20 × residual + lumpSum`, and solving
246
+ *
247
+ * L = c × (20 × (P − L/f) + L)
248
+ *
249
+ * for L gives the expression below. Written from
250
+ * {@link HMRC_LUMP_SUM_CAP_PCT} rather than from its
251
+ * rearrangement — the familiar `(20P) / (3 + 20/f)` is this
252
+ * same solution with `c = 0.25` already substituted in, which
253
+ * hides the one number a reader would want to check.
177
254
  */
178
255
  export function maxLumpSum(adjustedPension) {
179
- return (20 * adjustedPension) / (3 + 20 / COMMUTATION_FACTOR);
256
+ const cap = HMRC_LUMP_SUM_CAP_PCT / 100;
257
+ return ((20 * cap * adjustedPension)
258
+ / (1 - cap + (20 * cap) / COMMUTATION_FACTOR));
180
259
  }
181
260
  /**
182
261
  * Calculate commutation at a given fraction of max.
@@ -207,176 +286,289 @@ export function commute(adjustedPension, fraction) {
207
286
  * could flip the ms-precision accrued flag).
208
287
  */
209
288
  export function projectPension(input, today = new Date()) {
210
- const resolved = resolveProjection(input, today);
211
- // Each figure is scaled against ITS OWN date: the exit
212
- // figure is cash at exit, the retirement ones cash at
213
- // retirement. Handing consumers a horizon to apply is what
214
- // let one of them deflate the exit figure over the years to
215
- // retirement.
216
- const atExit = (real) => money(resolved, real, resolved.exitDate);
217
- const atRetirement = (real) => money(resolved, real, resolved.retirementDate);
218
- return {
219
- accruedAtExit: atExit(resolved.accruedAtExit),
220
- revaluedAtRetirement: atRetirement(resolved.revaluedAtRetirement),
221
- annualPension: atRetirement(resolved.annualPension),
222
- factor: resolved.factor,
223
- factorType: resolved.factorType,
224
- adjustmentAmount: atRetirement(resolved.revaluedAtRetirement - resolved.annualPension),
225
- curve: buildCurve(resolved),
226
- isEstimation: resolved.isEstimation,
227
- };
228
- }
229
- // ── Internal Helpers ────────────────────────────────
230
- /**
231
- * Today's money → actual pounds at `date`. The exponent is
232
- * SIGNED: a date in the past scales the figure down, because
233
- * the same real pension was fewer actual pounds back then.
234
- */
235
- function money(resolved, real, date) {
236
- const years = yearsBetween(resolved.today, date);
289
+ /* TWO RUNS, not one run read two ways. Cash at the caller's
290
+ assumption; today's money with that assumption set to zero,
291
+ which is what "ignore inflation" means: the pension
292
+ revalues at 1.5% a year while accruing and not at all once
293
+ deferred, and pay stays the figure the caller gave.
294
+
295
+ Cheap, deterministic and pure, so running the model twice
296
+ costs a few microseconds and buys a definition a reader can
297
+ check by hand. The deflated alternative cost an anchor
298
+ date, a face-value window, a rule against restating a
299
+ stated balance, and three failed attempts at placing the
300
+ anchor — all to arrive at 1.47% where the member's own
301
+ arithmetic says 1.5%. */
302
+ const cash = resolveProjection(input, today);
303
+ const todays = input.assumedCpi === 0
304
+ ? cash
305
+ : resolveProjection({ ...input, assumedCpi: 0 }, today);
306
+ const pair = (n, r, asAt) => ({ nominal: n, real: r, asAt });
237
307
  return {
238
- real,
239
- nominal: real * Math.pow(1 + resolved.assumedCpi, years),
308
+ accruedAtExit: pair(cash.accruedAtExit, todays.accruedAtExit,
309
+ // Dated at the close it is the closing of.
310
+ schemeYearEndDate(schemeYearEndFor(cash.exitDate))),
311
+ revaluedAtRetirement: pair(cash.revaluedAtRetirement, todays.revaluedAtRetirement, cash.retirementDate),
312
+ annualPension: pair(cash.annualPension, todays.annualPension, cash.retirementDate),
313
+ accruedNow: pair(cash.ledger.atDate(today), todays.ledger.atDate(today), today),
314
+ factor: cash.factor,
315
+ factorType: cash.factorType,
316
+ adjustmentAmount: pair(cash.revaluedAtRetirement - cash.annualPension, todays.revaluedAtRetirement - todays.annualPension, cash.retirementDate),
317
+ curve: buildCurve(cash, todays),
318
+ isEstimation: cash.isEstimation,
319
+ estimatedHistory: todays.history,
320
+ ledger: cash.ledger,
321
+ todaysMoneyLedger: todays.ledger,
240
322
  };
241
323
  }
242
324
  /**
243
- * The inverse of `money`: a figure quoted in the cash of
244
- * `date`, read in today's money. A date in the PAST scales
245
- * the figure UP — the same pounds bought more back then.
246
- */
247
- function realAt(nominal, date, today, assumedCpi) {
248
- return nominal
249
- / Math.pow(1 + assumedCpi, yearsBetween(today, date));
250
- }
251
- /**
252
- * Simulate year-by-year accrual with in-service
253
- * revaluation over a fractional number of years.
325
+ * A member's stated balance, on whatever date it is stated —
326
+ * the day they read it, or the day their statement prints. That
327
+ * is a position mid-scheme-year, and a seed is a year-end
328
+ * closing balance, so it has to be carried back to one.
329
+ *
330
+ * In November the April uplift has already been applied to the
331
+ * figure being read, so dividing it out lands on the last
332
+ * year-end closing balance and the walk re-applies it — no
333
+ * double count, and no year of accrual thrown away. On a date
334
+ * before that April the figure already IS the year-end balance
335
+ * and nothing is divided, which is why a statement printed on
336
+ * 31 March passes through untouched.
254
337
  *
255
- * The order is load-bearing: the pot is revalued FIRST and
256
- * the year's slice added after, so a slice earns nothing in
257
- * the year it is earned. See the statement reconciliation in
258
- * the module header.
338
+ * ONE route for both the dated and the undated case, because
339
+ * there is only one question: what was the closing balance at
340
+ * the year end before this date? `seedFromStatement` stays
341
+ * strict about wanting a year end; this is what finds it.
342
+ * Statements print on arbitrary days — 7 November is a real
343
+ * one — so the strict form alone could not serve them.
259
344
  */
260
- function simulateAccrual(startPension, salary, activeRate, years) {
261
- let pension = startPension;
262
- const fullYears = Math.max(0, Math.floor(years));
263
- for (let i = 0; i < fullYears; i++) {
264
- pension = pension * (1 + activeRate)
265
- + yearlyAccrual(salary);
266
- }
267
- const partial = years - fullYears;
268
- if (partial > 0) {
269
- pension = pension * (1 + activeRate * partial)
270
- + yearlyAccrual(salary) * partial;
271
- }
272
- return pension;
345
+ function seedFromBalanceAt(balance, asOf, exitDate, retirementDate, prices) {
346
+ const lastYearEnd = schemeYearClosedBy(asOf);
347
+ /* The uplift undone here is the one OPENING year
348
+ `lastYearEnd + 1`, and it is the very object `buildLedger`
349
+ re-applies to that year: inverting the walk exactly is this
350
+ function's only job, so both sides ask `openingUpliftFor`
351
+ rather than each naming the phase, the year and the CPI
352
+ series for themselves. */
353
+ const applied = openingUpliftFor(lastYearEnd, exitDate, retirementDate, prices);
354
+ const already = applied.appliedOn <= asOf;
355
+ return seedFromStatement(already ? balance / (1 + applied.percent / 100) : balance, schemeYearEndDate(lastYearEnd));
273
356
  }
274
- /**
275
- * Accrued pension in today's money at a date in the active
276
- * phase. A date at or before the origin degrades to zero
277
- * years, which simulateAccrual returns untouched — so the
278
- * statement path's "already past exit" case needs no
279
- * special branch.
280
- */
281
- function accruedRealAt(anchor, date) {
282
- const years = Math.max(0, yearsBetween(anchor.accrualOrigin, date));
283
- return simulateAccrual(anchor.accrualBase, anchor.currentSalary, anchor.activeRate, years);
357
+ /** The earliest of some dates. */
358
+ function earliest(...dates) {
359
+ return new Date(Math.min(...dates.map((d) => d.getTime())));
284
360
  }
285
- /** The single place input.kind is read */
286
361
  function resolveProjection(input, today) {
287
362
  const { currentSalary, dateOfBirth, exitDate, retirementDate, npa, assumedCpi, } = input;
363
+ /* The drawing date is used EXACTLY AS GIVEN, to the day.
364
+ Retiring on a birthday, mid-month, or on a scheme year end
365
+ are three different questions and this function answers
366
+ whichever one it is asked — the GAD tables are printed by
367
+ year AND month, and the rounding rules (ERF up §2.3, LRF
368
+ down §3.4) exist precisely for the part-months a date-exact
369
+ answer produces.
370
+
371
+ A CONSUMER may want less than that. The NHS pension
372
+ calculator prices retirement in whole years from NPA,
373
+ because it draws a chart whose every point is a 31 March
374
+ and a factor that moved when you retired "on time" would
375
+ be harder to follow than one that is a little rough. It
376
+ gets that by handing this function two birthdays, which are
377
+ a whole number of years apart. That is its simplification
378
+ to declare, in its own methods, and it did not belong in
379
+ here: a library that has already thrown the precision away
380
+ cannot offer it back to the next caller. */
288
381
  const isEstimation = input.kind === 'estimation';
289
- // The accrual anchor is the only residue of kind:
290
- // statement = (ABS figure, the date the ABS valued it);
291
- // estimation = (nothing banked, scheme join date).
292
- //
293
- // A statement figure is CASH at its own date, so it is read
294
- // back into today's money before the simulation — which
295
- // works in today's money throughout — rather than being
296
- // dropped in as though the two rulers were the same. With
297
- // the date omitted the conversion is a no-op, so the
298
- // default costs nothing.
299
- const statementOrigin = isEstimation
300
- ? today
301
- : input.statementDate ?? today;
302
- const anchor = {
303
- accrualBase: isEstimation
304
- ? 0
305
- : realAt(input.accruedPension, statementOrigin, today, assumedCpi),
306
- accrualOrigin: isEstimation
307
- ? input.joinDate
308
- : statementOrigin,
309
- currentSalary,
310
- activeRate: ACTIVE_REAL_RATE,
311
- };
312
- const accruedAtExit = accruedRealAt(anchor, exitDate);
313
- // Deferred revaluation is CPI exactly, so in today's money
314
- // the pension simply holds its value. The call stays to
315
- // name the phase; revalue self-guards non-positive periods.
316
- const revaluedAtRetirement = revalue(accruedAtExit, DEFERRED_REAL_RATE, yearsBetween(exitDate, retirementDate));
317
- // Apply ERF/LRF
382
+ const prices = createPrices(assumedCpi, today);
383
+ // The ONLY place the input variant is read.
384
+ const seed = isEstimation
385
+ ? seedFromJoinDate(input.joinDate)
386
+ : seedFromBalanceAt(input.accruedPension, input.statementDate ?? today, exitDate, retirementDate, prices);
318
387
  const { factor, type: factorType } = retirementFactor(retirementDate, npaDate(dateOfBirth, npa));
319
- const annualPension = revaluedAtRetirement * factor;
320
- return {
321
- ...anchor,
322
- today,
323
- dateOfBirth,
388
+ const retireYear = schemeYearEndFor(retirementDate);
389
+ // Walk five years past the later of NPA and retirement, which
390
+ // is as far as the curve is ever asked to reach.
391
+ const through = Math.max(retireYear, schemeYearEndFor(npaDate(dateOfBirth, npa))) + 6;
392
+ const ledger = buildLedger({
393
+ seed,
394
+ pensionableEarnings: currentSalary,
324
395
  exitDate,
325
396
  retirementDate,
326
- npa,
327
- assumedCpi,
328
- isEstimation,
329
- accruedAtExit,
330
- revaluedAtRetirement,
331
- factor,
332
- factorType,
333
- annualPension,
397
+ prices,
398
+ through,
399
+ drawingFor: () => ({
400
+ on: retirementDate,
401
+ factor,
402
+ kind: factorType === 'none' ? 'erf' : factorType,
403
+ provenance: factorProvenance(factorType === 'none' ? 'erf' : factorType),
404
+ commuted: null,
405
+ }),
406
+ });
407
+ // Absent when retirement falls at or before the seed's own
408
+ // year end — a member handing over a balance and drawing it
409
+ // the same day. There is no row then, but there is still an
410
+ // answer: the balance they handed over.
411
+ const retireRow = ledger.years.find((r) => r.schemeYearEnd === retireYear);
412
+ const revalued = retireRow === undefined
413
+ ? ledger.accruedAt(retirementDate)
414
+ : retireRow.revalued + retireRow.earned;
415
+ const drawn = retireRow === undefined
416
+ ? revalued * factor
417
+ : retireRow.closing;
418
+ /* Illustration only, and only where a statement leaves a gap:
419
+ an estimation path already walks from the join date, so
420
+ there is nothing to fill in. Calibrated to land exactly on
421
+ the stated balance, so the two arms meet without a seam. */
422
+ const history = input.kind === 'statement'
423
+ && input.joinDate !== undefined
424
+ ? estimateHistory({
425
+ joinDate: input.joinDate,
426
+ statedBalance: seed.opening,
427
+ statementSchemeYearEnd: seed.atSchemeYearEnd,
428
+ prices,
429
+ })
430
+ : null;
431
+ return {
432
+ today, dateOfBirth, exitDate, retirementDate, npa,
433
+ prices, ledger, history, isEstimation, factor, factorType,
434
+ /* The earliest date the ledger holds a balance for, which
435
+ is the seed's own year end — NOT today.
436
+
437
+ The seed IS a balance at a scheme year end, so the months
438
+ between it and today are rows of this walk like any
439
+ other; starting the curve at today withholds them.
440
+ Starting at today also puts a past leaving date OUTSIDE
441
+ the plotted range, leaving the "stops paying in" marker
442
+ floating in space beside a chart that begins after it. */
443
+ curveFrom: earliest(today, exitDate, schemeYearEndDate(history === null ? seed.atSchemeYearEnd : history.from - 1)),
444
+ /* The close of that year, not the exit date — see
445
+ docs/how-it-works.md, "An exit date names a SCHEME
446
+ YEAR, not a day". Reading the date puts this a whole
447
+ year's accrual below the rest of this object for a
448
+ mid-year leaver. */
449
+ accruedAtExit: ledger.closingAt(schemeYearEndFor(exitDate)),
450
+ revaluedAtRetirement: revalued,
451
+ annualPension: drawn,
334
452
  };
335
453
  }
336
454
  /**
337
- * Build the projection curve at yearly intervals. The curve
338
- * begins at the accrual origin — the scheme join date on the
339
- * estimation path — so the built-up history is on the curve,
340
- * not just the projection forward (a statement's accrual
341
- * origin is today: an ABS figure carries no join history).
455
+ * A member's age on a date, as WHOLE YEARS plus the fraction of
456
+ * the year since their birthday.
457
+ *
458
+ * The whole part is calendar arithmetic, so it is the age they
459
+ * would give if asked. The fraction only orders points within a
460
+ * year, which is all the chart needs it for.
342
461
  */
343
- function buildCurve(resolved) {
344
- const { today, dateOfBirth, retirementDate, npa, } = resolved;
345
- const points = [];
346
- const currentAge = yearsBetween(dateOfBirth, today);
347
- const originAge = yearsBetween(dateOfBirth, resolved.accrualOrigin);
348
- const endAge = Math.max(npa + 5, yearsBetween(dateOfBirth, retirementDate) + 5);
349
- const startAge = Math.floor(Math.min(currentAge, originAge));
350
- for (let age = startAge; age <= Math.ceil(endAge); age++) {
351
- const pointDate = new Date(dateOfBirth.getFullYear() + age, dateOfBirth.getMonth(), dateOfBirth.getDate());
352
- const { real, accrued } = curvePointValue(resolved, pointDate);
353
- const { nominal } = money(resolved, real, pointDate);
354
- points.push({ age, nominal, real, accrued });
355
- }
356
- return points;
462
+ function ageAtYearEnd(dateOfBirth, on) {
463
+ const birthdayIn = (year) => new Date(year, dateOfBirth.getMonth(), dateOfBirth.getDate());
464
+ const thisYear = birthdayIn(on.getFullYear());
465
+ const reached = thisYear <= on;
466
+ const whole = on.getFullYear() - dateOfBirth.getFullYear()
467
+ - (reached ? 0 : 1);
468
+ const last = reached ? thisYear : birthdayIn(on.getFullYear() - 1);
469
+ const next = reached ? birthdayIn(on.getFullYear() + 1) : thisYear;
470
+ return whole
471
+ + (on.getTime() - last.getTime())
472
+ / (next.getTime() - last.getTime());
357
473
  }
358
474
  /**
359
- * Today's-money value and accrued flag for one curve point —
360
- * names the three lifecycle phases (active, deferred,
361
- * in payment) and nothing else. The two revalue calls are
362
- * flat in this ruler, which IS the shape the reader sees:
363
- * the line rises only while you are paying in.
475
+ * The curve is the ledger's own steps, plotted ON THEM.
476
+ *
477
+ * **One point per scheme year, at its 31 March close** — the
478
+ * date an Annual Benefit Statement is drawn to, so every
479
+ * plotted value is a figure a member can lay beside paper.
480
+ *
481
+ * **Never at BIRTHDAYS**, which is the plotting the age axis
482
+ * invites. A birthday falls somewhere inside a scheme year:
483
+ * after the April uplift but before the year's slice lands, or
484
+ * the other way about. So a member born in January reads their
485
+ * 43rd-birthday point as "the 2026 figure" and gets a balance
486
+ * with neither the year's accrual in it nor any relation to a
487
+ * year end — values right for their dates and wrong for every
488
+ * question anyone asks of them, which surfaces as "the chart
489
+ * disagrees with my statement".
490
+ *
491
+ * The x-axis stays an AGE, because that is how people think
492
+ * about retiring. Age N is plotted at the close of the scheme
493
+ * year N's birthday falls in — the year that birthday belongs
494
+ * to — so the axis is unchanged and only the dates behind it
495
+ * move onto the scheme's own calendar.
496
+ *
497
+ * Nothing is drawn before the ledger's own start. For a
498
+ * statement that is the statement's date, and the reason is
499
+ * not tidiness: a member enters one figure, not their history,
500
+ * so anything earlier would be that figure run BACKWARDS
501
+ * through rates nobody checked. An inverse calculation drawn
502
+ * as history is a claim the tool cannot support.
364
503
  */
365
- function curvePointValue(resolved, pointDate) {
366
- const { today, exitDate, retirementDate } = resolved;
367
- if (pointDate <= exitDate) {
368
- const real = accruedRealAt(resolved, pointDate);
369
- return { real, accrued: pointDate <= today };
370
- }
371
- if (pointDate <= retirementDate) {
372
- const yrsDeferred = yearsBetween(exitDate, pointDate);
373
- const real = revalue(resolved.accruedAtExit, DEFERRED_REAL_RATE, yrsDeferred);
374
- return { real, accrued: false };
504
+ function buildCurve(cash, todays) {
505
+ const { today, dateOfBirth, retirementDate, npa } = cash;
506
+ const endAge = Math.max(npa + 5, yearsBetween(dateOfBirth, retirementDate) + 5);
507
+ /** The scheme year an age's birthday falls in. */
508
+ const yearOfAge = (age) => schemeYearEndFor(new Date(dateOfBirth.getFullYear() + age, dateOfBirth.getMonth(), dateOfBirth.getDate()));
509
+ /** The age whose birthday falls in a scheme year — the
510
+ * inverse, used once to find where the axis starts. */
511
+ const ageInYear = (schemeYearEnd) => {
512
+ const end = schemeYearEndDate(schemeYearEnd);
513
+ const birthday = new Date(schemeYearEnd, dateOfBirth.getMonth(), dateOfBirth.getDate());
514
+ return schemeYearEnd - dateOfBirth.getFullYear()
515
+ - (birthday > end ? 1 : 0);
516
+ };
517
+ const startAge = ageInYear(schemeYearEndFor(cash.curveFrom));
518
+ const points = [];
519
+ for (let label = startAge; label <= Math.ceil(endAge); label++) {
520
+ const year = yearOfAge(label);
521
+ const on = schemeYearEndDate(year);
522
+ /* The age the member actually IS on that 31 March, not the
523
+ whole age whose birthday the scheme year contains.
524
+
525
+ Those differ by anything from nought to twelve months —
526
+ the gap between a birthday and the following 31 March —
527
+ so plotting at the whole age put every value up to a year
528
+ early on the x-axis. Where "today" fell in that gap the
529
+ curve ran BACKWARDS: a member born in June read 7,738 at
530
+ 39, 8,577 at 40, then 7,854 at 40.2 for today, then
531
+ 9,429 at 41. Three of those are right; the axis was
532
+ wrong.
533
+
534
+ A January birthday hides it, being three months from the
535
+ year end. A June one puts nine months of accrual in the
536
+ wrong place.
537
+
538
+ Built as WHOLE AGE + fraction rather than as a span in
539
+ 365.25-day years, so that `Math.floor(age)` is the age
540
+ the member actually is on that 31 March — by calendar
541
+ arithmetic, not within a rounding of it. Someone born on
542
+ 1 April reads 42.997 at the year end before their 43rd
543
+ birthday, which floors correctly today and sits three
544
+ thousandths from flooring wrongly after enough leap
545
+ days. The fraction still orders the points; only the
546
+ whole part is now guaranteed. */
547
+ const age = ageAtYearEnd(dateOfBirth, on);
548
+ /* Two walks meet here, and the estimate owns everything up
549
+ to and including the statement's own year — its last row
550
+ IS the stated balance, so reading it there rather than
551
+ the main ledger changes nothing and keeps the join
552
+ seamless. */
553
+ const from = (r) => r.history !== null && year <= r.history.to
554
+ ? r.history.ledger
555
+ : r.ledger;
556
+ const row = from(cash).years.find((r) => r.schemeYearEnd === year);
557
+ points.push({
558
+ age,
559
+ nominal: from(cash).atDate(on),
560
+ real: from(todays).atDate(on),
561
+ accrued: on <= today,
562
+ // Compared by scheme YEAR, matching the ledger's own
563
+ // rule, not by date: a point sits at a 31 March close, so
564
+ // a member who left in January of that year would read as
565
+ // deferred on the very year they were still paying in.
566
+ phase: row?.phase
567
+ ?? (year <= schemeYearEndFor(cash.exitDate)
568
+ ? 'active'
569
+ : 'deferred'),
570
+ });
375
571
  }
376
- // In payment — grows from the annualPension the
377
- // projection reports, never a re-derivation of it
378
- const yrsInPayment = yearsBetween(retirementDate, pointDate);
379
- const real = revalue(resolved.annualPension, IN_PAYMENT_REAL_RATE, yrsInPayment);
380
- return { real, accrued: false };
572
+ return points;
381
573
  }
382
574
  //# sourceMappingURL=pension-projection.js.map