@actuarial-ts/core 0.1.0 → 0.3.0

package/src/benktander.ts

@@ -0,0 +1,90 @@
+import type { BornhuetterFergusonResult, ChainLadderResult } from "./types.js";
+import { ReservingError } from "./types.js";
+
+/**
+ * Benktander-Hovinen method (the "iterated Bornhuetter-Ferguson").
+ *
+ * Ground truth (Mack 2000, "Credible Claims Reserves: The Benktander
+ * Method", ASTIN Bulletin 30(2)):
+ * - With q = 1 - 1/CDF (the expected unreported/unpaid fraction) and C the
+ *   losses to date: U_GB = C + q x U_BF — Bornhuetter-Ferguson applied once
+ *   more, with the BF ultimate as the a-priori.
+ * - Equivalently a credibility mixture U_GB = (1-q) x U_CL + q x U_BF with
+ *   credibility Z = 1-q on the chain ladder: mature periods lean on CL,
+ *   green periods lean on the a-priori — automatically.
+ * - Mack (2000) shows U_GB has a smaller mean squared error than both CL and
+ *   BF over a wide parameter range; it is the standard "use both" answer.
+ *
+ * Rows are the BF result's rows (BF excludes origins with no usable
+ * premium; those stay excluded here). CDFs below 1 (incurred bases with
+ * expected downward development) make q negative — the estimator still
+ * evaluates, but it is an extrapolation past the chain ladder rather than a
+ * mixture, and the result says so in warnings.
+ */
+
+export interface BenktanderRow {
+  origin: string;
+  latestValue: number;
+  cdf: number;
+  /** Credibility on the chain ladder: Z = 1 - q = 1/CDF. */
+  credibilityZ: number;
+  clUltimate: number;
+  bfUltimate: number;
+  ultimate: number;
+  unpaid: number;
+}
+
+export interface BenktanderResult {
+  method: "benktander";
+  basis: BornhuetterFergusonResult["basis"];
+  rows: BenktanderRow[];
+  totals: { latest: number; ultimate: number; unpaid: number };
+  warnings: string[];
+}
+
+export function runBenktander(
+  chainLadder: ChainLadderResult,
+  bf: BornhuetterFergusonResult,
+): BenktanderResult {
+  const warnings: string[] = [];
+  const clByOrigin = new Map(chainLadder.rows.map((r) => [r.origin, r]));
+
+  const rows: BenktanderRow[] = bf.rows.map((bfRow) => {
+    const cl = clByOrigin.get(bfRow.origin);
+    if (!cl) {
+      throw new ReservingError(
+        "SHAPE",
+        `Origin ${bfRow.origin} is in the Bornhuetter-Ferguson result but missing from the chain ladder result; both must come from the same run`,
+      );
+    }
+    const q = 1 - 1 / bfRow.cdf;
+    if (q < 0) {
+      warnings.push(
+        `Origin ${bfRow.origin}: CDF ${bfRow.cdf.toFixed(3)} is below 1, so Benktander extrapolates past the chain ladder rather than blending (expected downward development)`,
+      );
+    }
+    const ultimate = bfRow.latestValue + q * bfRow.ultimate;
+    return {
+      origin: bfRow.origin,
+      latestValue: bfRow.latestValue,
+      cdf: bfRow.cdf,
+      credibilityZ: 1 - q,
+      clUltimate: cl.ultimate,
+      bfUltimate: bfRow.ultimate,
+      ultimate,
+      unpaid: ultimate - bfRow.latestValue,
+    };
+  });
+
+  return {
+    method: "benktander",
+    basis: bf.basis,
+    rows,
+    totals: {
+      latest: rows.reduce((a, r) => a + r.latestValue, 0),
+      ultimate: rows.reduce((a, r) => a + r.ultimate, 0),
+      unpaid: rows.reduce((a, r) => a + r.unpaid, 0),
+    },
+    warnings,
+  };
+}

package/src/berquist.ts

@@ -0,0 +1,349 @@
+import type {
+  BerquistCaseAdequacyResult,
+  BerquistSettlementResult,
+  Triangle,
+} from "./types.js";
+import { ReservingError } from "./types.js";
+import { isNum, lastObservedIndex, ols, safeRatio } from "./util.js";
+
+/**
+ * Berquist-Sherman adjustments (Berquist & Sherman 1977; Friedland ch. 13).
+ *
+ * Case-reserve adequacy: restate historical average case reserves (case
+ * reserves / open counts, by cell) to the current adequacy level by
+ * de-trending the latest diagonal backwards at an annual severity trend,
+ * then rebuild adjusted incurred = paid + restated average case x open counts.
+ *
+ * Settlement-rate: compute disposal rates (closed counts / ultimate counts),
+ * take the current settlement pattern from the latest diagonal, and restate
+ * historical paid losses by interpolating paid at the disposal-rate-equivalent
+ * closed-count level -- the textbook interpolation on (closed count, paid)
+ * points within each origin row, not a scalar ratio shortcut.
+ */
+
+function assertSameShape(a: Triangle, b: Triangle, what: string): void {
+  if (
+    a.origins.length !== b.origins.length ||
+    a.ages.length !== b.ages.length ||
+    a.origins.some((o, i) => o !== b.origins[i]) ||
+    a.ages.some((g, j) => g !== b.ages[j])
+  ) {
+    throw new ReservingError("SHAPE", `${what} triangles must share origins and ages`);
+  }
+}
+
+/** Last observed row index in a column; -1 when the column is empty. */
+function lastObservedRowInColumn(tri: Triangle, j: number): number {
+  for (let i = tri.origins.length - 1; i >= 0; i--) {
+    if (isNum(tri.values[i]![j] ?? null)) return i;
+  }
+  return -1;
+}
+
+export interface CaseAdequacyOptions {
+  /** Annual severity trend override (e.g. 0.15 for +15%/yr). Fitted when omitted. */
+  severityTrend?: number;
+}
+
+export function berquistCaseAdequacy(
+  paid: Triangle,
+  incurred: Triangle,
+  openCounts: Triangle,
+  options: CaseAdequacyOptions = {},
+): BerquistCaseAdequacyResult {
+  assertSameShape(paid, incurred, "Paid and incurred");
+  assertSameShape(paid, openCounts, "Paid and open-count");
+  const nOrigins = paid.origins.length;
+  const nAges = paid.ages.length;
+  const warnings: string[] = [];
+  const periodYears = (paid.ages[0] ?? 12) / 12;
+
+  // Average open case reserve per open claim, by cell.
+  const averageCaseReserves: (number | null)[][] = [];
+  for (let i = 0; i < nOrigins; i++) {
+    const row: (number | null)[] = [];
+    for (let j = 0; j < nAges; j++) {
+      const inc = incurred.values[i]![j] ?? null;
+      const pd = paid.values[i]![j] ?? null;
+      const open = openCounts.values[i]![j] ?? null;
+      const caseAmt = isNum(inc) && isNum(pd) ? inc - pd : null;
+      row.push(safeRatio(caseAmt, open));
+    }
+    averageCaseReserves.push(row);
+  }
+
+  // Severity trend: user override, else fitted from ln(average case) regressed
+  // on origin index within each column, combined as a point-weighted average.
+  let severityTrend: number;
+  let trendSource: "fitted" | "user";
+  if (options.severityTrend !== undefined) {
+    severityTrend = options.severityTrend;
+    trendSource = "user";
+  } else {
+    let weighted = 0;
+    let weight = 0;
+    for (let j = 0; j < nAges; j++) {
+      const xs: number[] = [];
+      const ys: number[] = [];
+      for (let i = 0; i < nOrigins; i++) {
+        const v = averageCaseReserves[i]![j] ?? null;
+        if (isNum(v) && v > 0) {
+          xs.push(i);
+          ys.push(Math.log(v));
+        }
+      }
+      if (xs.length >= 3) {
+        const fit = ols(xs, ys);
+        if (fit) {
+          const annualTrend = Math.exp(fit.slope / periodYears) - 1;
+          weighted += annualTrend * fit.n;
+          weight += fit.n;
+        }
+      }
+    }
+    if (weight > 0) {
+      severityTrend = weighted / weight;
+      trendSource = "fitted";
+    } else {
+      severityTrend = 0;
+      trendSource = "fitted";
+      warnings.push(
+        "Could not fit a severity trend from the data (too few open-claim cells); used 0% -- supply a trend explicitly",
+      );
+    }
+  }
+  if (severityTrend <= -1) {
+    throw new ReservingError("BAD_TREND", "Severity trend must be greater than -100%");
+  }
+
+  // Restate: de-trend each column's latest-diagonal average case backwards.
+  const restated: (number | null)[][] = averageCaseReserves.map((r) => r.map(() => null));
+  for (let j = 0; j < nAges; j++) {
+    const diagRow = lastObservedRowInColumn(openCounts, j);
+    if (diagRow < 0) continue;
+    const diagAvg = averageCaseReserves[diagRow]![j] ?? null;
+    for (let i = 0; i <= diagRow; i++) {
+      if (!isNum(openCounts.values[i]![j] ?? null)) continue;
+      if (!isNum(diagAvg)) {
+        // No open claims on the diagonal for this maturity; keep the actual value.
+        restated[i]![j] = averageCaseReserves[i]![j] ?? null;
+        continue;
+      }
+      const yearsBack = (diagRow - i) * periodYears;
+      restated[i]![j] = diagAvg / Math.pow(1 + severityTrend, yearsBack);
+    }
+  }
+
+  // Adjusted incurred = paid + restated average case x open counts.
+  const adjustedValues: (number | null)[][] = [];
+  let fallbackCells = 0;
+  for (let i = 0; i < nOrigins; i++) {
+    const row: (number | null)[] = [];
+    for (let j = 0; j < nAges; j++) {
+      const pd = paid.values[i]![j] ?? null;
+      const open = openCounts.values[i]![j] ?? null;
+      if (!isNum(pd) || !isNum(open)) {
+        row.push(null);
+        continue;
+      }
+      if (open === 0) {
+        row.push(pd);
+        continue;
+      }
+      const avg = restated[i]![j] ?? null;
+      if (!isNum(avg)) {
+        row.push(incurred.values[i]![j] ?? null);
+        fallbackCells++;
+        continue;
+      }
+      row.push(pd + avg * open);
+    }
+    adjustedValues.push(row);
+  }
+  if (fallbackCells > 0) {
+    warnings.push(
+      `${fallbackCells} cell(s) kept their unadjusted incurred value because no diagonal average case reserve was available at that maturity`,
+    );
+  }
+
+  return {
+    averageCaseReserves,
+    severityTrend,
+    trendSource,
+    restatedAverageCaseReserves: restated,
+    adjustedIncurred: {
+      kind: "incurred",
+      origins: [...paid.origins],
+      ages: [...paid.ages],
+      values: adjustedValues,
+    },
+    warnings,
+  };
+}
+
+export interface SettlementOptions {
+  /** Selected ultimate claim counts per origin (same order as triangle origins). */
+  ultimateCounts: number[];
+  /** Interpolation between (closed count, paid) points. Friedland uses exponential. */
+  interpolation?: "exponential" | "linear";
+}
+
+interface Point {
+  x: number; // cumulative closed counts
+  y: number; // cumulative paid
+}
+
+function interpolate(
+  points: Point[],
+  x: number,
+  mode: "exponential" | "linear",
+  warnings: string[],
+  cellLabel: string,
+): number | null {
+  if (points.length === 0) return null;
+  // Exact hit keeps the actual value.
+  for (const p of points) {
+    if (Math.abs(p.x - x) < 1e-9) return p.y;
+  }
+  let lower: Point | null = null;
+  let upper: Point | null = null;
+  for (const p of points) {
+    if (p.x < x && (!lower || p.x > lower.x)) lower = p;
+    if (p.x > x && (!upper || p.x < upper.x)) upper = p;
+  }
+  if (lower && upper) {
+    return interpolateSegment(lower, upper, x, mode);
+  }
+  if (!lower && upper) {
+    // Below every observed point: anchor at the origin (0 closed, 0 paid).
+    return interpolateSegment({ x: 0, y: 0 }, upper, x, mode);
+  }
+  if (lower && !upper) {
+    // Above every observed point: extrapolate from the last segment.
+    const below = points.filter((p) => p.x < lower!.x);
+    const prev = below.length > 0 ? below[below.length - 1]! : { x: 0, y: 0 };
+    warnings.push(
+      `Adjusted closed counts at ${cellLabel} exceed every observed count in that origin row; paid was extrapolated beyond the data`,
+    );
+    return interpolateSegment(prev, lower, x, mode);
+  }
+  return null;
+}
+
+function interpolateSegment(
+  p1: Point,
+  p2: Point,
+  x: number,
+  mode: "exponential" | "linear",
+): number {
+  if (p2.x === p1.x) return p1.y;
+  if (mode === "exponential" && p1.y > 0 && p2.y > 0) {
+    // y = a * e^(b x) through both points (log-linear in paid).
+    const b = Math.log(p2.y / p1.y) / (p2.x - p1.x);
+    const a = p1.y * Math.exp(-b * p1.x);
+    return a * Math.exp(b * x);
+  }
+  // Linear (also the fallback when a zero paid value makes exponential undefined).
+  return p1.y + ((p2.y - p1.y) * (x - p1.x)) / (p2.x - p1.x);
+}
+
+export function berquistSettlement(
+  paid: Triangle,
+  closedCounts: Triangle,
+  options: SettlementOptions,
+): BerquistSettlementResult {
+  assertSameShape(paid, closedCounts, "Paid and closed-count");
+  const { ultimateCounts } = options;
+  const interpolation = options.interpolation ?? "exponential";
+  const nOrigins = paid.origins.length;
+  const nAges = paid.ages.length;
+  if (ultimateCounts.length !== nOrigins) {
+    throw new ReservingError(
+      "SHAPE",
+      `Expected ${nOrigins} ultimate claim counts (one per origin), got ${ultimateCounts.length}`,
+    );
+  }
+  const warnings: string[] = [];
+
+  // Disposal rates = closed counts / ultimate counts.
+  const disposalRates: (number | null)[][] = [];
+  for (let i = 0; i < nOrigins; i++) {
+    const ult = ultimateCounts[i]!;
+    const row: (number | null)[] = [];
+    for (let j = 0; j < nAges; j++) {
+      row.push(safeRatio(closedCounts.values[i]![j] ?? null, ult > 0 ? ult : null));
+    }
+    disposalRates.push(row);
+  }
+
+  // Current settlement pattern: disposal rates along the latest diagonal.
+  const selectedDisposalRates: (number | null)[] = [];
+  for (let j = 0; j < nAges; j++) {
+    const diagRow = lastObservedRowInColumn(closedCounts, j);
+    selectedDisposalRates.push(diagRow >= 0 ? (disposalRates[diagRow]![j] ?? null) : null);
+  }
+
+  // Restated closed counts at the current settlement pattern.
+  const adjustedClosedCounts: (number | null)[][] = [];
+  for (let i = 0; i < nOrigins; i++) {
+    const ult = ultimateCounts[i]!;
+    const row: (number | null)[] = [];
+    for (let j = 0; j < nAges; j++) {
+      const observed = isNum(closedCounts.values[i]![j] ?? null);
+      const sel = selectedDisposalRates[j] ?? null;
+      row.push(observed && isNum(sel) && ult > 0 ? sel * ult : null);
+    }
+    adjustedClosedCounts.push(row);
+  }
+
+  // Interpolate adjusted paid within each origin row on (closed, paid) points.
+  const adjustedValues: (number | null)[][] = [];
+  for (let i = 0; i < nOrigins; i++) {
+    const points: Point[] = [];
+    for (let j = 0; j < nAges; j++) {
+      const c = closedCounts.values[i]![j] ?? null;
+      const p = paid.values[i]![j] ?? null;
+      if (isNum(c) && isNum(p)) points.push({ x: c, y: p });
+    }
+    points.sort((a, b) => a.x - b.x);
+    // Collapse duplicate closed counts, keeping the latest evaluation's paid
+    // (points sort stably by closed count, so for equal counts the later
+    // development age comes last; taking its value also handles the rare
+    // decreasing-paid case, e.g. recoveries).
+    const dedup: Point[] = [];
+    for (const p of points) {
+      const last = dedup[dedup.length - 1];
+      if (last && Math.abs(last.x - p.x) < 1e-9) last.y = p.y;
+      else dedup.push({ ...p });
+    }
+
+    const row: (number | null)[] = [];
+    for (let j = 0; j < nAges; j++) {
+      const target = adjustedClosedCounts[i]![j] ?? null;
+      const actualPaid = paid.values[i]![j] ?? null;
+      if (!isNum(target) || !isNum(actualPaid)) {
+        row.push(actualPaid);
+        continue;
+      }
+      const label = `${paid.origins[i]} @ ${paid.ages[j]}mo`;
+      const y = interpolate(dedup, target, interpolation, warnings, label);
+      row.push(isNum(y) ? Math.max(0, y) : actualPaid);
+    }
+    adjustedValues.push(row);
+  }
+
+  return {
+    disposalRates,
+    selectedDisposalRates,
+    ultimateCounts: [...ultimateCounts],
+    adjustedClosedCounts,
+    interpolation,
+    adjustedPaid: {
+      kind: "paid",
+      origins: [...paid.origins],
+      ages: [...paid.ages],
+      values: adjustedValues,
+    },
+    warnings,
+  };
+}

package/src/bf.ts

@@ -0,0 +1,129 @@
+import type {
+  BornhuetterFergusonResult,
+  BornhuetterFergusonRow,
+  ChainLadderResult,
+  ExposureRecord,
+  Triangle,
+} from "./types.js";
+import { ReservingError } from "./types.js";
+import { isNum, lastObservedIndex } from "./util.js";
+
+/**
+ * Bornhuetter-Ferguson method.
+ *
+ * Ground truth:
+ * - Expected ultimate = a-priori loss ratio x earned premium.
+ * - BF ultimate = actual to date + expected ultimate x (1 - 1/CDF).
+ *
+ * A-priori selection: by default, derived from the chain ladder ultimates of
+ * mature origin periods (percent developed >= maturityThreshold), as the
+ * premium-weighted loss ratio across those periods. The user (or the advisor)
+ * can override with an explicit loss ratio, globally or per origin.
+ */
+export interface BfOptions {
+  /** Global a-priori loss ratio override. */
+  aprioriLossRatio?: number;
+  /** Per-origin a-priori overrides (take precedence over the global value). */
+  aprioriByOrigin?: Record<string, number>;
+  /** Percent-developed cutoff for "mature" periods used to derive the default a-priori. */
+  maturityThreshold?: number;
+}
+
+export function runBornhuetterFerguson(
+  tri: Triangle,
+  chainLadder: ChainLadderResult,
+  exposures: ExposureRecord[],
+  options: BfOptions = {},
+): BornhuetterFergusonResult {
+  const warnings: string[] = [];
+  const maturityThreshold = options.maturityThreshold ?? 0.9;
+  const premiumByOrigin = new Map(exposures.map((e) => [e.origin, e.earnedPremium]));
+
+  // Default a-priori: premium-weighted CL loss ratio across mature periods.
+  let derivedApriori: number | null = null;
+  {
+    let lossSum = 0;
+    let premSum = 0;
+    for (const row of chainLadder.rows) {
+      const prem = premiumByOrigin.get(row.origin);
+      if (!isNum(prem ?? null) || prem! <= 0) continue;
+      if (row.percentDeveloped >= maturityThreshold) {
+        lossSum += row.ultimate;
+        premSum += prem!;
+      }
+    }
+    if (premSum > 0) derivedApriori = lossSum / premSum;
+  }
+  if (derivedApriori === null && options.aprioriLossRatio === undefined) {
+    // Fall back to all periods when nothing is mature enough.
+    let lossSum = 0;
+    let premSum = 0;
+    for (const row of chainLadder.rows) {
+      const prem = premiumByOrigin.get(row.origin);
+      if (!isNum(prem ?? null) || prem! <= 0) continue;
+      lossSum += row.ultimate;
+      premSum += prem!;
+    }
+    if (premSum > 0) {
+      derivedApriori = lossSum / premSum;
+      warnings.push(
+        "No origin period is mature enough to anchor the a-priori; derived it from all periods' chain ladder ultimates instead",
+      );
+    }
+  }
+
+  const clByOrigin = new Map(chainLadder.rows.map((r) => [r.origin, r]));
+  const rows: BornhuetterFergusonRow[] = [];
+  for (let i = 0; i < tri.origins.length; i++) {
+    const origin = tri.origins[i]!;
+    const cl = clByOrigin.get(origin);
+    if (!cl) continue;
+    const latestIdx = lastObservedIndex(tri.values[i]!);
+    const latestValue = latestIdx >= 0 ? tri.values[i]![latestIdx]! : 0;
+    const prem = premiumByOrigin.get(origin) ?? null;
+    if (!isNum(prem) || prem <= 0) {
+      warnings.push(`Origin ${origin} has no usable earned premium; excluded from BF`);
+      continue;
+    }
+    const apriori =
+      options.aprioriByOrigin?.[origin] ?? options.aprioriLossRatio ?? derivedApriori;
+    if (!isNum(apriori ?? null)) {
+      throw new ReservingError(
+        "NO_APRIORI",
+        "Cannot derive an a-priori loss ratio (no exposure data matched the triangle origins) and no override was supplied",
+      );
+    }
+    const expectedUltimate = apriori! * prem;
+    const expectedUnreported = expectedUltimate * (1 - 1 / cl.cdf);
+    const ultimate = latestValue + expectedUnreported;
+    rows.push({
+      origin,
+      latestValue,
+      cdf: cl.cdf,
+      aprioriLossRatio: apriori!,
+      earnedPremium: prem,
+      expectedUltimate,
+      expectedUnreported,
+      ultimate,
+      unpaid: ultimate - latestValue,
+    });
+  }
+
+  if (rows.length === 0) {
+    throw new ReservingError(
+      "NO_BF_ROWS",
+      "Bornhuetter-Ferguson produced no rows; check that exposure origins match the triangle origins",
+    );
+  }
+
+  const totals = rows.reduce(
+    (acc, r) => ({
+      latest: acc.latest + r.latestValue,
+      ultimate: acc.ultimate + r.ultimate,
+      unpaid: acc.unpaid + r.unpaid,
+    }),
+    { latest: 0, ultimate: 0, unpaid: 0 },
+  );
+
+  return { method: "bornhuetterFerguson", basis: tri.kind, rows, totals, warnings };
+}

package/src/canonical.ts

@@ -0,0 +1,122 @@
+import { ReservingError } from "./types.js";
+
+/**
+ * Canonical JSON serialization and the FNV-1a integrity hash — the SDK's
+ * single equality oracle, relocated here from @actuarial-ts/compliance so
+ * the interchange layer can depend on it without a package cycle
+ * (compliance re-exports both names unchanged).
+ *
+ * Ground truth:
+ * - Object keys sort recursively (UTF-16 code-unit order), arrays keep
+ *   order, no whitespace, numbers render via `String(n)` with -0
+ *   normalized to "0", and anything JSON cannot faithfully represent
+ *   (undefined, functions, NaN/Infinity, bigint, symbol, non-plain objects
+ *   such as Date/Map/Set, circular references) THROWS with the offending
+ *   path instead of being silently dropped or coerced the way
+ *   JSON.stringify would.
+ * - RFC 8785 (JCS) conformance: for the plain-JSON value space this
+ *   function accepts, the output IS JCS — ECMAScript `String(n)` is
+ *   exactly the shortest-round-trip number serialization RFC 8785
+ *   specifies, default `sort()` is the UTF-16 code-unit key order it
+ *   requires, and `JSON.stringify` string escaping matches its minimal
+ *   escaping rules. The committed vector suite
+ *   (schema/interchange/1.0/jcs-vectors.json) pins this claim byte for
+ *   byte, and every non-TS interchange adapter must reproduce the same
+ *   vectors.
+ * - Timestamps are caller-supplied ISO strings; this module never reads a
+ *   clock, so identical inputs yield byte-identical output.
+ * - Browser-safe: no node builtins (TextEncoder is a web-standard global).
+ */
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function canonicalize(value: unknown, path: string, seen: Set<object>): string {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "string":
+      return JSON.stringify(value);
+    case "boolean":
+      return value ? "true" : "false";
+    case "number": {
+      if (!Number.isFinite(value)) {
+        throw new ReservingError("UNSUPPORTED_VALUE", `non-finite number (${String(value)}) at ${path}`);
+      }
+      return Object.is(value, -0) ? "0" : String(value);
+    }
+    case "undefined":
+      throw new ReservingError("UNSUPPORTED_VALUE", `undefined at ${path}`);
+    case "function":
+      throw new ReservingError("UNSUPPORTED_VALUE", `function at ${path}`);
+    case "bigint":
+    case "symbol":
+      throw new ReservingError("UNSUPPORTED_VALUE", `${typeof value} at ${path}`);
+    case "object":
+      break;
+  }
+  const obj = value as object;
+  if (seen.has(obj)) {
+    throw new ReservingError("UNSUPPORTED_VALUE", `circular reference at ${path}`);
+  }
+  seen.add(obj);
+  let out: string;
+  if (Array.isArray(obj)) {
+    const parts: string[] = [];
+    for (let i = 0; i < obj.length; i++) {
+      parts.push(canonicalize(obj[i], `${path}[${i}]`, seen));
+    }
+    out = `[${parts.join(",")}]`;
+  } else if (isPlainObject(obj)) {
+    const keys = Object.keys(obj).sort();
+    const parts: string[] = [];
+    for (const key of keys) {
+      parts.push(`${JSON.stringify(key)}:${canonicalize(obj[key], `${path}.${key}`, seen)}`);
+    }
+    out = `{${parts.join(",")}}`;
+  } else {
+    const name = (obj.constructor as { name?: string } | undefined)?.name ?? "unknown";
+    throw new ReservingError(
+      "UNSUPPORTED_VALUE",
+      `non-plain object (${name}) at ${path}; only plain objects, arrays, and JSON primitives are canonicalizable`,
+    );
+  }
+  seen.delete(obj);
+  return out;
+}
+
+/**
+ * Deterministic JSON serialization: sorted object keys (recursively), arrays
+ * in order, no whitespace, -0 normalized to "0". Two structurally equal
+ * values always produce the same string regardless of key insertion order.
+ * Throws ReservingError("UNSUPPORTED_VALUE") — with the offending path, e.g.
+ * "$.rows[2].ultimate" — for any value JSON cannot faithfully represent.
+ */
+export function canonicalJson(value: unknown): string {
+  return canonicalize(value, "$", new Set());
+}
+
+const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const MASK_64 = 0xffffffffffffffffn;
+
+/**
+ * FNV-1a 64-bit hash over the UTF-8 bytes of `text`, returned as a 16-hex-char
+ * string.
+ *
+ * This is an INTEGRITY AID for detecting accidental divergence between a
+ * payload and a re-run. It is NOT a security control: FNV-1a is not collision
+ * resistant and offers no protection against deliberate tampering. Anyone
+ * needing tamper evidence must sign or cryptographically hash the payload.
+ */
+export function fnv1a64(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  let hash = FNV_OFFSET_BASIS;
+  for (const byte of bytes) {
+    hash ^= BigInt(byte);
+    hash = (hash * FNV_PRIME) & MASK_64;
+  }
+  return hash.toString(16).padStart(16, "0");
+}