@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.
@@ -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, COMMUTATION_FACTOR, HMRC_LUMP_SUM_CAP_PCT, commute, factorProvenance, maxLumpSum, projectPension, retirementFactor, yearlyAccrual, } from './pension-projection.js';
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 { CommutationResult, PensionEstimationInput, PensionProjectionInput, PensionProjectionResult, PensionStatementInput, ProjectionMoney, ProjectionPoint, } from './pension-projection.js';
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, COMMUTATION_FACTOR, HMRC_LUMP_SUM_CAP_PCT, commute, factorProvenance, maxLumpSum, projectPension, retirementFactor, yearlyAccrual, } from './pension-projection.js';
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":"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"}
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,2 @@
1
+ export {};
2
+ //# sourceMappingURL=money.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"money.js","sourceRoot":"","sources":["../../src/pension/money.ts"],"names":[],"mappings":""}
@@ -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. Two members and no third: reading the
71
- * published record is `revaluation.ts`'s job, and a reader here
72
- * would be a second answer to a question already answered. */
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
@@ -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
- payAt: (todaysMoney, asAt) => todaysMoney * inflationFactor(asAt, asOf, assumedCpi),
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;AAsD/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;IAEpC,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,KAAK,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,CAC3B,WAAW,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC;KACxD,CAAC;AACJ,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 → commutation.
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.