@casomoltd/nhs-pay 0.11.0 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +48 -0
  2. package/dist/award.d.ts +8 -8
  3. package/dist/award.js +8 -8
  4. package/dist/circulars/england-md-1-2026r.d.ts +2 -3
  5. package/dist/circulars/england-md-1-2026r.js +2 -3
  6. package/dist/circulars/england-md-1-2026r.js.map +1 -1
  7. package/dist/circulars/ni-hsc-tc8-05-2025.d.ts +2 -2
  8. package/dist/circulars/ni-hsc-tc8-05-2025.js +2 -2
  9. package/dist/circulars/scotland-pcs-dd-2025-01.d.ts +2 -3
  10. package/dist/circulars/scotland-pcs-dd-2025-01.js +2 -3
  11. package/dist/circulars/scotland-pcs-dd-2025-01.js.map +1 -1
  12. package/dist/circulars/scotland-pcs-dd-2026-01.d.ts +2 -2
  13. package/dist/circulars/scotland-pcs-dd-2026-01.js +2 -2
  14. package/dist/circulars/wales-mdw-01-2025.d.ts +2 -2
  15. package/dist/circulars/wales-mdw-01-2025.js +2 -2
  16. package/dist/circulars/wales-mdw-01-2026.d.ts +2 -2
  17. package/dist/circulars/wales-mdw-01-2026.js +2 -2
  18. package/dist/gad/erf-2023-06-30.d.ts +39 -3
  19. package/dist/gad/erf-2023-06-30.js +39 -3
  20. package/dist/gad/erf-2023-06-30.js.map +1 -1
  21. package/dist/gad/factor-table.d.ts +10 -0
  22. package/dist/gad/factor-table.js.map +1 -1
  23. package/dist/gad/lrf-2023-06-30.d.ts +39 -3
  24. package/dist/gad/lrf-2023-06-30.js +39 -3
  25. package/dist/gad/lrf-2023-06-30.js.map +1 -1
  26. package/dist/hcas-pcts.js +3 -1
  27. package/dist/hcas-pcts.js.map +1 -1
  28. package/dist/index.d.ts +11 -3
  29. package/dist/index.js +9 -2
  30. package/dist/index.js.map +1 -1
  31. package/dist/pension/history.d.ts +105 -0
  32. package/dist/pension/history.js +115 -0
  33. package/dist/pension/history.js.map +1 -0
  34. package/dist/pension/ledger.d.ts +146 -0
  35. package/dist/pension/ledger.js +193 -0
  36. package/dist/pension/ledger.js.map +1 -0
  37. package/dist/pension/prices.d.ts +125 -0
  38. package/dist/pension/prices.js +108 -0
  39. package/dist/pension/prices.js.map +1 -0
  40. package/dist/pension/seed.d.ts +75 -0
  41. package/dist/pension/seed.js +82 -0
  42. package/dist/pension/seed.js.map +1 -0
  43. package/dist/pension/uplift.d.ts +151 -0
  44. package/dist/pension/uplift.js +135 -0
  45. package/dist/pension/uplift.js.map +1 -0
  46. package/dist/pension-projection.d.ts +217 -48
  47. package/dist/pension-projection.js +394 -202
  48. package/dist/pension-projection.js.map +1 -1
  49. package/dist/pension.js +9 -10
  50. package/dist/pension.js.map +1 -1
  51. package/dist/post.d.ts +24 -16
  52. package/dist/post.js +2 -3
  53. package/dist/post.js.map +1 -1
  54. package/dist/revaluation.d.ts +119 -30
  55. package/dist/revaluation.js +175 -29
  56. package/dist/revaluation.js.map +1 -1
  57. package/dist/scales.d.ts +17 -10
  58. package/dist/scales.js +17 -10
  59. package/dist/scales.js.map +1 -1
  60. package/dist/take-home.d.ts +9 -5
  61. package/dist/take-home.js +9 -5
  62. package/dist/take-home.js.map +1 -1
  63. package/package.json +1 -1
@@ -1,9 +1,18 @@
1
1
  /**
2
2
  * Verbatim transcription — GAD "NHSPS_EW — Consolidated Factor
3
- * Spreadsheet" (workbook: NHS EW Consolidated Factors 2023-03),
4
- * issued 30 June 2023. Sheet x-421 · PDF p.26.
3
+ * Spreadsheet", table 0-421, factors issued 30 June 2023.
4
+ * Sheet x-421 · PDF p.26.
5
5
  *
6
- * https://www.nhsbsa.nhs.uk/sites/default/files/2024-02/Early%20and%20Late%20Retirement%20Factors.pdf
6
+ * The WORKBOOK VERSION is deliberately not named: GAD reissues
7
+ * the consolidated workbook and a version pinned here rots
8
+ * silently. What is cited is what does not move — the table,
9
+ * and the date its factors were issued. Which workbook it was
10
+ * last checked against is a dated fact, and lives below.
11
+ *
12
+ * Sources: "NHSBSA, Early and Late Retirement Factors" (the
13
+ * member-facing extract) and "GAD NHS_EW Consolidated Factors,
14
+ * version 2026-01" (the workbook, and the source of record) —
15
+ * see docs/source-archive.md.
7
16
  *
8
17
  * Table 0-421 (LRF1): 2015 scheme late retirement factors — main
9
18
  * scheme pension, members retiring from active service. Unisex;
@@ -16,6 +25,33 @@
16
25
  * printed — the 10yr row prints a single 0-month value. Delete
17
26
  * this file whole when a later issue supersedes the table
18
27
  * (expected with the post-May-2026 SCAPE review).
28
+ *
29
+ * ── Checked against GAD's own workbook, 20 Aug 2026 ─
30
+ *
31
+ * Source of truth is the consolidated workbook, not the NHSBSA
32
+ * extract above: **NHS_EW Consolidated Factors, version
33
+ * 2026-01** (Date Modified 1 June 2026), the current issue.
34
+ * The extract carries the tables but not the version-control
35
+ * sheet, so it cannot answer whether they moved; the workbook
36
+ * can, and is the reason this check is possible at all.
37
+ *
38
+ * **This table is unchanged and still current.** Two checks,
39
+ * because a changelog is a claim and cell values are evidence:
40
+ *
41
+ * 1. Its *Version control* sheet shows x-421 last updated in
42
+ * version **2023-02**, dated 30 June 2023 — which is the
43
+ * `issued` date below, and the sheet's own "Date Factors
44
+ * Issued" cell agrees. Versions since (2023-03, 2023-04, two
45
+ * 2025-01 releases, 2026-01) updated other tables: 2026-01
46
+ * touched only x-201 to x-209 and x-301 to x-308.
47
+ * 2. Every cell of the x-421 sheet was diffed against the rows
48
+ * below — 11 rows — with **zero differences**.
49
+ *
50
+ * Re-run both before assuming a later workbook changed nothing:
51
+ * a table can be reissued without its number changing. Note
52
+ * x-423 arrived in 2025-01 and is NOT this table — it is an
53
+ * eligibility factor for actuarially reduced early retirement,
54
+ * looked up by age rather than by time to NPA.
19
55
  */
20
56
  /** 2015 scheme LRF — Table 0-421, issued 30 Jun 2023. */
21
57
  export const LRF_0_421 = {
@@ -1 +1 @@
1
- {"version":3,"file":"lrf-2023-06-30.js","sourceRoot":"","sources":["../../src/gad/lrf-2023-06-30.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,yDAAyD;AACzD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,KAAK;IACX,UAAU,EAAE;QACV,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,EAAE;QACR,WAAW,EAAE,MAAM;QACnB,MAAM,EAAE,YAAY;QACpB,SAAS,EAAE,0CAA0C;cACjD,+CAA+C;cAC/C,gBAAgB;QACpB,cAAc,EAAE,qCAAqC;cACjD,0CAA0C;KAC/C;IACD,IAAI,EAAE;QACJ,iDAAiD;QACjD,mCAAmC;QACnC,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,CAAC,EAAsC,kBAAkB;KAChE;CACiC,CAAC"}
1
+ {"version":3,"file":"lrf-2023-06-30.js","sourceRoot":"","sources":["../../src/gad/lrf-2023-06-30.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAIH,yDAAyD;AACzD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,KAAK;IACX,UAAU,EAAE;QACV,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,EAAE;QACR,WAAW,EAAE,MAAM;QACnB,MAAM,EAAE,YAAY;QACpB,SAAS,EAAE,0CAA0C;cACjD,+CAA+C;cAC/C,gBAAgB;QACpB,cAAc,EAAE,qCAAqC;cACjD,0CAA0C;KAC/C;IACD,IAAI,EAAE;QACJ,iDAAiD;QACjD,mCAAmC;QACnC,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;YACvC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM;QACnD,CAAC,KAAK,CAAC,EAAsC,kBAAkB;KAChE;CACiC,CAAC"}
package/dist/hcas-pcts.js CHANGED
@@ -8,7 +8,9 @@
8
8
  *
9
9
  * Browser-safe — no node:fs dependency.
10
10
  */
11
- // ── PCT data — NHS T&Cs Handbook Annex 8 (HCAS zones) ──
11
+ // ── PCT data — Annex 8, HCAS payment zones ──
12
+ // Source: "NHS Terms and Conditions of Service Handbook,
13
+ // amendment 62" (#sa-41) — see docs/source-archive.md.
12
14
  const INNER_LONDON_PCTS = [
13
15
  'Hammersmith & Fulham',
14
16
  'Kensington & Chelsea',
@@ -1 +1 @@
1
- {"version":3,"file":"hcas-pcts.js","sourceRoot":"","sources":["../src/hcas-pcts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,0DAA0D;AAE1D,MAAM,iBAAiB,GAAsB;IAC3C,sBAAsB;IACtB,sBAAsB;IACtB,aAAa;IACb,QAAQ;IACR,WAAW;IACX,gBAAgB;IAChB,eAAe;IACf,SAAS;IACT,UAAU;IACV,WAAW;IACX,YAAY;CACb,CAAC;AAEF,MAAM,iBAAiB,GAAsB;IAC3C,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,YAAY;IACZ,UAAU;IACV,QAAQ;IACR,SAAS;IACT,UAAU;IACV,oBAAoB;IACpB,UAAU;IACV,QAAQ;IACR,WAAW;IACX,iBAAiB;IACjB,QAAQ;IACR,SAAS;IACT,WAAW;IACX,SAAS;IACT,UAAU;IACV,uBAAuB;IACvB,iBAAiB;CAClB,CAAC;AAEF,MAAM,WAAW,GAAsB;IACrC,+BAA+B;IAC/B,UAAU;IACV,kCAAkC;IAClC,gBAAgB;IAChB,QAAQ;IACR,UAAU;IACV,SAAS;IACT,WAAW;IACX,yCAAyC;IACzC,0BAA0B;IAC1B,uBAAuB;IACvB,wBAAwB;IACxB,kBAAkB;IAClB,mBAAmB;IACnB,QAAQ;IACR,6BAA6B;IAC7B,WAAW;IACX,6BAA6B;IAC7B,aAAa;IACb,sBAAsB;IACtB,cAAc;IACd,yBAAyB;CAC1B,CAAC;AAEF,MAAM,SAAS,GAGT;IACJ,EAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,EAAC;IAC/C,EAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,EAAC;IAC/C,EAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAC;CACpC,CAAC;AAEF,mDAAmD;AAEnD,MAAM,SAAS,GACb,IAAI,GAAG,EAAE,CAAC;AAEZ,KAAK,MAAM,EAAC,IAAI,EAAE,IAAI,EAAC,IAAI,SAAS,EAAE,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AASD,gDAAgD;AAChD,MAAM,UAAU,WAAW,CACzB,GAAW;IAEX,OAAO,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,CAAC;AAClD,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAc,EAAE,CAAC;IAC7B,KAAK,MAAM,EAAC,IAAI,EAAE,IAAI,EAAC,IAAI,SAAS,EAAE,CAAC;QACrC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,GAAG,EAAC,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
1
+ {"version":3,"file":"hcas-pcts.js","sourceRoot":"","sources":["../src/hcas-pcts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,+CAA+C;AAC/C,yDAAyD;AACzD,uDAAuD;AAEvD,MAAM,iBAAiB,GAAsB;IAC3C,sBAAsB;IACtB,sBAAsB;IACtB,aAAa;IACb,QAAQ;IACR,WAAW;IACX,gBAAgB;IAChB,eAAe;IACf,SAAS;IACT,UAAU;IACV,WAAW;IACX,YAAY;CACb,CAAC;AAEF,MAAM,iBAAiB,GAAsB;IAC3C,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,YAAY;IACZ,UAAU;IACV,QAAQ;IACR,SAAS;IACT,UAAU;IACV,oBAAoB;IACpB,UAAU;IACV,QAAQ;IACR,WAAW;IACX,iBAAiB;IACjB,QAAQ;IACR,SAAS;IACT,WAAW;IACX,SAAS;IACT,UAAU;IACV,uBAAuB;IACvB,iBAAiB;CAClB,CAAC;AAEF,MAAM,WAAW,GAAsB;IACrC,+BAA+B;IAC/B,UAAU;IACV,kCAAkC;IAClC,gBAAgB;IAChB,QAAQ;IACR,UAAU;IACV,SAAS;IACT,WAAW;IACX,yCAAyC;IACzC,0BAA0B;IAC1B,uBAAuB;IACvB,wBAAwB;IACxB,kBAAkB;IAClB,mBAAmB;IACnB,QAAQ;IACR,6BAA6B;IAC7B,WAAW;IACX,6BAA6B;IAC7B,aAAa;IACb,sBAAsB;IACtB,cAAc;IACd,yBAAyB;CAC1B,CAAC;AAEF,MAAM,SAAS,GAGT;IACJ,EAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,EAAC;IAC/C,EAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,iBAAiB,EAAC;IAC/C,EAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAC;CACpC,CAAC;AAEF,mDAAmD;AAEnD,MAAM,SAAS,GACb,IAAI,GAAG,EAAE,CAAC;AAEZ,KAAK,MAAM,EAAC,IAAI,EAAE,IAAI,EAAC,IAAI,SAAS,EAAE,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AASD,gDAAgD;AAChD,MAAM,UAAU,WAAW,CACzB,GAAW;IAEX,OAAO,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,CAAC;AAClD,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAc,EAAE,CAAC;IAC7B,KAAK,MAAM,EAAC,IAAI,EAAE,IAAI,EAAC,IAAI,SAAS,EAAE,CAAC;QACrC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,GAAG,EAAC,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
package/dist/index.d.ts CHANGED
@@ -15,12 +15,20 @@ export { DENTAL_GRADES, DENTAL_GRADE_IDS, DENTAL_TAX_YEARS, getDentalScales, } f
15
15
  export type { DentalGradeId, DentalGradeMeta, } from './dental-scales.js';
16
16
  export { AwardUnavailable, PensionTiersUnavailable, RetirementFactorOutOfRange, ScaleUnavailable, } from './errors.js';
17
17
  export { afcAward } from './award.js';
18
- export { ACTIVE_REVAL_BONUS_PCT, IN_SERVICE_REVALUATION, revaluationFor, } from './revaluation.js';
19
- export type { RevaluationYear } from './revaluation.js';
20
- export { ACCRUAL_RATE, COMMUTATION_FACTOR, commute, factorProvenance, maxLumpSum, projectPension, retirementFactor, yearlyAccrual, } from './pension-projection.js';
18
+ export { ACTIVE_REVAL_BONUS_PCT, IN_SERVICE_REVALUATION, publishedInflationBetween, revaluationFor, } from './revaluation.js';
19
+ export type { PublishedInflation, 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';
21
21
  export type { FactorProvenance, FactorTableKind, } from './gad/factor-table.js';
22
22
  export { normalPensionAge } from './npa.js';
23
23
  export type { CommutationResult, PensionEstimationInput, PensionProjectionInput, PensionProjectionResult, PensionStatementInput, ProjectionMoney, ProjectionPoint, } from './pension-projection.js';
24
+ export { createPrices } from './pension/prices.js';
25
+ export type { CpiEntry, Prices } from './pension/prices.js';
26
+ export { activeRatePct, deferredRatePct, upliftsFor, } from './pension/uplift.js';
27
+ export type { AppliedUplift, MemberPhase, UpliftSource, } from './pension/uplift.js';
28
+ export { schemeYearClosedBy, schemeYearEndDate, schemeYearEndFor, schemeYearStartDate, seedFromJoinDate, seedFromStatement, } from './pension/seed.js';
29
+ export type { LedgerSeed } from './pension/seed.js';
30
+ export { buildLedger } from './pension/ledger.js';
31
+ export type { AppliedDrawing, LedgerRequest, LedgerYear, MemberLedger, } from './pension/ledger.js';
24
32
  export { HCAS_ZONE_IDS, calculateHcasSupplement, grossSalary, isHcasZoneId, } from './hcas.js';
25
33
  export type { HcasZoneId } from './hcas.js';
26
34
  export { getHcasPcts, getHcasZone, } from './hcas-pcts.js';
package/dist/index.js CHANGED
@@ -12,7 +12,7 @@ export { DENTAL_GRADES, DENTAL_GRADE_IDS, DENTAL_TAX_YEARS, getDentalScales, } f
12
12
  export { AwardUnavailable, PensionTiersUnavailable, RetirementFactorOutOfRange, ScaleUnavailable, } from './errors.js';
13
13
  // ── AfC pay award ────────────────────────────────
14
14
  export { afcAward } from './award.js';
15
- export { ACTIVE_REVAL_BONUS_PCT, IN_SERVICE_REVALUATION, revaluationFor, } from './revaluation.js';
15
+ export { ACTIVE_REVAL_BONUS_PCT, IN_SERVICE_REVALUATION, publishedInflationBetween, revaluationFor, } from './revaluation.js';
16
16
  // ── Pension Projection ─────────────────────────────
17
17
  // Deliberate surface: the scenario-level API plus
18
18
  // yearlyAccrual (hub-site builds its pension-growth
@@ -23,9 +23,16 @@ export { ACTIVE_REVAL_BONUS_PCT, IN_SERVICE_REVALUATION, revaluationFor, } from
23
23
  // own the GAD 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, commute, factorProvenance, maxLumpSum, projectPension, retirementFactor, yearlyAccrual, } from './pension-projection.js';
26
+ export { ACCRUAL_RATE, COMMUTATION_FACTOR, HMRC_LUMP_SUM_CAP_PCT, commute, factorProvenance, maxLumpSum, projectPension, retirementFactor, yearlyAccrual, } from './pension-projection.js';
27
27
  // ── Normal pension age ───────────────────────────────
28
28
  export { normalPensionAge } from './npa.js';
29
+ // ── The pension ledger ───────────────────────────────
30
+ // Additive: the projection API above is unchanged, and a
31
+ // consumer reads the ledger only when it wants the workings.
32
+ export { createPrices } from './pension/prices.js';
33
+ export { activeRatePct, deferredRatePct, upliftsFor, } from './pension/uplift.js';
34
+ export { schemeYearClosedBy, schemeYearEndDate, schemeYearEndFor, schemeYearStartDate, seedFromJoinDate, seedFromStatement, } from './pension/seed.js';
35
+ export { buildLedger } from './pension/ledger.js';
29
36
  // ── HCAS ─────────────────────────────────────────
30
37
  export { HCAS_ZONE_IDS, calculateHcasSupplement, grossSalary, isHcasZoneId, } from './hcas.js';
31
38
  // ── HCAS PCTs ────────────────────────────────────
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,OAAO,EACL,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,aAAa,CAAC;AAQrB,oDAAoD;AACpD,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,cAAc,CAAC;AAStB,oDAAoD;AACpD,OAAO,EAAC,IAAI,EAAE,cAAc,EAAC,MAAM,WAAW,CAAC;AAU/C,OAAO,EAAC,WAAW,EAAE,cAAc,EAAE,eAAe,EAAC,MAAM,eAAe,CAAC;AAS3E,oDAAoD;AACpD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAK5B,oDAAoD;AACpD,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AAEpC,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAG1B,sDAAsD;AACtD,kDAAkD;AAClD,oDAAoD;AACpD,sDAAsD;AACtD,kDAAkD;AAClD,uDAAuD;AACvD,wDAAwD;AACxD,wDAAwD;AACxD,kDAAkD;AAClD,gBAAgB;AAChB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,OAAO,EACP,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,aAAa,GACd,MAAM,yBAAyB,CAAC;AAMjC,wDAAwD;AACxD,OAAO,EAAC,gBAAgB,EAAC,MAAM,UAAU,CAAC;AAW1C,oDAAoD;AACpD,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,WAAW,EACX,YAAY,GACb,MAAM,WAAW,CAAC;AAGnB,oDAAoD;AACpD,OAAO,EACL,WAAW,EACX,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAGxB,oDAAoD;AACpD,OAAO,EACL,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,QAAQ,EACR,aAAa,GACd,MAAM,cAAc,CAAC;AAMtB,oDAAoD;AACpD,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,GACb,MAAM,YAAY,CAAC;AAMpB,oDAAoD;AACpD,OAAO,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAG3C,oDAAoD;AACpD,OAAO,EACL,QAAQ,EACR,MAAM,EACN,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,SAAS,EACT,gBAAgB,EAChB,SAAS,GACV,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,mDAAmD;AACnD,qDAAqD;AACrD,OAAO,EACL,WAAW,EACX,SAAS,EACT,OAAO,EACP,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,GACb,MAAM,sBAAsB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,105 @@
1
+ /**
2
+ * The years BEFORE a statement, estimated for illustration.
3
+ *
4
+ * A member hands over one figure — the pension accrued by their
5
+ * statement's date — and their join date. Everything between
6
+ * the two is unknown: this library has no route to anyone's
7
+ * year-by-year earnings. Without this the chart can only begin
8
+ * at the statement, and the join date — which the form asks for,
9
+ * visibly — does nothing at all.
10
+ *
11
+ * This fills that gap the only honest way available. It asks
12
+ * what FLAT pensionable pay, in today's money, would have
13
+ * produced exactly the balance the member states, over exactly
14
+ * the years they say they were in the scheme — and then walks
15
+ * that pay forward as the illustration.
16
+ *
17
+ * ── What it is and is not ───────────────────────────
18
+ *
19
+ * It is **for plotting**. It gives the built-up arm a shape and
20
+ * a starting point, and it is drawn in the same line as the
21
+ * rest because it is the same pension. What makes it honest is
22
+ * the disclosure beside it, not a different colour.
23
+ *
24
+ * It is **not a reconstruction of anyone's career**. Real
25
+ * earnings are not flat: the statement this was checked against
26
+ * runs £42k, £33k, £37k, £51k across four years, and no single
27
+ * figure produces that shape. What the estimate gets right is
28
+ * the ENDPOINT, exactly, and the trajectory approximately.
29
+ *
30
+ * It is **not an input to the projection**. Nothing after the
31
+ * statement reads it; the forward figures use the pay the
32
+ * member actually gave. A pension projected from a pay derived
33
+ * from that same pension would be arguing in a circle.
34
+ *
35
+ * ── Why it is calibrated by a walk, not a formula ───
36
+ *
37
+ * Closed form exists. With flat pay, a constant rate `r` and
38
+ * `n` whole years, the balance is
39
+ *
40
+ * P = (W / 54) x (r^n - 1) / (r - 1)
41
+ *
42
+ * and inverting gives `W = 54 P (r - 1) / (r^n - 1)`. That is
43
+ * the oracle the tests check this against, and it is exact for
44
+ * the case it describes.
45
+ *
46
+ * The code does not use it, because the cases it does not
47
+ * describe are ordinary. A member joining in September has a
48
+ * seven-twelfths first year. A join date before April 2015 is
49
+ * clamped to the scheme's own start. The first row of any walk
50
+ * carries no uplift. Each is a special case in the formula and
51
+ * none in a walk.
52
+ *
53
+ * So the calibration exploits the one structural fact that
54
+ * makes a walk enough: **the ledger is exactly LINEAR in pay.**
55
+ * Every slice is `pay x months / 12 / 54`, and everything after
56
+ * is multiplication by uplift factors and addition. Walk once
57
+ * at a pay of 1, read the closing balance, and that is the
58
+ * whole accumulation factor; the pay that hits any target is
59
+ * one division. One walk, exact, and no second copy of the
60
+ * recurrence to drift out of step with the first.
61
+ *
62
+ * ── Checked against a real statement ────────────────
63
+ *
64
+ * The estimate lands within 0.2% of a real member's own career
65
+ * average, once both are expressed in the same money — see
66
+ * `tests/golden-abs.test.ts`. That check matters more than it
67
+ * looks, because the naive comparison FAILS: the earnings
68
+ * printed on a statement are each year's cash, carrying that
69
+ * year's pay award inside them, so averaging them raw mixes
70
+ * 2021 pounds with 2025 pounds and reads low by a tenth.
71
+ */
72
+ import type { MemberLedger } from './ledger.js';
73
+ import type { Prices } from './prices.js';
74
+ /** An illustrative run-up to a stated balance. */
75
+ export interface EstimatedHistory {
76
+ /**
77
+ * The flat pensionable pay that reproduces the stated
78
+ * balance, in the money of the run it belongs to.
79
+ *
80
+ * Reportable, and worth reporting: it is the one number a
81
+ * reader can sanity-check the illustration against. Wildly
82
+ * below the pay they entered usually means the join date is
83
+ * earlier than their 2015-scheme service really began.
84
+ */
85
+ readonly impliedPay: number;
86
+ /** The walked years, ending exactly on the stated balance. */
87
+ readonly ledger: MemberLedger;
88
+ /** First and last scheme year covered, inclusive. */
89
+ readonly from: number;
90
+ readonly to: number;
91
+ }
92
+ /**
93
+ * Estimate the years from `joinDate` up to a stated balance.
94
+ *
95
+ * Null when there is nothing to draw — a member who joined in
96
+ * or after the statement's own scheme year has no run-up, and
97
+ * inventing one would put pension on the chart before they had
98
+ * any.
99
+ */
100
+ export declare function estimateHistory({ joinDate, statedBalance, statementSchemeYearEnd, prices, }: {
101
+ joinDate: Date;
102
+ statedBalance: number;
103
+ statementSchemeYearEnd: number;
104
+ prices: Prices;
105
+ }): EstimatedHistory | null;
@@ -0,0 +1,115 @@
1
+ /**
2
+ * The years BEFORE a statement, estimated for illustration.
3
+ *
4
+ * A member hands over one figure — the pension accrued by their
5
+ * statement's date — and their join date. Everything between
6
+ * the two is unknown: this library has no route to anyone's
7
+ * year-by-year earnings. Without this the chart can only begin
8
+ * at the statement, and the join date — which the form asks for,
9
+ * visibly — does nothing at all.
10
+ *
11
+ * This fills that gap the only honest way available. It asks
12
+ * what FLAT pensionable pay, in today's money, would have
13
+ * produced exactly the balance the member states, over exactly
14
+ * the years they say they were in the scheme — and then walks
15
+ * that pay forward as the illustration.
16
+ *
17
+ * ── What it is and is not ───────────────────────────
18
+ *
19
+ * It is **for plotting**. It gives the built-up arm a shape and
20
+ * a starting point, and it is drawn in the same line as the
21
+ * rest because it is the same pension. What makes it honest is
22
+ * the disclosure beside it, not a different colour.
23
+ *
24
+ * It is **not a reconstruction of anyone's career**. Real
25
+ * earnings are not flat: the statement this was checked against
26
+ * runs £42k, £33k, £37k, £51k across four years, and no single
27
+ * figure produces that shape. What the estimate gets right is
28
+ * the ENDPOINT, exactly, and the trajectory approximately.
29
+ *
30
+ * It is **not an input to the projection**. Nothing after the
31
+ * statement reads it; the forward figures use the pay the
32
+ * member actually gave. A pension projected from a pay derived
33
+ * from that same pension would be arguing in a circle.
34
+ *
35
+ * ── Why it is calibrated by a walk, not a formula ───
36
+ *
37
+ * Closed form exists. With flat pay, a constant rate `r` and
38
+ * `n` whole years, the balance is
39
+ *
40
+ * P = (W / 54) x (r^n - 1) / (r - 1)
41
+ *
42
+ * and inverting gives `W = 54 P (r - 1) / (r^n - 1)`. That is
43
+ * the oracle the tests check this against, and it is exact for
44
+ * the case it describes.
45
+ *
46
+ * The code does not use it, because the cases it does not
47
+ * describe are ordinary. A member joining in September has a
48
+ * seven-twelfths first year. A join date before April 2015 is
49
+ * clamped to the scheme's own start. The first row of any walk
50
+ * carries no uplift. Each is a special case in the formula and
51
+ * none in a walk.
52
+ *
53
+ * So the calibration exploits the one structural fact that
54
+ * makes a walk enough: **the ledger is exactly LINEAR in pay.**
55
+ * Every slice is `pay x months / 12 / 54`, and everything after
56
+ * is multiplication by uplift factors and addition. Walk once
57
+ * at a pay of 1, read the closing balance, and that is the
58
+ * whole accumulation factor; the pay that hits any target is
59
+ * one division. One walk, exact, and no second copy of the
60
+ * recurrence to drift out of step with the first.
61
+ *
62
+ * ── Checked against a real statement ────────────────
63
+ *
64
+ * The estimate lands within 0.2% of a real member's own career
65
+ * average, once both are expressed in the same money — see
66
+ * `tests/golden-abs.test.ts`. That check matters more than it
67
+ * looks, because the naive comparison FAILS: the earnings
68
+ * printed on a statement are each year's cash, carrying that
69
+ * year's pay award inside them, so averaging them raw mixes
70
+ * 2021 pounds with 2025 pounds and reads low by a tenth.
71
+ */
72
+ import { buildLedger } from './ledger.js';
73
+ import { schemeYearEndDate, seedFromJoinDate } from './seed.js';
74
+ /**
75
+ * Estimate the years from `joinDate` up to a stated balance.
76
+ *
77
+ * Null when there is nothing to draw — a member who joined in
78
+ * or after the statement's own scheme year has no run-up, and
79
+ * inventing one would put pension on the chart before they had
80
+ * any.
81
+ */
82
+ export function estimateHistory({ joinDate, statedBalance, statementSchemeYearEnd, prices, }) {
83
+ const seed = seedFromJoinDate(joinDate);
84
+ const first = seed.atSchemeYearEnd + 1;
85
+ if (first > statementSchemeYearEnd || statedBalance <= 0) {
86
+ return null;
87
+ }
88
+ const walk = (pensionableEarnings) => buildLedger({
89
+ seed,
90
+ pensionableEarnings,
91
+ // Accruing throughout, and drawing far enough out that no
92
+ // retirement factor lands inside the window.
93
+ exitDate: schemeYearEndDate(statementSchemeYearEnd),
94
+ retirementDate: schemeYearEndDate(statementSchemeYearEnd + 60),
95
+ prices,
96
+ drawingFor: () => null,
97
+ through: statementSchemeYearEnd,
98
+ });
99
+ // The accumulation factor, read off the model itself rather
100
+ // than re-derived: pay of 1 in, whole factor out.
101
+ const perPound = walk(1).closingAt(statementSchemeYearEnd);
102
+ // Finite AND positive, spelt out: `<= 0` alone lets NaN
103
+ // through, and a NaN factor would divide into an implied pay
104
+ // that renders as a real figure rather than an absent one.
105
+ if (!Number.isFinite(perPound) || perPound <= 0)
106
+ return null;
107
+ const impliedPay = statedBalance / perPound;
108
+ return {
109
+ impliedPay,
110
+ ledger: walk(impliedPay),
111
+ from: first,
112
+ to: statementSchemeYearEnd,
113
+ };
114
+ }
115
+ //# sourceMappingURL=history.js.map
@@ -0,0 +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,EAAC,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAqB9D;;;;;;;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,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;IACvC,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"}
@@ -0,0 +1,146 @@
1
+ /**
2
+ * The member's pension as a balance-forward periodic ledger.
3
+ *
4
+ * closing(N) = [closing(N−1) × (1 + uplift(N)) + earned(N)]
5
+ * × factor(N) − cash(N)
6
+ *
7
+ * One uniform row per scheme year. `factor` is 1 and `cash` is 0
8
+ * on every row but the retirement one, so there is no branch in
9
+ * the recurrence — only a multiplier that is usually the
10
+ * identity, the same trick as an uplift of zero.
11
+ *
12
+ * **The order is load-bearing.** The pot is revalued FIRST and
13
+ * the year's slice added after, so a slice earns no revaluation
14
+ * in the scheme year it is earned. The other order overstates a
15
+ * real statement by 3.2% while every internal test still passes.
16
+ *
17
+ * This is a READ MODEL, not a book of record: it is rebuilt from
18
+ * source on every call, never stored, and every row is frozen at
19
+ * construction.
20
+ */
21
+ import type { FactorProvenance } from '../gad/factor-table.js';
22
+ import type { Prices } from './prices.js';
23
+ import type { AppliedUplift, MemberPhase } from './uplift.js';
24
+ import type { LedgerSeed } from './seed.js';
25
+ /** The retirement event, recorded on the year it falls in. */
26
+ export interface AppliedDrawing {
27
+ /** The retirement date itself — drawing is date-based, by
28
+ * years and months from NPA, not annual. */
29
+ readonly on: Date;
30
+ readonly factor: number;
31
+ readonly kind: 'erf' | 'lrf';
32
+ /** Which issue of which table the factor came from. */
33
+ readonly provenance: FactorProvenance;
34
+ /** Pension given up and cash taken, or null if none was. */
35
+ readonly commuted: {
36
+ readonly pensionGivenUp: number;
37
+ readonly lumpSum: number;
38
+ } | null;
39
+ }
40
+ /** One scheme year, accounted for the way the scheme accounts
41
+ * for it. Every field is nominal £/yr unless said otherwise. */
42
+ export interface LedgerYear {
43
+ /** Scheme year END — 2026 for 2025/26. The same key the
44
+ * revaluation table uses, so a row joins by value. */
45
+ readonly schemeYearEnd: number;
46
+ readonly phase: MemberPhase;
47
+ /** Nominal pensionable pay for this year, or null when not
48
+ * accruing. In a partial year this is the PAY scaled by months
49
+ * worked — the 1/54 divisor is never pro-rated. */
50
+ readonly pensionableEarnings: number | null;
51
+ /** pensionableEarnings / 54, or 0. */
52
+ readonly earned: number;
53
+ /**
54
+ * Whether this year's earnings are the scheme's own figure or
55
+ * ours. Sits BESIDE the uplift's provenance rather than
56
+ * folded into it, because the two answer different questions:
57
+ * this one is about the PAY, `uplift.from.si` about the RATE.
58
+ *
59
+ * It is the only knownness a projected row carries. Every
60
+ * uplift after the seed is the caller's assumption, so
61
+ * `uplift.from.si` is null on every row and no row is the
62
+ * scheme's own record — the seed is the last figure that was.
63
+ *
64
+ * Always `assumed` where anything was earned: the library has
65
+ * no route to a member's actual year-by-year pay, so every
66
+ * non-zero figure derives from the single pay the caller gave,
67
+ * held flat in real terms. `none` where the member was not
68
+ * accruing, which is the only case with nothing to be wrong
69
+ * about. A statement's own earnings history would add a
70
+ * `given` here, and is the reason this field exists now.
71
+ */
72
+ readonly earningsBasis: 'assumed' | 'none';
73
+ /** Brought INTO this year — last year's closing balance,
74
+ * untouched. The whole banked pot, not a slice. */
75
+ readonly opening: number;
76
+ /** Applied at the START of this year, to the WHOLE opening
77
+ * balance. Null for the first year of membership. */
78
+ readonly uplift: AppliedUplift | null;
79
+ /** opening × (1 + uplift), before this year's slice. */
80
+ readonly revalued: number;
81
+ /** The retirement transform, on the one row where it happens. */
82
+ readonly drawing: AppliedDrawing | null;
83
+ /** (revalued + earned) × factor − pension given up. Before the
84
+ * drawing row an accrued ENTITLEMENT; after it, a pension IN
85
+ * PAYMENT — the same money, with `drawing` the dated record of
86
+ * the moment it changed character. */
87
+ readonly closing: number;
88
+ }
89
+ /** Named indices into the ledger, not stored copies of it. */
90
+ export interface MemberLedger {
91
+ readonly years: readonly LedgerYear[];
92
+ /** Closing balance in force at `date`, in this walk's own
93
+ * money. Flat between steps, which is the whole point.
94
+ *
95
+ * ONE ruler per ledger: a walk is either the cash projection
96
+ * or the today's-money one, and it reports in the money it
97
+ * was built in. Pairing the two is the orchestrator's job —
98
+ * see `pension-projection.ts` — because neither walk can see
99
+ * the other. */
100
+ atDate(date: Date): number;
101
+ /** Closing balance at the end of a scheme year. Years at or
102
+ * before the seed's own year return the seed balance: the
103
+ * walk starts after it, so there is no row, but there is
104
+ * still an answer. */
105
+ closingAt(schemeYearEnd: number): number;
106
+ /** The ACCRUED entitlement at `date`, before any retirement
107
+ * factor. Distinct from `atDate`, which reports the pension
108
+ * actually in force: on the row carrying the drawing those
109
+ * two differ by the ERF or LRF, and asking "what had they
110
+ * built up" must not be answered with the reduced figure. */
111
+ accruedAt(date: Date): number;
112
+ /** The statement-shaped view: the years a member can lay
113
+ * beside the paper. */
114
+ earningsRows(): readonly LedgerYear[];
115
+ }
116
+ export interface LedgerRequest {
117
+ readonly seed: LedgerSeed;
118
+ /**
119
+ * Pensionable pay in TODAY'S MONEY, held flat.
120
+ *
121
+ * **This is the base case and the only one built.** Every
122
+ * year's slice is the same figure in today's money; what
123
+ * varies is only its expression in each year's own cash,
124
+ * because a nominal model that froze pay in CASH while
125
+ * revaluing the pot above CPI would count inflation twice.
126
+ *
127
+ * Pay progression is a deliberate non-feature — issue #11.
128
+ * Anything that makes a year's slice differ from
129
+ * `pensionableEarnings / 54` in today's money is that unbuilt
130
+ * feature arriving by accident: quote the figure at the
131
+ * statement date and hold it flat in real terms FROM there,
132
+ * and the member collects a 5.6% real pay rise. Held to a
133
+ * date, `earnings in today's money are pay / 54, every year`
134
+ * is the invariant that catches it.
135
+ */
136
+ readonly pensionableEarnings: number;
137
+ /** Last day of service. */
138
+ readonly exitDate: Date;
139
+ readonly retirementDate: Date;
140
+ readonly prices: Prices;
141
+ /** Built once, against the balance standing at retirement. */
142
+ readonly drawingFor: (revalued: number) => AppliedDrawing | null;
143
+ /** Last scheme year to walk. */
144
+ readonly through: number;
145
+ }
146
+ export declare function buildLedger(req: LedgerRequest): MemberLedger;