@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
@@ -0,0 +1,151 @@
1
+ /**
2
+ * The uplift rule: a function of PHASE alone.
3
+ *
4
+ * Both published rate columns are pure functions of the CPI
5
+ * figure, verified against every year the library holds:
6
+ *
7
+ * active CPI + 1.5, a negative CPI carried through
8
+ * deferred/paid max(0, CPI), floored
9
+ *
10
+ * `rate = CPI + 1.5` holds on 11 of 11 rows, 2016–2026. The
11
+ * Pensions Increase column of the 2020 Valuation Report App. E
12
+ * equals `max(0, CPI)` on 8 of 8 published years, 2016–2023 —
13
+ * including 2016, where −0.1 CPI gives 1.4 active and 0.0
14
+ * deferred, and 2023's 10.1 spike.
15
+ *
16
+ * So there is no second rate table. The published Pensions
17
+ * Increase figures are a GOLDEN TEST, not production data.
18
+ *
19
+ * Note the direction: CPI is sourced independently from each
20
+ * Order's operative words and the rates derive forward from it.
21
+ * Never the reverse — back-computing CPI as `rate − 1.5` would
22
+ * make the test of the +1.5 rule agree with itself.
23
+ */
24
+ import type { CpiEntry, CpiSource, Prices } from './prices.js';
25
+ /**
26
+ * The three phases. Ordered by date and DERIVED from the member's
27
+ * own dates: a phase is never "entered", so there are no
28
+ * transitions to guard and no machine to run.
29
+ *
30
+ * FOUNDING ASSUMPTION, and this is where it lives: the phases are
31
+ * TOTALLY ORDERED and each occurs at most once, because the input
32
+ * carries a single exitDate. One unbroken membership — join,
33
+ * contribute, leave, draw. A career break or a return to the
34
+ * scheme cannot be expressed, and would be modelled as continuous
35
+ * active service, OVERSTATING the pension. Relaxing it later
36
+ * means allowing the sequence to repeat, which this shape already
37
+ * permits: phase is computed per year from the member's dates.
38
+ */
39
+ export type MemberPhase = 'active' | 'deferred' | 'inPayment';
40
+ /** Active until the member leaves, deferred until they draw, in
41
+ * payment after. Derived from dates; never entered.
42
+ *
43
+ * Lives beside the rule it selects, because the rule is a
44
+ * function of phase alone and this is the only way a phase is
45
+ * ever obtained. */
46
+ export declare function phaseAt(year: number, exitYear: number, retireYear: number): MemberPhase;
47
+ /** One uplift, as applied to a member's record. */
48
+ export interface AppliedUplift {
49
+ /** The date the POT moves — 1 April through 2022, 6 April from
50
+ * 2023. Not the order's commencement, and not the Pensions
51
+ * Increase date, which is a third date again. */
52
+ readonly appliedOn: Date;
53
+ /** Percentage points applied to the whole balance. Negative
54
+ * is legal. One rate for the year, never a blend: the phase
55
+ * on the day it lands settles it (see `upliftOpening`). */
56
+ readonly percent: number;
57
+ /** The CPI row this rate derives from. Provenance is READ from
58
+ * here and stored nowhere else, so a figure and its source
59
+ * cannot drift apart. */
60
+ readonly from: CpiEntry;
61
+ }
62
+ /** Where one year's uplift comes from. A single operation, so a
63
+ * phase fixes its rule once and the walker never branches.
64
+ *
65
+ * TOTAL: every scheme year asked for has an uplift. The rate is
66
+ * a `CpiSource` reading and a series has no gaps, so there is no
67
+ * year to answer "none" about. A ROW that carries no uplift —
68
+ * the first of a walk, which opens nothing — says so in its own
69
+ * field, `LedgerYear.uplift`; nullability there is about the
70
+ * walk's first step, not about this rule, and putting it here
71
+ * would make every caller narrow a value it always gets. */
72
+ export type UpliftSource = (schemeYearEnd: number) => AppliedUplift;
73
+ /** CPI + 1.5 points. A negative CPI is carried through, not
74
+ * floored: September 2015's −0.1 gave a 1.4% uplift, not 1.5%. */
75
+ export declare function activeRatePct(cpi: number): number;
76
+ /** Pensions Increase: CPI, floored at zero. Prices falling does
77
+ * not claw a pension back.
78
+ *
79
+ * A DIFFERENT instrument from the one above. The in-service rate
80
+ * comes from the Public Service Pensions Revaluation Order, made
81
+ * under s.9(2) Public Service Pensions Act 2013; this one is
82
+ * Pensions Increase, made by the annual Pensions Increase
83
+ * (Review) Order under s.59 Social Security Pensions Act 1975,
84
+ * and it is what lifts a preserved pension and one in payment.
85
+ * Two orders, two section powers, the same September CPI.
86
+ *
87
+ * Sources: "HM Treasury — 2026 pensions increase multiplier
88
+ * tables, covering note" and "HM Treasury — 2026 pensions
89
+ * increase multiplier tables, Annexes B and C" — see
90
+ * docs/source-archive.md. */
91
+ export declare function deferredRatePct(cpi: number): number;
92
+ /**
93
+ * The whole rule, in one factory.
94
+ *
95
+ * Takes a CPI READER rather than the whole table: the rule is a
96
+ * function of phase and a series, and WHICH series is the
97
+ * caller's question, not this one's. Whatever entry it is handed
98
+ * goes through unbranched — an Order's figure and an assumption
99
+ * are the same arithmetic here, and differ only in the
100
+ * provenance carried out beside the rate.
101
+ *
102
+ * Nothing in a projection calls this directly; both the walk and
103
+ * the seed go through `openingUpliftFor`, which fixes the series
104
+ * once so they cannot choose differently.
105
+ *
106
+ * That the published rates ARE `CPI + 1.5` is not asserted here,
107
+ * because nothing here reads them: the rule is checked against
108
+ * the TABLE, on all eleven rows at once, by
109
+ * `tests/prices.test.ts` — "reproduces every published rate, 11
110
+ * of 11". That check owns it, and it fires whether or not any
111
+ * caller ever asks for a published year.
112
+ */
113
+ export declare function upliftsFor(phase: MemberPhase, cpiFor: CpiSource): UpliftSource;
114
+ /**
115
+ * The uplift that OPENS the scheme year after
116
+ * `seedSchemeYearEnd` — the one question the seed and the walk
117
+ * must never answer differently.
118
+ *
119
+ * A seed is a balance standing at a year end and the walk's
120
+ * first step revalues it; `seedFromBalanceAt` divides that same
121
+ * step back out of a figure read mid-year. Three coordinates
122
+ * settle the answer — the phase the member is in for the year
123
+ * being OPENED, the year the rate is labelled by, and the CPI
124
+ * series it is read from — and a difference in any one of them
125
+ * stops a member's own stated balance round-tripping, with
126
+ * nothing in the output to show it. Hence one producer that both
127
+ * call: a coordinate spelled out twice is a coordinate that can
128
+ * drift.
129
+ *
130
+ * The rate is labelled by the year that just ENDED, which is why
131
+ * the seed's own year is the argument: SI 2016/438, applied 1
132
+ * April 2016, opens the year ending 31 March 2017. The
133
+ * off-by-one is the scheme's, not ours.
134
+ *
135
+ * ── One rate after the seed ─────────────────────────
136
+ *
137
+ * `assumedFor` is read for every year, whether or not an Order
138
+ * covers it. An Order is a NOMINAL rate, and today's money is
139
+ * this same model at an assumption of ZERO, so one applied
140
+ * inside that run puts a whole year of CPI into a reading
141
+ * defined to hold none — 8.2 points for a member holding a 2024
142
+ * statement, 3.2 for a 2025 one, so the size of it is a property
143
+ * of the paperwork rather than of the member. Nor is the
144
+ * exactness collectable: the year-end figure an Order produces
145
+ * here also carries this library's guess at that year's pay, so
146
+ * there is nothing to check it against until a statement the
147
+ * member has not received.
148
+ *
149
+ * Decided at https://github.com/casomoltd/nhs-pay/issues/13
150
+ */
151
+ export declare function openingUpliftFor(seedSchemeYearEnd: number, exitDate: Date, retirementDate: Date, prices: Prices): AppliedUplift;
@@ -0,0 +1,135 @@
1
+ /**
2
+ * The uplift rule: a function of PHASE alone.
3
+ *
4
+ * Both published rate columns are pure functions of the CPI
5
+ * figure, verified against every year the library holds:
6
+ *
7
+ * active CPI + 1.5, a negative CPI carried through
8
+ * deferred/paid max(0, CPI), floored
9
+ *
10
+ * `rate = CPI + 1.5` holds on 11 of 11 rows, 2016–2026. The
11
+ * Pensions Increase column of the 2020 Valuation Report App. E
12
+ * equals `max(0, CPI)` on 8 of 8 published years, 2016–2023 —
13
+ * including 2016, where −0.1 CPI gives 1.4 active and 0.0
14
+ * deferred, and 2023's 10.1 spike.
15
+ *
16
+ * So there is no second rate table. The published Pensions
17
+ * Increase figures are a GOLDEN TEST, not production data.
18
+ *
19
+ * Note the direction: CPI is sourced independently from each
20
+ * Order's operative words and the rates derive forward from it.
21
+ * Never the reverse — back-computing CPI as `rate − 1.5` would
22
+ * make the test of the +1.5 rule agree with itself.
23
+ */
24
+ import { ACTIVE_REVAL_BONUS_PCT, appliedOnFor, } from '../revaluation.js';
25
+ import { schemeYearEndFor } from './seed.js';
26
+ /** Active until the member leaves, deferred until they draw, in
27
+ * payment after. Derived from dates; never entered.
28
+ *
29
+ * Lives beside the rule it selects, because the rule is a
30
+ * function of phase alone and this is the only way a phase is
31
+ * ever obtained. */
32
+ export function phaseAt(year, exitYear, retireYear) {
33
+ if (year <= exitYear)
34
+ return 'active';
35
+ return year < retireYear ? 'deferred' : 'inPayment';
36
+ }
37
+ /** CPI + 1.5 points. A negative CPI is carried through, not
38
+ * floored: September 2015's −0.1 gave a 1.4% uplift, not 1.5%. */
39
+ export function activeRatePct(cpi) {
40
+ return cpi + ACTIVE_REVAL_BONUS_PCT;
41
+ }
42
+ /** Pensions Increase: CPI, floored at zero. Prices falling does
43
+ * not claw a pension back.
44
+ *
45
+ * A DIFFERENT instrument from the one above. The in-service rate
46
+ * comes from the Public Service Pensions Revaluation Order, made
47
+ * under s.9(2) Public Service Pensions Act 2013; this one is
48
+ * Pensions Increase, made by the annual Pensions Increase
49
+ * (Review) Order under s.59 Social Security Pensions Act 1975,
50
+ * and it is what lifts a preserved pension and one in payment.
51
+ * Two orders, two section powers, the same September CPI.
52
+ *
53
+ * Sources: "HM Treasury — 2026 pensions increase multiplier
54
+ * tables, covering note" and "HM Treasury — 2026 pensions
55
+ * increase multiplier tables, Annexes B and C" — see
56
+ * docs/source-archive.md. */
57
+ export function deferredRatePct(cpi) {
58
+ return Math.max(0, cpi);
59
+ }
60
+ /**
61
+ * The whole rule, in one factory.
62
+ *
63
+ * Takes a CPI READER rather than the whole table: the rule is a
64
+ * function of phase and a series, and WHICH series is the
65
+ * caller's question, not this one's. Whatever entry it is handed
66
+ * goes through unbranched — an Order's figure and an assumption
67
+ * are the same arithmetic here, and differ only in the
68
+ * provenance carried out beside the rate.
69
+ *
70
+ * Nothing in a projection calls this directly; both the walk and
71
+ * the seed go through `openingUpliftFor`, which fixes the series
72
+ * once so they cannot choose differently.
73
+ *
74
+ * That the published rates ARE `CPI + 1.5` is not asserted here,
75
+ * because nothing here reads them: the rule is checked against
76
+ * the TABLE, on all eleven rows at once, by
77
+ * `tests/prices.test.ts` — "reproduces every published rate, 11
78
+ * of 11". That check owns it, and it fires whether or not any
79
+ * caller ever asks for a published year.
80
+ */
81
+ export function upliftsFor(phase, cpiFor) {
82
+ const ratePct = phase === 'active'
83
+ ? activeRatePct
84
+ : deferredRatePct;
85
+ return (schemeYearEnd) => {
86
+ const from = cpiFor(schemeYearEnd);
87
+ return {
88
+ appliedOn: appliedOnFor(schemeYearEnd),
89
+ percent: ratePct(from.cpi),
90
+ from,
91
+ };
92
+ };
93
+ }
94
+ /**
95
+ * The uplift that OPENS the scheme year after
96
+ * `seedSchemeYearEnd` — the one question the seed and the walk
97
+ * must never answer differently.
98
+ *
99
+ * A seed is a balance standing at a year end and the walk's
100
+ * first step revalues it; `seedFromBalanceAt` divides that same
101
+ * step back out of a figure read mid-year. Three coordinates
102
+ * settle the answer — the phase the member is in for the year
103
+ * being OPENED, the year the rate is labelled by, and the CPI
104
+ * series it is read from — and a difference in any one of them
105
+ * stops a member's own stated balance round-tripping, with
106
+ * nothing in the output to show it. Hence one producer that both
107
+ * call: a coordinate spelled out twice is a coordinate that can
108
+ * drift.
109
+ *
110
+ * The rate is labelled by the year that just ENDED, which is why
111
+ * the seed's own year is the argument: SI 2016/438, applied 1
112
+ * April 2016, opens the year ending 31 March 2017. The
113
+ * off-by-one is the scheme's, not ours.
114
+ *
115
+ * ── One rate after the seed ─────────────────────────
116
+ *
117
+ * `assumedFor` is read for every year, whether or not an Order
118
+ * covers it. An Order is a NOMINAL rate, and today's money is
119
+ * this same model at an assumption of ZERO, so one applied
120
+ * inside that run puts a whole year of CPI into a reading
121
+ * defined to hold none — 8.2 points for a member holding a 2024
122
+ * statement, 3.2 for a 2025 one, so the size of it is a property
123
+ * of the paperwork rather than of the member. Nor is the
124
+ * exactness collectable: the year-end figure an Order produces
125
+ * here also carries this library's guess at that year's pay, so
126
+ * there is nothing to check it against until a statement the
127
+ * member has not received.
128
+ *
129
+ * Decided at https://github.com/casomoltd/nhs-pay/issues/13
130
+ */
131
+ export function openingUpliftFor(seedSchemeYearEnd, exitDate, retirementDate, prices) {
132
+ const phase = phaseAt(seedSchemeYearEnd + 1, schemeYearEndFor(exitDate), schemeYearEndFor(retirementDate));
133
+ return upliftsFor(phase, prices.assumedFor)(seedSchemeYearEnd);
134
+ }
135
+ //# sourceMappingURL=uplift.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"uplift.js","sourceRoot":"","sources":["../../src/pension/uplift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,sBAAsB,EACtB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAkB3C;;;;;oBAKoB;AACpB,MAAM,UAAU,OAAO,CACrB,IAAY,EAAE,QAAgB,EAAE,UAAkB;IAElD,IAAI,IAAI,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACtC,OAAO,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;AACtD,CAAC;AAgCD;kEACkE;AAClE,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,GAAG,GAAG,sBAAsB,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;6BAc6B;AAC7B,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CACxB,KAAkB,EAClB,MAAiB;IAEjB,MAAM,OAAO,GAAG,KAAK,KAAK,QAAQ;QAChC,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,eAAe,CAAC;IAEpB,OAAO,CAAC,aAAa,EAAE,EAAE;QACvB,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;QACnC,OAAO;YACL,SAAS,EAAE,YAAY,CAAC,aAAa,CAAC;YACtC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;YAC1B,IAAI;SACL,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,gBAAgB,CAC9B,iBAAyB,EACzB,QAAc,EACd,cAAoB,EACpB,MAAc;IAEd,MAAM,KAAK,GAAG,OAAO,CACnB,iBAAiB,GAAG,CAAC,EACrB,gBAAgB,CAAC,QAAQ,CAAC,EAC1B,gBAAgB,CAAC,cAAc,CAAC,CACjC,CAAC;IACF,OAAO,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,iBAAiB,CAAC,CAAC;AACjE,CAAC"}
@@ -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,38 +128,69 @@
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
  */
157
+ import type { EstimatedHistory } from './pension/history.js';
158
+ import type { MemberLedger } from './pension/ledger.js';
159
+ import type { MemberPhase } from './pension/uplift.js';
95
160
  import type { FactorProvenance, FactorTableKind } from './gad/factor-table.js';
96
161
  /**
97
- * One figure in both rulers. Every scalar the projection
98
- * reports is a pair, so a consumer picks a ruler rather than
99
- * doing CPI arithmetic of its own — and so it can never apply
100
- * the wrong horizon to a figure, because each pair was scaled
101
- * against the date its own figure falls on.
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.
102
180
  */
103
181
  export interface ProjectionMoney {
104
- /** Today's money — the projection's native ruler. */
105
- readonly real: number;
106
- /** Actual pounds, at the date this figure falls on. */
182
+ /** Actual pounds at `asAt`, the pension revalued at CPI plus
183
+ * 1.5 points a year while accruing. */
107
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;
108
194
  }
109
195
  /** A point on the projection curve */
110
196
  export interface ProjectionPoint {
@@ -116,8 +202,15 @@ export interface ProjectionPoint {
116
202
  /** Annual pension in today's £ — what the projection
117
203
  * computes; `nominal` is this scaled by CPI. */
118
204
  real: number;
119
- /** 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. */
120
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;
121
214
  }
122
215
  /** Input for statement path */
123
216
  export interface PensionStatementInput {
@@ -135,6 +228,20 @@ export interface PensionStatementInput {
135
228
  statementDate?: Date;
136
229
  /** Current pensionable pay */
137
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;
138
245
  dateOfBirth: Date;
139
246
  /** Date member stops accruing (leaves NHS) */
140
247
  exitDate: Date;
@@ -172,12 +279,24 @@ export interface CommutationResult {
172
279
  }
173
280
  /** Full projection result */
174
281
  export interface PensionProjectionResult {
175
- /** Accrued pension at exit date, scaled at the EXIT date */
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". */
176
285
  accruedAtExit: ProjectionMoney;
177
286
  /** After revaluation, before ERF/LRF, at retirement */
178
287
  revaluedAtRetirement: ProjectionMoney;
179
288
  /** After ERF/LRF, at retirement */
180
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;
181
300
  /** ERF or LRF factor applied */
182
301
  factor: number;
183
302
  factorType: FactorTableKind | 'none';
@@ -187,11 +306,47 @@ export interface PensionProjectionResult {
187
306
  curve: ProjectionPoint[];
188
307
  /** Whether estimation path was used */
189
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;
190
333
  }
191
334
  /** 1/54 accrual rate — NHS 2015 CARE scheme */
192
335
  export declare const ACCRUAL_RATE: number;
193
336
  /** Commutation: £12 lump sum per £1 pension */
194
337
  export declare const COMMUTATION_FACTOR = 12;
338
+ /**
339
+ * The most of a member's benefits HMRC lets them take as a
340
+ * tax-free lump sum, as a percentage.
341
+ *
342
+ * Exported because it is the only part of the commutation rule
343
+ * a member can be told directly — {@link maxLumpSum} is the cap
344
+ * in pounds, which answers "how much" but never "why that
345
+ * much". A consumer explaining the swap needs this figure, and
346
+ * a consumer that writes its own copy of it is one that can
347
+ * drift from the library that applies it.
348
+ */
349
+ export declare const HMRC_LUMP_SUM_CAP_PCT = 25;
195
350
  /**
196
351
  * Provenance of the in-force table behind a factor kind — the
197
352
  * citation facts (table ref, guidance name, issue date, source
@@ -217,8 +372,22 @@ export declare function yearlyAccrual(pensionablePay: number): number;
217
372
  */
218
373
  export declare function revalue(pension: number, annualRate: number, years: number): number;
219
374
  /**
220
- * Maximum tax-free lump sum under HMRC 25% rule.
221
- * Formula: (20 × pension) / (3 + 20/commutationFactor)
375
+ * Maximum tax-free lump sum under the HMRC cap.
376
+ *
377
+ * The cap is on the lump sum as a share of the CAPITAL VALUE of
378
+ * the benefits, and taking a lump sum lowers the pension that
379
+ * value is measured from — so the answer is a fixed point, not
380
+ * a percentage of anything the caller already holds. With `c`
381
+ * the cap and `f` the commutation factor, capital value is
382
+ * `20 × residual + lumpSum`, and solving
383
+ *
384
+ * L = c × (20 × (P − L/f) + L)
385
+ *
386
+ * for L gives the expression below. Written from
387
+ * {@link HMRC_LUMP_SUM_CAP_PCT} rather than from its
388
+ * rearrangement — the familiar `(20P) / (3 + 20/f)` is this
389
+ * same solution with `c = 0.25` already substituted in, which
390
+ * hides the one number a reader would want to check.
222
391
  */
223
392
  export declare function maxLumpSum(adjustedPension: number): number;
224
393
  /**