@actuarial-ts/core 0.2.0 → 0.4.0

package/src/triangle.ts

@@ -0,0 +1,235 @@
+import type {
+  ClaimSnapshot,
+  OriginCadence,
+  Triangle,
+  TriangleKind,
+} from "./types.js";
+import { ReservingError } from "./types.js";
+
+/**
+ * Builds development triangles from claim-level evaluation snapshots.
+ *
+ * Conventions:
+ * - A claim belongs to the origin period containing its accident date.
+ * - Development age is measured in months from the start of the origin
+ *   period; the age-m evaluation date is the last day of month (start + m - 1).
+ * - A cell is observable only when its evaluation date is on or before the
+ *   as-of date; unobservable cells are null.
+ * - A claim's state at an evaluation date is the latest snapshot on or
+ *   before that date (step function). A reported claim with no snapshot yet
+ *   counts as reported/open with zero paid and zero case.
+ */
+
+interface ParsedDate {
+  y: number;
+  m: number; // 1-12
+  d: number;
+}
+
+function parseISO(date: string): ParsedDate {
+  const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(date);
+  if (!match) {
+    throw new ReservingError("BAD_DATE", `Invalid ISO date: "${date}"`);
+  }
+  const y = Number(match[1]);
+  const m = Number(match[2]);
+  const d = Number(match[3]);
+  if (m < 1 || m > 12 || d < 1 || d > 31) {
+    throw new ReservingError("BAD_DATE", `Invalid ISO date: "${date}"`);
+  }
+  return { y, m, d };
+}
+
+function monthIndex(p: ParsedDate): number {
+  return p.y * 12 + (p.m - 1);
+}
+
+function daysInMonth(y: number, m: number): number {
+  return new Date(Date.UTC(y, m, 0)).getUTCDate();
+}
+
+/** ISO date of the last day of the month holding this month index. */
+function endOfMonthISO(mIdx: number): string {
+  const y = Math.floor(mIdx / 12);
+  const m = (mIdx % 12) + 1;
+  const d = daysInMonth(y, m);
+  return `${String(y).padStart(4, "0")}-${String(m).padStart(2, "0")}-${String(d).padStart(2, "0")}`;
+}
+
+function periodIndexOf(p: ParsedDate, cadence: OriginCadence): number {
+  return cadence === "annual" ? p.y : p.y * 4 + Math.floor((p.m - 1) / 3);
+}
+
+function periodLabel(index: number, cadence: OriginCadence): string {
+  if (cadence === "annual") return String(index);
+  const y = Math.floor(index / 4);
+  const q = (index % 4) + 1;
+  return `${y}Q${q}`;
+}
+
+/** Month index of the first month of an origin period. */
+function periodStartMonth(index: number, cadence: OriginCadence): number {
+  return cadence === "annual" ? index * 12 : index * 3;
+}
+
+export interface BuildTrianglesOptions {
+  cadence: OriginCadence;
+  /** ISO evaluation date of the analysis (the latest diagonal). */
+  asOfDate: string;
+}
+
+export interface TriangleSet {
+  paid: Triangle;
+  incurred: Triangle;
+  caseReserve: Triangle;
+  reportedCount: Triangle;
+  openCount: Triangle;
+  closedCount: Triangle;
+  closedWithPayCount: Triangle;
+}
+
+interface ClaimTimeline {
+  originIdx: number;
+  reportISO: string;
+  /** Snapshots sorted ascending by evaluation date. */
+  snapshots: ClaimSnapshot[];
+}
+
+export function buildTriangles(
+  claims: ClaimSnapshot[],
+  options: BuildTrianglesOptions,
+): TriangleSet {
+  const { cadence, asOfDate } = options;
+  if (claims.length === 0) {
+    throw new ReservingError("NO_CLAIMS", "Cannot build triangles from an empty loss run");
+  }
+  const asOf = parseISO(asOfDate);
+  const asOfMonth = monthIndex(asOf);
+  const asOfIsMonthEnd = asOf.d === daysInMonth(asOf.y, asOf.m);
+  // The latest complete evaluation month.
+  const lastCompleteMonth = asOfIsMonthEnd ? asOfMonth : asOfMonth - 1;
+  const cadenceMonths = cadence === "annual" ? 12 : 3;
+
+  // Group snapshots into claim timelines and find the origin period range.
+  const byClaim = new Map<string, ClaimTimeline>();
+  let minPeriod = Infinity;
+  let maxPeriod = -Infinity;
+  for (const snap of claims) {
+    const accident = parseISO(snap.accidentDate);
+    if (snap.evaluationDate > asOfDate) continue; // beyond the analysis date
+    const period = periodIndexOf(accident, cadence);
+    minPeriod = Math.min(minPeriod, period);
+    maxPeriod = Math.max(maxPeriod, period);
+    let timeline = byClaim.get(snap.claimId);
+    if (!timeline) {
+      timeline = { originIdx: period, reportISO: snap.reportDate, snapshots: [] };
+      byClaim.set(snap.claimId, timeline);
+    }
+    timeline.snapshots.push(snap);
+  }
+  if (!Number.isFinite(minPeriod)) {
+    throw new ReservingError(
+      "NO_CLAIMS",
+      "No claim snapshots fall on or before the as-of date",
+    );
+  }
+  for (const timeline of byClaim.values()) {
+    timeline.snapshots.sort((a, b) =>
+      a.evaluationDate < b.evaluationDate ? -1 : a.evaluationDate > b.evaluationDate ? 1 : 0,
+    );
+  }
+
+  const nOrigins = maxPeriod - minPeriod + 1;
+  const origins: string[] = [];
+  for (let p = minPeriod; p <= maxPeriod; p++) origins.push(periodLabel(p, cadence));
+
+  // Ages available to the oldest origin period determine the column count.
+  const oldestStart = periodStartMonth(minPeriod, cadence);
+  const maxAge = lastCompleteMonth - oldestStart + 1;
+  const nAges = Math.floor(maxAge / cadenceMonths);
+  if (nAges < 1) {
+    throw new ReservingError(
+      "NO_DEVELOPMENT",
+      "The as-of date precedes the first complete development age",
+    );
+  }
+  const ages: number[] = [];
+  for (let j = 1; j <= nAges; j++) ages.push(j * cadenceMonths);
+
+  const mk = (kind: TriangleKind): Triangle => ({
+    kind,
+    origins: [...origins],
+    ages: [...ages],
+    values: Array.from({ length: nOrigins }, (_, i) =>
+      ages.map((age) => {
+        const evalMonth = periodStartMonth(minPeriod + i, cadence) + age - 1;
+        return evalMonth <= lastCompleteMonth ? 0 : null;
+      }),
+    ),
+  });
+
+  const set: TriangleSet = {
+    paid: mk("paid"),
+    incurred: mk("incurred"),
+    caseReserve: mk("caseReserve"),
+    reportedCount: mk("reportedCount"),
+    openCount: mk("openCount"),
+    closedCount: mk("closedCount"),
+    closedWithPayCount: mk("closedWithPayCount"),
+  };
+
+  const add = (tri: Triangle, i: number, j: number, v: number) => {
+    const cell = tri.values[i]![j];
+    if (cell !== null && cell !== undefined) tri.values[i]![j] = cell + v;
+  };
+
+  for (const timeline of byClaim.values()) {
+    const i = timeline.originIdx - minPeriod;
+    const originStart = periodStartMonth(timeline.originIdx, cadence);
+    for (let j = 0; j < nAges; j++) {
+      const evalMonth = originStart + ages[j]! - 1;
+      if (evalMonth > lastCompleteMonth) break; // this and later cells are null
+      const evalISO = endOfMonthISO(evalMonth);
+      if (timeline.reportISO > evalISO) continue; // not yet reported
+      // Latest snapshot on or before the cell's evaluation date.
+      let state: ClaimSnapshot | null = null;
+      for (const snap of timeline.snapshots) {
+        if (snap.evaluationDate <= evalISO) state = snap;
+        else break;
+      }
+      const paid = state?.paidToDate ?? 0;
+      const caseReserve = state?.status === "open" ? (state?.caseReserve ?? 0) : 0;
+      const isClosed = state?.status === "closed";
+      add(set.reportedCount, i, j, 1);
+      add(set.paid, i, j, paid);
+      add(set.caseReserve, i, j, caseReserve);
+      add(set.incurred, i, j, paid + caseReserve);
+      if (isClosed) {
+        add(set.closedCount, i, j, 1);
+        if (paid > 0) add(set.closedWithPayCount, i, j, 1);
+      } else {
+        add(set.openCount, i, j, 1);
+      }
+    }
+  }
+
+  return set;
+}
+
+/** Constructs a triangle directly from a grid of values (import path). */
+export function triangleFromGrid(
+  kind: TriangleKind,
+  origins: string[],
+  ages: number[],
+  values: (number | null)[][],
+): Triangle {
+  if (values.length !== origins.length) {
+    throw new ReservingError("SHAPE", "Row count does not match origin count");
+  }
+  for (const row of values) {
+    if (row.length !== ages.length) {
+      throw new ReservingError("SHAPE", "Column count does not match age count");
+    }
+  }
+  return { kind, origins: [...origins], ages: [...ages], values: values.map((r) => [...r]) };
+}

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;
+  }
+}