@actuarial-ts/core 0.1.0 → 0.3.0

package/src/triangleAlgebra.ts

@@ -0,0 +1,111 @@
+import type { Triangle } from "./types.js";
+import { ReservingError } from "./types.js";
+import { isNum } from "./util.js";
+
+/**
+ * Triangle algebra: incremental <-> cumulative conversion and cell-wise
+ * arithmetic. Prerequisites for the stochastic methods (the ODP model works
+ * on incrementals) and for gross/ceded/net and paid+case identities.
+ *
+ * Ground truth:
+ * - cumulativeToIncremental: an interior null makes the increments touching
+ *   it undefined - the hole's cell and the cell immediately after it are
+ *   null, and increments RESUME wherever two consecutive cells are both
+ *   observed. Nothing is ever fabricated to bridge a hole.
+ * - incrementalToCumulative: accumulation stops at the FIRST null in a row
+ *   (a later observed increment has no defined cumulative base).
+ * - Incremental[0] = cumulative[0] (the first cell is its own increment).
+ */
+
+function sameShape(a: Triangle, b: Triangle): boolean {
+  return (
+    a.origins.length === b.origins.length &&
+    a.origins.every((o, i) => o === b.origins[i]) &&
+    a.ages.length === b.ages.length &&
+    a.ages.every((v, j) => v === b.ages[j])
+  );
+}
+
+function assertShape(a: Triangle, b: Triangle): void {
+  if (!sameShape(a, b)) {
+    throw new ReservingError(
+      "SHAPE",
+      "Triangle algebra requires identical origins and development ages",
+    );
+  }
+}
+
+/** Cumulative -> incremental. First cell passes through; nulls propagate. */
+export function cumulativeToIncremental(tri: Triangle): Triangle {
+  return {
+    kind: tri.kind,
+    origins: [...tri.origins],
+    ages: [...tri.ages],
+    values: tri.values.map((row) => {
+      const out: (number | null)[] = new Array(row.length).fill(null);
+      for (let j = 0; j < row.length; j++) {
+        const cur = row[j] ?? null;
+        if (!isNum(cur)) continue;
+        if (j === 0) {
+          out[0] = cur;
+          continue;
+        }
+        const prev = row[j - 1] ?? null;
+        out[j] = isNum(prev) ? cur - prev : null;
+      }
+      return out;
+    }),
+  };
+}
+
+/** Incremental -> cumulative. A null stops accumulation for the row. */
+export function incrementalToCumulative(tri: Triangle): Triangle {
+  return {
+    kind: tri.kind,
+    origins: [...tri.origins],
+    ages: [...tri.ages],
+    values: tri.values.map((row) => {
+      const out: (number | null)[] = new Array(row.length).fill(null);
+      let running: number | null = null;
+      for (let j = 0; j < row.length; j++) {
+        const v = row[j] ?? null;
+        if (!isNum(v)) break;
+        running = (running ?? 0) + v;
+        out[j] = running;
+      }
+      return out;
+    }),
+  };
+}
+
+/** Cell-wise a + b; null wherever either side is null. */
+export function addTriangles(a: Triangle, b: Triangle): Triangle {
+  assertShape(a, b);
+  return {
+    kind: a.kind,
+    origins: [...a.origins],
+    ages: [...a.ages],
+    values: a.values.map((row, i) =>
+      row.map((v, j) => {
+        const w = b.values[i]![j] ?? null;
+        return isNum(v ?? null) && isNum(w) ? v! + w : null;
+      }),
+    ),
+  };
+}
+
+/** Cell-wise a - b (gross - ceded = net); null wherever either side is null. */
+export function subtractTriangles(a: Triangle, b: Triangle): Triangle {
+  assertShape(a, b);
+  return {
+    kind: a.kind,
+    origins: [...a.origins],
+    ages: [...a.ages],
+    values: a.values.map((row, i) =>
+      row.map((v, j) => {
+        const w = b.values[i]![j] ?? null;
+        return isNum(v ?? null) && isNum(w) ? v! - w : null;
+      }),
+    ),
+  };
+}

package/src/types.ts

@@ -0,0 +1,357 @@
+/**
+ * Core domain types for the reserving engine.
+ *
+ * Triangle semantics (ground truth for the whole engine):
+ * - rows = origin periods, columns = development ages
+ * - cells not yet observable are null
+ * - every computation must be null-safe; division by a missing, zero, or
+ *   negative denominator yields "no factor" (null), never an exception or NaN
+ */
+
+/** Cadence of origin periods. */
+export type OriginCadence = "annual" | "quarterly";
+
+/** The kinds of triangles the engine knows how to build and analyze. */
+export type TriangleKind =
+  | "paid"
+  | "incurred"
+  | "caseReserve"
+  | "reportedCount"
+  | "openCount"
+  | "closedCount"
+  | "closedWithPayCount";
+
+export interface Triangle {
+  kind: TriangleKind;
+  /** Human-readable origin period labels, ascending (e.g. "2019", "2021Q3"). */
+  origins: string[];
+  /** Development ages in months, ascending (e.g. [12, 24, 36] or [3, 6, 9]). */
+  ages: number[];
+  /** values[originIndex][ageIndex]; null = not yet observable / missing. */
+  values: (number | null)[][];
+}
+
+/** A single claim evaluation snapshot: one row per claim per evaluation date. */
+export interface ClaimSnapshot {
+  claimId: string;
+  /** ISO date (yyyy-mm-dd) the loss occurred. */
+  accidentDate: string;
+  /** ISO date the claim was reported to the insurer. */
+  reportDate: string;
+  /** ISO date this snapshot was evaluated. */
+  evaluationDate: string;
+  /** Cumulative paid loss as of the evaluation date. */
+  paidToDate: number;
+  /** Outstanding case reserve as of the evaluation date. */
+  caseReserve: number;
+  /** Claim status as of the evaluation date. */
+  status: "open" | "closed";
+}
+
+/**
+ * Exposure data by origin period. A period may carry earned premium (the base
+ * for the loss-ratio method), exposure units (the base for the pure-premium
+ * method), or both. The reserving methods are base-agnostic: the caller feeds
+ * whichever base the chosen method uses into `earnedPremium`.
+ */
+export interface ExposureRecord {
+  /** Origin period label matching triangle origins (e.g. "2021" or "2021Q3"). */
+  origin: string;
+  /** Earned premium for the period (the loss-ratio base); null if not imported. */
+  earnedPremium: number | null;
+  /** Exposure units for the period (the pure-premium base); null if not imported. */
+  exposureUnits: number | null;
+}
+
+/** How a link-ratio average is computed for a development column. */
+/**
+ * Keys of the standard averages menu (DEFAULT_AVERAGES). Custom AverageSpec
+ * keys remain legal; these are the ones every exhibit and consumer can rely
+ * on being present.
+ */
+export const AVERAGE_KEYS = [
+  "all-wtd",
+  "all-str",
+  "5-wtd",
+  "5-str",
+  "3-wtd",
+  "3-str",
+  "med-5x1",
+  "geo-all",
+] as const;
+
+export type AverageKey = (typeof AVERAGE_KEYS)[number];
+
+export interface AverageSpec {
+  /** One of AVERAGE_KEYS for the standard menu; custom keys are permitted. */
+  key: AverageKey | (string & {});
+  label: string;
+  kind: "straight" | "weighted" | "medial" | "geometric";
+  /** Number of most recent origin periods to include; omit for all-year. */
+  years?: number;
+}
+
+/** Age-to-age factors for one triangle. */
+export interface DevelopmentFactors {
+  /** For column j: development from ages[j] to ages[j+1]. Length = ages.length - 1. */
+  fromAges: number[];
+  toAges: number[];
+  /** individual[originIndex][columnIndex]; null where not computable. */
+  individual: (number | null)[][];
+  /** Per-average-key, per-column computed averages; null where not computable. */
+  averages: { spec: AverageSpec; values: (number | null)[] }[];
+}
+
+/** Per-column LDF selection made by the user or the advisor. */
+export interface LdfSelections {
+  /** selected[j] = LDF for development column j; null = not selected. */
+  selected: (number | null)[];
+  tailFactor: number;
+}
+
+export interface ChainLadderRow {
+  origin: string;
+  /** Age (months) of the latest observed diagonal cell for this origin. */
+  latestAge: number;
+  /** Value on the latest observed diagonal. */
+  latestValue: number;
+  /** Cumulative development factor from latestAge to ultimate. */
+  cdf: number;
+  percentDeveloped: number;
+  ultimate: number;
+  /** ultimate - latestValue (IBNR on incurred basis; unpaid on paid basis). */
+  unpaid: number;
+}
+
+export interface ChainLadderResult {
+  method: "chainLadder";
+  basis: TriangleKind;
+  /** cdfs[j] = cumulative factor from ages[j] to ultimate (last = tail factor). */
+  cdfs: number[];
+  percentDeveloped: number[];
+  rows: ChainLadderRow[];
+  totals: { latest: number; ultimate: number; unpaid: number };
+  warnings: string[];
+}
+
+export interface BornhuetterFergusonRow {
+  origin: string;
+  latestValue: number;
+  cdf: number;
+  /** A-priori expected loss ratio applied to the exposure base. */
+  aprioriLossRatio: number;
+  earnedPremium: number;
+  expectedUltimate: number;
+  expectedUnreported: number;
+  ultimate: number;
+  unpaid: number;
+}
+
+export interface BornhuetterFergusonResult {
+  method: "bornhuetterFerguson";
+  basis: TriangleKind;
+  rows: BornhuetterFergusonRow[];
+  totals: { latest: number; ultimate: number; unpaid: number };
+  warnings: string[];
+}
+
+export type TailMethod = "exponentialDecay" | "inversePower";
+
+export interface TailFit {
+  method: TailMethod;
+  /** ln(f-1) = intercept + slope * x, x = period index (exp) or ln(index) (power). */
+  intercept: number;
+  slope: number;
+  rSquared: number;
+  nPoints: number;
+  /** Individual extrapolated age-to-age factors beyond the last observed age. */
+  extrapolatedFactors: number[];
+  tailFactor: number;
+  valid: boolean;
+  warnings: string[];
+}
+
+export interface MackRow {
+  origin: string;
+  latest: number;
+  ultimate: number;
+  reserve: number;
+  standardError: number;
+  /** standardError / reserve; null when reserve is 0. */
+  cv: number | null;
+}
+
+export interface MackResult {
+  method: "mack";
+  /** The projection factors: selected LDFs when supplied, else volume-weighted. */
+  developmentFactors: number[];
+  sigmaSquared: number[];
+  /** Tail factor the projection used (1 = none). */
+  tailFactor?: number;
+  /** Extrapolated sigma^2 for the tail step; present only when a tail was applied. */
+  sigmaSquaredTail?: number;
+  rows: MackRow[];
+  totals: {
+    latest: number;
+    ultimate: number;
+    reserve: number;
+    standardError: number;
+    cv: number | null;
+  };
+  warnings: string[];
+}
+
+export interface MerzWuthrichRow {
+  origin: string;
+  /** Chain ladder reserve at time I (ultimate minus the latest diagonal). */
+  reserve: number;
+  /**
+   * sqrt of the one-year CDR msep (Merz-Wuthrich 2008, eq. 3.17): the
+   * prediction uncertainty of 0 for next year's observable claims
+   * development result - the Solvency II / SST one-year reserve risk.
+   */
+  cdrMsepRoot: number;
+  /** sqrt of Mack's full-runoff msep for the same origin (ultimate view). */
+  mackMsepRoot: number;
+  /** cdrMsepRoot / mackMsepRoot; null when the Mack msep is 0. */
+  oneYearRatio: number | null;
+}
+
+export interface MerzWuthrichResult {
+  method: "merzWuthrich";
+  /** Volume-weighted development factors fhat_j estimated at time I. */
+  developmentFactors: number[];
+  /** sigma^2_j estimates; the final column uses Mack's extrapolation (4.1). */
+  sigmaSquared: number[];
+  rows: MerzWuthrichRow[];
+  totals: {
+    reserve: number;
+    /** Aggregate one-year msep root per eq. (3.18), cross terms included. */
+    cdrMsepRoot: number;
+    /** Mack's total full-runoff msep root, cross terms included. */
+    mackMsepRoot: number;
+    /** totals.cdrMsepRoot / totals.mackMsepRoot; null when the Mack total is 0. */
+    oneYearRatio: number | null;
+  };
+  warnings: string[];
+}
+
+export interface BerquistCaseAdequacyResult {
+  /** Average open case reserve per open claim, by cell. */
+  averageCaseReserves: (number | null)[][];
+  /** Annual severity trend used to restate historical average case reserves. */
+  severityTrend: number;
+  /** Whether the trend was fitted from the data or supplied by the user. */
+  trendSource: "fitted" | "user";
+  restatedAverageCaseReserves: (number | null)[][];
+  /** paid + restated average case reserve x open counts. */
+  adjustedIncurred: Triangle;
+  warnings: string[];
+}
+
+export interface BerquistSettlementResult {
+  /** disposal[i][j] = closed counts / ultimate counts for origin i. */
+  disposalRates: (number | null)[][];
+  /** Selected disposal rate per age (latest diagonal). */
+  selectedDisposalRates: (number | null)[];
+  ultimateCounts: number[];
+  adjustedClosedCounts: (number | null)[][];
+  interpolation: "exponential" | "linear";
+  adjustedPaid: Triangle;
+  warnings: string[];
+}
+
+export interface CalendarYearDiagnostic {
+  /** One entry per calendar-period diagonal that has testable factors. */
+  diagonals: {
+    label: string;
+    countLarge: number;
+    countSmall: number;
+    z: number;
+    expectedZ: number;
+    varianceZ: number;
+  }[];
+  totalZ: number;
+  expectedTotalZ: number;
+  varianceTotalZ: number;
+  /** Total Z outside the 95% confidence range indicates calendar-year effects. */
+  significant: boolean;
+  confidenceInterval: [number, number];
+}
+
+export interface DiagnosticsResult {
+  paidToIncurredRatios: (number | null)[][];
+  averageCaseReserves: (number | null)[][];
+  /** closed / reported counts by cell. */
+  closureRates: (number | null)[][];
+  calendarYearTest: CalendarYearDiagnostic | null;
+  /** Human-readable findings an actuary would care about. */
+  findings: DiagnosticFinding[];
+}
+
+export interface DiagnosticFinding {
+  severity: "info" | "warning" | "critical";
+  code: string;
+  message: string;
+}
+
+/**
+ * Every machine-readable code a ReservingError can carry. This registry is
+ * public contract: consumers may switch exhaustively on ReservingErrorCode,
+ * and test/registry.test.ts enforces that the list matches every constructor
+ * site in source. Add the code here when introducing a new throw.
+ */
+export const RESERVING_ERROR_CODES = [
+  "BAD_ADJ",
+  "BAD_CAP",
+  "BAD_CASHFLOWS",
+  "BAD_CDF",
+  "BAD_COUNTS",
+  "BAD_DATE",
+  "BAD_ELR",
+  "BAD_FIT",
+  "BAD_INTERCHANGE",
+  "BAD_LIMIT",
+  "BAD_LOSSES",
+  "BAD_MARGIN",
+  "BAD_ORIGIN",
+  "BAD_PERCENTILE",
+  "BAD_PREMIUM",
+  "BAD_RATE",
+  "BAD_RATE_CHANGE",
+  "BAD_RATIO",
+  "BAD_SEED",
+  "BAD_SHAPE",
+  "BAD_TABLE",
+  "BAD_TAIL",
+  "BAD_TREND",
+  "BAD_WEIGHTS",
+  "INCOHERENT_SELECTION",
+  "INFINITE_MEAN",
+  "NO_APRIORI",
+  "NO_BF_ROWS",
+  "NO_CLAIMS",
+  "NO_DATA",
+  "NO_DEVELOPMENT",
+  "NO_FACTOR",
+  "NO_PROVENANCE",
+  "NO_SELECTIONS",
+  "SELECTION_SHAPE",
+  "SHAPE",
+  "TABLE_RANGE",
+  "TOO_SMALL",
+  "UNSUPPORTED_VALUE",
+  "UNSUPPORTED_VERSION",
+] as const;
+
+export type ReservingErrorCode = (typeof RESERVING_ERROR_CODES)[number];
+
+/** Thrown for invalid analysis input (all-missing selections, shape mismatches). */
+export class ReservingError extends Error {
+  readonly code: ReservingErrorCode;
+  constructor(code: ReservingErrorCode, message: string) {
+    super(message);
+    this.name = "ReservingError";
+    this.code = code;
+  }
+}