@actuarial-ts/core 0.1.0 → 0.3.0

package/src/stochastic.ts

@@ -0,0 +1,151 @@
+import { ReservingError } from "./types.js";
+import { isNum } from "./util.js";
+
+/**
+ * Stochastic infrastructure: a seeded, reproducible RNG and the shared
+ * result shape every simulation-based method returns.
+ *
+ * Ground truth:
+ * - NO ambient randomness anywhere in the engine: every stochastic method
+ *   takes an explicit integer seed, and the same seed + same inputs must
+ *   reproduce the same output bit for bit (the reproducibility-bundle
+ *   contract depends on it).
+ * - The generator is mulberry32: tiny, fast, well-distributed for
+ *   simulation purposes. It is NOT cryptographic and does not need to be.
+ */
+
+export interface Rng {
+  /** Uniform on [0, 1). */
+  next(): number;
+  /** Standard normal (Box-Muller with cached spare). */
+  normal(): number;
+  /**
+   * Gamma(shape, scale = 1) via Marsaglia-Tsang squeeze (shape >= 1) with
+   * the Ahrens-Dieter boost for shape < 1.
+   */
+  gamma(shape: number): number;
+}
+
+/** Deterministic seeded RNG. Same seed = same stream, forever. */
+export function createRng(seed: number): Rng {
+  if (!Number.isInteger(seed)) {
+    throw new ReservingError("BAD_SEED", "The RNG seed must be an integer");
+  }
+  let a = seed >>> 0;
+  const next = (): number => {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+
+  let spare: number | null = null;
+  const normal = (): number => {
+    if (spare !== null) {
+      const v = spare;
+      spare = null;
+      return v;
+    }
+    // Box-Muller; u clamped away from 0 so log stays finite.
+    let u = next();
+    if (u < 1e-12) u = 1e-12;
+    const v = next();
+    const r = Math.sqrt(-2 * Math.log(u));
+    const theta = 2 * Math.PI * v;
+    spare = r * Math.sin(theta);
+    return r * Math.cos(theta);
+  };
+
+  const gamma = (shape: number): number => {
+    if (!isNum(shape) || shape <= 0) {
+      throw new ReservingError("BAD_SHAPE", "Gamma shape must be a positive number");
+    }
+    if (shape < 1) {
+      // Ahrens-Dieter boost: G(a) = G(a+1) * U^(1/a).
+      const u = Math.max(next(), 1e-12);
+      return gamma(shape + 1) * Math.pow(u, 1 / shape);
+    }
+    // Marsaglia & Tsang (2000).
+    const d = shape - 1 / 3;
+    const c = 1 / Math.sqrt(9 * d);
+    for (;;) {
+      let x: number;
+      let v: number;
+      do {
+        x = normal();
+        v = 1 + c * x;
+      } while (v <= 0);
+      v = v * v * v;
+      const u = next();
+      if (u < 1 - 0.0331 * x * x * x * x) return d * v;
+      if (Math.log(Math.max(u, 1e-300)) < 0.5 * x * x + d * (1 - v + Math.log(v))) return d * v;
+    }
+  };
+
+  return { next, normal, gamma };
+}
+
+/** The percentiles every stochastic summary reports, as fractions. */
+export const STANDARD_PERCENTILES = [0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99] as const;
+
+export interface StochasticSummary {
+  mean: number;
+  /** Sample standard deviation (n - 1). */
+  sd: number;
+  /** sd / |mean|; null when the mean is 0. */
+  cv: number | null;
+  /** Keyed "p50", "p75", ... per STANDARD_PERCENTILES; linear interpolation. */
+  percentiles: Record<string, number>;
+}
+
+export interface StochasticOriginResult {
+  origin: string;
+  summary: StochasticSummary;
+}
+
+export interface StochasticResult {
+  /** What the simulated quantity IS (e.g. "unpaid", "ultimate", "cdr"). */
+  quantity: string;
+  seed: number;
+  nSims: number;
+  total: StochasticSummary;
+  byOrigin: StochasticOriginResult[];
+  /** Total-level simulated values, ascending, for caller-side percentiles/plots. */
+  totalSamples: number[];
+  warnings: string[];
+}
+
+/** Linear-interpolated percentile of a SORTED ascending sample. */
+export function percentileOfSorted(sorted: number[], p: number): number {
+  if (sorted.length === 0) {
+    throw new ReservingError("NO_DATA", "Cannot take a percentile of an empty sample");
+  }
+  if (!isNum(p) || p < 0 || p > 1) {
+    throw new ReservingError("BAD_PERCENTILE", `Percentile must be in [0, 1] (got ${p})`);
+  }
+  const idx = p * (sorted.length - 1);
+  const lo = Math.floor(idx);
+  const hi = Math.ceil(idx);
+  if (lo === hi) return sorted[lo]!;
+  return sorted[lo]! + (idx - lo) * (sorted[hi]! - sorted[lo]!);
+}
+
+/** Summarizes a sample (sorts a copy; the input is not mutated). */
+export function summarizeSample(values: number[]): StochasticSummary {
+  if (values.length < 2) {
+    throw new ReservingError("TOO_SMALL", "A stochastic summary needs at least two simulations");
+  }
+  const sorted = [...values].sort((a, b) => a - b);
+  const n = sorted.length;
+  let sum = 0;
+  for (const v of sorted) sum += v;
+  const mean = sum / n;
+  let ss = 0;
+  for (const v of sorted) ss += (v - mean) ** 2;
+  const sd = Math.sqrt(ss / (n - 1));
+  const percentiles: Record<string, number> = {};
+  for (const p of STANDARD_PERCENTILES) {
+    percentiles[`p${Math.round(p * 100)}`] = percentileOfSorted(sorted, p);
+  }
+  return { mean, sd, cv: mean === 0 ? null : sd / Math.abs(mean), percentiles };
+}

package/src/tail.ts

@@ -0,0 +1,156 @@
+import type { TailFit, TailMethod } from "./types.js";
+import { isNum, ols } from "./util.js";
+
+/**
+ * Tail factor curve fitting per Sherman (1984) and Boor (2006).
+ *
+ * - Exponential decay: ln(LDF_j - 1) is linear in the development period index.
+ * - Inverse power:     ln(LDF_j - 1) is linear in ln(period index).
+ *
+ * The fit runs on the SELECTED age-to-age factors. Guards:
+ * - fewer than MIN_POINTS usable points (factor > 1) -> invalid;
+ * - non-negative slope (growth instead of decay) -> invalid;
+ * - extrapolation is capped in horizon and in total tail size, with a loud
+ *   warning when the cap binds (inverse power with slope > -1 diverges).
+ */
+
+const MIN_POINTS = 3;
+/** Extrapolate at most this many development periods beyond the last age. */
+const MAX_HORIZON = 200;
+/** Stop extrapolating once the incremental factor is this close to 1. */
+const CONVERGENCE_EPS = 1e-7;
+/** A fitted tail beyond this bound is treated as divergent. */
+const MAX_TAIL = 5;
+
+export interface FitTailOptions {
+  method: TailMethod;
+  /**
+   * Selected LDFs by development column (from ages[j] to ages[j+1]);
+   * null entries are skipped.
+   */
+  selectedLdfs: (number | null)[];
+  /** Cap on extrapolated development periods (default 200). */
+  maxHorizon?: number;
+}
+
+export function fitTail(options: FitTailOptions): TailFit {
+  const { method, selectedLdfs } = options;
+  const maxHorizon = options.maxHorizon ?? MAX_HORIZON;
+  const warnings: string[] = [];
+
+  // x = 1-based development period index of each factor; y = ln(f - 1).
+  const xs: number[] = [];
+  const ys: number[] = [];
+  let skippedAtOrBelowOne = 0;
+  for (let j = 0; j < selectedLdfs.length; j++) {
+    const f = selectedLdfs[j] ?? null;
+    if (!isNum(f)) continue;
+    if (f <= 1) {
+      skippedAtOrBelowOne++;
+      continue;
+    }
+    const idx = j + 1;
+    xs.push(method === "exponentialDecay" ? idx : Math.log(idx));
+    ys.push(Math.log(f - 1));
+  }
+  if (skippedAtOrBelowOne > 0) {
+    warnings.push(
+      `${skippedAtOrBelowOne} selected factor(s) at or below 1.000 were excluded from the fit (ln(f-1) undefined)`,
+    );
+  }
+
+  const invalid = (message: string): TailFit => ({
+    method,
+    intercept: NaN,
+    slope: NaN,
+    rSquared: NaN,
+    nPoints: xs.length,
+    extrapolatedFactors: [],
+    tailFactor: 1,
+    valid: false,
+    warnings: [...warnings, message],
+  });
+
+  if (xs.length < MIN_POINTS) {
+    return invalid(
+      `Only ${xs.length} usable point(s); at least ${MIN_POINTS} factors above 1.000 are required to fit a tail curve`,
+    );
+  }
+  const fit = ols(xs, ys);
+  if (!fit) return invalid("Degenerate regression (no variation in development ages)");
+  if (fit.slope >= 0) {
+    return invalid(
+      "Fitted curve grows with age instead of decaying; the selected factors do not support a tail extrapolation with this model",
+    );
+  }
+
+  // Extrapolate incremental factors beyond the last SELECTED column. Trailing
+  // null selections carry no development of their own (chain ladder treats
+  // them as 1.000), so the extrapolation must start right after the last
+  // non-null selection or the curve's predicted factors for those columns
+  // would silently vanish from the tail.
+  let lastIdx = 0; // 1-based index of the last non-null selection
+  for (let j = selectedLdfs.length - 1; j >= 0; j--) {
+    if (isNum(selectedLdfs[j] ?? null)) {
+      lastIdx = j + 1;
+      break;
+    }
+  }
+  if (lastIdx < selectedLdfs.length) {
+    warnings.push(
+      `The last ${selectedLdfs.length - lastIdx} development column(s) have no selected factor; the fitted tail covers them via the curve (chain ladder would otherwise treat them as 1.000)`,
+    );
+  }
+  const extrapolatedFactors: number[] = [];
+  let tail = 1;
+  let converged = false;
+  for (let step = 1; step <= maxHorizon; step++) {
+    const idx = lastIdx + step;
+    const x = method === "exponentialDecay" ? idx : Math.log(idx);
+    const f = 1 + Math.exp(fit.intercept + fit.slope * x);
+    extrapolatedFactors.push(f);
+    tail *= f;
+    if (tail > MAX_TAIL) {
+      return invalid(
+        `Extrapolated tail exceeded ${MAX_TAIL.toFixed(1)} after ${step} periods; the fit is divergent (inverse power with slope > -1 has an unbounded product). Enter a tail judgmentally instead.`,
+      );
+    }
+    if (f - 1 < CONVERGENCE_EPS) {
+      converged = true;
+      break;
+    }
+  }
+  if (!converged) {
+    warnings.push(
+      `Extrapolation stopped at the ${maxHorizon}-period horizon before the factors converged to 1.000; the tail is truncated and understated`,
+    );
+  }
+
+  if (fit.rSquared < 0.8) {
+    warnings.push(
+      `Fit quality is weak (R-squared ${fit.rSquared.toFixed(3)}); treat this tail as indicative only`,
+    );
+  }
+
+  return {
+    method,
+    intercept: fit.intercept,
+    slope: fit.slope,
+    rSquared: fit.rSquared,
+    nPoints: fit.n,
+    extrapolatedFactors,
+    tailFactor: tail,
+    valid: true,
+    warnings,
+  };
+}
+
+/** Fits both supported curves so the user can compare them side by side. */
+export function fitAllTails(
+  selectedLdfs: (number | null)[],
+): { exponentialDecay: TailFit; inversePower: TailFit } {
+  return {
+    exponentialDecay: fitTail({ method: "exponentialDecay", selectedLdfs }),
+    inversePower: fitTail({ method: "inversePower", selectedLdfs }),
+  };
+}

package/src/trend.ts

@@ -0,0 +1,150 @@
+import { ReservingError } from "./types.js";
+import { isNum, ols } from "./util.js";
+
+/**
+ * Trend machinery: log-linear regressions on year-indexed actuarial series
+ * (ultimate frequency, severity, pure premium), with the same menu
+ * discipline as the LDF exhibit - several fitted windows plus judgment.
+ *
+ * ln(y) = a + b·t fitted by ordinary least squares; the annual trend is
+ * e^b - 1. R-squared is reported so thin or noisy series are judged, not
+ * trusted blindly.
+ */
+
+export interface TrendPoint {
+  /** Origin year (the regression x, centered internally). */
+  year: number;
+  /** The series value (must be positive to enter the log fit). */
+  value: number | null;
+}
+
+export interface TrendFit {
+  key: string;
+  label: string;
+  /** Annual trend rate, e.g. 0.05 = +5%/yr; null when the window can't fit. */
+  annualRate: number | null;
+  rSquared: number | null;
+  nPoints: number;
+  /** Yearly values the window actually used. */
+  usedYears: number[];
+  warnings: string[];
+}
+
+export interface TrendAnalysis {
+  points: TrendPoint[];
+  fits: TrendFit[];
+}
+
+function fitWindow(
+  points: { year: number; value: number }[],
+  key: string,
+  label: string,
+): TrendFit {
+  const warnings: string[] = [];
+  if (points.length < 3) {
+    return {
+      key,
+      label,
+      annualRate: null,
+      rSquared: null,
+      nPoints: points.length,
+      usedYears: points.map((p) => p.year),
+      warnings: ["Fewer than 3 usable points; no fit"],
+    };
+  }
+  const xs = points.map((p) => p.year);
+  const ys = points.map((p) => Math.log(p.value));
+  // n >= 3 here, so a null fit can only mean zero variation in years.
+  const fit = ols(xs, ys);
+  if (fit === null) {
+    return {
+      key,
+      label,
+      annualRate: null,
+      rSquared: null,
+      nPoints: points.length,
+      usedYears: xs,
+      warnings: ["No variation in years; no fit"],
+    };
+  }
+  if (points.length < 5) {
+    warnings.push(`Only ${points.length} points; the fitted trend is volatile`);
+  }
+  return {
+    key,
+    label,
+    annualRate: Math.exp(fit.slope) - 1,
+    rSquared: fit.rSquared,
+    nPoints: points.length,
+    usedYears: xs,
+    warnings,
+  };
+}
+
+/**
+ * Fits the standard windows over a year-indexed series: all years, last 5
+ * YEARS, last 3 YEARS, and all years excluding the highest and lowest values
+ * (the ex-hi-lo medial convention). Windows are sized in POINTS PER YEAR so
+ * a quarterly series' "Last 5 years" really spans 5 years (20 quarters), not
+ * 5 points. Non-positive and missing values are excluded from every window
+ * (a log fit cannot see them), with a warning.
+ */
+export function analyzeTrend(points: TrendPoint[], pointsPerYear = 1): TrendAnalysis {
+  const usable = points
+    .filter((p): p is { year: number; value: number } => isNum(p.value) && p.value! > 0)
+    .sort((a, b) => a.year - b.year);
+  const excluded = points.length - usable.length;
+
+  const fits: TrendFit[] = [];
+  const base = (key: string, label: string, pts: { year: number; value: number }[]) => {
+    const fit = fitWindow(pts, key, label);
+    if (excluded > 0) {
+      fit.warnings.push(`${excluded} missing/non-positive year(s) excluded from the series`);
+    }
+    fits.push(fit);
+  };
+
+  const ppy = Math.max(1, Math.round(pointsPerYear));
+  base("all", "All years", usable);
+  base("last5", "Last 5 years", usable.slice(-5 * ppy));
+  base("last3", "Last 3 years", usable.slice(-3 * ppy));
+  if (usable.length >= 5) {
+    const sortedByValue = [...usable].sort((a, b) => a.value - b.value);
+    const hi = sortedByValue[sortedByValue.length - 1]!;
+    const lo = sortedByValue[0]!;
+    base(
+      "exhilo",
+      "Ex high/low",
+      usable.filter((p) => p !== hi && p !== lo),
+    );
+  } else {
+    fits.push({
+      key: "exhilo",
+      label: "Ex high/low",
+      annualRate: null,
+      rSquared: null,
+      nPoints: usable.length,
+      usedYears: [],
+      warnings: ["Needs at least 5 usable points"],
+    });
+  }
+
+  return { points, fits };
+}
+
+/**
+ * Trend a value from one year's cost level to another's:
+ * value × (1 + rate)^(toYear − fromYear). Midpoint-to-midpoint conventions
+ * are the caller's responsibility (whole years in, whole years out).
+ */
+export function trendValue(
+  value: number,
+  rate: number,
+  fromYear: number,
+  toYear: number,
+): number {
+  if (!isNum(rate) || rate <= -1) {
+    throw new ReservingError("BAD_TREND", "A trend rate must be a number greater than -100%");
+  }
+  return value * Math.pow(1 + rate, toYear - fromYear);
+}

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