@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.
- package/README.md +48 -0
- package/dist/award.d.ts +8 -8
- package/dist/award.js +8 -8
- package/dist/circulars/england-md-1-2026r.d.ts +2 -3
- package/dist/circulars/england-md-1-2026r.js +2 -3
- package/dist/circulars/england-md-1-2026r.js.map +1 -1
- package/dist/circulars/ni-hsc-tc8-05-2025.d.ts +2 -2
- package/dist/circulars/ni-hsc-tc8-05-2025.js +2 -2
- package/dist/circulars/scotland-pcs-dd-2025-01.d.ts +2 -3
- package/dist/circulars/scotland-pcs-dd-2025-01.js +2 -3
- package/dist/circulars/scotland-pcs-dd-2025-01.js.map +1 -1
- package/dist/circulars/scotland-pcs-dd-2026-01.d.ts +2 -2
- package/dist/circulars/scotland-pcs-dd-2026-01.js +2 -2
- package/dist/circulars/wales-mdw-01-2025.d.ts +2 -2
- package/dist/circulars/wales-mdw-01-2025.js +2 -2
- package/dist/circulars/wales-mdw-01-2026.d.ts +2 -2
- package/dist/circulars/wales-mdw-01-2026.js +2 -2
- package/dist/gad/erf-2023-06-30.d.ts +39 -3
- package/dist/gad/erf-2023-06-30.js +39 -3
- package/dist/gad/erf-2023-06-30.js.map +1 -1
- package/dist/gad/factor-table.d.ts +10 -0
- package/dist/gad/factor-table.js.map +1 -1
- package/dist/gad/lrf-2023-06-30.d.ts +39 -3
- package/dist/gad/lrf-2023-06-30.js +39 -3
- package/dist/gad/lrf-2023-06-30.js.map +1 -1
- package/dist/hcas-pcts.js +3 -1
- package/dist/hcas-pcts.js.map +1 -1
- package/dist/index.d.ts +11 -3
- package/dist/index.js +9 -2
- package/dist/index.js.map +1 -1
- package/dist/pension/history.d.ts +105 -0
- package/dist/pension/history.js +115 -0
- package/dist/pension/history.js.map +1 -0
- package/dist/pension/ledger.d.ts +146 -0
- package/dist/pension/ledger.js +193 -0
- package/dist/pension/ledger.js.map +1 -0
- package/dist/pension/prices.d.ts +125 -0
- package/dist/pension/prices.js +108 -0
- package/dist/pension/prices.js.map +1 -0
- package/dist/pension/seed.d.ts +75 -0
- package/dist/pension/seed.js +82 -0
- package/dist/pension/seed.js.map +1 -0
- package/dist/pension/uplift.d.ts +151 -0
- package/dist/pension/uplift.js +135 -0
- package/dist/pension/uplift.js.map +1 -0
- package/dist/pension-projection.d.ts +217 -48
- package/dist/pension-projection.js +394 -202
- package/dist/pension-projection.js.map +1 -1
- package/dist/pension.js +9 -10
- package/dist/pension.js.map +1 -1
- package/dist/post.d.ts +24 -16
- package/dist/post.js +2 -3
- package/dist/post.js.map +1 -1
- package/dist/revaluation.d.ts +119 -30
- package/dist/revaluation.js +175 -29
- package/dist/revaluation.js.map +1 -1
- package/dist/scales.d.ts +17 -10
- package/dist/scales.js +17 -10
- package/dist/scales.js.map +1 -1
- package/dist/take-home.d.ts +9 -5
- package/dist/take-home.js +9 -5
- package/dist/take-home.js.map +1 -1
- package/package.json +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
|
-
* ──
|
|
30
|
-
*
|
|
31
|
-
* Everything
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
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
|
-
*
|
|
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. `
|
|
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
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
90
|
-
*
|
|
91
|
-
*
|
|
92
|
-
*
|
|
93
|
-
*
|
|
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
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
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
|
-
/**
|
|
105
|
-
|
|
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
|
|
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
|
|
221
|
-
*
|
|
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
|
/**
|