@casomoltd/nhs-pay 0.19.4 → 0.20.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.
Files changed (90) hide show
  1. package/README.md +69 -5
  2. package/dist/afc-scales.d.ts +14 -7
  3. package/dist/afc-scales.js +19 -19
  4. package/dist/afc-scales.js.map +1 -1
  5. package/dist/bands.d.ts +2 -2
  6. package/dist/commutation.d.ts +49 -5
  7. package/dist/commutation.js +124 -43
  8. package/dist/commutation.js.map +1 -1
  9. package/dist/dates.d.ts +2 -0
  10. package/dist/dates.js +4 -0
  11. package/dist/dates.js.map +1 -1
  12. package/dist/errors.d.ts +70 -12
  13. package/dist/errors.js +85 -19
  14. package/dist/errors.js.map +1 -1
  15. package/dist/factor-basis.d.ts +87 -0
  16. package/dist/factor-basis.js +99 -0
  17. package/dist/factor-basis.js.map +1 -0
  18. package/dist/gad/erf-1-401-2023-06-30.d.ts +47 -0
  19. package/dist/gad/erf-1-401-2023-06-30.js +73 -0
  20. package/dist/gad/erf-1-401-2023-06-30.js.map +1 -0
  21. package/dist/gad/erf-1-402-2023-06-30.d.ts +48 -0
  22. package/dist/gad/erf-1-402-2023-06-30.js +84 -0
  23. package/dist/gad/erf-1-402-2023-06-30.js.map +1 -0
  24. package/dist/gad/erf-1-407-2023-06-30.d.ts +47 -0
  25. package/dist/gad/erf-1-407-2023-06-30.js +73 -0
  26. package/dist/gad/erf-1-407-2023-06-30.js.map +1 -0
  27. package/dist/gad/erf-2023-06-30.d.ts +3 -0
  28. package/dist/gad/erf-2023-06-30.js +1 -0
  29. package/dist/gad/erf-2023-06-30.js.map +1 -1
  30. package/dist/gad/factor-table.d.ts +62 -31
  31. package/dist/gad/factor-table.js +67 -34
  32. package/dist/gad/factor-table.js.map +1 -1
  33. package/dist/gad/lrf-2-416-2023-06-30.d.ts +46 -0
  34. package/dist/gad/lrf-2-416-2023-06-30.js +72 -0
  35. package/dist/gad/lrf-2-416-2023-06-30.js.map +1 -0
  36. package/dist/gad/lrf-2023-06-30.d.ts +3 -0
  37. package/dist/gad/lrf-2023-06-30.js +1 -0
  38. package/dist/gad/lrf-2023-06-30.js.map +1 -1
  39. package/dist/gad/promotional-scale-2020.d.ts +37 -0
  40. package/dist/gad/promotional-scale-2020.js +38 -0
  41. package/dist/gad/promotional-scale-2020.js.map +1 -0
  42. package/dist/index.d.ts +16 -3
  43. package/dist/index.js +21 -12
  44. package/dist/index.js.map +1 -1
  45. package/dist/iso-date.d.ts +7 -0
  46. package/dist/iso-date.js +11 -0
  47. package/dist/iso-date.js.map +1 -1
  48. package/dist/member-benefits.d.ts +237 -0
  49. package/dist/member-benefits.js +440 -0
  50. package/dist/member-benefits.js.map +1 -0
  51. package/dist/pay-path.d.ts +70 -0
  52. package/dist/pay-path.js +155 -0
  53. package/dist/pay-path.js.map +1 -0
  54. package/dist/pension/curve.d.ts +74 -0
  55. package/dist/pension/curve.js +134 -0
  56. package/dist/pension/curve.js.map +1 -0
  57. package/dist/pension/history.js +3 -3
  58. package/dist/pension/history.js.map +1 -1
  59. package/dist/pension/ledger.d.ts +71 -31
  60. package/dist/pension/ledger.js +41 -6
  61. package/dist/pension/ledger.js.map +1 -1
  62. package/dist/pension/money.d.ts +23 -6
  63. package/dist/pension/money.js +23 -1
  64. package/dist/pension/money.js.map +1 -1
  65. package/dist/pension/uplift.d.ts +23 -0
  66. package/dist/pension/uplift.js +34 -1
  67. package/dist/pension/uplift.js.map +1 -1
  68. package/dist/pension-projection.d.ts +25 -31
  69. package/dist/pension-projection.js +40 -197
  70. package/dist/pension-projection.js.map +1 -1
  71. package/dist/scale-point.d.ts +11 -1
  72. package/dist/scales.d.ts +9 -9
  73. package/dist/scales.js +68 -67
  74. package/dist/scales.js.map +1 -1
  75. package/dist/sections/final-salary.d.ts +97 -0
  76. package/dist/sections/final-salary.js +99 -0
  77. package/dist/sections/final-salary.js.map +1 -0
  78. package/dist/sections/section-1995.d.ts +20 -0
  79. package/dist/sections/section-1995.js +52 -0
  80. package/dist/sections/section-1995.js.map +1 -0
  81. package/dist/sections/section-2008.d.ts +16 -0
  82. package/dist/sections/section-2008.js +44 -0
  83. package/dist/sections/section-2008.js.map +1 -0
  84. package/dist/sections/section-2015.d.ts +43 -0
  85. package/dist/sections/section-2015.js +57 -0
  86. package/dist/sections/section-2015.js.map +1 -0
  87. package/dist/values.d.ts +4 -5
  88. package/dist/values.js +4 -5
  89. package/dist/values.js.map +1 -1
  90. package/package.json +5 -3
@@ -0,0 +1,155 @@
1
+ /**
2
+ * A member's pensionable pay in every scheme year of their career,
3
+ * in today's money, and why each year's figure is what it is.
4
+ *
5
+ * Every section reads pay: the 2015 Section banks a slice of each
6
+ * year's, and a final-salary section measures its last window. So pay
7
+ * is built once per member and every section reads the same path,
8
+ * which is what makes final pay identical under both remedy elections
9
+ * by construction rather than by care.
10
+ *
11
+ * A member rarely declares more than today's pay, so the rest is
12
+ * worked out, the same way for everybody, and each year says which
13
+ * of four things it is:
14
+ *
15
+ * - **declared** — the member told us: their current pay, and any
16
+ * year they gave a figure for.
17
+ * - **contractual** — owed under their pay scale: the steps still to
18
+ * come on an Agenda for Change band, which progression pays on
19
+ * service rather than on promotion.
20
+ * - **projected** — after the last contractual step, on GAD's
21
+ * promotional curve from the pay at that step.
22
+ * - **reconstructed** — before today, on the same curve run
23
+ * backwards from today's pay.
24
+ *
25
+ * One curve in both directions, because reconstructing an unknown
26
+ * past and projecting an unknown future are the same problem and the
27
+ * same published research answers both.
28
+ */
29
+ import { PROMOTIONAL_SCALE_2020 } from './gad/promotional-scale-2020.js';
30
+ import { invariant, PayPathUnavailable } from './errors.js';
31
+ import { isoToDate } from './iso-date.js';
32
+ import { schemeYearEndFor } from './pension/seed.js';
33
+ /**
34
+ * GAD's promotional pay index at an age: growth from promotion and
35
+ * progression over and above general pay awards, 100 at age 25,
36
+ * linear between the published five-year rows and flat beyond their
37
+ * ends.
38
+ *
39
+ * **The two non-manual columns, averaged.** GAD splits the index by
40
+ * sex and we do not ask a member's sex, nor infer it: averaging is
41
+ * the only version that encodes no guess about the member. It
42
+ * overstates progression for women and understates it for men, which a
43
+ * caller showing its figures should disclose. Non-manual is not a second
44
+ * assumption — every Agenda for Change band is non-manual in GAD's
45
+ * terms.
46
+ */
47
+ export function promotionalIndex(age) {
48
+ invariant(Number.isFinite(age), `promotionalIndex: age ${age}`);
49
+ const { ages, nonManual } = PROMOTIONAL_SCALE_2020;
50
+ const blend = (i) => (nonManual.male[i] + nonManual.female[i]) / 2;
51
+ const last = ages.length - 1;
52
+ if (age <= ages[0])
53
+ return blend(0);
54
+ if (age >= ages[last])
55
+ return blend(last);
56
+ const hi = ages.findIndex((a) => a > age);
57
+ const lo = hi - 1;
58
+ const through = (age - ages[lo]) / (ages[hi] - ages[lo]);
59
+ return blend(lo) + (blend(hi) - blend(lo)) * through;
60
+ }
61
+ /** What a year's pay rests on: see the module header. */
62
+ export const PAY_BASES = {
63
+ declared: 'declared',
64
+ contractual: 'contractual',
65
+ projected: 'projected',
66
+ reconstructed: 'reconstructed',
67
+ };
68
+ /**
69
+ * The contractual steps still to come, as the scheme years each is
70
+ * first paid in, scaled to the member's own pay so a part-time
71
+ * member's steps stay in proportion to what they are actually paid.
72
+ */
73
+ function contractualSteps(ladder, current, currentYear) {
74
+ const here = ladder.current;
75
+ if (!ladder.points.includes(here)) {
76
+ throw new RangeError(`pay ladder: current point "${here.label}" is not one of its points`);
77
+ }
78
+ const hereYears = here.yearsExperience;
79
+ const scale = current.todaysMoney / here.salary;
80
+ return ladder.points
81
+ .filter((p) => p.yearsExperience > hereYears)
82
+ .map((p) => ({
83
+ from: currentYear + p.yearsExperience - hereYears,
84
+ pay: p.salary * scale,
85
+ }))
86
+ .sort((a, b) => a.from - b.from);
87
+ }
88
+ /**
89
+ * Build a member's pay path. Refuses only where there is nothing to
90
+ * build from: every other gap is filled, the same way for everybody,
91
+ * and labelled as filled.
92
+ */
93
+ export function buildPayPath(dateOfBirth, pay) {
94
+ const { current } = pay;
95
+ // Nought is a figure: a member paid nothing accrues nothing, and a
96
+ // stated balance still revalues. Only what is not a figure refuses.
97
+ if (!Number.isFinite(current.todaysMoney) || current.todaysMoney < 0) {
98
+ throw new PayPathUnavailable(`current pay ${current.todaysMoney} is not a pay figure`);
99
+ }
100
+ const born = isoToDate(dateOfBirth);
101
+ /** The age whose birthday falls in a scheme year: the years since
102
+ * the scheme year the member was born in. */
103
+ const bornIn = schemeYearEndFor(born);
104
+ const ageIn = (schemeYearEnd) => schemeYearEnd - bornIn;
105
+ const indexIn = (schemeYearEnd) => promotionalIndex(ageIn(schemeYearEnd));
106
+ const currentYear = schemeYearEndFor(isoToDate(current.asAt));
107
+ const declared = new Map();
108
+ for (const { schemeYearEnd, todaysMoney: figure } of pay.declared) {
109
+ if (declared.has(schemeYearEnd)) {
110
+ throw new RangeError(`pay path: ${schemeYearEnd} declared twice`);
111
+ }
112
+ if (!Number.isFinite(figure) || figure <= 0) {
113
+ throw new RangeError(`pay path: ${schemeYearEnd} declared as ${figure}`);
114
+ }
115
+ declared.set(schemeYearEnd, figure);
116
+ }
117
+ const steps = pay.ladder === null
118
+ ? []
119
+ : contractualSteps(pay.ladder, current, currentYear);
120
+ const lastStep = steps.at(-1);
121
+ /** Where the curve takes over going forwards: the top of the
122
+ * ladder, or today where there is no ladder left to climb. */
123
+ const curveFrom = lastStep ?? { from: currentYear, pay: current.todaysMoney };
124
+ return {
125
+ payFor(schemeYearEnd) {
126
+ invariant(Number.isInteger(schemeYearEnd), `pay path: scheme year ${schemeYearEnd}`);
127
+ const given = declared.get(schemeYearEnd);
128
+ if (given !== undefined)
129
+ return { pay: given, basis: PAY_BASES.declared };
130
+ if (schemeYearEnd === currentYear) {
131
+ return { pay: current.todaysMoney, basis: PAY_BASES.declared };
132
+ }
133
+ if (schemeYearEnd < currentYear) {
134
+ return {
135
+ pay: current.todaysMoney * indexIn(schemeYearEnd)
136
+ / indexIn(currentYear),
137
+ basis: PAY_BASES.reconstructed,
138
+ };
139
+ }
140
+ if (schemeYearEnd <= curveFrom.from) {
141
+ const paid = steps.filter((s) => s.from <= schemeYearEnd);
142
+ return {
143
+ pay: paid.at(-1)?.pay ?? current.todaysMoney,
144
+ basis: PAY_BASES.contractual,
145
+ };
146
+ }
147
+ return {
148
+ pay: curveFrom.pay * indexIn(schemeYearEnd)
149
+ / indexIn(curveFrom.from),
150
+ basis: PAY_BASES.projected,
151
+ };
152
+ },
153
+ };
154
+ }
155
+ //# sourceMappingURL=pay-path.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pay-path.js","sourceRoot":"","sources":["../src/pay-path.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,74 @@
1
+ import type { EstimatedHistory } from './history.js';
2
+ import type { MemberLedger } from './ledger.js';
3
+ import type { MemberPhase } from './uplift.js';
4
+ /** A point on the projection curve */
5
+ export interface ProjectionPoint {
6
+ /** Age in years (can be fractional) */
7
+ age: number;
8
+ /** Annual pension in actual £ of that year. Below today's
9
+ * age this is SMALLER than `real`: past pounds bought more. */
10
+ nominal: number;
11
+ /** Annual pension in today's £ — what the projection
12
+ * computes; `nominal` is this scaled by CPI. */
13
+ real: number;
14
+ /** Whether this is accrued (known) or projected — i.e.
15
+ * whether the point falls on or before today. Deliberately
16
+ * NOT `phase === 'active'`: a consumer uses this to separate
17
+ * history from forecast, and a future working year is
18
+ * forecast. */
19
+ accrued: boolean;
20
+ /** Which lifecycle phase the point falls in. */
21
+ phase: MemberPhase;
22
+ }
23
+ /** What drawing the curve needs of one walk: its ledger, its dates,
24
+ * and where it starts. */
25
+ interface CurveRun {
26
+ readonly today: Date;
27
+ readonly dateOfBirth: Date;
28
+ readonly exitDate: Date;
29
+ readonly retirementDate: Date;
30
+ readonly npa: number;
31
+ readonly ledger: MemberLedger;
32
+ readonly history: EstimatedHistory | null;
33
+ readonly curveFrom: Date;
34
+ }
35
+ /**
36
+ * The last scheme year a walk reaches: six past the later of the
37
+ * drawing and the pension age. The curve draws five years of age
38
+ * beyond that point, and a birthday can fall in the scheme year after
39
+ * the one the age is counted from, so five years of age can span six
40
+ * scheme years.
41
+ */
42
+ export declare function walkThrough(drawing: Date, pensionAge: Date): number;
43
+ /**
44
+ * The curve is the ledger's own steps, plotted ON THEM.
45
+ *
46
+ * **One point per scheme year, at its 31 March close** — the
47
+ * date an Annual Benefit Statement is drawn to, so every
48
+ * plotted value is a figure a member can lay beside paper.
49
+ *
50
+ * **Never at BIRTHDAYS**, which is the plotting the age axis
51
+ * invites. A birthday falls somewhere inside a scheme year:
52
+ * after the April uplift but before the year's slice lands, or
53
+ * the other way about. So a member born in January reads their
54
+ * 43rd-birthday point as "the 2026 figure" and gets a balance
55
+ * with neither the year's accrual in it nor any relation to a
56
+ * year end — values right for their dates and wrong for every
57
+ * question anyone asks of them, which surfaces as "the chart
58
+ * disagrees with my statement".
59
+ *
60
+ * The x-axis stays an AGE, because that is how people think
61
+ * about retiring. Age N is plotted at the close of the scheme
62
+ * year N's birthday falls in — the year that birthday belongs
63
+ * to — so the axis is unchanged and only the dates behind it
64
+ * move onto the scheme's own calendar.
65
+ *
66
+ * Nothing is drawn before the ledger's own start. For a
67
+ * statement that is the statement's date, and the reason is
68
+ * not tidiness: a member enters one figure, not their history,
69
+ * so anything earlier would be that figure run BACKWARDS
70
+ * through rates nobody checked. An inverse calculation drawn
71
+ * as history is a claim the tool cannot support.
72
+ */
73
+ export declare function buildCurve(cash: CurveRun, todays: CurveRun): ProjectionPoint[];
74
+ export {};
@@ -0,0 +1,134 @@
1
+ /**
2
+ * The 2015 Section's balance drawn as a curve: one point per scheme
3
+ * year, on both rulers, from where the ledger starts to five years of
4
+ * age past the later of the drawing and the pension age.
5
+ *
6
+ * Shared by `projectPension` and `memberBenefits`, which each walk
7
+ * the same ledger and plot it the same way, so it belongs to neither.
8
+ */
9
+ import { yearsBetween } from '../dates.js';
10
+ import { schemeYearEndDate, schemeYearEndFor } from './seed.js';
11
+ import { phaseAt } from './uplift.js';
12
+ /**
13
+ * The last scheme year a walk reaches: six past the later of the
14
+ * drawing and the pension age. The curve draws five years of age
15
+ * beyond that point, and a birthday can fall in the scheme year after
16
+ * the one the age is counted from, so five years of age can span six
17
+ * scheme years.
18
+ */
19
+ export function walkThrough(drawing, pensionAge) {
20
+ return Math.max(schemeYearEndFor(drawing), schemeYearEndFor(pensionAge)) + 6;
21
+ }
22
+ /**
23
+ * A member's age on a date, as WHOLE YEARS plus the fraction of
24
+ * the year since their birthday.
25
+ *
26
+ * The whole part is calendar arithmetic, so it is the age they
27
+ * would give if asked. The fraction only orders points within a
28
+ * year, which is all the chart needs it for.
29
+ */
30
+ function ageAtYearEnd(dateOfBirth, on) {
31
+ const birthdayIn = (year) => new Date(year, dateOfBirth.getMonth(), dateOfBirth.getDate());
32
+ const thisYear = birthdayIn(on.getFullYear());
33
+ const reached = thisYear <= on;
34
+ const whole = on.getFullYear() - dateOfBirth.getFullYear()
35
+ - (reached ? 0 : 1);
36
+ const last = reached ? thisYear : birthdayIn(on.getFullYear() - 1);
37
+ const next = reached ? birthdayIn(on.getFullYear() + 1) : thisYear;
38
+ return whole
39
+ + (on.getTime() - last.getTime())
40
+ / (next.getTime() - last.getTime());
41
+ }
42
+ /**
43
+ * The curve is the ledger's own steps, plotted ON THEM.
44
+ *
45
+ * **One point per scheme year, at its 31 March close** — the
46
+ * date an Annual Benefit Statement is drawn to, so every
47
+ * plotted value is a figure a member can lay beside paper.
48
+ *
49
+ * **Never at BIRTHDAYS**, which is the plotting the age axis
50
+ * invites. A birthday falls somewhere inside a scheme year:
51
+ * after the April uplift but before the year's slice lands, or
52
+ * the other way about. So a member born in January reads their
53
+ * 43rd-birthday point as "the 2026 figure" and gets a balance
54
+ * with neither the year's accrual in it nor any relation to a
55
+ * year end — values right for their dates and wrong for every
56
+ * question anyone asks of them, which surfaces as "the chart
57
+ * disagrees with my statement".
58
+ *
59
+ * The x-axis stays an AGE, because that is how people think
60
+ * about retiring. Age N is plotted at the close of the scheme
61
+ * year N's birthday falls in — the year that birthday belongs
62
+ * to — so the axis is unchanged and only the dates behind it
63
+ * move onto the scheme's own calendar.
64
+ *
65
+ * Nothing is drawn before the ledger's own start. For a
66
+ * statement that is the statement's date, and the reason is
67
+ * not tidiness: a member enters one figure, not their history,
68
+ * so anything earlier would be that figure run BACKWARDS
69
+ * through rates nobody checked. An inverse calculation drawn
70
+ * as history is a claim the tool cannot support.
71
+ */
72
+ export function buildCurve(cash, todays) {
73
+ const { today, dateOfBirth, retirementDate, npa } = cash;
74
+ const endAge = Math.max(npa + 5, yearsBetween(dateOfBirth, retirementDate) + 5);
75
+ /** The scheme year an age's birthday falls in. */
76
+ const yearOfAge = (age) => schemeYearEndFor(new Date(dateOfBirth.getFullYear() + age, dateOfBirth.getMonth(), dateOfBirth.getDate()));
77
+ /** The age whose birthday falls in a scheme year — the
78
+ * inverse, used once to find where the axis starts. */
79
+ const ageInYear = (schemeYearEnd) => {
80
+ const end = schemeYearEndDate(schemeYearEnd);
81
+ const birthday = new Date(schemeYearEnd, dateOfBirth.getMonth(), dateOfBirth.getDate());
82
+ return schemeYearEnd - dateOfBirth.getFullYear()
83
+ - (birthday > end ? 1 : 0);
84
+ };
85
+ const startAge = ageInYear(schemeYearEndFor(cash.curveFrom));
86
+ const points = [];
87
+ for (let label = startAge; label <= Math.ceil(endAge); label++) {
88
+ const year = yearOfAge(label);
89
+ const on = schemeYearEndDate(year);
90
+ /* The age the member actually IS on that 31 March, not the
91
+ whole age whose birthday the scheme year contains.
92
+
93
+ Those differ by anything from nought to twelve months —
94
+ the gap between a birthday and the following 31 March —
95
+ so plotting at the whole age would put a value up to a
96
+ year early on the x-axis, and a "today" point falling in
97
+ that gap would sit out of order with its neighbours.
98
+
99
+ Built as WHOLE AGE + fraction rather than as a span in
100
+ 365.25-day years, so that `Math.floor(age)` is the age
101
+ the member actually is on that 31 March — by calendar
102
+ arithmetic, not within a rounding of it. Someone born on
103
+ 1 April reads 42.997 at the year end before their 43rd
104
+ birthday, which floors correctly today and sits three
105
+ thousandths from flooring wrongly after enough leap
106
+ days. The fraction orders the points; the whole part is
107
+ exact. */
108
+ const age = ageAtYearEnd(dateOfBirth, on);
109
+ /* Two walks meet here, and the estimate owns everything up
110
+ to and including the statement's own year — its last row
111
+ IS the stated balance, so reading it there rather than
112
+ the main ledger changes nothing and keeps the join
113
+ seamless. */
114
+ const from = (r) => r.history !== null && year <= r.history.to
115
+ ? r.history.ledger
116
+ : r.ledger;
117
+ const row = from(cash).years.find((r) => r.schemeYearEnd === year);
118
+ points.push({
119
+ age,
120
+ nominal: from(cash).atDate(on),
121
+ real: from(todays).atDate(on),
122
+ accrued: on <= today,
123
+ /* Off the row where there is one, and otherwise from the
124
+ SAME rule the row was built by — never a second copy of
125
+ it here. Compared by scheme YEAR, matching the ledger:
126
+ a point sits at a 31 March close, so a member who left
127
+ in January of that year would read as deferred on the
128
+ very year they were still paying in. */
129
+ phase: row?.phase ?? phaseAt(year, schemeYearEndFor(cash.exitDate), schemeYearEndFor(cash.retirementDate)),
130
+ });
131
+ }
132
+ return points;
133
+ }
134
+ //# sourceMappingURL=curve.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"curve.js","sourceRoot":"","sources":["../../src/pension/curve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAC,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAC,OAAO,EAAC,MAAM,aAAa,CAAC;AAoCpC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,OAAa,EAAE,UAAgB;IACzD,OAAO,IAAI,CAAC,GAAG,CACb,gBAAgB,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC,UAAU,CAAC,CACxD,GAAG,CAAC,CAAC;AACR,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,WAAiB,EAAE,EAAQ;IAC/C,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,IAAI,CAC3C,IAAI,EAAE,WAAW,CAAC,QAAQ,EAAE,EAAE,WAAW,CAAC,OAAO,EAAE,CACpD,CAAC;IACF,MAAM,QAAQ,GAAG,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,QAAQ,IAAI,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,EAAE,GAAG,WAAW,CAAC,WAAW,EAAE;UACtD,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACnE,OAAO,KAAK;UACR,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;cAC7B,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,UAAU,CACxB,IAAc,EACd,MAAgB;IAEhB,MAAM,EAAC,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,EAAC,GAAG,IAAI,CAAC;IAEvD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CACrB,GAAG,GAAG,CAAC,EAAE,YAAY,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,CAAC,CACvD,CAAC;IAEF,kDAAkD;IAClD,MAAM,SAAS,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,gBAAgB,CACjD,IAAI,IAAI,CACN,WAAW,CAAC,WAAW,EAAE,GAAG,GAAG,EAC/B,WAAW,CAAC,QAAQ,EAAE,EACtB,WAAW,CAAC,OAAO,EAAE,CACtB,CACF,CAAC;IAEF;2DACuD;IACvD,MAAM,SAAS,GAAG,CAAC,aAAqB,EAAE,EAAE;QAC1C,MAAM,GAAG,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,IAAI,IAAI,CACvB,aAAa,EAAE,WAAW,CAAC,QAAQ,EAAE,EAAE,WAAW,CAAC,OAAO,EAAE,CAC7D,CAAC;QACF,OAAO,aAAa,GAAG,WAAW,CAAC,WAAW,EAAE;cAC5C,CAAC,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,SAAS,CAAC,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAE7D,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,KAAK,IAAI,KAAK,GAAG,QAAQ,EAAE,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QAC/D,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QAC9B,MAAM,EAAE,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACnC;;;;;;;;;;;;;;;;;oBAiBY;QACZ,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QAC1C;;;;uBAIe;QACf,MAAM,IAAI,GAAG,CAAC,CAAW,EAAE,EAAE,CAC3B,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,EAAE;YACxC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM;YAClB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,IAAI,CAChC,CAAC;QACF,MAAM,CAAC,IAAI,CAAC;YACV,GAAG;YACH,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,EAAE,IAAI,KAAK;YACpB;;;;;sDAK0C;YAC1C,KAAK,EAAE,GAAG,EAAE,KAAK,IAAI,OAAO,CAC1B,IAAI,EACJ,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAC/B,gBAAgB,CAAC,IAAI,CAAC,cAAc,CAAC,CACtC;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
@@ -69,7 +69,7 @@
69
69
  * year's pay award inside them, so averaging them raw mixes
70
70
  * 2021 pounds with 2025 pounds and reads low by a tenth.
71
71
  */
72
- import { buildLedger } from './ledger.js';
72
+ import { buildLedger, flatPay } from './ledger.js';
73
73
  import { firstWalkedYear, schemeYearEndDate, seedFromJoinDate, } from './seed.js';
74
74
  /**
75
75
  * Estimate the years from `joinDate` up to a stated balance.
@@ -85,9 +85,9 @@ export function estimateHistory({ joinDate, statedBalance, statementSchemeYearEn
85
85
  if (first > statementSchemeYearEnd || statedBalance <= 0) {
86
86
  return null;
87
87
  }
88
- const walk = (pensionableEarnings) => buildLedger({
88
+ const walk = (pay) => buildLedger({
89
89
  seed,
90
- pensionableEarnings,
90
+ payIn: flatPay(pay),
91
91
  // Accruing throughout, and drawing far enough out that no
92
92
  // retirement factor lands inside the window.
93
93
  exitDate: schemeYearEndDate(statementSchemeYearEnd),
@@ -1 +1 @@
1
- {"version":3,"file":"history.js","sourceRoot":"","sources":["../../src/pension/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH,OAAO,EAAC,WAAW,EAAC,MAAM,aAAa,CAAC;AAGxC,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAqBnB;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,QAAQ,EACR,aAAa,EACb,sBAAsB,EACtB,MAAM,GAMP;IACC,MAAM,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,KAAK,GAAG,sBAAsB,IAAI,aAAa,IAAI,CAAC,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,mBAA2B,EAAE,EAAE,CAAC,WAAW,CAAC;QACxD,IAAI;QACJ,mBAAmB;QACnB,0DAA0D;QAC1D,6CAA6C;QAC7C,QAAQ,EAAE,iBAAiB,CAAC,sBAAsB,CAAC;QACnD,cAAc,EAAE,iBAAiB,CAAC,sBAAsB,GAAG,EAAE,CAAC;QAC9D,MAAM;QACN,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI;QACtB,OAAO,EAAE,sBAAsB;KAChC,CAAC,CAAC;IAEH,4DAA4D;IAC5D,kDAAkD;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;IAC3D,wDAAwD;IACxD,6DAA6D;IAC7D,2DAA2D;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAE7D,MAAM,UAAU,GAAG,aAAa,GAAG,QAAQ,CAAC;IAC5C,OAAO;QACL,UAAU;QACV,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC;QACxB,IAAI,EAAE,KAAK;QACX,EAAE,EAAE,sBAAsB;KAC3B,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"history.js","sourceRoot":"","sources":["../../src/pension/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH,OAAO,EAAC,WAAW,EAAE,OAAO,EAAC,MAAM,aAAa,CAAC;AAGjD,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAqBnB;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,QAAQ,EACR,aAAa,EACb,sBAAsB,EACtB,MAAM,GAMP;IACC,MAAM,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,KAAK,GAAG,sBAAsB,IAAI,aAAa,IAAI,CAAC,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,WAAW,CAAC;QACxC,IAAI;QACJ,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC;QACnB,0DAA0D;QAC1D,6CAA6C;QAC7C,QAAQ,EAAE,iBAAiB,CAAC,sBAAsB,CAAC;QACnD,cAAc,EAAE,iBAAiB,CAAC,sBAAsB,GAAG,EAAE,CAAC;QAC9D,MAAM;QACN,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI;QACtB,OAAO,EAAE,sBAAsB;KAChC,CAAC,CAAC;IAEH,4DAA4D;IAC5D,kDAAkD;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;IAC3D,wDAAwD;IACxD,6DAA6D;IAC7D,2DAA2D;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAE7D,MAAM,UAAU,GAAG,aAAa,GAAG,QAAQ,CAAC;IAC5C,OAAO;QACL,UAAU;QACV,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC;QACxB,IAAI,EAAE,KAAK;QACX,EAAE,EAAE,sBAAsB;KAC3B,CAAC;AACJ,CAAC"}
@@ -19,6 +19,7 @@
19
19
  * construction.
20
20
  */
21
21
  import type { FactorProvenance, FactorTableKind } from '../gad/factor-table.js';
22
+ import type { PayBasis, YearPay } from '../pay-path.js';
22
23
  import type { Prices } from './prices.js';
23
24
  import type { AppliedUplift, MemberPhase } from './uplift.js';
24
25
  import type { LedgerSeed } from './seed.js';
@@ -37,15 +38,23 @@ export interface AppliedDrawing {
37
38
  * years and months from NPA, not annual. */
38
39
  readonly on: Date;
39
40
  readonly factor: number;
40
- /** Which table the factor was read from, or null where none
41
- * was: retiring at NPA is neither early nor late, and naming
42
- * a table there would cite an early-retirement reduction to a
43
- * member who took none. */
44
- readonly kind: FactorTableKind | null;
45
- /** Which issue of that table the factor came from. Null
46
- * exactly when `kind` is — there is no issue to cite. */
47
- readonly provenance: FactorProvenance | null;
41
+ /** The table the factor was read from, and which issue of it; null
42
+ * where none was: retiring at NPA is neither early nor late, and
43
+ * naming a table there would cite an early-retirement reduction to
44
+ * a member who took none. One field, so a table cannot be named
45
+ * without the issue it was read from. */
46
+ readonly table: {
47
+ readonly kind: FactorTableKind;
48
+ readonly provenance: FactorProvenance;
49
+ } | null;
48
50
  }
51
+ /** What a ledger row's earnings rest on beyond a pay path's own bases:
52
+ * one flat figure the caller assumed, or nothing earned. */
53
+ declare const LEDGER_BASES: {
54
+ readonly assumed: "assumed";
55
+ readonly none: "none";
56
+ };
57
+ export type EarningsBasis = (typeof LEDGER_BASES)[keyof typeof LEDGER_BASES] | PayBasis;
49
58
  /** One scheme year, accounted for the way the scheme accounts
50
59
  * for it. Every field is nominal £/yr unless said otherwise. */
51
60
  export interface LedgerYear {
@@ -70,15 +79,13 @@ export interface LedgerYear {
70
79
  * `uplift.from.si` is null on every row and no row is the
71
80
  * scheme's own record — the seed is the last figure that was.
72
81
  *
73
- * Always `assumed` where anything was earned: the library has
74
- * no route to a member's actual year-by-year pay, so every
75
- * non-zero figure derives from the single pay the caller gave,
76
- * held flat in real terms. `none` where the member was not
77
- * accruing, which is the only case with nothing to be wrong
78
- * about. A statement's own earnings history would add a
79
- * `given` here, and is the reason this field exists now.
82
+ * `assumed` where the caller gave one pay held flat in real terms,
83
+ * which is `projectPension`'s case; a ledger reading a member's pay
84
+ * path carries that year's basis instead — declared, contractual,
85
+ * projected or reconstructed. `none` where nothing was earned,
86
+ * which is the only case with nothing to be wrong about.
80
87
  */
81
- readonly earningsBasis: 'assumed' | 'none';
88
+ readonly earningsBasis: EarningsBasis;
82
89
  /** Brought INTO this year — last year's closing balance,
83
90
  * untouched. The whole banked pot, not a slice. */
84
91
  readonly opening: number;
@@ -122,27 +129,46 @@ export interface MemberLedger {
122
129
  * beside the paper. */
123
130
  earningsRows(): readonly LedgerYear[];
124
131
  }
132
+ /**
133
+ * A year's pensionable pay for a ledger that reads a pay path: the
134
+ * figure in today's money and what it rests on, or null for an active
135
+ * year this ledger does not accrue in — the years after a remedy
136
+ * window, when the member is still in service and their pot is still
137
+ * revalued at the in-service rate, but their accrual belongs to
138
+ * another ledger.
139
+ */
140
+ export type PayIn = (schemeYearEnd: number) => YearPay | {
141
+ readonly pay: number;
142
+ readonly basis: typeof LEDGER_BASES.assumed;
143
+ } | null;
144
+ /**
145
+ * One figure held flat every year, in today's money: no promotion, no
146
+ * progression, and every row saying its pay was assumed.
147
+ */
148
+ export declare function flatPay(pay: number): PayIn;
125
149
  export interface LedgerRequest {
126
150
  readonly seed: LedgerSeed;
127
151
  /**
128
- * Pensionable pay in TODAY'S MONEY, held flat.
152
+ * Pensionable pay in TODAY'S MONEY, per scheme year: `flatPay` holds
153
+ * one figure every year, or a member's pay path gives each its own.
129
154
  *
130
- * **This is the base case and the only one built.** Every
131
- * year's slice is the same figure in today's money; what
132
- * varies is only its expression in each year's own cash,
133
- * because a nominal model that froze pay in CASH while
134
- * revaluing the pot above CPI would count inflation twice.
155
+ * Either way a year's slice is that year's pay / 54 in today's
156
+ * money; what varies is only its expression in each year's own cash,
157
+ * because a nominal model that froze pay in CASH while revaluing the
158
+ * pot above CPI would count inflation twice.
135
159
  *
136
- * Pay progression is a deliberate non-feature — issue #11.
137
- * Anything that makes a year's slice differ from
138
- * `pensionableEarnings / 54` in today's money is that unbuilt
139
- * feature arriving by accident: quote the figure at the
140
- * statement date and hold it flat in real terms FROM there,
141
- * and the member collects a 5.6% real pay rise. Held to a
142
- * date, `earnings in today's money are pay / 54, every year`
143
- * is the invariant that catches it.
160
+ * **Flat pay** is `projectPension`'s case: no
161
+ * promotion, no progression. Anything that makes a year's slice
162
+ * differ from the flat figure / 54 there is pay growth
163
+ * arriving by accident — quote the figure at the statement date and
164
+ * hold it flat in real terms FROM there, and the member collects a
165
+ * 5.6% real pay rise. `earnings in today's money are pay / 54, every
166
+ * year` is the invariant that catches it.
167
+ *
168
+ * **A pay path** is `memberBenefits`'s: each year's figure is the
169
+ * path's, with its basis on the row.
144
170
  */
145
- readonly pensionableEarnings: number;
171
+ readonly payIn: PayIn;
146
172
  /**
147
173
  * A date in the last scheme year of service. Only the year it
148
174
  * names is read: the member is active for all of it and the
@@ -158,3 +184,17 @@ export interface LedgerRequest {
158
184
  readonly through: number;
159
185
  }
160
186
  export declare function buildLedger(req: LedgerRequest): MemberLedger;
187
+ /**
188
+ * The pension at the drawing, before and after its factor, read off
189
+ * the row the drawing falls in.
190
+ *
191
+ * There is no such row when the drawing falls at or before the seed's
192
+ * own year end — a member handing over a balance and drawing it the
193
+ * same day — and there is still an answer: the balance they handed
194
+ * over, with the factor applied here instead of on a row.
195
+ */
196
+ export declare function atDrawing(ledger: MemberLedger, drawing: Date, factor: number): {
197
+ revalued: number;
198
+ drawn: number;
199
+ };
200
+ export {};
@@ -31,6 +31,19 @@ import { firstWalkedYear, schemeYearEndDate, schemeYearEndFor, schemeYearStartDa
31
31
  * rather than a literal here and a name somewhere else.
32
32
  */
33
33
  export const ACCRUAL_RATE = 1 / 54;
34
+ /** What a ledger row's earnings rest on beyond a pay path's own bases:
35
+ * one flat figure the caller assumed, or nothing earned. */
36
+ const LEDGER_BASES = {
37
+ assumed: 'assumed',
38
+ none: 'none',
39
+ };
40
+ /**
41
+ * One figure held flat every year, in today's money: no promotion, no
42
+ * progression, and every row saying its pay was assumed.
43
+ */
44
+ export function flatPay(pay) {
45
+ return () => ({ pay, basis: LEDGER_BASES.assumed });
46
+ }
34
47
  /** Complete months from `from` to `to`. */
35
48
  function completeMonths(from, to) {
36
49
  if (to <= from)
@@ -91,13 +104,16 @@ function rowFor(ctx) {
91
104
  const revalued = uplift === null
92
105
  ? opening
93
106
  : opening * (1 + uplift.percent / 100);
94
- const pensionableEarnings = phase === 'active'
95
- ? payFor({
107
+ const given = phase === 'active'
108
+ ? req.payIn(year)
109
+ : null;
110
+ const pensionableEarnings = given === null
111
+ ? null
112
+ : payFor({
96
113
  year, prices, first: ctx.first,
97
114
  accruingFrom: seed.accruingFrom,
98
- annualPay: req.pensionableEarnings,
99
- })
100
- : null;
115
+ annualPay: given.pay,
116
+ });
101
117
  const earned = pensionableEarnings === null
102
118
  ? 0
103
119
  : pensionableEarnings * ACCRUAL_RATE;
@@ -115,7 +131,9 @@ function rowFor(ctx) {
115
131
  phase,
116
132
  pensionableEarnings,
117
133
  earned,
118
- earningsBasis: earned === 0 ? 'none' : 'assumed',
134
+ earningsBasis: earned === 0 || given === null
135
+ ? LEDGER_BASES.none
136
+ : given.basis,
119
137
  opening,
120
138
  uplift: uplift === null ? null : Object.freeze(uplift),
121
139
  revalued,
@@ -204,4 +222,21 @@ function readerOver(frozen, seed) {
204
222
  earningsRows: () => frozen.filter((row) => row.pensionableEarnings !== null),
205
223
  });
206
224
  }
225
+ /**
226
+ * The pension at the drawing, before and after its factor, read off
227
+ * the row the drawing falls in.
228
+ *
229
+ * There is no such row when the drawing falls at or before the seed's
230
+ * own year end — a member handing over a balance and drawing it the
231
+ * same day — and there is still an answer: the balance they handed
232
+ * over, with the factor applied here instead of on a row.
233
+ */
234
+ export function atDrawing(ledger, drawing, factor) {
235
+ const row = ledger.years.find((r) => r.schemeYearEnd === schemeYearEndFor(drawing));
236
+ if (row === undefined) {
237
+ const revalued = ledger.accruedAt(drawing);
238
+ return { revalued, drawn: revalued * factor };
239
+ }
240
+ return { revalued: row.revalued + row.earned, drawn: row.closing };
241
+ }
207
242
  //# sourceMappingURL=ledger.js.map