@actuarial-ts/core 0.10.0 → 0.11.0

package/src/diagnosticSourceOrdering.ts

@@ -30,21 +30,125 @@ export function compareDiagnosticSourceLocations(
   );
 }
 
+const SCHEMA_FIELDS = [
+  "artifactId",
+  "sourceFile",
+  "sourceSheet",
+  "sourceRow",
+  "sourceCell",
+] as const;
+// Canonical JSON of an object always starts with "{"; this prefix cannot.
+const SCHEMA_KEY_PREFIX = "
";
+
+/**
+ * Exact dedupe key: two source locations receive the same key exactly when
+ * their canonical JSON is identical. A location holding only the declared
+ * fields with string or finite-number values takes a cheap length-prefixed
+ * encoding; every other shape (extra own data, null or non-string values,
+ * foreign prototypes) defers to `canonicalJson`, including its error
+ * behaviour. Properties are read exactly as `canonicalJson` reads them. The
+ * key is an internal lookup token, never emitted or hashed into an identity.
+ */
+export function diagnosticSourceLocationKey(
+  value: DiagnosticSourceLocation,
+): string {
+  const record = value as unknown as Record<string, unknown>;
+  const prototype: unknown = Object.getPrototypeOf(record);
+  if (prototype === Object.prototype || prototype === null) {
+    let key = SCHEMA_KEY_PREFIX;
+    let matched = 0;
+    for (let index = 0; index < SCHEMA_FIELDS.length; index++) {
+      const field = SCHEMA_FIELDS[index]!;
+      if (!Object.hasOwn(record, field)) {
+        key += "-";
+        continue;
+      }
+      matched++;
+      const item: unknown = record[field];
+      if (typeof item === "string") key += `s${item.length}:${item}`;
+      else if (
+        field === "sourceRow" &&
+        typeof item === "number" &&
+        Number.isFinite(item)
+      )
+        key += `n${String(normalizeDiagnosticNumber(item))}`;
+      else return canonicalJson(value);
+    }
+    if (Object.keys(record).length === matched) return key;
+  }
+  return canonicalJson(value);
+}
+
+interface NormalizedSource {
+  readonly key: string;
+  readonly value: DiagnosticSourceLocation;
+}
+/**
+ * Invocation-scoped memo: one normalized snapshot and key per input object.
+ * Holders must release it with the invocation; it must never outlive or be
+ * shared across public calls, and inputs must be immutable while it is live.
+ */
+export type DiagnosticSourceLocationMemo = Map<
+  DiagnosticSourceLocation,
+  NormalizedSource
+>;
+
+function normalizedSource(value: DiagnosticSourceLocation): NormalizedSource {
+  const normalized = {
+    ...value,
+    ...(value.sourceRow === undefined
+      ? {}
+      : { sourceRow: normalizeDiagnosticNumber(value.sourceRow) }),
+  };
+  return { key: diagnosticSourceLocationKey(normalized), value: normalized };
+}
+
 /** Exact-deduplicates, snapshots, and contract-sorts source provenance. */
 export function normalizeDiagnosticSourceLocations(
   values: readonly (DiagnosticSourceLocation | null | undefined)[],
 ): DiagnosticSourceLocation[] {
+  return normalizeDiagnosticSourceLocationsMemoized(values);
+}
+
+/**
+ * `normalizeDiagnosticSourceLocations` that reuses one owned snapshot per
+ * distinct input object across calls sharing a memo. Results are identical;
+ * only the identity of equal snapshots is shared within the invocation.
+ */
+export function normalizeDiagnosticSourceLocationsMemoized(
+  values: readonly (DiagnosticSourceLocation | null | undefined)[],
+  memo?: DiagnosticSourceLocationMemo,
+): DiagnosticSourceLocation[] {
+  if (values.length === 0) return [];
+  // One cited source is the overwhelmingly common case: there is nothing to
+  // deduplicate or order, so the union map and its iteration are skipped.
+  // `normalizedSource` still runs, so an unrepresentable value throws here
+  // exactly as it would on the general path.
+  if (values.length === 1) {
+    const only = values[0];
+    if (only === null || only === undefined) return [];
+    let entry = memo?.get(only);
+    if (entry === undefined) {
+      entry = normalizedSource(only);
+      memo?.set(only, entry);
+    }
+    return [entry.value];
+  }
   const unique = new Map<string, DiagnosticSourceLocation>();
-  for (const value of values)
-    if (value !== null && value !== undefined) {
-      const normalized = {
-        ...value,
-        ...(value.sourceRow === undefined
-          ? {}
-          : { sourceRow: normalizeDiagnosticNumber(value.sourceRow) }),
-      };
-      const key = canonicalJson(normalized);
-      if (!unique.has(key)) unique.set(key, normalized);
+  for (let index = 0; index < values.length; index++) {
+    const value = values[index];
+    if (value === null || value === undefined) continue;
+    let entry = memo?.get(value);
+    if (entry === undefined) {
+      entry = normalizedSource(value);
+      memo?.set(value, entry);
     }
-  return [...unique.values()].sort(compareDiagnosticSourceLocations);
+    if (!unique.has(entry.key)) unique.set(entry.key, entry.value);
+  }
+  if (unique.size === 1) return [unique.values().next().value!];
+  const ordered = [...unique.values()];
+  for (let index = 1; index < ordered.length; index++)
+    if (compareDiagnosticSourceLocations(ordered[index - 1]!, ordered[index]!) > 0)
+      return ordered.sort(compareDiagnosticSourceLocations);
+  return ordered;
 }

package/src/mack.ts

@@ -241,6 +241,27 @@ export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
   }
 
   // Project the full rectangle with the projection factors.
+  // A non-positive projection factor makes Mack's variance terms undefined:
+  // every one of them divides by f_k^2. The SELECTED path above coerces such a
+  // factor to 1.000 with a warning; the volume-weighted path must not silently
+  // do the same, because f_k there IS the data's own estimate and changing it
+  // would change the projection. Instead the affected columns are excluded from
+  // the variance and the result says so. Without this the column contributes
+  // sigma^2/0 = Infinity, which the ultimate (collapsed to 0 by the same zero
+  // factor) then turns into NaN - a standard error that serializes as null.
+  const degenerateFactorColumns = new Set<number>();
+  for (let k = 0; k < K - 1; k++) if (!(fEff[k]! > 0)) degenerateFactorColumns.add(k);
+  if (degenerateFactorColumns.size > 0) {
+    const intervals = [...degenerateFactorColumns]
+      .map((k) => `${tri.ages[k]}-${tri.ages[k + 1]}`)
+      .join(", ");
+    warnings.push(
+      `Development factor for ${intervals} months is not positive; Mack's variance ` +
+        `is undefined there, so those columns are excluded from every standard error, ` +
+        `which is therefore understated`,
+    );
+  }
+
   const projected: number[][] = tri.values.map((row) => {
     const out: number[] = new Array(K).fill(NaN);
     const last = lastObservedIndex(row);
@@ -260,6 +281,8 @@ export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
     let mse = 0;
     let droppedColumns = 0;
     for (let k = last; k < K - 1; k++) {
+      // Excluded globally above, with a warning naming the interval.
+      if (degenerateFactorColumns.has(k)) continue;
       const cik = projected[i]![k]!;
       if (!(cik > 0)) {
         // Mack's 1/C_ik is undefined for a non-positive cumulative. Skipping
@@ -346,6 +369,7 @@ export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
 
       let shared = 0;
       for (let k = floor; k < K - 1; k++) {
+        if (degenerateFactorColumns.has(k)) continue;
         shared += (2 * sigma2[k]!) / fEff[k]! ** 2 / denomSums[k]!;
       }
       if (tail !== 1) {
@@ -368,6 +392,23 @@ export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
   );
   const totalSe = Math.sqrt(totalMse);
 
+  // Safety net, not the primary path: every degeneracy above is handled by
+  // excluding a column with a warning, so nothing here should be non-finite.
+  // A standard error that escapes as NaN serializes to JSON as `null`, which a
+  // reader cannot distinguish from "not computed" - so refuse loudly instead.
+  for (const r of rows) {
+    if (!Number.isFinite(r.standardError))
+      throw new ReservingError(
+        "DEGENERATE_TRIANGLE",
+        `Standard error for origin ${r.origin} is not finite; the triangle is degenerate for Mack's model`,
+      );
+  }
+  if (!Number.isFinite(totalSe))
+    throw new ReservingError(
+      "DEGENERATE_TRIANGLE",
+      "Total standard error is not finite; the triangle is degenerate for Mack's model",
+    );
+
   return {
     method: "mack",
     developmentFactors: fEff,

package/src/types.ts

@@ -510,6 +510,7 @@ export const RESERVING_ERROR_CODES = [
   "BAD_LIMIT",
   "BAD_LOSSES",
   "BAD_MARGIN",
+  "DEGENERATE_TRIANGLE",
   "BAD_ORIGIN",
   "BAD_PERCENTILE",
   "BAD_PREMIUM",

package/src/version.ts

@@ -1,2 +1,2 @@
 /** This package's runtime version. A test pins it to package.json. */
-export const CORE_PACKAGE_VERSION = "0.10.0";
+export const CORE_PACKAGE_VERSION = "0.11.0";