@casomoltd/nhs-pay 0.11.0 → 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 (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 +10 -2
  29. package/dist/index.js +8 -1
  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 +189 -46
  47. package/dist/pension-projection.js +365 -201
  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,6 @@ 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
- /**
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.
117
- */
118
- const ACTIVE_REAL_RATE = ACTIVE_REVAL_BONUS;
119
- const DEFERRED_REAL_RATE = 0;
120
- const IN_PAYMENT_REAL_RATE = 0;
121
172
  // ── Factor Tables ───────────────────────────────────
122
173
  // Which issue is in force is exactly these two constructions —
123
174
  // swap the import when GAD supersedes a table (the two tables
@@ -207,176 +258,289 @@ export function commute(adjustedPension, fraction) {
207
258
  * could flip the ms-precision accrued flag).
208
259
  */
209
260
  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);
261
+ /* TWO RUNS, not one run read two ways. Cash at the caller's
262
+ assumption; today's money with that assumption set to zero,
263
+ which is what "ignore inflation" means: the pension
264
+ revalues at 1.5% a year while accruing and not at all once
265
+ deferred, and pay stays the figure the caller gave.
266
+
267
+ Cheap, deterministic and pure, so running the model twice
268
+ costs a few microseconds and buys a definition a reader can
269
+ check by hand. The deflated alternative cost an anchor
270
+ date, a face-value window, a rule against restating a
271
+ stated balance, and three failed attempts at placing the
272
+ anchor — all to arrive at 1.47% where the member's own
273
+ arithmetic says 1.5%. */
274
+ const cash = resolveProjection(input, today);
275
+ const todays = input.assumedCpi === 0
276
+ ? cash
277
+ : resolveProjection({ ...input, assumedCpi: 0 }, today);
278
+ const pair = (n, r, asAt) => ({ nominal: n, real: r, asAt });
218
279
  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,
280
+ accruedAtExit: pair(cash.accruedAtExit, todays.accruedAtExit,
281
+ // Dated at the close it is the closing of.
282
+ schemeYearEndDate(schemeYearEndFor(cash.exitDate))),
283
+ revaluedAtRetirement: pair(cash.revaluedAtRetirement, todays.revaluedAtRetirement, cash.retirementDate),
284
+ annualPension: pair(cash.annualPension, todays.annualPension, cash.retirementDate),
285
+ accruedNow: pair(cash.ledger.atDate(today), todays.ledger.atDate(today), today),
286
+ factor: cash.factor,
287
+ factorType: cash.factorType,
288
+ adjustmentAmount: pair(cash.revaluedAtRetirement - cash.annualPension, todays.revaluedAtRetirement - todays.annualPension, cash.retirementDate),
289
+ curve: buildCurve(cash, todays),
290
+ isEstimation: cash.isEstimation,
291
+ estimatedHistory: todays.history,
292
+ ledger: cash.ledger,
293
+ todaysMoneyLedger: todays.ledger,
227
294
  };
228
295
  }
229
- // ── Internal Helpers ────────────────────────────────
230
296
  /**
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);
237
- return {
238
- real,
239
- nominal: real * Math.pow(1 + resolved.assumedCpi, years),
240
- };
241
- }
242
- /**
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.
297
+ * A member's stated balance, on whatever date it is stated —
298
+ * the day they read it, or the day their statement prints. That
299
+ * is a position mid-scheme-year, and a seed is a year-end
300
+ * closing balance, so it has to be carried back to one.
301
+ *
302
+ * In November the April uplift has already been applied to the
303
+ * figure being read, so dividing it out lands on the last
304
+ * year-end closing balance and the walk re-applies it — no
305
+ * double count, and no year of accrual thrown away. On a date
306
+ * before that April the figure already IS the year-end balance
307
+ * and nothing is divided, which is why a statement printed on
308
+ * 31 March passes through untouched.
254
309
  *
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.
310
+ * ONE route for both the dated and the undated case, because
311
+ * there is only one question: what was the closing balance at
312
+ * the year end before this date? `seedFromStatement` stays
313
+ * strict about wanting a year end; this is what finds it.
314
+ * Statements print on arbitrary days — 7 November is a real
315
+ * one — so the strict form alone could not serve them.
259
316
  */
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;
317
+ function seedFromBalanceAt(balance, asOf, exitDate, retirementDate, prices) {
318
+ const lastYearEnd = schemeYearClosedBy(asOf);
319
+ /* The uplift undone here is the one OPENING year
320
+ `lastYearEnd + 1`, and it is the very object `buildLedger`
321
+ re-applies to that year: inverting the walk exactly is this
322
+ function's only job, so both sides ask `openingUpliftFor`
323
+ rather than each naming the phase, the year and the CPI
324
+ series for themselves. */
325
+ const applied = openingUpliftFor(lastYearEnd, exitDate, retirementDate, prices);
326
+ const already = applied.appliedOn <= asOf;
327
+ return seedFromStatement(already ? balance / (1 + applied.percent / 100) : balance, schemeYearEndDate(lastYearEnd));
273
328
  }
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);
329
+ /** The earliest of some dates. */
330
+ function earliest(...dates) {
331
+ return new Date(Math.min(...dates.map((d) => d.getTime())));
284
332
  }
285
- /** The single place input.kind is read */
286
333
  function resolveProjection(input, today) {
287
334
  const { currentSalary, dateOfBirth, exitDate, retirementDate, npa, assumedCpi, } = input;
335
+ /* The drawing date is used EXACTLY AS GIVEN, to the day.
336
+ Retiring on a birthday, mid-month, or on a scheme year end
337
+ are three different questions and this function answers
338
+ whichever one it is asked — the GAD tables are printed by
339
+ year AND month, and the rounding rules (ERF up §2.3, LRF
340
+ down §3.4) exist precisely for the part-months a date-exact
341
+ answer produces.
342
+
343
+ A CONSUMER may want less than that. The NHS pension
344
+ calculator prices retirement in whole years from NPA,
345
+ because it draws a chart whose every point is a 31 March
346
+ and a factor that moved when you retired "on time" would
347
+ be harder to follow than one that is a little rough. It
348
+ gets that by handing this function two birthdays, which are
349
+ a whole number of years apart. That is its simplification
350
+ to declare, in its own methods, and it did not belong in
351
+ here: a library that has already thrown the precision away
352
+ cannot offer it back to the next caller. */
288
353
  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
354
+ const prices = createPrices(assumedCpi, today);
355
+ // The ONLY place the input variant is read.
356
+ const seed = isEstimation
357
+ ? seedFromJoinDate(input.joinDate)
358
+ : seedFromBalanceAt(input.accruedPension, input.statementDate ?? today, exitDate, retirementDate, prices);
318
359
  const { factor, type: factorType } = retirementFactor(retirementDate, npaDate(dateOfBirth, npa));
319
- const annualPension = revaluedAtRetirement * factor;
320
- return {
321
- ...anchor,
322
- today,
323
- dateOfBirth,
360
+ const retireYear = schemeYearEndFor(retirementDate);
361
+ // Walk five years past the later of NPA and retirement, which
362
+ // is as far as the curve is ever asked to reach.
363
+ const through = Math.max(retireYear, schemeYearEndFor(npaDate(dateOfBirth, npa))) + 6;
364
+ const ledger = buildLedger({
365
+ seed,
366
+ pensionableEarnings: currentSalary,
324
367
  exitDate,
325
368
  retirementDate,
326
- npa,
327
- assumedCpi,
328
- isEstimation,
329
- accruedAtExit,
330
- revaluedAtRetirement,
331
- factor,
332
- factorType,
333
- annualPension,
369
+ prices,
370
+ through,
371
+ drawingFor: () => ({
372
+ on: retirementDate,
373
+ factor,
374
+ kind: factorType === 'none' ? 'erf' : factorType,
375
+ provenance: factorProvenance(factorType === 'none' ? 'erf' : factorType),
376
+ commuted: null,
377
+ }),
378
+ });
379
+ // Absent when retirement falls at or before the seed's own
380
+ // year end — a member handing over a balance and drawing it
381
+ // the same day. There is no row then, but there is still an
382
+ // answer: the balance they handed over.
383
+ const retireRow = ledger.years.find((r) => r.schemeYearEnd === retireYear);
384
+ const revalued = retireRow === undefined
385
+ ? ledger.accruedAt(retirementDate)
386
+ : retireRow.revalued + retireRow.earned;
387
+ const drawn = retireRow === undefined
388
+ ? revalued * factor
389
+ : retireRow.closing;
390
+ /* Illustration only, and only where a statement leaves a gap:
391
+ an estimation path already walks from the join date, so
392
+ there is nothing to fill in. Calibrated to land exactly on
393
+ the stated balance, so the two arms meet without a seam. */
394
+ const history = input.kind === 'statement'
395
+ && input.joinDate !== undefined
396
+ ? estimateHistory({
397
+ joinDate: input.joinDate,
398
+ statedBalance: seed.opening,
399
+ statementSchemeYearEnd: seed.atSchemeYearEnd,
400
+ prices,
401
+ })
402
+ : null;
403
+ return {
404
+ today, dateOfBirth, exitDate, retirementDate, npa,
405
+ prices, ledger, history, isEstimation, factor, factorType,
406
+ /* The earliest date the ledger holds a balance for, which
407
+ is the seed's own year end — NOT today.
408
+
409
+ The seed IS a balance at a scheme year end, so the months
410
+ between it and today are rows of this walk like any
411
+ other; starting the curve at today withholds them.
412
+ Starting at today also puts a past leaving date OUTSIDE
413
+ the plotted range, leaving the "stops paying in" marker
414
+ floating in space beside a chart that begins after it. */
415
+ curveFrom: earliest(today, exitDate, schemeYearEndDate(history === null ? seed.atSchemeYearEnd : history.from - 1)),
416
+ /* The close of that year, not the exit date — see
417
+ docs/how-it-works.md, "An exit date names a SCHEME
418
+ YEAR, not a day". Reading the date puts this a whole
419
+ year's accrual below the rest of this object for a
420
+ mid-year leaver. */
421
+ accruedAtExit: ledger.closingAt(schemeYearEndFor(exitDate)),
422
+ revaluedAtRetirement: revalued,
423
+ annualPension: drawn,
334
424
  };
335
425
  }
336
426
  /**
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).
427
+ * A member's age on a date, as WHOLE YEARS plus the fraction of
428
+ * the year since their birthday.
429
+ *
430
+ * The whole part is calendar arithmetic, so it is the age they
431
+ * would give if asked. The fraction only orders points within a
432
+ * year, which is all the chart needs it for.
342
433
  */
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;
434
+ function ageAtYearEnd(dateOfBirth, on) {
435
+ const birthdayIn = (year) => new Date(year, dateOfBirth.getMonth(), dateOfBirth.getDate());
436
+ const thisYear = birthdayIn(on.getFullYear());
437
+ const reached = thisYear <= on;
438
+ const whole = on.getFullYear() - dateOfBirth.getFullYear()
439
+ - (reached ? 0 : 1);
440
+ const last = reached ? thisYear : birthdayIn(on.getFullYear() - 1);
441
+ const next = reached ? birthdayIn(on.getFullYear() + 1) : thisYear;
442
+ return whole
443
+ + (on.getTime() - last.getTime())
444
+ / (next.getTime() - last.getTime());
357
445
  }
358
446
  /**
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.
447
+ * The curve is the ledger's own steps, plotted ON THEM.
448
+ *
449
+ * **One point per scheme year, at its 31 March close** — the
450
+ * date an Annual Benefit Statement is drawn to, so every
451
+ * plotted value is a figure a member can lay beside paper.
452
+ *
453
+ * **Never at BIRTHDAYS**, which is the plotting the age axis
454
+ * invites. A birthday falls somewhere inside a scheme year:
455
+ * after the April uplift but before the year's slice lands, or
456
+ * the other way about. So a member born in January reads their
457
+ * 43rd-birthday point as "the 2026 figure" and gets a balance
458
+ * with neither the year's accrual in it nor any relation to a
459
+ * year end — values right for their dates and wrong for every
460
+ * question anyone asks of them, which surfaces as "the chart
461
+ * disagrees with my statement".
462
+ *
463
+ * The x-axis stays an AGE, because that is how people think
464
+ * about retiring. Age N is plotted at the close of the scheme
465
+ * year N's birthday falls in — the year that birthday belongs
466
+ * to — so the axis is unchanged and only the dates behind it
467
+ * move onto the scheme's own calendar.
468
+ *
469
+ * Nothing is drawn before the ledger's own start. For a
470
+ * statement that is the statement's date, and the reason is
471
+ * not tidiness: a member enters one figure, not their history,
472
+ * so anything earlier would be that figure run BACKWARDS
473
+ * through rates nobody checked. An inverse calculation drawn
474
+ * as history is a claim the tool cannot support.
364
475
  */
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 };
476
+ function buildCurve(cash, todays) {
477
+ const { today, dateOfBirth, retirementDate, npa } = cash;
478
+ const endAge = Math.max(npa + 5, yearsBetween(dateOfBirth, retirementDate) + 5);
479
+ /** The scheme year an age's birthday falls in. */
480
+ const yearOfAge = (age) => schemeYearEndFor(new Date(dateOfBirth.getFullYear() + age, dateOfBirth.getMonth(), dateOfBirth.getDate()));
481
+ /** The age whose birthday falls in a scheme year — the
482
+ * inverse, used once to find where the axis starts. */
483
+ const ageInYear = (schemeYearEnd) => {
484
+ const end = schemeYearEndDate(schemeYearEnd);
485
+ const birthday = new Date(schemeYearEnd, dateOfBirth.getMonth(), dateOfBirth.getDate());
486
+ return schemeYearEnd - dateOfBirth.getFullYear()
487
+ - (birthday > end ? 1 : 0);
488
+ };
489
+ const startAge = ageInYear(schemeYearEndFor(cash.curveFrom));
490
+ const points = [];
491
+ for (let label = startAge; label <= Math.ceil(endAge); label++) {
492
+ const year = yearOfAge(label);
493
+ const on = schemeYearEndDate(year);
494
+ /* The age the member actually IS on that 31 March, not the
495
+ whole age whose birthday the scheme year contains.
496
+
497
+ Those differ by anything from nought to twelve months —
498
+ the gap between a birthday and the following 31 March —
499
+ so plotting at the whole age put every value up to a year
500
+ early on the x-axis. Where "today" fell in that gap the
501
+ curve ran BACKWARDS: a member born in June read 7,738 at
502
+ 39, 8,577 at 40, then 7,854 at 40.2 for today, then
503
+ 9,429 at 41. Three of those are right; the axis was
504
+ wrong.
505
+
506
+ A January birthday hides it, being three months from the
507
+ year end. A June one puts nine months of accrual in the
508
+ wrong place.
509
+
510
+ Built as WHOLE AGE + fraction rather than as a span in
511
+ 365.25-day years, so that `Math.floor(age)` is the age
512
+ the member actually is on that 31 March — by calendar
513
+ arithmetic, not within a rounding of it. Someone born on
514
+ 1 April reads 42.997 at the year end before their 43rd
515
+ birthday, which floors correctly today and sits three
516
+ thousandths from flooring wrongly after enough leap
517
+ days. The fraction still orders the points; only the
518
+ whole part is now guaranteed. */
519
+ const age = ageAtYearEnd(dateOfBirth, on);
520
+ /* Two walks meet here, and the estimate owns everything up
521
+ to and including the statement's own year — its last row
522
+ IS the stated balance, so reading it there rather than
523
+ the main ledger changes nothing and keeps the join
524
+ seamless. */
525
+ const from = (r) => r.history !== null && year <= r.history.to
526
+ ? r.history.ledger
527
+ : r.ledger;
528
+ const row = from(cash).years.find((r) => r.schemeYearEnd === year);
529
+ points.push({
530
+ age,
531
+ nominal: from(cash).atDate(on),
532
+ real: from(todays).atDate(on),
533
+ accrued: on <= today,
534
+ // Compared by scheme YEAR, matching the ledger's own
535
+ // rule, not by date: a point sits at a 31 March close, so
536
+ // a member who left in January of that year would read as
537
+ // deferred on the very year they were still paying in.
538
+ phase: row?.phase
539
+ ?? (year <= schemeYearEndFor(cash.exitDate)
540
+ ? 'active'
541
+ : 'deferred'),
542
+ });
375
543
  }
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 };
544
+ return points;
381
545
  }
382
546
  //# sourceMappingURL=pension-projection.js.map