@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/README.md CHANGED
@@ -124,7 +124,12 @@ unpublished nation/year or grade rather than defaulting.
124
124
  ### Project a 2015-scheme pension
125
125
 
126
126
  ```ts
127
- import {projectPension, commute} from '@casomoltd/nhs-pay';
127
+ import {
128
+ COMMUTATION_FACTOR,
129
+ LUMP_SUM_ALLOWANCE,
130
+ commute,
131
+ projectPension,
132
+ } from '@casomoltd/nhs-pay';
128
133
 
129
134
  const projection = projectPension({
130
135
  kind: 'statement',
@@ -141,11 +146,52 @@ console.log(projection.annualPension); // after ERF/LRF
141
146
  console.log(projection.factorType); // 'erf'
142
147
  console.log(projection.curve); // chart-ready points
143
148
 
144
- const {lumpSum, residualPension} = commute(
145
- projection.annualPension.nominal, 1, // take the HMRC max
149
+ // Commutation takes the whole {nominal, real, asAt} figure, not
150
+ // one side of it: the lump sum allowance is a cash amount tested
151
+ // on a date, so a dateless number could not say which ruler it
152
+ // was in. Every limit is required for the same reason — a
153
+ // default would answer a question the caller did not ask.
154
+ const {lumpSum, residualPension, limit} = commute(
155
+ projection.annualPension,
156
+ 1, // take the permitted maximum
157
+ {
158
+ commutationFactor: COMMUTATION_FACTOR,
159
+ allowance: {
160
+ amount: LUMP_SUM_ALLOWANCE,
161
+ asAt: new Date(2026, 2, 31),
162
+ },
163
+ // The run's OWN price series, so the allowance is carried
164
+ // forward at the rate the pension was projected at.
165
+ prices: projection.prices,
166
+ },
146
167
  );
168
+ console.log(lumpSum.real, lumpSum.nominal); // both rulers
169
+ // The maximum, and which cap stopped it — PER RULER.
170
+ console.log(limit.real.amount, limit.real.binding);
171
+ console.log(limit.nominal.amount, limit.nominal.binding);
147
172
  ```
148
173
 
174
+ The maximum is the **lower** of two caps, and **both are
175
+ statutory**: 25% of the capital value of the benefits, and the
176
+ Lump Sum Allowance. The scheme's own contribution to the swap is
177
+ the 12:1 rate and nothing else, so a consumer must not attribute
178
+ the 25% to the scheme — `LUMP_SUM_CAPS.Scheme` names the
179
+ discriminant, not the rule's author. `binding` says which cap
180
+ stopped it, so a consumer can explain the figure rather than
181
+ restate the rule.
182
+
183
+ Why that name is left as it is, and what moves where when it
184
+ changes: [*The two caps on tax-free
185
+ cash*](docs/how-it-works.md#the-two-caps-on-tax-free-cash).
186
+
187
+ There is **one limit per ruler, and no single flag**, because the
188
+ two can genuinely disagree: `real` is the model run at zero CPI
189
+ while the allowance is carried forward at CPI, so around the
190
+ crossover the allowance binds in today's money while the scheme
191
+ limb still binds in cash. Show the limit belonging to the ruler
192
+ on screen. See
193
+ [*The two caps on tax-free cash*](docs/how-it-works.md#the-two-caps-on-tax-free-cash).
194
+
149
195
  Without a statement figure, `kind: 'estimation'` accrues from a
150
196
  `joinDate` instead. ERF/LRF factors are transcribed verbatim from
151
197
  the GAD consolidated factor workbook (30 June 2023 issue) with
@@ -190,9 +236,17 @@ Table A25 (AfC 2025/26 data for England, NI, Wales).
190
236
  | September CPI + in-service rate | [HM Treasury Revaluation Orders][sis], one SI per year |
191
237
  | Accrual rate, NPA | NHSBSA 2015 Members' Guide (V13) |
192
238
  | ERF / LRF factors | GAD NHS EW consolidated factor workbook |
193
- | Commutation | NHSBSA Key Notes — 2015 Scheme Estimates (V2) |
239
+ | Commutation rate (£12 : £1) | NHSBSA Key Notes — 2015 Scheme Estimates (V2) |
240
+ | Permitted maximum (lowest of three limbs) | [Sch 29 Finance Act 2004 para 2][sch29] |
241
+ | Applicable amount, defined benefits, `(A + (B × C)) / 4` | [Sch 29 Finance Act 2004 para 2C][sch29p2c] |
242
+ | Relevant valuation factor (20) | [Finance Act 2004 s.276][s276] |
243
+ | Lump Sum Allowance (£268,275, frozen) | [ITEPA 2003 s.637P][s637p] |
194
244
 
195
245
  [sis]: https://www.legislation.gov.uk/secondary/public+service+pensions
246
+ [sch29]: https://www.legislation.gov.uk/ukpga/2004/12/schedule/29
247
+ [sch29p2c]: https://www.legislation.gov.uk/ukpga/2004/12/schedule/29/paragraph/2C
248
+ [s276]: https://www.legislation.gov.uk/ukpga/2004/12/section/276
249
+ [s637p]: https://www.legislation.gov.uk/ukpga/2003/1/part/9/chapter/15A
196
250
 
197
251
  Reconciled line by line against a real **Annual Benefit
198
252
  Statement** (2015 Section, updated to 31/03/2025, name and
@@ -371,7 +425,8 @@ NI 2025/26) — see
371
425
  ## Development
372
426
 
373
427
  ```bash
374
- npm run check # lint + typecheck + knip + jscpd + test
428
+ npm run check # lint + typecheck + knip + jscpd
429
+ # + api-docs drift gate + test
375
430
  npm run build # compile to dist/
376
431
  npm test # vitest
377
432
  npm run test:watch # vitest watch mode
@@ -379,4 +434,13 @@ npm run test:watch # vitest watch mode
379
434
 
380
435
  ## License
381
436
 
382
- LGPL-3.0-only
437
+ AGPL-3.0-only — see [LICENSE](LICENSE).
438
+ Copyright © 2026 Casomo Ltd.
439
+
440
+ There is no linking exception: combine this library with your
441
+ own code and the combined work is AGPL too, and letting people
442
+ use that work over a network obliges you to offer them its
443
+ source. Charging money is not what triggers this, and not
444
+ charging is no exemption. A commercial licence is available for
445
+ use that needs to stay closed — enquire via
446
+ [casomoltd.com](https://casomoltd.com).
@@ -0,0 +1,331 @@
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 type { ProjectionMoney } from './pension/money.js';
26
+ import type { Prices } from './pension/prices.js';
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 declare const COMMUTATION_FACTOR = 12;
45
+ /**
46
+ * The most of a member's benefits HMRC lets them take as a
47
+ * tax-free lump sum, as a percentage.
48
+ *
49
+ * Exported because it is the only part of the commutation rule
50
+ * a member can be told directly — {@link lumpSumLimit} is the
51
+ * cap in pounds, which answers "how much" but never "why that
52
+ * much". A consumer explaining the swap needs this figure, and
53
+ * a consumer that writes its own copy of it is one that can
54
+ * drift from the library that applies it.
55
+ *
56
+ * THIS IS THE FORM THE STATUTE USES. Schedule 29 FA 2004
57
+ * paragraph 2C gives the defined-benefits applicable amount as
58
+ * `(A + (B × C)) / 4`, where A is the amount of the lump sum, B
59
+ * is the relevant valuation factor ({@link VALUATION_FACTOR})
60
+ * and C is the pension payable in the 12 months beginning with
61
+ * the day the member becomes entitled to it. `A + (B × C)` IS
62
+ * the capital value, so a quarter of it is this constant.
63
+ *
64
+ * Two things follow, and both are load-bearing. C is the pension
65
+ * AFTER commutation, which is what makes the cap a fixed point
66
+ * rather than a percentage of anything the caller already holds.
67
+ * And the one-third-of-the-remaining-pension form that guidance
68
+ * often quotes is this same rule solved for A: 4A = A + (B × C)
69
+ * gives A = B × C / 3. Both reach 30P/7 at a 12:1 rate, verified
70
+ * numerically either way. Do NOT "correct" this constant to a
71
+ * third — it would be the same number and the wrong citation.
72
+ *
73
+ * Source: Schedule 29 Finance Act 2004, paragraphs 2 (the
74
+ * permitted maximum is the LOWEST of three amounts) and 2C (the
75
+ * defined-benefits applicable amount, which invokes B by
76
+ * reference to s.276 rather than restating 20). Verified against
77
+ * the Act on 27 August 2026. Paragraph 2C's formula is published
78
+ * as an image, so its shape is corroborated by the variable
79
+ * definitions in the surrounding text and by HMRC's own
80
+ * 20P / (3 + 20/CF), which agrees to the penny.
81
+ */
82
+ export declare const HMRC_LUMP_SUM_CAP_PCT = 25;
83
+ /**
84
+ * The statutory factor turning an annual defined-benefit pension
85
+ * into a capital value: capital value is 20 × annual pension.
86
+ *
87
+ * Named because it is a RULE, not arithmetic. A statutory
88
+ * factor written as a bare `20` inside an expression is
89
+ * invisible to a search, to a citation and to a test, and reads
90
+ * as a coefficient someone chose.
91
+ *
92
+ * Reached by reference, not by repetition: Schedule 29 paragraph
93
+ * 2C names "the relevant valuation factor" as its B rather than
94
+ * writing 20 into the lump sum rule, so the factor and the cap
95
+ * are one rule in two provisions and a change to s.276 would
96
+ * move the cap without touching Schedule 29.
97
+ *
98
+ * Source: Finance Act 2004 s.276, "Relevant valuation factor":
99
+ * "the relevant valuation factor in relation to any registered
100
+ * pension scheme, or any arrangement under a registered pension
101
+ * scheme, is 20", unless a higher one is agreed with HMRC.
102
+ * Verified against the Act on 27 August 2026.
103
+ */
104
+ export declare const VALUATION_FACTOR = 20;
105
+ /**
106
+ * The Lump Sum Allowance: the absolute cap on tax-free pension
107
+ * cash, in pounds.
108
+ *
109
+ * £268,275 since 6 April 2024, when it replaced the Lifetime
110
+ * Allowance. FROZEN IN LAW — it is not indexed, so its real
111
+ * value erodes every year it stands.
112
+ *
113
+ * "Frozen" states the LAW, not how a projection should treat it.
114
+ * Whether to carry this figure forward in real terms is the
115
+ * CALLER's assumption, declared through
116
+ * {@link CommutationLimits.allowance}. Do not read this comment
117
+ * as an instruction to hold the figure fixed in cash.
118
+ *
119
+ * This is the STANDARD allowance. A member holding a Lifetime
120
+ * Allowance protection has a higher one — HMRC PTM174700 puts
121
+ * fixed protection 2016 at £312,500, 2014 at £375,000 and 2012
122
+ * at £450,000, with the other classes worked out per member.
123
+ * None of them is modelled here and none is detectable from
124
+ * what this library is given.
125
+ *
126
+ * Source: ITEPA 2003 s.637P, verified against the Act on
127
+ * 27 August 2026 — <https://www.legislation.gov.uk/ukpga/2003/1/
128
+ * part/9/chapter/15A>. Cited to the instrument rather than to
129
+ * HMRC's Pensions Tax Manual, which is written for
130
+ * administrators and gave the wrong section number when this
131
+ * figure was first transcribed. Its source-archive row is in
132
+ * docs/how-it-works.md.
133
+ */
134
+ export declare const LUMP_SUM_ALLOWANCE = 268275;
135
+ /**
136
+ * The two limbs of the permitted maximum, as a const object so
137
+ * the keys are reachable at a call site instead of a bare
138
+ * literal repeated across modules.
139
+ *
140
+ * `Scheme` IS A MISLEADING NAME AND IS KNOWN TO BE. Both limbs
141
+ * are statutory and bind every registered pension scheme in the
142
+ * UK; the scheme's only contribution to this swap is
143
+ * {@link COMMUTATION_FACTOR}. The name has already leaked into
144
+ * prose that told members "the scheme stops the swap at 25%",
145
+ * which was wrong wherever it appeared.
146
+ *
147
+ * It is not renamed in place on purpose. The whole statutory
148
+ * half of this module moves to the UK-tax library
149
+ * (casomoltd/nhs-pay#15, casomoltd/paye-calc#30), and renaming
150
+ * here as well would spend two breaking changes on one defect.
151
+ * When the rule lands in its new home the key should be named
152
+ * for the statute — `Applicable`, after the applicable amount
153
+ * in Schedule 29 paragraph 2C.
154
+ *
155
+ * Until then: read `Scheme` as the name of a discriminant, not
156
+ * as an attribution, and never render it to a member.
157
+ */
158
+ export declare const LUMP_SUM_CAPS: {
159
+ readonly Scheme: "scheme";
160
+ readonly Allowance: "allowance";
161
+ };
162
+ /** Which limb of the permitted maximum bound. */
163
+ export type LumpSumCap = (typeof LUMP_SUM_CAPS)[keyof typeof LUMP_SUM_CAPS];
164
+ /**
165
+ * A cash amount and the date it is stated in.
166
+ *
167
+ * The pairing is the point. An amount without its date cannot be
168
+ * moved into another ruler, and it cannot say which ruler it is
169
+ * already in — cash at retirement and today's money are the same
170
+ * number in different units. A function handed a bare number has
171
+ * to assume one, and its assumption is unwritten.
172
+ */
173
+ export interface DatedAmount {
174
+ readonly amount: number;
175
+ readonly asAt: Date;
176
+ }
177
+ /**
178
+ * Everything the permitted maximum depends on besides the
179
+ * pension itself.
180
+ *
181
+ * EVERY FIELD IS REQUIRED. Each selects WHICH answer you get,
182
+ * not how it is computed, so a default would hand a
183
+ * plausible-but-wrong figure to a caller who forgot it — with no
184
+ * error, no type failure and no failing test. A cap is exactly
185
+ * the kind of figure that looks right at every value except the
186
+ * ones it exists to catch.
187
+ */
188
+ export interface CommutationLimits {
189
+ /**
190
+ * The SCHEME's commutation rate — £ of lump sum per £1 of
191
+ * pension. {@link COMMUTATION_FACTOR} for the NHS. The only
192
+ * non-statutory input here.
193
+ */
194
+ readonly commutationFactor: number;
195
+ /**
196
+ * The lump sum allowance, and the date it is stated in.
197
+ *
198
+ * Modelled as a REAL-TERMS constant: the today's-money run
199
+ * tests `amount` as given, and the cash run tests the same cap
200
+ * carried forward to the pension's own date. That is an
201
+ * assumption — the allowance is frozen in law — and a consumer
202
+ * showing these figures should say so.
203
+ */
204
+ readonly allowance: DatedAmount;
205
+ /**
206
+ * The price series the pension was PROJECTED with, used to
207
+ * carry the allowance to the pension's own date.
208
+ *
209
+ * PASS THE ONE FROM `projectPension`'s RESULT. Taking the
210
+ * object rather than a bare rate removes the need to restate
211
+ * the assumption, and gives the conversion the run's own
212
+ * anchor — but it does not make a mismatch impossible:
213
+ * `createPrices` is exported, so a caller can still build a
214
+ * series the pension was never projected with. That is a
215
+ * caller error this library cannot detect.
216
+ */
217
+ readonly prices: Prices;
218
+ }
219
+ /**
220
+ * The NHS binding of {@link CommutationLimits}.
221
+ *
222
+ * Every field of that interface is required so a non-NHS caller
223
+ * cannot inherit an NHS default by omitting one. That stops a
224
+ * field being LEFT OUT; it does nothing to stop several call
225
+ * sites each assembling the same NHS combination by hand and one
226
+ * of them getting it subtly wrong — a different `asAt`, a
227
+ * `createPrices` of its own, a literal `12`. Two consumers
228
+ * already spelled the date two ways.
229
+ *
230
+ * So the combination is published once, here, beside the
231
+ * constants it pairs. Pass the `prices` your own projection
232
+ * returned; the allowance is stated at that run's anchor,
233
+ * because these are the prices that will convert it and
234
+ * anchoring it anywhere else converts it across a gap the
235
+ * projection never travelled.
236
+ */
237
+ export declare function nhsCommutationLimits(prices: Prices): CommutationLimits;
238
+ /**
239
+ * The permitted maximum tax-free lump sum, and the working
240
+ * behind it.
241
+ *
242
+ * A value object rather than a number because a consumer that
243
+ * stops a control at this figure has to be able to say WHY it
244
+ * stopped, and a UI that re-derives "was it the allowance?" from
245
+ * a comparison keeps a second copy of the rule in the layer
246
+ * least able to test it.
247
+ */
248
+ export interface LumpSumLimit {
249
+ /** The permitted maximum: the lower of the two limbs. */
250
+ readonly amount: number;
251
+ /**
252
+ * Which limb set `amount`. Equal limbs report `Allowance` — at
253
+ * the crossover the allowance is what stops it moving.
254
+ */
255
+ readonly binding: LumpSumCap;
256
+ /** The applicable-amount limb, before the allowance. */
257
+ readonly schemeMax: number;
258
+ /**
259
+ * The allowance actually tested against, in this ruler — so a
260
+ * consumer cites the figure that was applied rather than the
261
+ * statutory one it assumes was applied.
262
+ */
263
+ readonly allowance: number;
264
+ /**
265
+ * `amount` as a share of the capital value of the benefits,
266
+ * in percentage points.
267
+ *
268
+ * The unit the statute states the rule in, and the one a
269
+ * member can check the rule against — so it is reported here
270
+ * rather than left to a consumer to re-derive from the capital
271
+ * value, which is not a figure this library otherwise hands
272
+ * out. It is HMRC_LUMP_SUM_CAP_PCT exactly when the scheme
273
+ * limb binds, and LESS when the allowance does: a flat cash
274
+ * cap is a smaller share of a larger pension. A control whose
275
+ * ceiling is labelled 25% while the allowance binds is telling
276
+ * the member a share they are not taking.
277
+ */
278
+ readonly sharePct: number;
279
+ }
280
+ /**
281
+ * One reading per ruler.
282
+ *
283
+ * Named rather than left inline because it is public API: a
284
+ * consumer writing a caption helper should not have to spell
285
+ * `CommutationResult['limit']` to type its argument.
286
+ */
287
+ export interface LumpSumLimits {
288
+ readonly real: LumpSumLimit;
289
+ readonly nominal: LumpSumLimit;
290
+ }
291
+ /** Commutation, in both rulers, from one call. */
292
+ export interface CommutationResult {
293
+ readonly pensionGivenUp: ProjectionMoney;
294
+ readonly residualPension: ProjectionMoney;
295
+ readonly lumpSum: ProjectionMoney;
296
+ /**
297
+ * The full working behind each ruler's maximum — which limb
298
+ * bound it, and both limbs' figures.
299
+ *
300
+ * TWO limits, not one flag, because the rulers can genuinely
301
+ * disagree about which limb stopped the lump sum. They are not
302
+ * one walk in different units: `real` is the model run at zero
303
+ * CPI, growing 1.5% a year, while the allowance is carried
304
+ * forward at CPI — so the pension's real-to-cash ratio and the
305
+ * allowance's are different numbers. Around the crossover
306
+ * there is a band where the allowance binds in today's money
307
+ * and the scheme limb still binds in cash. A consumer shows
308
+ * the limit for the ruler it is displaying; one flag for both
309
+ * would caption one column with the other's reason.
310
+ *
311
+ * The maximum itself is `limit.<ruler>.amount`. It is not also
312
+ * reported as a pair: two shapes for one number is two places
313
+ * an edit can change it.
314
+ */
315
+ readonly limit: LumpSumLimits;
316
+ }
317
+ /**
318
+ * Commutation at a fraction of the permitted maximum, reported
319
+ * in both rulers.
320
+ *
321
+ * Takes the pension as a {@link ProjectionMoney} rather than a
322
+ * bare number so the ruler travels with the money. A dateless
323
+ * figure cannot say which ruler it is in, and the allowance is a
324
+ * cash amount tested on a date — so the two could only be
325
+ * compared by assuming, which is the defect this signature
326
+ * removes.
327
+ *
328
+ * ERF/LRF is applied BEFORE commutation (§1.18), so `pension` is
329
+ * the pension at retirement after any factor.
330
+ */
331
+ export declare function commute(pension: ProjectionMoney, fraction: number, limits: CommutationLimits): CommutationResult;