@actuarial-ts/core 0.6.0 → 0.6.1

package/src/diagnosticRuntime.ts

@@ -0,0 +1,264 @@
+import {
+  DiagnosticValidationError,
+  type DiagnosticValidationDomain,
+  type DiagnosticValidationIssue,
+} from "./types.js";
+
+export const MAX_DIAGNOSTIC_JSON_DEPTH = 256;
+export const MAX_DIAGNOSTIC_JSON_NODES = 1_000_000;
+
+/** True only for ordinary data records, including deliberately prototype-free records. */
+export function isDiagnosticPlainRecord(
+  value: unknown,
+): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** Own-property lookup which remains correct for every legal string key. */
+export function hasDiagnosticOwn(value: object, key: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+/** Creates a record in which `__proto__`, `constructor`, and `toString` are ordinary keys. */
+export function diagnosticRecord<T>(): Record<string, T> {
+  return Object.create(null) as Record<string, T>;
+}
+
+export function normalizeDiagnosticNumber(value: number): number {
+  return Object.is(value, -0) ? 0 : value;
+}
+
+/** Rejects U+0000 and unpaired UTF-16 surrogate code units. */
+export function isWellFormedDiagnosticString(value: string): boolean {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code === 0) return false;
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) return false;
+      index++;
+    } else if (code >= 0xdc00 && code <= 0xdfff) return false;
+  }
+  return true;
+}
+
+export function isDiagnosticToken(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    isWellFormedDiagnosticString(value) &&
+    value.length > 0 &&
+    !/^[\u0009-\u000d\u0020]|[\u0009-\u000d\u0020]$/.test(value)
+  );
+}
+
+/** Strict Gregorian date validation for public SDK date boundaries. */
+export function isRealIsoDate(value: unknown): value is string {
+  if (typeof value !== "string" || !isWellFormedDiagnosticString(value))
+    return false;
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return false;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (year < 1 || year > 9999 || month < 1 || month > 12 || day < 1)
+    return false;
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return day <= days[month - 1]!;
+}
+
+interface JsonFrame {
+  readonly value: unknown;
+  readonly path: string;
+  readonly depth: number;
+  readonly exiting: boolean;
+}
+
+/**
+ * Iterative JSON boundary preflight. It never invokes getters and reports
+ * malformed values before recursive normalization or hashing can run.
+ */
+export function diagnosticJsonPreflight(
+  value: unknown,
+  domain: DiagnosticValidationDomain,
+  options: { readonly maxDepth?: number; readonly maxNodes?: number } = {},
+): readonly DiagnosticValidationIssue[] {
+  const maxDepth = options.maxDepth ?? MAX_DIAGNOSTIC_JSON_DEPTH;
+  const maxNodes = options.maxNodes ?? MAX_DIAGNOSTIC_JSON_NODES;
+  const issues: DiagnosticValidationIssue[] = [];
+  const active = new WeakSet<object>();
+  const stack: JsonFrame[] = [{ value, path: "$", depth: 1, exiting: false }];
+  let nodes = 0;
+  while (stack.length > 0) {
+    const frame = stack.pop()!;
+    if (frame.exiting) {
+      active.delete(frame.value as object);
+      continue;
+    }
+    nodes++;
+    if (nodes > maxNodes) {
+      issues.push({
+        domain,
+        code: "expression-limit",
+        path: "$",
+        message: `JSON node count exceeds ${maxNodes}`,
+      });
+      break;
+    }
+    if (frame.depth > maxDepth) {
+      issues.push({
+        domain,
+        code: "expression-limit",
+        path: frame.path,
+        message: `JSON depth exceeds ${maxDepth}`,
+      });
+      continue;
+    }
+    const item = frame.value;
+    if (item === null || typeof item === "boolean") continue;
+    if (typeof item === "string") {
+      if (!isWellFormedDiagnosticString(item))
+        issues.push({
+          domain,
+          code: "invalid-json-value",
+          path: frame.path,
+          message: "String is not well-formed UTF-16 or contains U+0000",
+        });
+      continue;
+    }
+    if (typeof item === "number") {
+      if (!Number.isFinite(item))
+        issues.push({
+          domain,
+          code: "invalid-json-value",
+          path: frame.path,
+          message: "JSON numeric value must be finite",
+        });
+      continue;
+    }
+    if (typeof item !== "object") {
+      issues.push({
+        domain,
+        code: "invalid-json-value",
+        path: frame.path,
+        message: "Value is not plain JSON data",
+      });
+      continue;
+    }
+    const isArray = Array.isArray(item);
+    if (
+      isArray
+        ? Object.getPrototypeOf(item) !== Array.prototype
+        : !isDiagnosticPlainRecord(item)
+    ) {
+      issues.push({
+        domain,
+        code: "invalid-json-value",
+        path: frame.path,
+        message: "Value must use a plain object or array prototype",
+      });
+      continue;
+    }
+    if (active.has(item)) {
+      issues.push({
+        domain,
+        code: "cycle",
+        path: frame.path,
+        message: "JSON value contains a cycle",
+      });
+      continue;
+    }
+    active.add(item);
+    stack.push({ ...frame, exiting: true });
+    if (isArray) {
+      for (const key of Reflect.ownKeys(item)) {
+        if (key === "length") continue;
+        const index = typeof key === "string" ? Number(key) : Number.NaN;
+        if (
+          Number.isInteger(index) && index >= 0 && index < item.length &&
+          String(index) === key
+        ) continue;
+        const path = typeof key === "symbol"
+          ? frame.path
+          : /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+            ? `${frame.path}.${key}`
+            : `${frame.path}[${JSON.stringify(key)}]`;
+        issues.push({
+          domain,
+          code: "invalid-json-value",
+          path,
+          message: "JSON arrays may contain only indexed data properties",
+        });
+      }
+      for (let index = item.length - 1; index >= 0; index--) {
+        const path = `${frame.path}[${index}]`;
+        const descriptor = Object.getOwnPropertyDescriptor(item, String(index));
+        if (!descriptor || !("value" in descriptor))
+          issues.push({
+            domain,
+            code: "invalid-json-value",
+            path,
+            message: "JSON arrays may contain only indexed data properties",
+          });
+        else
+          stack.push({
+            value: descriptor.value,
+            path,
+            depth: frame.depth + 1,
+            exiting: false,
+          });
+      }
+      continue;
+    }
+    for (const key of Object.keys(item).sort().reverse()) {
+      const path = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+        ? `${frame.path}.${key}`
+        : `${frame.path}[${JSON.stringify(key)}]`;
+      if (!isWellFormedDiagnosticString(key))
+        issues.push({
+          domain,
+          code: "invalid-json-value",
+          path,
+          message: "Object key is not well-formed UTF-16 or contains U+0000",
+        });
+      const descriptor = Object.getOwnPropertyDescriptor(item, key);
+      if (!descriptor || !("value" in descriptor)) {
+        issues.push({
+          domain,
+          code: "invalid-json-value",
+          path,
+          message: "JSON objects may contain only data properties",
+        });
+      } else {
+        stack.push({
+          value: descriptor.value,
+          path,
+          depth: frame.depth + 1,
+          exiting: false,
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+/** Snapshot JSON-shaped data into owned, deeply frozen arrays/null-prototype records. */
+export function snapshotDiagnosticJson<T>(value: T): T {
+  const issues = diagnosticJsonPreflight(value, "input");
+  if (issues.length > 0) throw new DiagnosticValidationError(issues);
+  const clone = (item: unknown): unknown => {
+    if (item === null || typeof item !== "object") {
+      return typeof item === "number" ? normalizeDiagnosticNumber(item) : item;
+    }
+    if (Array.isArray(item)) return Object.freeze(item.map(clone));
+    const result = diagnosticRecord<unknown>();
+    for (const key of Object.keys(item).sort()) {
+      result[key] = clone((item as Record<string, unknown>)[key]);
+    }
+    return Object.freeze(result);
+  };
+  return clone(value) as T;
+}

package/src/diagnosticSourceOrdering.ts

@@ -0,0 +1,50 @@
+import { canonicalJson } from "./canonical.js";
+import type { DiagnosticSourceLocation } from "./diagnosticDefinitions.js";
+import { normalizeDiagnosticNumber } from "./diagnosticRuntime.js";
+
+function codeUnit(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function optional<T>(
+  left: T | undefined,
+  right: T | undefined,
+  compare: (a: T, b: T) => number,
+): number {
+  if (left === undefined) return right === undefined ? 0 : -1;
+  if (right === undefined) return 1;
+  return compare(left, right);
+}
+
+/** Contract comparator for source provenance; source rows compare numerically. */
+export function compareDiagnosticSourceLocations(
+  left: DiagnosticSourceLocation,
+  right: DiagnosticSourceLocation,
+): number {
+  return (
+    codeUnit(left.artifactId, right.artifactId) ||
+    optional(left.sourceFile, right.sourceFile, codeUnit) ||
+    optional(left.sourceSheet, right.sourceSheet, codeUnit) ||
+    optional(left.sourceRow, right.sourceRow, (a, b) => a - b) ||
+    optional(left.sourceCell, right.sourceCell, codeUnit)
+  );
+}
+
+/** Exact-deduplicates, snapshots, and contract-sorts source provenance. */
+export function normalizeDiagnosticSourceLocations(
+  values: readonly (DiagnosticSourceLocation | null | undefined)[],
+): DiagnosticSourceLocation[] {
+  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);
+    }
+  return [...unique.values()].sort(compareDiagnosticSourceLocations);
+}

package/src/index.ts

@@ -2,6 +2,19 @@ export * from "./types.js";
 export * from "./util.js";
 export * from "./canonical.js";
 export * from "./version.js";
+export {
+  MAX_DIAGNOSTIC_JSON_DEPTH,
+  MAX_DIAGNOSTIC_JSON_NODES,
+  diagnosticJsonPreflight,
+  diagnosticRecord,
+  hasDiagnosticOwn,
+  isDiagnosticPlainRecord,
+  isDiagnosticToken,
+  isRealIsoDate,
+  isWellFormedDiagnosticString,
+  normalizeDiagnosticNumber,
+  snapshotDiagnosticJson,
+} from "./diagnosticRuntime.js";
 export {
   MAX_DIAGNOSTIC_DEFINITION_EXPRESSION_NODES,
   MAX_DIAGNOSTIC_EXPRESSION_DEPTH,
@@ -63,7 +76,10 @@ export type {
   NormalizedDiagnosticReviewRuleIdentity,
   NormalizedDiagnosticSourceLocationIdentity,
   NormalizedDiagnosticToleranceIdentity,
+  NormalizedDiagnosticsFilterIdentity,
+  DiagnosticIdentityProjection,
 } from "./diagnosticIdentity.js";
+export { projectDiagnosticIdentity, normalizeDiagnosticsFilterIdentity } from "./diagnosticIdentity.js";
 export {
   CASUALTY_FORMULA_TEMPLATES,
   applyDiagnosticPresentation,
@@ -75,9 +91,7 @@ export type {
   DiagnosticQuantitySemantics,
   FinalizedDiagnosticMeasure,
 } from "./diagnosticFormulas.js";
-export {
-  classifyDiagnosticComparison,
-} from "./diagnosticRules.js";
+export { classifyDiagnosticComparison } from "./diagnosticRules.js";
 export { deriveDiagnosticClaimMeasures } from "./diagnosticDerivations.js";
 export type {
   DiagnosticMeasureValues,
@@ -89,6 +103,11 @@ export {
   normalizeDiagnosticPeriod,
 } from "./diagnosticPeriods.js";
 export type { DiagnosticNormalizedPeriod } from "./diagnosticPeriods.js";
+export {
+  compareDiagnosticSourceLocations,
+  normalizeDiagnosticSourceLocations,
+} from "./diagnosticSourceOrdering.js";
+export { compareDiagnosticIdentityValues } from "./diagnosticOrdering.js";
 export {
   auditedDiagnosticContribution,
   finalizeDiagnosticContributions,
@@ -112,12 +131,16 @@ export type {
   DiagnosticClaimObservation,
   DiagnosticCompletePeriodCutoff,
   DiagnosticExpectedCell,
+  DiagnosticExpectedCellAuditSnapshot,
+  DiagnosticExposureInputAuditSnapshot,
   DiagnosticInputAuditRecord,
   DiagnosticInputDisposition,
   DiagnosticLossInput,
+  DiagnosticLossInputAuditSnapshot,
   DiagnosticLossRecordBase,
   DiagnosticLossSnapshot,
   NormalizedDiagnosticPreparationIdentity,
+  NormalizedDiagnosticExpectedCellIdentity,
   PrepareDiagnosticDataInput,
   PreparedDiagnosticData,
   PreparedDiagnosticSourceCell,
@@ -131,9 +154,14 @@ export {
 } from "./diagnosticRunner.js";
 export { evaluateDiagnosticReviewRules } from "./diagnosticReview.js";
 export type {
+  DiagnosticCellReviewScope,
+  DiagnosticControlTotalReviewScope,
   DiagnosticReviewCoordinate,
   DiagnosticReviewEvaluationScope,
+  DiagnosticReviewExpressionOverflow,
   DiagnosticReviewRuleEvaluation,
+  DiagnosticReviewRuleEvaluationBase,
+  DiagnosticValuationPairReviewScope,
 } from "./diagnosticReview.js";
 export type {
   CommonMaturityResult,

package/src/mack.ts

@@ -11,6 +11,10 @@ export interface MackOptions {
   selected?: (number | null)[];
   /** Multiplicative tail factor beyond the last observed age (1 = none). */
   tailFactor?: number;
+  /** Standard error of the selected tail-factor estimate (Mack 1999). */
+  tailStandardError?: number;
+  /** Tail random-error scale sigma, applied as sigma / sqrt(C) (Mack 1999). */
+  tailSigma?: number;
 }
 
 /**
@@ -46,7 +50,10 @@ export function mackEstimators(tri: Triangle): {
   const n = tri.origins.length;
   const K = tri.ages.length;
   if (K < 2) {
-    throw new ReservingError("TOO_SMALL", "Mack requires at least two development ages");
+    throw new ReservingError(
+      "TOO_SMALL",
+      "Mack requires at least two development ages",
+    );
   }
   const f: number[] = [];
   const denomSums: number[] = [];
@@ -169,7 +176,45 @@ export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
   }
   const tail = options.tailFactor ?? 1;
   if (!isNum(tail) || tail <= 0) {
-    throw new ReservingError("BAD_TAIL", "Tail factor must be a positive number");
+    throw new ReservingError(
+      "BAD_TAIL",
+      "Tail factor must be a positive number",
+    );
+  }
+  const hasPublishedTailInputs =
+    options.tailStandardError !== undefined || options.tailSigma !== undefined;
+  if (
+    hasPublishedTailInputs &&
+    (options.tailStandardError === undefined || options.tailSigma === undefined)
+  ) {
+    throw new ReservingError(
+      "BAD_TAIL",
+      "tailStandardError and tailSigma must be supplied together",
+    );
+  }
+  if (
+    options.tailStandardError !== undefined &&
+    (!isNum(options.tailStandardError) || options.tailStandardError < 0)
+  ) {
+    throw new ReservingError(
+      "BAD_TAIL",
+      "Tail standard error must be a finite nonnegative number",
+    );
+  }
+  if (
+    options.tailSigma !== undefined &&
+    (!isNum(options.tailSigma) || options.tailSigma < 0)
+  ) {
+    throw new ReservingError(
+      "BAD_TAIL",
+      "Tail sigma must be a finite nonnegative number",
+    );
+  }
+  if (tail === 1 && hasPublishedTailInputs) {
+    throw new ReservingError(
+      "BAD_TAIL",
+      "Tail uncertainty inputs require a tailFactor other than 1",
+    );
   }
 
   // sigma^2_k estimates: data-estimated where possible; Mack's extrapolation
@@ -189,9 +234,10 @@ export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
       sigma2Tail = s2b;
     }
     denomTail = denomSums[K - 2]!;
-    warnings.push(
-      "The tail step's standard-error contribution extrapolates sigma^2 beyond the observed columns and reuses the final column's volume; treat it as approximate (Mack 1999)",
-    );
+    if (!hasPublishedTailInputs)
+      warnings.push(
+        "The tail step's standard-error contribution extrapolates sigma^2 beyond the observed columns and reuses the final column's volume; supply tailStandardError and tailSigma for the explicit Mack (1999) treatment",
+      );
   }
 
   // Project the full rectangle with the projection factors.
@@ -233,7 +279,12 @@ export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
       );
     }
     if (tail !== 1 && projected[i]![K - 1]! > 0) {
-      mse += (sigma2Tail / tail ** 2) * (1 / projected[i]![K - 1]! + 1 / denomTail);
+      const finalCumulative = projected[i]![K - 1]!;
+      mse += hasPublishedTailInputs
+        ? (options.tailSigma! ** 2 / finalCumulative +
+            options.tailStandardError! ** 2) /
+          tail ** 2
+        : (sigma2Tail / tail ** 2) * (1 / finalCumulative + 1 / denomTail);
     }
     mse *= ultimate ** 2;
     mseByRow[i] = mse;
@@ -283,7 +334,10 @@ export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
       const uj = ultimateOf(j);
       if (!(uj > 0)) continue;
       const floor = Math.max(maturity[i]!, maturity[j]!);
-      partnerUltimatesByFloor.set(floor, (partnerUltimatesByFloor.get(floor) ?? 0) + uj);
+      partnerUltimatesByFloor.set(
+        floor,
+        (partnerUltimatesByFloor.get(floor) ?? 0) + uj,
+      );
     }
 
     for (const [floor, partnerUltimates] of partnerUltimatesByFloor) {
@@ -295,7 +349,9 @@ export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
         shared += (2 * sigma2[k]!) / fEff[k]! ** 2 / denomSums[k]!;
       }
       if (tail !== 1) {
-        shared += (2 * sigma2Tail) / tail ** 2 / denomTail;
+        shared += hasPublishedTailInputs
+          ? (2 * options.tailStandardError! ** 2) / tail ** 2
+          : (2 * sigma2Tail) / tail ** 2 / denomTail;
       }
 
       totalMse += ui * partnerUltimates * shared;
@@ -317,7 +373,14 @@ export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
     developmentFactors: fEff,
     sigmaSquared: sigma2,
     tailFactor: tail,
-    sigmaSquaredTail: tail !== 1 ? sigma2Tail : undefined,
+    sigmaSquaredTail:
+      tail !== 1 && !hasPublishedTailInputs ? sigma2Tail : undefined,
+    tailStandardError:
+      tail !== 1 && hasPublishedTailInputs
+        ? options.tailStandardError
+        : undefined,
+    tailSigma:
+      tail !== 1 && hasPublishedTailInputs ? options.tailSigma : undefined,
     rows,
     totals: {
       ...totals,