@actuarial-ts/core 0.6.0 → 0.7.0

package/src/canonical.ts

@@ -1,4 +1,5 @@
 import { ReservingError } from "./types.js";
+import { createFnvAccumulator } from "./fnvAccumulator.js";
 
 /**
  * Canonical JSON serialization and the FNV-1a integrity hash — the SDK's
@@ -34,18 +35,35 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return proto === Object.prototype || proto === null;
 }
 
-function canonicalize(value: unknown, path: string, seen: Set<object>): string {
-  if (value === null) return "null";
+interface CanonicalSink {
+  write(text: string): void;
+  quote(text: string): void;
+  startContainer(token: "[" | "{"): void;
+  endContainer(token: "]" | "}"): void;
+}
+
+/** One traversal owns validation and property access order for both outputs. */
+function canonicalize(value: unknown, path: string, seen: Set<object>, sink: CanonicalSink): void {
+  if (value === null) {
+    sink.write("null");
+    return;
+  }
   switch (typeof value) {
     case "string":
-      return JSON.stringify(value);
+      sink.quote(value);
+      return;
     case "boolean":
-      return value ? "true" : "false";
+      sink.write(value ? "true" : "false");
+      return;
     case "number": {
       if (!Number.isFinite(value)) {
-        throw new ReservingError("UNSUPPORTED_VALUE", `non-finite number (${String(value)}) at ${path}`);
+        throw new ReservingError(
+          "UNSUPPORTED_VALUE",
+          `non-finite number (${String(value)}) at ${path}`,
+        );
       }
-      return Object.is(value, -0) ? "0" : String(value);
+      sink.write(Object.is(value, -0) ? "0" : String(value));
+      return;
     }
     case "undefined":
       throw new ReservingError("UNSUPPORTED_VALUE", `undefined at ${path}`);
@@ -62,20 +80,24 @@ function canonicalize(value: unknown, path: string, seen: Set<object>): string {
     throw new ReservingError("UNSUPPORTED_VALUE", `circular reference at ${path}`);
   }
   seen.add(obj);
-  let out: string;
   if (Array.isArray(obj)) {
-    const parts: string[] = [];
+    sink.startContainer("[");
     for (let i = 0; i < obj.length; i++) {
-      parts.push(canonicalize(obj[i], `${path}[${i}]`, seen));
+      if (i > 0) sink.write(",");
+      canonicalize(obj[i], `${path}[${i}]`, seen, sink);
     }
-    out = `[${parts.join(",")}]`;
+    sink.endContainer("]");
   } 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)}`);
+    sink.startContainer("{");
+    for (let i = 0; i < keys.length; i++) {
+      if (i > 0) sink.write(",");
+      const key = keys[i]!;
+      sink.quote(key);
+      sink.write(":");
+      canonicalize(obj[key], `${path}.${key}`, seen, sink);
     }
-    out = `{${parts.join(",")}}`;
+    sink.endContainer("}");
   } else {
     const name = (obj.constructor as { name?: string } | undefined)?.name ?? "unknown";
     throw new ReservingError(
@@ -84,7 +106,6 @@ function canonicalize(value: unknown, path: string, seen: Set<object>): string {
     );
   }
   seen.delete(obj);
-  return out;
 }
 
 /**
@@ -95,12 +116,59 @@ function canonicalize(value: unknown, path: string, seen: Set<object>): string {
  * "$.rows[2].ultimate" — for any value JSON cannot faithfully represent.
  */
 export function canonicalJson(value: unknown): string {
-  return canonicalize(value, "$", new Set());
+  // Join finished subtrees as before, rather than retaining a flat token array
+  // for the entire input graph alongside the final serialized string.
+  const frames: string[][] = [[]];
+  const write = (text: string) => {
+    frames[frames.length - 1]!.push(text);
+  };
+  canonicalize(value, "$", new Set(), {
+    write,
+    quote(text) {
+      write(JSON.stringify(text));
+    },
+    startContainer(token) {
+      frames.push([token]);
+    },
+    endContainer(token) {
+      const parts = frames.pop()!;
+      parts.push(token);
+      write(parts.join(""));
+    },
+  });
+  return frames[0]!.join("");
 }
 
-const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
-const FNV_PRIME = 0x100000001b3n;
-const MASK_64 = 0xffffffffffffffffn;
+const UTF8_CHUNK_CODE_UNITS = 16_384;
+const QUOTED_CHUNK_CODE_UNITS = 4_096;
+
+/** A valid surrogate pair must reach native escaping/encoding together. */
+function chunkEnd(text: string, start: number, limit: number): number {
+  let end = Math.min(start + limit, text.length);
+  const before = text.charCodeAt(end - 1);
+  const after = text.charCodeAt(end);
+  if (before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff) end -= 1;
+  return end;
+}
+
+/** Reuse at most 48 KiB for long strings instead of duplicating all UTF-8 bytes. */
+function* utf8Chunks(text: string): Generator<Uint8Array> {
+  const encoder = new TextEncoder();
+  // Retain TextEncoder's runtime coercion for untyped JavaScript callers.
+  if (typeof text !== "string" || text.length <= UTF8_CHUNK_CODE_UNITS) {
+    yield encoder.encode(text);
+    return;
+  }
+  // A UTF-16 code unit needs at most three UTF-8 bytes (a surrogate pair
+  // needs four bytes for two code units), so encodeInto always consumes a chunk.
+  const buffer = new Uint8Array(UTF8_CHUNK_CODE_UNITS * 3);
+  for (let start = 0; start < text.length; ) {
+    const end = chunkEnd(text, start, UTF8_CHUNK_CODE_UNITS);
+    const { written } = encoder.encodeInto(text.slice(start, end), buffer);
+    yield buffer.subarray(0, written);
+    start = end;
+  }
+}
 
 /**
  * FNV-1a 64-bit hash over the UTF-8 bytes of `text`, returned as a 16-hex-char
@@ -112,11 +180,61 @@ const MASK_64 = 0xffffffffffffffffn;
  * 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");
+  const hash = createFnvAccumulator();
+  for (const bytes of utf8Chunks(text)) hash.update(bytes);
+  return hash.digest();
+}
+
+/**
+ * The exact integrity tag `fnv1a64(canonicalJson(value))`, without constructing
+ * the complete canonical string or UTF-8 byte array. Validation, key ordering,
+ * escaping and unsupported-value error paths match `canonicalJson`.
+ *
+ * Text and byte buffers are bounded, including for a single large string/key;
+ * object-key sorting, ancestor tracking and paths still scale with input shape.
+ * The caller's input remains in memory. This is not a constant-memory dataset
+ * pipeline, a collision-resistant hash, or a substitute for exact equality.
+ */
+export function canonicalFnv1a64(value: unknown): string {
+  const hash = createFnvAccumulator();
+  const encoder = new TextEncoder();
+  const bytes = new Uint8Array(UTF8_CHUNK_CODE_UNITS * 3);
+  let buffered = "";
+  const flush = () => {
+    if (!buffered.length) return;
+    // Three bytes per UTF-16 code unit always fit; pairs need only four for two.
+    const { written } = encoder.encodeInto(buffered, bytes);
+    hash.update(bytes.subarray(0, written));
+    buffered = "";
+  };
+  const write = (text: string) => {
+    for (let start = 0; start < text.length; ) {
+      const end = chunkEnd(text, start, UTF8_CHUNK_CODE_UNITS - buffered.length);
+      if (end === start) {
+        flush();
+        continue;
+      }
+      buffered += text.slice(start, end);
+      start = end;
+      if (buffered.length >= UTF8_CHUNK_CODE_UNITS - 1) flush();
+    }
+  };
+  canonicalize(value, "$", new Set(), {
+    write,
+    startContainer: write,
+    endContainer: write,
+    quote(text) {
+      write('"');
+      for (let start = 0; start < text.length; ) {
+        const end = chunkEnd(text, start, QUOTED_CHUNK_CODE_UNITS);
+        // Bounded native escaping retains minimal JSON escape spelling and lone
+        // surrogate escapes without allocating one full escaped string atom.
+        write(JSON.stringify(text.slice(start, end)).slice(1, -1));
+        start = end;
+      }
+      write('"');
+    },
+  });
+  flush();
+  return hash.digest();
 }

package/src/capping.ts

@@ -39,7 +39,10 @@ function accidentYear(snap: ClaimSnapshot): number {
  * diverge from what the exhibits report; services should resolve it once via
  * this helper and pass baseYear explicitly to both.
  */
-export function latestAccidentYear(claims: ClaimSnapshot[], asOfDate?: string): number {
+export function latestAccidentYear(
+  claims: ClaimSnapshot[],
+  asOfDate?: string,
+): number {
   const asOf = asOfDate ?? "9999-12-31";
   let year = -Infinity;
   for (const snap of claims) {
@@ -56,25 +59,61 @@ export function latestAccidentYear(claims: ClaimSnapshot[], asOfDate?: string):
 }
 
 /** The effective cap for one accident year under the index. */
-export function effectiveCap(options: Required<CapOptions>, year: number): number {
-  return options.cap * Math.pow(1 + options.indexRate, year - options.baseYear);
+export function effectiveCap(
+  options: Required<CapOptions>,
+  year: number,
+): number {
+  if (
+    !isNum(options.cap) ||
+    options.cap <= 0 ||
+    !isNum(options.indexRate) ||
+    options.indexRate <= -1 ||
+    !Number.isSafeInteger(options.baseYear) ||
+    !Number.isSafeInteger(year)
+  ) {
+    throw new ReservingError(
+      "BAD_CAP",
+      "Cap, index rate, base year, and accident year must define a finite positive layer",
+    );
+  }
+  const value =
+    options.cap * Math.pow(1 + options.indexRate, year - options.baseYear);
+  if (!Number.isFinite(value) || value <= 0)
+    throw new ReservingError(
+      "BAD_CAP",
+      "Indexed effective cap must be finite and positive",
+    );
+  return value;
 }
 
-function resolveOptions(claims: ClaimSnapshot[], options: CapOptions): Required<CapOptions> {
+function resolveOptions(
+  claims: ClaimSnapshot[],
+  options: CapOptions,
+): Required<CapOptions> {
   if (!isNum(options.cap) || options.cap <= 0) {
-    throw new ReservingError("BAD_CAP", "The per-occurrence cap must be a positive number");
+    throw new ReservingError(
+      "BAD_CAP",
+      "The per-occurrence cap must be a positive number",
+    );
   }
   const indexRate = options.indexRate ?? 0;
   if (!isNum(indexRate) || indexRate <= -1) {
-    throw new ReservingError("BAD_CAP", "The cap index rate must be a number greater than -100%");
+    throw new ReservingError(
+      "BAD_CAP",
+      "The cap index rate must be a number greater than -100%",
+    );
   }
   let baseYear = options.baseYear ?? null;
   if (baseYear === null) {
     baseYear = -Infinity;
-    for (const snap of claims) baseYear = Math.max(baseYear, accidentYear(snap));
+    for (const snap of claims)
+      baseYear = Math.max(baseYear, accidentYear(snap));
   }
-  if (!isNum(baseYear) || !Number.isFinite(baseYear)) {
-    throw new ReservingError("BAD_CAP", "Could not resolve a base year for the cap index");
+  if (!isNum(baseYear) || !Number.isSafeInteger(baseYear)) {
+    throw new ReservingError(
+      "BAD_CAP",
+      "Could not resolve a base year for the cap index",
+    );
   }
   return { cap: options.cap, indexRate, baseYear };
 }
@@ -86,14 +125,18 @@ function resolveOptions(claims: ClaimSnapshot[], options: CapOptions): Required<
  * negative by construction). Claim counts and statuses are untouched - the
  * cap limits dollars, not claims.
  */
-export function capClaims(claims: ClaimSnapshot[], options: CapOptions): ClaimSnapshot[] {
+export function capClaims(
+  claims: ClaimSnapshot[],
+  options: CapOptions,
+): ClaimSnapshot[] {
   const resolved = resolveOptions(claims, options);
   return claims.map((snap) => {
     const capY = effectiveCap(resolved, accidentYear(snap));
     const incurred = snap.paidToDate + snap.caseReserve;
     const cappedIncurred = Math.min(incurred, capY);
     const cappedPaid = Math.min(snap.paidToDate, capY);
-    if (cappedIncurred === incurred && cappedPaid === snap.paidToDate) return snap;
+    if (cappedIncurred === incurred && cappedPaid === snap.paidToDate)
+      return snap;
     return {
       ...snap,
       paidToDate: cappedPaid,
@@ -161,7 +204,10 @@ const PERCENTILES = [0.5, 0.75, 0.9, 0.95, 0.99];
 // interpolated refinement in stochastic.ts's percentileOfSorted buys nothing.
 function percentile(sorted: number[], p: number): number {
   if (sorted.length === 0) return 0;
-  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1));
+  const idx = Math.min(
+    sorted.length - 1,
+    Math.max(0, Math.ceil(p * sorted.length) - 1),
+  );
   return sorted[idx]!;
 }
 
@@ -183,7 +229,10 @@ export function claimSizeDiagnostics(
   options: ClaimSizeDiagnosticsOptions = {},
 ): ClaimSizeDiagnostics {
   if (claims.length === 0) {
-    throw new ReservingError("NO_CLAIMS", "Cannot analyze claim sizes with no claims");
+    throw new ReservingError(
+      "NO_CLAIMS",
+      "Cannot analyze claim sizes with no claims",
+    );
   }
   const asOf = options.asOfDate ?? "9999-12-31";
   // Latest evaluation per claim on or before the analysis date.
@@ -191,20 +240,48 @@ export function claimSizeDiagnostics(
   for (const snap of claims) {
     if (snap.evaluationDate > asOf) continue;
     const prev = latest.get(snap.claimId);
-    if (!prev || snap.evaluationDate > prev.evaluationDate) latest.set(snap.claimId, snap);
+    if (!prev || snap.evaluationDate > prev.evaluationDate)
+      latest.set(snap.claimId, snap);
   }
 
   const byYear = new Map<number, number[]>();
   for (const snap of latest.values()) {
     const year = accidentYear(snap);
     const incurred = snap.paidToDate + snap.caseReserve;
+    if (
+      !Number.isSafeInteger(year) ||
+      year < 1 ||
+      year > 9999 ||
+      !Number.isFinite(incurred) ||
+      incurred < 0
+    ) {
+      throw new ReservingError(
+        "BAD_LOSSES",
+        "Claim-size diagnostics require valid accident years and finite nonnegative incurred amounts",
+      );
+    }
     let arr = byYear.get(year);
     if (!arr) byYear.set(year, (arr = []));
     arr.push(incurred);
   }
   const years = [...byYear.keys()].sort((a, b) => a - b);
   const indexRate = options.indexRate ?? 0;
+  if (years.length === 0)
+    throw new ReservingError(
+      "NO_CLAIMS",
+      "No claim snapshots on or before the analysis date; cannot analyze claim sizes",
+    );
+  if (!isNum(indexRate) || indexRate <= -1)
+    throw new ReservingError(
+      "BAD_CAP",
+      "The cap index rate must be finite and greater than -100%",
+    );
   const baseYear = options.baseYear ?? years[years.length - 1]!;
+  if (!Number.isSafeInteger(baseYear))
+    throw new ReservingError(
+      "BAD_CAP",
+      "The cap base year must be a safe integer",
+    );
 
   const yearRows: ClaimSizeYearRow[] = years.map((year) => {
     const sorted = [...byYear.get(year)!].sort((a, b) => a - b);
@@ -213,7 +290,10 @@ export function claimSizeDiagnostics(
       claimCount: sorted.length,
       totalIncurred: sorted.reduce((a, v) => a + v, 0),
       maxClaim: sorted[sorted.length - 1] ?? 0,
-      percentiles: PERCENTILES.map((p) => ({ p, value: percentile(sorted, p) })),
+      percentiles: PERCENTILES.map((p) => ({
+        p,
+        value: percentile(sorted, p),
+      })),
     };
   });
 
@@ -223,6 +303,16 @@ export function claimSizeDiagnostics(
   // incurred is deflated to that level before taking percentiles - otherwise
   // a nominal anchor re-indexed forward overshoots the whole distribution
   // and every derived candidate reads near-zero pierce.
+  for (const [label, values] of [
+    ["candidateCaps", options.candidateCaps],
+    ["extraCaps", options.extraCaps],
+  ] as const) {
+    if (values?.some((value) => !isNum(value) || value <= 0))
+      throw new ReservingError(
+        "BAD_CAP",
+        `${label} must contain only finite positive caps`,
+      );
+  }
   let candidateCaps = options.candidateCaps;
   if (!candidateCaps || candidateCaps.length === 0) {
     const pooled = [...latest.values()]
@@ -251,7 +341,7 @@ export function claimSizeDiagnostics(
     let totalExcess = 0;
     let totalIncurred = 0;
     const cells: CapCandidateYearCell[] = years.map((year) => {
-      const capY = cap * Math.pow(1 + resolved.indexRate, year - resolved.baseYear);
+      const capY = effectiveCap({ ...resolved, cap }, year);
       const values = byYear.get(year)!;
       let pierce = 0;
       let excess = 0;
@@ -289,7 +379,8 @@ export function claimSizeDiagnostics(
     candidates,
     baseYear,
     indexRate,
-    nonZeroClaimCount: [...latest.values()].filter((s) => s.paidToDate + s.caseReserve > 0)
-      .length,
+    nonZeroClaimCount: [...latest.values()].filter(
+      (s) => s.paidToDate + s.caseReserve > 0,
+    ).length,
   };
 }

package/src/diagnosticAggregation.ts

@@ -1,10 +1,18 @@
-import type { DiagnosticMeasureStats, DiagnosticMissingPolicy, DiagnosticSourceLocation } from "./diagnosticDefinitions.js";
+import type {
+  DiagnosticMeasureStats,
+  DiagnosticMissingPolicy,
+  DiagnosticSourceLocation,
+} from "./diagnosticDefinitions.js";
+import type { DiagnosticMetricFinding } from "./diagnosticFormulas.js";
+import { compareDiagnosticContributions } from "./diagnosticOrdering.js";
 
 export interface DiagnosticStructuralBlocker {
   readonly code: string;
   readonly message: string;
   readonly sourceIds: readonly string[];
   readonly sources: readonly DiagnosticSourceLocation[];
+  /** Exact preparation finding whose dependency this blocker represents. */
+  readonly finding?: DiagnosticMetricFinding;
 }
 
 export interface DiagnosticMeasureContributionBase {
@@ -14,10 +22,23 @@ export interface DiagnosticMeasureContributionBase {
 }
 
 export type DiagnosticMeasureContribution =
-  | (DiagnosticMeasureContributionBase & { readonly status: "observed"; readonly value: number })
-  | (DiagnosticMeasureContributionBase & { readonly status: "imputed-zero"; readonly value: 0 })
-  | (DiagnosticMeasureContributionBase & { readonly status: "missing"; readonly value: null })
-  | (DiagnosticMeasureContributionBase & { readonly status: "non-finite"; readonly value: null; readonly nonFiniteKind: "nan" | "positive-infinity" | "negative-infinity" });
+  | (DiagnosticMeasureContributionBase & {
+      readonly status: "observed";
+      readonly value: number;
+    })
+  | (DiagnosticMeasureContributionBase & {
+      readonly status: "imputed-zero";
+      readonly value: 0;
+    })
+  | (DiagnosticMeasureContributionBase & {
+      readonly status: "missing";
+      readonly value: null;
+    })
+  | (DiagnosticMeasureContributionBase & {
+      readonly status: "non-finite";
+      readonly value: null;
+      readonly nonFiniteKind: "nan" | "positive-infinity" | "negative-infinity";
+    });
 
 export function auditedDiagnosticContribution(
   sourceId: string,
@@ -26,17 +47,35 @@ export function auditedDiagnosticContribution(
   sources: readonly DiagnosticSourceLocation[] = [],
   deduplicated = 0,
 ): DiagnosticMeasureContribution {
-  const base = { sourceId, sources: Object.freeze([...sources]), deduplicated } as const;
-  if (value === null || value === undefined) return missing === "zero"
-    ? Object.freeze({ ...base, status: "imputed-zero" as const, value: 0 as const })
-    : Object.freeze({ ...base, status: "missing" as const, value: null });
-  if (!Number.isFinite(value)) return Object.freeze({
+  const base = {
+    sourceId,
+    sources: Object.freeze([...sources]),
+    deduplicated,
+  } as const;
+  if (value === null || value === undefined)
+    return missing === "zero"
+      ? Object.freeze({
+          ...base,
+          status: "imputed-zero" as const,
+          value: 0 as const,
+        })
+      : Object.freeze({ ...base, status: "missing" as const, value: null });
+  if (!Number.isFinite(value))
+    return Object.freeze({
+      ...base,
+      status: "non-finite" as const,
+      value: null,
+      nonFiniteKind: Number.isNaN(value)
+        ? ("nan" as const)
+        : value > 0
+          ? ("positive-infinity" as const)
+          : ("negative-infinity" as const),
+    });
+  return Object.freeze({
     ...base,
-    status: "non-finite" as const,
-    value: null,
-    nonFiniteKind: Number.isNaN(value) ? "nan" as const : value > 0 ? "positive-infinity" as const : "negative-infinity" as const,
+    status: "observed" as const,
+    value: Object.is(value, -0) ? 0 : value,
   });
-  return Object.freeze({ ...base, status: "observed" as const, value: Object.is(value, -0) ? 0 : value });
 }
 
 function neumaier(values: readonly number[]): number | null {
@@ -44,7 +83,10 @@ function neumaier(values: readonly number[]): number | null {
   let correction = 0;
   for (const value of values) {
     const next = sum + value;
-    correction += Math.abs(sum) >= Math.abs(value) ? (sum - next) + value : (value - next) + sum;
+    correction +=
+      Math.abs(sum) >= Math.abs(value)
+        ? sum - next + value
+        : value - next + sum;
     sum = next;
     if (!Number.isFinite(sum) || !Number.isFinite(correction)) return null;
   }
@@ -57,15 +99,22 @@ export function finalizeDiagnosticContributions(
   missingPolicy: DiagnosticMissingPolicy,
   blockers: readonly DiagnosticStructuralBlocker[] = [],
 ): DiagnosticMeasureStats {
-  const ordered = [...contributions].sort((left, right) => left.sourceId < right.sourceId ? -1 : left.sourceId > right.sourceId ? 1 : 0);
+  const ordered = [...contributions].sort(compareDiagnosticContributions);
   const observed = ordered.filter((item) => item.status === "observed");
   const imputed = ordered.filter((item) => item.status === "imputed-zero");
-  const missing = ordered.filter((item) => item.status === "missing").length + imputed.length;
-  const nonFinite = ordered.filter((item) => item.status === "non-finite").length;
-  const finiteSum = neumaier([...observed.map((item) => item.value), ...imputed.map(() => 0)]);
+  const missing =
+    ordered.filter((item) => item.status === "missing").length + imputed.length;
+  const nonFinite = ordered.filter(
+    (item) => item.status === "non-finite",
+  ).length;
+  const finiteSum = neumaier([
+    ...observed.map((item) => item.value),
+    ...imputed.map(() => 0),
+  ]);
   const blocked = blockers.length > 0;
   const sum = nonFinite > 0 || blocked || finiteSum === null ? null : finiteSum;
-  const value = sum === null || (missingPolicy === "unknown" && missing > 0) ? null : sum;
+  const value =
+    sum === null || (missingPolicy === "unknown" && missing > 0) ? null : sum;
   return Object.freeze({
     value,
     sum,