@casomoltd/nhs-pay 0.13.2 → 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +656 -160
- package/README.md +70 -6
- package/dist/commutation.d.ts +331 -0
- package/dist/commutation.js +324 -0
- package/dist/commutation.js.map +1 -0
- package/dist/index.d.ts +5 -2
- package/dist/index.js +6 -1
- package/dist/index.js.map +1 -1
- package/dist/pension/money.d.ts +34 -0
- package/dist/pension/money.js +2 -0
- package/dist/pension/money.js.map +1 -0
- package/dist/pension/prices.d.ts +25 -3
- package/dist/pension/prices.js +6 -1
- package/dist/pension/prices.js.map +1 -1
- package/dist/pension-projection.d.ts +14 -80
- package/dist/pension-projection.js +8 -58
- package/dist/pension-projection.js.map +1 -1
- package/package.json +2 -2
|
@@ -0,0 +1,324 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Commutation — exchanging annual pension for a tax-free lump
|
|
3
|
+
* sum, and the caps on how much of it may be taken.
|
|
4
|
+
*
|
|
5
|
+
* Separate from the projection because it IS separate: nothing
|
|
6
|
+
* in `pension-projection.ts` calls into here and the ledger
|
|
7
|
+
* applies no commutation. It is a choice taken AT retirement, on
|
|
8
|
+
* a pension the projection has already finished producing. It
|
|
9
|
+
* borrows one thing, by type only: the `Prices` the projection
|
|
10
|
+
* ran with, so the allowance is carried forward at the SAME
|
|
11
|
+
* assumption the pension was projected at and cannot silently
|
|
12
|
+
* use another.
|
|
13
|
+
*
|
|
14
|
+
* ── Only one figure here is an NHS rule ─────────────
|
|
15
|
+
*
|
|
16
|
+
* The commutation RATE — £12 of cash per £1 of pension — is the
|
|
17
|
+
* scheme's own. The three caps are statutory and bind every
|
|
18
|
+
* registered pension scheme in the UK: the 25% of capital value,
|
|
19
|
+
* the 20:1 factor that capital value is measured with, and the
|
|
20
|
+
* Lump Sum Allowance. They are grouped apart below, and the
|
|
21
|
+
* scheme's rate is passed to the solver as a parameter rather
|
|
22
|
+
* than read from the module, so the statutory half can move to a
|
|
23
|
+
* scheme-neutral home without a redesign.
|
|
24
|
+
*/
|
|
25
|
+
import { invariant } from './errors.js';
|
|
26
|
+
// ── The scheme's own rule ───────────────────────────
|
|
27
|
+
/**
|
|
28
|
+
* Commutation: £12 lump sum per £1 of annual pension given up.
|
|
29
|
+
*
|
|
30
|
+
* The NHS scheme's rate. Other schemes commute at other rates,
|
|
31
|
+
* which is why {@link lumpSumLimit} takes it as an argument
|
|
32
|
+
* instead of reading it here.
|
|
33
|
+
*
|
|
34
|
+
* Source: NHSBSA Key Notes, 2015 Scheme Estimates (V2) —
|
|
35
|
+
* **not archived**; see docs/how-it-works.md's source table.
|
|
36
|
+
* NHSBSA states the same terms to members, publicly, at
|
|
37
|
+
* <https://www.nhsbsa.nhs.uk/employee-section/
|
|
38
|
+
* understanding-your-statement/maximum-lump-sum> ("reducing your
|
|
39
|
+
* pension by £1 for every £12"). Named here as well as in the
|
|
40
|
+
* table because the Key Notes document has no public URL, so
|
|
41
|
+
* without it this constant is the one figure in the module a
|
|
42
|
+
* reader cannot go and check.
|
|
43
|
+
*/
|
|
44
|
+
export const COMMUTATION_FACTOR = 12;
|
|
45
|
+
// ── HMRC's rules ────────────────────────────────────
|
|
46
|
+
// None of the three below is an NHS rule. They are limbs of one
|
|
47
|
+
// statutory test — Schedule 29 Finance Act 2004, paragraphs 2
|
|
48
|
+
// and 2C — which makes the permitted maximum the LOWER of the
|
|
49
|
+
// applicable amount and the member's available allowance.
|
|
50
|
+
/**
|
|
51
|
+
* The most of a member's benefits HMRC lets them take as a
|
|
52
|
+
* tax-free lump sum, as a percentage.
|
|
53
|
+
*
|
|
54
|
+
* Exported because it is the only part of the commutation rule
|
|
55
|
+
* a member can be told directly — {@link lumpSumLimit} is the
|
|
56
|
+
* cap in pounds, which answers "how much" but never "why that
|
|
57
|
+
* much". A consumer explaining the swap needs this figure, and
|
|
58
|
+
* a consumer that writes its own copy of it is one that can
|
|
59
|
+
* drift from the library that applies it.
|
|
60
|
+
*
|
|
61
|
+
* THIS IS THE FORM THE STATUTE USES. Schedule 29 FA 2004
|
|
62
|
+
* paragraph 2C gives the defined-benefits applicable amount as
|
|
63
|
+
* `(A + (B × C)) / 4`, where A is the amount of the lump sum, B
|
|
64
|
+
* is the relevant valuation factor ({@link VALUATION_FACTOR})
|
|
65
|
+
* and C is the pension payable in the 12 months beginning with
|
|
66
|
+
* the day the member becomes entitled to it. `A + (B × C)` IS
|
|
67
|
+
* the capital value, so a quarter of it is this constant.
|
|
68
|
+
*
|
|
69
|
+
* Two things follow, and both are load-bearing. C is the pension
|
|
70
|
+
* AFTER commutation, which is what makes the cap a fixed point
|
|
71
|
+
* rather than a percentage of anything the caller already holds.
|
|
72
|
+
* And the one-third-of-the-remaining-pension form that guidance
|
|
73
|
+
* often quotes is this same rule solved for A: 4A = A + (B × C)
|
|
74
|
+
* gives A = B × C / 3. Both reach 30P/7 at a 12:1 rate, verified
|
|
75
|
+
* numerically either way. Do NOT "correct" this constant to a
|
|
76
|
+
* third — it would be the same number and the wrong citation.
|
|
77
|
+
*
|
|
78
|
+
* Source: Schedule 29 Finance Act 2004, paragraphs 2 (the
|
|
79
|
+
* permitted maximum is the LOWEST of three amounts) and 2C (the
|
|
80
|
+
* defined-benefits applicable amount, which invokes B by
|
|
81
|
+
* reference to s.276 rather than restating 20). Verified against
|
|
82
|
+
* the Act on 27 August 2026. Paragraph 2C's formula is published
|
|
83
|
+
* as an image, so its shape is corroborated by the variable
|
|
84
|
+
* definitions in the surrounding text and by HMRC's own
|
|
85
|
+
* 20P / (3 + 20/CF), which agrees to the penny.
|
|
86
|
+
*/
|
|
87
|
+
export const HMRC_LUMP_SUM_CAP_PCT = 25;
|
|
88
|
+
/**
|
|
89
|
+
* The statutory factor turning an annual defined-benefit pension
|
|
90
|
+
* into a capital value: capital value is 20 × annual pension.
|
|
91
|
+
*
|
|
92
|
+
* Named because it is a RULE, not arithmetic. A statutory
|
|
93
|
+
* factor written as a bare `20` inside an expression is
|
|
94
|
+
* invisible to a search, to a citation and to a test, and reads
|
|
95
|
+
* as a coefficient someone chose.
|
|
96
|
+
*
|
|
97
|
+
* Reached by reference, not by repetition: Schedule 29 paragraph
|
|
98
|
+
* 2C names "the relevant valuation factor" as its B rather than
|
|
99
|
+
* writing 20 into the lump sum rule, so the factor and the cap
|
|
100
|
+
* are one rule in two provisions and a change to s.276 would
|
|
101
|
+
* move the cap without touching Schedule 29.
|
|
102
|
+
*
|
|
103
|
+
* Source: Finance Act 2004 s.276, "Relevant valuation factor":
|
|
104
|
+
* "the relevant valuation factor in relation to any registered
|
|
105
|
+
* pension scheme, or any arrangement under a registered pension
|
|
106
|
+
* scheme, is 20", unless a higher one is agreed with HMRC.
|
|
107
|
+
* Verified against the Act on 27 August 2026.
|
|
108
|
+
*/
|
|
109
|
+
export const VALUATION_FACTOR = 20;
|
|
110
|
+
/**
|
|
111
|
+
* The Lump Sum Allowance: the absolute cap on tax-free pension
|
|
112
|
+
* cash, in pounds.
|
|
113
|
+
*
|
|
114
|
+
* £268,275 since 6 April 2024, when it replaced the Lifetime
|
|
115
|
+
* Allowance. FROZEN IN LAW — it is not indexed, so its real
|
|
116
|
+
* value erodes every year it stands.
|
|
117
|
+
*
|
|
118
|
+
* "Frozen" states the LAW, not how a projection should treat it.
|
|
119
|
+
* Whether to carry this figure forward in real terms is the
|
|
120
|
+
* CALLER's assumption, declared through
|
|
121
|
+
* {@link CommutationLimits.allowance}. Do not read this comment
|
|
122
|
+
* as an instruction to hold the figure fixed in cash.
|
|
123
|
+
*
|
|
124
|
+
* This is the STANDARD allowance. A member holding a Lifetime
|
|
125
|
+
* Allowance protection has a higher one — HMRC PTM174700 puts
|
|
126
|
+
* fixed protection 2016 at £312,500, 2014 at £375,000 and 2012
|
|
127
|
+
* at £450,000, with the other classes worked out per member.
|
|
128
|
+
* None of them is modelled here and none is detectable from
|
|
129
|
+
* what this library is given.
|
|
130
|
+
*
|
|
131
|
+
* Source: ITEPA 2003 s.637P, verified against the Act on
|
|
132
|
+
* 27 August 2026 — <https://www.legislation.gov.uk/ukpga/2003/1/
|
|
133
|
+
* part/9/chapter/15A>. Cited to the instrument rather than to
|
|
134
|
+
* HMRC's Pensions Tax Manual, which is written for
|
|
135
|
+
* administrators and gave the wrong section number when this
|
|
136
|
+
* figure was first transcribed. Its source-archive row is in
|
|
137
|
+
* docs/how-it-works.md.
|
|
138
|
+
*/
|
|
139
|
+
export const LUMP_SUM_ALLOWANCE = 268275;
|
|
140
|
+
// ── Which limb bound ────────────────────────────────
|
|
141
|
+
/**
|
|
142
|
+
* The two limbs of the permitted maximum, as a const object so
|
|
143
|
+
* the keys are reachable at a call site instead of a bare
|
|
144
|
+
* literal repeated across modules.
|
|
145
|
+
*
|
|
146
|
+
* `Scheme` IS A MISLEADING NAME AND IS KNOWN TO BE. Both limbs
|
|
147
|
+
* are statutory and bind every registered pension scheme in the
|
|
148
|
+
* UK; the scheme's only contribution to this swap is
|
|
149
|
+
* {@link COMMUTATION_FACTOR}. The name has already leaked into
|
|
150
|
+
* prose that told members "the scheme stops the swap at 25%",
|
|
151
|
+
* which was wrong wherever it appeared.
|
|
152
|
+
*
|
|
153
|
+
* It is not renamed in place on purpose. The whole statutory
|
|
154
|
+
* half of this module moves to the UK-tax library
|
|
155
|
+
* (casomoltd/nhs-pay#15, casomoltd/paye-calc#30), and renaming
|
|
156
|
+
* here as well would spend two breaking changes on one defect.
|
|
157
|
+
* When the rule lands in its new home the key should be named
|
|
158
|
+
* for the statute — `Applicable`, after the applicable amount
|
|
159
|
+
* in Schedule 29 paragraph 2C.
|
|
160
|
+
*
|
|
161
|
+
* Until then: read `Scheme` as the name of a discriminant, not
|
|
162
|
+
* as an attribution, and never render it to a member.
|
|
163
|
+
*/
|
|
164
|
+
export const LUMP_SUM_CAPS = {
|
|
165
|
+
Scheme: 'scheme',
|
|
166
|
+
Allowance: 'allowance',
|
|
167
|
+
};
|
|
168
|
+
/**
|
|
169
|
+
* The NHS binding of {@link CommutationLimits}.
|
|
170
|
+
*
|
|
171
|
+
* Every field of that interface is required so a non-NHS caller
|
|
172
|
+
* cannot inherit an NHS default by omitting one. That stops a
|
|
173
|
+
* field being LEFT OUT; it does nothing to stop several call
|
|
174
|
+
* sites each assembling the same NHS combination by hand and one
|
|
175
|
+
* of them getting it subtly wrong — a different `asAt`, a
|
|
176
|
+
* `createPrices` of its own, a literal `12`. Two consumers
|
|
177
|
+
* already spelled the date two ways.
|
|
178
|
+
*
|
|
179
|
+
* So the combination is published once, here, beside the
|
|
180
|
+
* constants it pairs. Pass the `prices` your own projection
|
|
181
|
+
* returned; the allowance is stated at that run's anchor,
|
|
182
|
+
* because these are the prices that will convert it and
|
|
183
|
+
* anchoring it anywhere else converts it across a gap the
|
|
184
|
+
* projection never travelled.
|
|
185
|
+
*/
|
|
186
|
+
export function nhsCommutationLimits(prices) {
|
|
187
|
+
return {
|
|
188
|
+
commutationFactor: COMMUTATION_FACTOR,
|
|
189
|
+
allowance: { amount: LUMP_SUM_ALLOWANCE, asAt: prices.asOf },
|
|
190
|
+
prices,
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
// ── The permitted maximum ───────────────────────────
|
|
194
|
+
/**
|
|
195
|
+
* The permitted maximum tax-free lump sum: the LOWER of the
|
|
196
|
+
* scheme's 25%-of-capital-value limb and the lump sum allowance.
|
|
197
|
+
*
|
|
198
|
+
* One statutory test, not two rules bolted together, so the
|
|
199
|
+
* `min` below is the rule rather than a convenience.
|
|
200
|
+
*
|
|
201
|
+
* The scheme limb is a fixed point, not a percentage of anything
|
|
202
|
+
* the caller already holds: the cap is on the lump sum as a
|
|
203
|
+
* share of the CAPITAL VALUE of the benefits, and taking a lump
|
|
204
|
+
* sum lowers the pension that value is measured from. With `c`
|
|
205
|
+
* the cap, `v` the valuation factor and `f` the commutation
|
|
206
|
+
* factor, capital value is `v × residual + lumpSum`, and solving
|
|
207
|
+
*
|
|
208
|
+
* L = c × (v × (P − L/f) + L)
|
|
209
|
+
*
|
|
210
|
+
* for L gives the expression below. Written from the named
|
|
211
|
+
* constants rather than from its rearrangement — the familiar
|
|
212
|
+
* `(20P) / (3 + 20/f)` is this same solution with `c = 0.25`
|
|
213
|
+
* already substituted in, which hides the one number a reader
|
|
214
|
+
* would want to check.
|
|
215
|
+
*
|
|
216
|
+
* Module-private, and deliberately so: it solves ONE ruler, so
|
|
217
|
+
* both money arguments must already be in that ruler. Exporting
|
|
218
|
+
* it would put a pair of bare, ruler-less numbers on the public
|
|
219
|
+
* API — the very thing {@link DatedAmount} exists to prevent.
|
|
220
|
+
* Consumers get both rulers' limits from {@link commute}.
|
|
221
|
+
*/
|
|
222
|
+
function lumpSumLimit({ pension, allowance, commutationFactor }) {
|
|
223
|
+
if (commutationFactor <= 0) {
|
|
224
|
+
throw new RangeError(`Commutation factor must be positive, got `
|
|
225
|
+
+ `${commutationFactor}`);
|
|
226
|
+
}
|
|
227
|
+
if (pension < 0 || allowance < 0) {
|
|
228
|
+
throw new RangeError(`Pension and allowance must be non-negative, got `
|
|
229
|
+
+ `${pension} and ${allowance}`);
|
|
230
|
+
}
|
|
231
|
+
const cap = HMRC_LUMP_SUM_CAP_PCT / 100;
|
|
232
|
+
const schemeMax = (VALUATION_FACTOR * cap * pension)
|
|
233
|
+
/ (1 - cap + (VALUATION_FACTOR * cap) / commutationFactor);
|
|
234
|
+
// One comparison decides both the figure and the reason, so
|
|
235
|
+
// the two cannot drift into disagreeing.
|
|
236
|
+
const boundByAllowance = allowance <= schemeMax;
|
|
237
|
+
const amount = boundByAllowance ? allowance : schemeMax;
|
|
238
|
+
/* The statute caps the lump sum at a quarter of the capital
|
|
239
|
+
value of the benefits crystallised. This solves that
|
|
240
|
+
as a fixed point, so checking the SOLVED form would prove
|
|
241
|
+
only that the rearrangement agrees with itself; checking the
|
|
242
|
+
ORIGINAL form proves the rearrangement is right. This is the
|
|
243
|
+
one guard here that could fail without the line above it
|
|
244
|
+
already being obviously wrong.
|
|
245
|
+
|
|
246
|
+
The tolerance is not slack: at the scheme limb the two sides
|
|
247
|
+
are EQUAL, and float leaves them differing by up to ~6e-11
|
|
248
|
+
in either direction across the realistic range. */
|
|
249
|
+
const capitalValue = VALUATION_FACTOR * (pension - amount / commutationFactor)
|
|
250
|
+
+ amount;
|
|
251
|
+
invariant(amount - cap * capitalValue <= Math.abs(capitalValue) * 1e-9, `Lump sum ${amount} exceeds ${HMRC_LUMP_SUM_CAP_PCT}% of `
|
|
252
|
+
+ `capital value ${capitalValue} — the fixed point is wrong`);
|
|
253
|
+
return {
|
|
254
|
+
amount,
|
|
255
|
+
sharePct: capitalValue === 0
|
|
256
|
+
? 0
|
|
257
|
+
: (amount / capitalValue) * 100,
|
|
258
|
+
binding: boundByAllowance
|
|
259
|
+
? LUMP_SUM_CAPS.Allowance
|
|
260
|
+
: LUMP_SUM_CAPS.Scheme,
|
|
261
|
+
schemeMax,
|
|
262
|
+
allowance,
|
|
263
|
+
};
|
|
264
|
+
}
|
|
265
|
+
// ── Commutation ─────────────────────────────────────
|
|
266
|
+
/**
|
|
267
|
+
* Commutation at a fraction of the permitted maximum, reported
|
|
268
|
+
* in both rulers.
|
|
269
|
+
*
|
|
270
|
+
* Takes the pension as a {@link ProjectionMoney} rather than a
|
|
271
|
+
* bare number so the ruler travels with the money. A dateless
|
|
272
|
+
* figure cannot say which ruler it is in, and the allowance is a
|
|
273
|
+
* cash amount tested on a date — so the two could only be
|
|
274
|
+
* compared by assuming, which is the defect this signature
|
|
275
|
+
* removes.
|
|
276
|
+
*
|
|
277
|
+
* ERF/LRF is applied BEFORE commutation (§1.18), so `pension` is
|
|
278
|
+
* the pension at retirement after any factor.
|
|
279
|
+
*/
|
|
280
|
+
export function commute(pension, fraction, limits) {
|
|
281
|
+
if (!(fraction >= 0 && fraction <= 1)) {
|
|
282
|
+
// A caller's mistake, not a library bug, so not `invariant`:
|
|
283
|
+
// see the note at the top of errors.ts.
|
|
284
|
+
throw new RangeError(`Commutation fraction must be 0–1, got ${fraction}`);
|
|
285
|
+
}
|
|
286
|
+
const { allowance, prices, commutationFactor } = limits;
|
|
287
|
+
// The allowance is a real-terms constant: the today's-money
|
|
288
|
+
// run tests its stated value, the cash run tests the same cap
|
|
289
|
+
// carried to the pension's own date.
|
|
290
|
+
const today = lumpSumLimit({
|
|
291
|
+
pension: pension.real,
|
|
292
|
+
// Into the ruler the today's-money reading is anchored in —
|
|
293
|
+
// the run date. Usually the identity, because that is where
|
|
294
|
+
// a caller states the allowance; not assumed to be.
|
|
295
|
+
allowance: prices.valueAt(allowance.amount, allowance.asAt, prices.asOf),
|
|
296
|
+
commutationFactor,
|
|
297
|
+
});
|
|
298
|
+
const cash = lumpSumLimit({
|
|
299
|
+
pension: pension.nominal,
|
|
300
|
+
allowance: prices.valueAt(allowance.amount, allowance.asAt, pension.asAt),
|
|
301
|
+
commutationFactor,
|
|
302
|
+
});
|
|
303
|
+
/* Takes the object, not two same-typed positional numbers: a
|
|
304
|
+
transposition would swap the rulers silently. */
|
|
305
|
+
const pair = (m) => ({ ...m, asAt: pension.asAt });
|
|
306
|
+
const lumpSum = pair({
|
|
307
|
+
real: today.amount * fraction,
|
|
308
|
+
nominal: cash.amount * fraction,
|
|
309
|
+
});
|
|
310
|
+
const pensionGivenUp = pair({
|
|
311
|
+
real: lumpSum.real / commutationFactor,
|
|
312
|
+
nominal: lumpSum.nominal / commutationFactor,
|
|
313
|
+
});
|
|
314
|
+
return {
|
|
315
|
+
lumpSum,
|
|
316
|
+
pensionGivenUp,
|
|
317
|
+
residualPension: pair({
|
|
318
|
+
real: pension.real - pensionGivenUp.real,
|
|
319
|
+
nominal: pension.nominal - pensionGivenUp.nominal,
|
|
320
|
+
}),
|
|
321
|
+
limit: { real: today, nominal: cash },
|
|
322
|
+
};
|
|
323
|
+
}
|
|
324
|
+
//# sourceMappingURL=commutation.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"commutation.js","sourceRoot":"","sources":["../src/commutation.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
CHANGED
|
@@ -17,10 +17,13 @@ export { AwardUnavailable, PensionTiersUnavailable, RetirementFactorOutOfRange,
|
|
|
17
17
|
export { afcAward } from './award.js';
|
|
18
18
|
export { ACTIVE_REVAL_BONUS_PCT, IN_SERVICE_REVALUATION, revaluationFor, } from './revaluation.js';
|
|
19
19
|
export type { RevaluationYear } from './revaluation.js';
|
|
20
|
-
export { ACCRUAL_RATE,
|
|
20
|
+
export { ACCRUAL_RATE, factorProvenance, projectPension, retirementFactor, yearlyAccrual, } from './pension-projection.js';
|
|
21
|
+
export { COMMUTATION_FACTOR, HMRC_LUMP_SUM_CAP_PCT, LUMP_SUM_ALLOWANCE, LUMP_SUM_CAPS, nhsCommutationLimits, VALUATION_FACTOR, commute, } from './commutation.js';
|
|
22
|
+
export type { CommutationLimits, CommutationResult, DatedAmount, LumpSumCap, LumpSumLimit, LumpSumLimits, } from './commutation.js';
|
|
21
23
|
export type { FactorProvenance, FactorTableKind, } from './gad/factor-table.js';
|
|
22
24
|
export { normalPensionAge } from './npa.js';
|
|
23
|
-
export type {
|
|
25
|
+
export type { PensionEstimationInput, PensionProjectionInput, PensionProjectionResult, PensionStatementInput, ProjectionPoint, } from './pension-projection.js';
|
|
26
|
+
export type { ProjectionMoney } from './pension/money.js';
|
|
24
27
|
export { createPrices } from './pension/prices.js';
|
|
25
28
|
export type { CpiEntry, CpiSource, Prices, } from './pension/prices.js';
|
|
26
29
|
export { activeRatePct, deferredRatePct, upliftsFor, } from './pension/uplift.js';
|
package/dist/index.js
CHANGED
|
@@ -23,7 +23,12 @@ export { ACTIVE_REVAL_BONUS_PCT, IN_SERVICE_REVALUATION, revaluationFor, } from
|
|
|
23
23
|
// rounding rules; factor PROVENANCE is data
|
|
24
24
|
// (factorProvenance), so consumers cite it, never
|
|
25
25
|
// hand-type it.
|
|
26
|
-
export { ACCRUAL_RATE,
|
|
26
|
+
export { ACCRUAL_RATE, factorProvenance, projectPension, retirementFactor, yearlyAccrual, } from './pension-projection.js';
|
|
27
|
+
// ── Commutation ──────────────────────────────────────
|
|
28
|
+
// Its own module: a choice taken AT retirement, on a pension
|
|
29
|
+
// the projection has already finished producing. Nothing in
|
|
30
|
+
// the projection calls into it.
|
|
31
|
+
export { COMMUTATION_FACTOR, HMRC_LUMP_SUM_CAP_PCT, LUMP_SUM_ALLOWANCE, LUMP_SUM_CAPS, nhsCommutationLimits, VALUATION_FACTOR, commute, } from './commutation.js';
|
|
27
32
|
// ── Normal pension age ───────────────────────────────
|
|
28
33
|
export { normalPensionAge } from './npa.js';
|
|
29
34
|
// ── The pension ledger ───────────────────────────────
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,OAAO,EACL,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,aAAa,CAAC;AAQrB,oDAAoD;AACpD,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,cAAc,CAAC;AAStB,oDAAoD;AACpD,OAAO,EAAC,IAAI,EAAE,cAAc,EAAC,MAAM,WAAW,CAAC;AAU/C,OAAO,EAAC,WAAW,EAAE,cAAc,EAAE,eAAe,EAAC,MAAM,eAAe,CAAC;AAS3E,oDAAoD;AACpD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAK5B,oDAAoD;AACpD,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AAEpC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAG1B,sDAAsD;AACtD,kDAAkD;AAClD,oDAAoD;AACpD,sDAAsD;AACtD,qDAAqD;AACrD,6CAA6C;AAC7C,qDAAqD;AACrD,4CAA4C;AAC5C,kDAAkD;AAClD,gBAAgB;AAChB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One figure under BOTH projections.
|
|
3
|
+
*
|
|
4
|
+
* Every scalar reported here is a pair, so a consumer picks a
|
|
5
|
+
* reading rather than doing CPI arithmetic of its own.
|
|
6
|
+
*
|
|
7
|
+
* **Neither reading is derived from the other.** They are two
|
|
8
|
+
* runs of the same model: `nominal` at the caller's inflation
|
|
9
|
+
* assumption, `real` with that assumption set to zero. So
|
|
10
|
+
* `real` is not `nominal` deflated, and dividing one by the
|
|
11
|
+
* other does not give the assumption back.
|
|
12
|
+
*
|
|
13
|
+
* That distinction is the whole of a long-running disagreement
|
|
14
|
+
* about a third of a percent. Deflating a CPI + 1.5 projection
|
|
15
|
+
* leaves 1.5 / (1 + cpi) of real growth — 1.47% at 2% — because
|
|
16
|
+
* the 1.5 points are added before the growth and eaten into by
|
|
17
|
+
* the same year's inflation. Running the model at zero gives
|
|
18
|
+
* 1.5% flat, which is what "ignore inflation" means and what
|
|
19
|
+
* every member's own arithmetic does.
|
|
20
|
+
*/
|
|
21
|
+
export interface ProjectionMoney {
|
|
22
|
+
/** Actual pounds at `asAt`, the pension revalued at CPI plus
|
|
23
|
+
* 1.5 points a year while accruing. */
|
|
24
|
+
readonly nominal: number;
|
|
25
|
+
/** Today's pounds: the same projection with inflation
|
|
26
|
+
* ignored, so 1.5% a year while accruing and flat once
|
|
27
|
+
* deferred. */
|
|
28
|
+
readonly real: number;
|
|
29
|
+
/** The date the figure falls on. Its absence is how a
|
|
30
|
+
* consumer once deflated an exit figure over the horizon to
|
|
31
|
+
* retirement: a figure that does not carry its own date
|
|
32
|
+
* cannot defend itself. */
|
|
33
|
+
readonly asAt: Date;
|
|
34
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"money.js","sourceRoot":"","sources":["../../src/pension/money.ts"],"names":[],"mappings":""}
|
package/dist/pension/prices.d.ts
CHANGED
|
@@ -67,9 +67,10 @@ export interface CpiEntry {
|
|
|
67
67
|
* makes that choice exactly once, in `openingUpliftFor`. */
|
|
68
68
|
export type CpiSource = (schemeYearEnd: number) => CpiEntry;
|
|
69
69
|
/** The rate a projection revalues at, and the money readings
|
|
70
|
-
* that follow from it.
|
|
71
|
-
*
|
|
72
|
-
*
|
|
70
|
+
* that follow from it. ONE conversion and a pinned convenience
|
|
71
|
+
* over it, plus the rate itself — reading the published record
|
|
72
|
+
* is `revaluation.ts`'s job, and a reader here would be a second
|
|
73
|
+
* answer to a question already answered. */
|
|
73
74
|
export interface Prices {
|
|
74
75
|
/**
|
|
75
76
|
* A scheme year read as the caller's ASSUMPTION, whatever the
|
|
@@ -92,6 +93,27 @@ export interface Prices {
|
|
|
92
93
|
* anything having to enforce it.
|
|
93
94
|
*/
|
|
94
95
|
payAt(todaysMoney: number, asAt: Date): number;
|
|
96
|
+
/** The date this run's today's-money readings are anchored
|
|
97
|
+
* at — the run date. Named so a caller converting an external
|
|
98
|
+
* figure INTO that ruler has a target to convert to, rather
|
|
99
|
+
* than assuming one. */
|
|
100
|
+
readonly asOf: Date;
|
|
101
|
+
/**
|
|
102
|
+
* An amount stated on one date, expressed in the money of
|
|
103
|
+
* another. `payAt` is this with `from` pinned to the run date.
|
|
104
|
+
*
|
|
105
|
+
* NARROW BY INTENT, and read the header above before reaching
|
|
106
|
+
* for it. It carries an EXTERNALLY FIXED cash amount — a
|
|
107
|
+
* statutory cap, a target income — into another year's money.
|
|
108
|
+
* NOT for figures the projection reports: those already arrive
|
|
109
|
+
* in both rulers, and converting one here would produce a
|
|
110
|
+
* second today's money, free to disagree with the run that
|
|
111
|
+
* produced it.
|
|
112
|
+
*
|
|
113
|
+
* On `Prices` rather than loose, so it cannot be called with
|
|
114
|
+
* an assumption that disagrees with the run's.
|
|
115
|
+
*/
|
|
116
|
+
valueAt(amount: number, from: Date, to: Date): number;
|
|
95
117
|
}
|
|
96
118
|
/**
|
|
97
119
|
* How much more a pound of `asAt` money is than a pound of
|
package/dist/pension/prices.js
CHANGED
|
@@ -97,6 +97,7 @@ function aprilsBetween(from, to) {
|
|
|
97
97
|
*/
|
|
98
98
|
export function createPrices(assumedCpi, asOf) {
|
|
99
99
|
const assumedPct = assumedCpi * 100;
|
|
100
|
+
const valueAt = (amount, from, to) => amount * inflationFactor(to, from, assumedCpi);
|
|
100
101
|
return {
|
|
101
102
|
/* Frozen at the mint. A `CpiEntry` is the provenance a
|
|
102
103
|
ledger row's rate is READ from rather than a copy of, so
|
|
@@ -106,7 +107,11 @@ export function createPrices(assumedCpi, asOf) {
|
|
|
106
107
|
assumedFor: (schemeYearEnd) => Object.freeze({
|
|
107
108
|
schemeYearEnd, cpi: assumedPct, si: null,
|
|
108
109
|
}),
|
|
109
|
-
|
|
110
|
+
asOf,
|
|
111
|
+
valueAt,
|
|
112
|
+
/* Literally the same function with `from` pinned to the run
|
|
113
|
+
date — not a second expression that happens to agree. */
|
|
114
|
+
payAt: (todaysMoney, asAt) => valueAt(todaysMoney, asOf, asAt),
|
|
110
115
|
};
|
|
111
116
|
}
|
|
112
117
|
//# sourceMappingURL=prices.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"prices.js","sourceRoot":"","sources":["../../src/pension/prices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAC;
|
|
1
|
+
{"version":3,"file":"prices.js","sourceRoot":"","sources":["../../src/pension/prices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAC;AA4E/C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAU,EACV,IAAU,EACV,UAAkB;IAElB,MAAM,KAAK,GAAG,IAAI,IAAI,IAAI,CAAC;IAC3B,MAAM,KAAK,GAAG,KAAK;QACjB,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC;QAC3B,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,IAAU,EAAE,EAAQ;IACzC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KACE,IAAI,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,EAC7B,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EACxB,IAAI,EAAE,EACN,CAAC;QACD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,OAAO,GAAG,IAAI,IAAI,OAAO,IAAI,EAAE;YAAE,KAAK,IAAI,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,UAAkB,EAClB,IAAU;IAEV,MAAM,UAAU,GAAG,UAAU,GAAG,GAAG,CAAC;IACpC,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,IAAU,EAAE,EAAQ,EAAU,EAAE,CAC/D,MAAM,GAAG,eAAe,CAAC,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAEjD,OAAO;QACL;;;;6CAIqC;QACrC,UAAU,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;YAC3C,aAAa,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI;SACzC,CAAC;QACF,IAAI;QACJ,OAAO;QACP;mEAC2D;QAC3D,KAAK,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC;KAC/D,CAAC;AACJ,CAAC"}
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
* NHS 2015 CARE Pension Projection
|
|
3
3
|
*
|
|
4
4
|
* Models the 2015 scheme lifecycle:
|
|
5
|
-
* accrual → revaluation → crystallisation
|
|
5
|
+
* accrual → revaluation → crystallisation. Commutation is a
|
|
6
|
+
* separate choice, in `commutation.ts`.
|
|
6
7
|
*
|
|
7
8
|
* Sources:
|
|
8
9
|
*
|
|
@@ -155,45 +156,13 @@
|
|
|
155
156
|
* 0.6% high over a full career at 2% CPI. That is now fixed,
|
|
156
157
|
* at the cost described above.
|
|
157
158
|
*/
|
|
159
|
+
import type { ProjectionMoney } from './pension/money.js';
|
|
160
|
+
import type { Prices } from './pension/prices.js';
|
|
158
161
|
import { ACCRUAL_RATE } from './pension/ledger.js';
|
|
159
162
|
import type { EstimatedHistory } from './pension/history.js';
|
|
160
163
|
import type { MemberLedger } from './pension/ledger.js';
|
|
161
164
|
import type { MemberPhase } from './pension/uplift.js';
|
|
162
165
|
import type { FactorProvenance, FactorTableKind } from './gad/factor-table.js';
|
|
163
|
-
/**
|
|
164
|
-
* One figure under BOTH projections.
|
|
165
|
-
*
|
|
166
|
-
* Every scalar reported here is a pair, so a consumer picks a
|
|
167
|
-
* reading rather than doing CPI arithmetic of its own.
|
|
168
|
-
*
|
|
169
|
-
* **Neither reading is derived from the other.** They are two
|
|
170
|
-
* runs of the same model: `nominal` at the caller's inflation
|
|
171
|
-
* assumption, `real` with that assumption set to zero. So
|
|
172
|
-
* `real` is not `nominal` deflated, and dividing one by the
|
|
173
|
-
* other does not give the assumption back.
|
|
174
|
-
*
|
|
175
|
-
* That distinction is the whole of a long-running disagreement
|
|
176
|
-
* about a third of a percent. Deflating a CPI + 1.5 projection
|
|
177
|
-
* leaves 1.5 / (1 + cpi) of real growth — 1.47% at 2% — because
|
|
178
|
-
* the 1.5 points are added before the growth and eaten into by
|
|
179
|
-
* the same year's inflation. Running the model at zero gives
|
|
180
|
-
* 1.5% flat, which is what "ignore inflation" means and what
|
|
181
|
-
* every member's own arithmetic does.
|
|
182
|
-
*/
|
|
183
|
-
export interface ProjectionMoney {
|
|
184
|
-
/** Actual pounds at `asAt`, the pension revalued at CPI plus
|
|
185
|
-
* 1.5 points a year while accruing. */
|
|
186
|
-
readonly nominal: number;
|
|
187
|
-
/** Today's pounds: the same projection with inflation
|
|
188
|
-
* ignored, so 1.5% a year while accruing and flat once
|
|
189
|
-
* deferred. */
|
|
190
|
-
readonly real: number;
|
|
191
|
-
/** The date the figure falls on. Its absence is how a
|
|
192
|
-
* consumer once deflated an exit figure over the horizon to
|
|
193
|
-
* retirement: a figure that does not carry its own date
|
|
194
|
-
* cannot defend itself. */
|
|
195
|
-
readonly asAt: Date;
|
|
196
|
-
}
|
|
197
166
|
/** A point on the projection curve */
|
|
198
167
|
export interface ProjectionPoint {
|
|
199
168
|
/** Age in years (can be fractional) */
|
|
@@ -276,13 +245,6 @@ export interface PensionEstimationInput {
|
|
|
276
245
|
assumedCpi: number;
|
|
277
246
|
}
|
|
278
247
|
export type PensionProjectionInput = PensionStatementInput | PensionEstimationInput;
|
|
279
|
-
/** Commutation options (separate from projection) */
|
|
280
|
-
export interface CommutationResult {
|
|
281
|
-
pensionGivenUp: number;
|
|
282
|
-
residualPension: number;
|
|
283
|
-
lumpSum: number;
|
|
284
|
-
maxLumpSum: number;
|
|
285
|
-
}
|
|
286
248
|
/** Full projection result */
|
|
287
249
|
export interface PensionProjectionResult {
|
|
288
250
|
/** Accrued pension at the close of the scheme year the exit
|
|
@@ -335,6 +297,16 @@ export interface PensionProjectionResult {
|
|
|
335
297
|
*/
|
|
336
298
|
estimatedHistory: EstimatedHistory | null;
|
|
337
299
|
ledger: MemberLedger;
|
|
300
|
+
/**
|
|
301
|
+
* The price series this run used.
|
|
302
|
+
*
|
|
303
|
+
* Reported so a consumer converting an EXTERNAL figure into
|
|
304
|
+
* these rulers — a statutory cap, a target income — does it at
|
|
305
|
+
* the assumption the pension was actually projected at. A
|
|
306
|
+
* caller rebuilding its own would be a second producer of the
|
|
307
|
+
* run's rate, free to disagree with it silently.
|
|
308
|
+
*/
|
|
309
|
+
prices: Prices;
|
|
338
310
|
/** The same walk with inflation ignored — the rows behind
|
|
339
311
|
* every `real` reading above, so a consumer showing its
|
|
340
312
|
* working in today's money reads them rather than
|
|
@@ -342,20 +314,6 @@ export interface PensionProjectionResult {
|
|
|
342
314
|
todaysMoneyLedger: MemberLedger;
|
|
343
315
|
}
|
|
344
316
|
export { ACCRUAL_RATE };
|
|
345
|
-
/** Commutation: £12 lump sum per £1 pension */
|
|
346
|
-
export declare const COMMUTATION_FACTOR = 12;
|
|
347
|
-
/**
|
|
348
|
-
* The most of a member's benefits HMRC lets them take as a
|
|
349
|
-
* tax-free lump sum, as a percentage.
|
|
350
|
-
*
|
|
351
|
-
* Exported because it is the only part of the commutation rule
|
|
352
|
-
* a member can be told directly — {@link maxLumpSum} is the cap
|
|
353
|
-
* in pounds, which answers "how much" but never "why that
|
|
354
|
-
* much". A consumer explaining the swap needs this figure, and
|
|
355
|
-
* a consumer that writes its own copy of it is one that can
|
|
356
|
-
* drift from the library that applies it.
|
|
357
|
-
*/
|
|
358
|
-
export declare const HMRC_LUMP_SUM_CAP_PCT = 25;
|
|
359
317
|
/**
|
|
360
318
|
* Provenance of the in-force table behind a factor kind — the
|
|
361
319
|
* citation facts (table ref, guidance name, issue date, source
|
|
@@ -380,30 +338,6 @@ export declare function retirementFactor(retirementDate: Date, npDate: Date): {
|
|
|
380
338
|
};
|
|
381
339
|
/** Annual pension accrual for one year of service */
|
|
382
340
|
export declare function yearlyAccrual(pensionablePay: number): number;
|
|
383
|
-
/**
|
|
384
|
-
* Maximum tax-free lump sum under the HMRC cap.
|
|
385
|
-
*
|
|
386
|
-
* The cap is on the lump sum as a share of the CAPITAL VALUE of
|
|
387
|
-
* the benefits, and taking a lump sum lowers the pension that
|
|
388
|
-
* value is measured from — so the answer is a fixed point, not
|
|
389
|
-
* a percentage of anything the caller already holds. With `c`
|
|
390
|
-
* the cap and `f` the commutation factor, capital value is
|
|
391
|
-
* `20 × residual + lumpSum`, and solving
|
|
392
|
-
*
|
|
393
|
-
* L = c × (20 × (P − L/f) + L)
|
|
394
|
-
*
|
|
395
|
-
* for L gives the expression below. Written from
|
|
396
|
-
* {@link HMRC_LUMP_SUM_CAP_PCT} rather than from its
|
|
397
|
-
* rearrangement — the familiar `(20P) / (3 + 20/f)` is this
|
|
398
|
-
* same solution with `c = 0.25` already substituted in, which
|
|
399
|
-
* hides the one number a reader would want to check.
|
|
400
|
-
*/
|
|
401
|
-
export declare function maxLumpSum(adjustedPension: number): number;
|
|
402
|
-
/**
|
|
403
|
-
* Calculate commutation at a given fraction of max.
|
|
404
|
-
* ERF/LRF is applied BEFORE commutation (§1.18).
|
|
405
|
-
*/
|
|
406
|
-
export declare function commute(adjustedPension: number, fraction: number): CommutationResult;
|
|
407
341
|
/**
|
|
408
342
|
* Generate a full pension projection including curve
|
|
409
343
|
* data for both nominal and real (CPI-deflated) views.
|