@actuarial-ts/core 0.10.0 → 0.11.0

package/src/diagnosticAuditText.ts

@@ -0,0 +1,187 @@
+import { canonicalJson } from "./canonical.js";
+import type { DiagnosticSourceLocation } from "./diagnosticDefinitions.js";
+import type { DiagnosticAuditedNumericValue } from "./diagnosticExposure.js";
+import type { DiagnosticInputAuditRecord } from "./diagnosticPreparation.js";
+
+/**
+ * Canonical JSON text of an input audit snapshot, byte-identical to
+ * `canonicalJson(record)`. Snapshots have three fixed shapes whose sorted key
+ * order is known, so each is rendered directly with the same string escaping
+ * and number rules. Any snapshot that does not match its shape exactly (an
+ * unexpected key, prototype or value type) defers to `canonicalJson`, so the
+ * text and every error stay those of the generic serializer.
+ */
+export function auditRecordCanonicalJson(
+  record: DiagnosticInputAuditRecord["record"],
+): string {
+  return snapshotText(record) ?? canonicalJson(record);
+}
+
+type Snapshot = Record<string, unknown>;
+
+/**
+ * `JSON.stringify` for a string. Printable ASCII other than `"` and `\` is
+ * never escaped, so such a string is quoted directly; everything else (control
+ * characters, `"`, `\`, and any non-ASCII, including lone surrogates) goes to
+ * the native serializer, which owns the escape spelling.
+ */
+const quote = (value: string): string => {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code < 0x20 || code > 0x7e || code === 0x22 || code === 0x5c)
+      return JSON.stringify(value);
+  }
+  return `"${value}"`;
+};
+const number = (value: number): string | undefined =>
+  Number.isFinite(value) ? (Object.is(value, -0) ? "0" : String(value)) : undefined;
+const hasOwn = (value: object, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key);
+const plain = (value: unknown): value is Snapshot =>
+  value !== null &&
+  typeof value === "object" &&
+  !Array.isArray(value) &&
+  Object.getPrototypeOf(value) === Object.prototype;
+
+function stringOrNull(value: unknown): string | undefined {
+  return value === null ? "null" : typeof value === "string" ? quote(value) : undefined;
+}
+
+/** Source keys in canonical order: artifactId, sourceCell, sourceFile, sourceRow, sourceSheet. */
+function sourceText(value: unknown): string | undefined {
+  if (value === null) return "null";
+  if (!plain(value)) return undefined;
+  const source = value as Partial<DiagnosticSourceLocation>;
+  if (typeof source.artifactId !== "string") return undefined;
+  let text = `{"artifactId":${quote(source.artifactId)}`;
+  let count = 1;
+  for (const field of ["sourceCell", "sourceFile"] as const)
+    if (hasOwn(source, field)) {
+      const item = source[field];
+      if (typeof item !== "string") return undefined;
+      text += `,"${field}":${quote(item)}`;
+      count++;
+    }
+  if (hasOwn(source, "sourceRow")) {
+    const item = source.sourceRow;
+    const rendered = typeof item === "number" ? number(item) : undefined;
+    if (rendered === undefined) return undefined;
+    text += `,"sourceRow":${rendered}`;
+    count++;
+  }
+  if (hasOwn(source, "sourceSheet")) {
+    const item = source.sourceSheet;
+    if (typeof item !== "string") return undefined;
+    text += `,"sourceSheet":${quote(item)}`;
+    count++;
+  }
+  if (Object.keys(source).length !== count) return undefined;
+  return `${text}}`;
+}
+
+/**
+ * Audited numeric records are immutable SDK-owned values that preparation
+ * shares across rows, so each distinct record's text is built once. Only a
+ * frozen record is remembered, and its text depends on nothing else.
+ */
+const auditedTexts = new WeakMap<object, string>();
+
+function auditedText(value: unknown): string | undefined {
+  if (!plain(value)) return undefined;
+  const cached = auditedTexts.get(value);
+  if (cached !== undefined) return cached;
+  const text = auditedTextOf(value);
+  if (text !== undefined && Object.isFrozen(value)) auditedTexts.set(value, text);
+  return text;
+}
+
+function auditedTextOf(value: Snapshot): string | undefined {
+  const audited = value as Partial<DiagnosticAuditedNumericValue>;
+  const keys = Object.keys(audited).length;
+  if (audited.status === "observed") {
+    const rendered = typeof audited.value === "number" ? number(audited.value) : undefined;
+    return keys === 2 && rendered !== undefined
+      ? `{"status":"observed","value":${rendered}}`
+      : undefined;
+  }
+  if (audited.status === "missing")
+    return keys === 2 && audited.value === null ? '{"status":"missing","value":null}' : undefined;
+  if (audited.status === "non-finite")
+    return keys === 3 && audited.value === null && typeof audited.nonFiniteKind === "string"
+      ? `{"nonFiniteKind":${quote(audited.nonFiniteKind)},"status":"non-finite","value":null}`
+      : undefined;
+  return undefined;
+}
+
+function measuresText(value: unknown): string | undefined {
+  if (!plain(value)) return undefined;
+  const keys = Object.keys(value);
+  for (let index = 1; index < keys.length; index++)
+    if (keys[index - 1]! > keys[index]!) {
+      keys.sort();
+      break;
+    }
+  let text = "{";
+  for (let index = 0; index < keys.length; index++) {
+    const key = keys[index]!;
+    const rendered = auditedText(value[key]);
+    if (rendered === undefined) return undefined;
+    text += `${index > 0 ? "," : ""}${quote(key)}:${rendered}`;
+  }
+  return `${text}}`;
+}
+
+function snapshotText(record: unknown): string | undefined {
+  if (!plain(record)) return undefined;
+  const keys = Object.keys(record).length;
+  if (hasOwn(record, "rowType")) {
+    // Loss: claimId, complete, measures, origin, recordId, rowType, source, sourceGroup, valuation.
+    if (keys !== 9) return undefined;
+    const claimId = stringOrNull(record.claimId);
+    const measures = measuresText(record.measures);
+    const source = sourceText(record.source);
+    if (
+      claimId === undefined ||
+      typeof record.complete !== "boolean" ||
+      measures === undefined ||
+      typeof record.origin !== "string" ||
+      typeof record.recordId !== "string" ||
+      typeof record.rowType !== "string" ||
+      source === undefined ||
+      typeof record.sourceGroup !== "string" ||
+      typeof record.valuation !== "string"
+    )
+      return undefined;
+    return `{"claimId":${claimId},"complete":${record.complete},"measures":${measures},"origin":${quote(record.origin)},"recordId":${quote(record.recordId)},"rowType":${quote(record.rowType)},"source":${source},"sourceGroup":${quote(record.sourceGroup)},"valuation":${quote(record.valuation)}}`;
+  }
+  if (hasOwn(record, "measureId")) {
+    // Exposure: complete, key, measureId, origin, source, sourceGroup, valuation, value.
+    if (keys !== 8) return undefined;
+    const source = sourceText(record.source);
+    const valuation = stringOrNull(record.valuation);
+    const audited = auditedText(record.value);
+    if (
+      typeof record.complete !== "boolean" ||
+      typeof record.key !== "string" ||
+      typeof record.measureId !== "string" ||
+      typeof record.origin !== "string" ||
+      source === undefined ||
+      typeof record.sourceGroup !== "string" ||
+      valuation === undefined ||
+      audited === undefined
+    )
+      return undefined;
+    return `{"complete":${record.complete},"key":${quote(record.key)},"measureId":${quote(record.measureId)},"origin":${quote(record.origin)},"source":${source},"sourceGroup":${quote(record.sourceGroup)},"valuation":${valuation},"value":${audited}}`;
+  }
+  // Expected cell: origin, source, sourceGroup, valuation.
+  if (keys !== 4) return undefined;
+  const source = sourceText(record.source);
+  if (
+    typeof record.origin !== "string" ||
+    source === undefined ||
+    typeof record.sourceGroup !== "string" ||
+    typeof record.valuation !== "string"
+  )
+    return undefined;
+  return `{"origin":${quote(record.origin)},"source":${source},"sourceGroup":${quote(record.sourceGroup)},"valuation":${quote(record.valuation)}}`;
+}

package/src/diagnosticFormulas.ts

@@ -188,10 +188,50 @@ function pointer(path: string, segment: string | number): string {
   return `${path}/${escaped}`;
 }
 
+// Shared immutable empties for clean operands; every consumer copies or iterates.
+const NO_REASONS: readonly DiagnosticRuleNotEvaluatedReason[] = Object.freeze([]);
+const NO_OVERFLOWS: readonly DiagnosticExpressionOverflow[] = Object.freeze([]);
+const NO_SOURCES: readonly import("./diagnosticDefinitions.js").DiagnosticSourceLocation[] =
+  Object.freeze([]);
+
+// Path segments below the caller's root, pushed and popped during one
+// synchronous evaluation. Rendering happens only when an overflow must cite a
+// path, so the common case allocates nothing. A re-entrant call while the
+// shared stack is in use gets its own stack.
+let sharedSegments: (string | number)[] | null = [];
+// A measure leaf never renders a path; it may evaluate against a fixed empty stack.
+const LEAF_SEGMENTS: (string | number)[] = [];
+
 export function evaluateDiagnosticMeasureExpression(
   expression: DiagnosticDeepReadonly<DiagnosticMeasureExpression>,
   measures: Readonly<Record<string, FinalizedDiagnosticMeasure>>,
   path: string,
+): ExpressionResult {
+  if (expression.op === "measure")
+    return evaluateMeasureExpression(expression, measures, path, LEAF_SEGMENTS);
+  const segments = sharedSegments ?? [];
+  sharedSegments = null;
+  segments.length = 0;
+  try {
+    return evaluateMeasureExpression(expression, measures, path, segments);
+  } finally {
+    sharedSegments = segments;
+  }
+}
+
+function renderPath(root: string, segments: readonly (string | number)[]): string {
+  let path = root;
+  for (let index = 0; index < segments.length; index++)
+    path = pointer(path, segments[index]!);
+  return path;
+}
+
+/** Expression paths are only rendered when an overflow has to cite one. */
+function evaluateMeasureExpression(
+  expression: DiagnosticDeepReadonly<DiagnosticMeasureExpression>,
+  measures: Readonly<Record<string, FinalizedDiagnosticMeasure>>,
+  root: string,
+  segments: (string | number)[],
 ): ExpressionResult {
   if (expression.op === "measure") {
     const value = hasDiagnosticOwn(measures, expression.measureId)
@@ -201,34 +241,44 @@ export function evaluateDiagnosticMeasureExpression(
       ? {
           value: value.quantity.value,
           reasons: value.readiness,
-          overflows: value.expressionOverflows ?? [],
-          sources: value.sources ?? [],
+          overflows: value.expressionOverflows ?? NO_OVERFLOWS,
+          sources: value.sources ?? NO_SOURCES,
         }
-      : { value: null, reasons: ["missing"], overflows: [], sources: [] };
+      : {
+          value: null,
+          reasons: ["missing"],
+          overflows: NO_OVERFLOWS,
+          sources: NO_SOURCES,
+        };
   }
-  const children =
-    expression.op === "add"
-      ? expression.terms.map((term, index) =>
-          evaluateDiagnosticMeasureExpression(
-            term,
-            measures,
-            pointer(pointer(path, "terms"), index),
-          ),
-        )
-      : [
-          evaluateDiagnosticMeasureExpression(
-            expression.left,
-            measures,
-            pointer(path, "left"),
-          ),
-          evaluateDiagnosticMeasureExpression(
-            expression.right,
-            measures,
-            pointer(path, "right"),
-          ),
-        ];
-  const reasons = uniqueReasons(children.flatMap((child) => child.reasons));
-  const overflows = children.flatMap((child) => child.overflows);
+  let children: ExpressionResult[];
+  if (expression.op === "add") {
+    children = new Array(expression.terms.length);
+    segments.push("terms", 0);
+    try {
+      for (let index = 0; index < expression.terms.length; index++) {
+        segments[segments.length - 1] = index;
+        children[index] = evaluateMeasureExpression(expression.terms[index]!, measures, root, segments);
+      }
+    } finally {
+      segments.length -= 2;
+    }
+  } else {
+    segments.push("left");
+    try {
+      const left = evaluateMeasureExpression(expression.left, measures, root, segments);
+      segments[segments.length - 1] = "right";
+      children = [left, evaluateMeasureExpression(expression.right, measures, root, segments)];
+    } finally {
+      segments.length -= 1;
+    }
+  }
+  const reasons = children.every((child) => child.reasons.length === 0)
+    ? NO_REASONS
+    : uniqueReasons(children.flatMap((child) => child.reasons));
+  const overflows = children.every((child) => child.overflows.length === 0)
+    ? NO_OVERFLOWS
+    : children.flatMap((child) => child.overflows);
   const sources = normalizeDiagnosticSourceLocations(
     children.flatMap((child) => child.sources),
   );
@@ -242,7 +292,7 @@ export function evaluateDiagnosticMeasureExpression(
     return {
       value: null,
       reasons: uniqueReasons([...reasons, "expression-overflow"]),
-      overflows: [...overflows, { expressionPath: path, sources }],
+      overflows: [...overflows, { expressionPath: renderPath(root, segments), sources }],
       sources,
     };
   }

package/src/diagnosticFreeze.ts

@@ -1,37 +1,82 @@
 import type { DiagnosticDeepReadonly } from "./diagnosticDefinitions.js";
 
-// Private knowledge of graphs traversed by this freezer. Object.isFrozen alone
-// is not evidence that caller-supplied children are immutable. Weak membership
-// does not keep released diagnostic datasets alive.
-let completedGraphs = new WeakSet<object>();
-let completedCount = 0;
-const MAX_COMPLETED_MEMBERS = 100_000;
+// Owned diagnostic graphs are JSON-shaped: shallow trees whose shared nodes are
+// small leaves (source locations, statistics, findings). Visiting a shared leaf
+// once per reference is far cheaper than remembering millions of visited nodes,
+// so ancestors are tracked only past this depth. A cycle must exceed it and is
+// then cut exactly where a visited-set walk would cut it.
+const UNGUARDED_DEPTH = 64;
 
-/** Freeze owned plain-data snapshots, visiting shared subgraphs only once. */
-export function freezeDiagnosticGraph<T>(value: T): DiagnosticDeepReadonly<T> {
-  // This walk already retains its nodes until success; a strong local set avoids
-  // a second large weak table and is released when the invocation returns.
-  const seen = new Set<object>();
-  const visit = (node: unknown): void => {
-    if (node === null || typeof node !== "object" || seen.has(node) || completedGraphs.has(node)) return;
-    seen.add(node);
-    for (const child of Object.values(node as Record<string, unknown>)) visit(child);
+/** True when Object.prototype carries an enumerable key, so for-in needs an own-key guard. */
+function objectPrototypeEnumerates(): boolean {
+  for (const key in {}) return key !== undefined;
+  return false;
+}
+
+function walk(value: unknown, skipFrozen: boolean): void {
+  const guardInherited = objectPrototypeEnumerates();
+  let ancestors: Set<object> | undefined;
+  const visit = (node: unknown, depth: number): void => {
+    if (node === null || typeof node !== "object") return;
+    if (skipFrozen && Object.isFrozen(node)) return;
+    const guarded = depth > UNGUARDED_DEPTH;
+    if (guarded) {
+      ancestors ??= new Set();
+      if (ancestors.has(node)) return;
+      ancestors.add(node);
+    }
+    // Scalars are checked inline: most children are numbers and strings, and a
+    // call per scalar would dominate the walk.
+    if (Array.isArray(node)) {
+      for (let index = 0; index < node.length; index++) {
+        const child: unknown = node[index];
+        if (child !== null && typeof child === "object") visit(child, depth + 1);
+      }
+    } else {
+      // for-in visits own enumerable string keys in the same order as
+      // Object.keys without allocating a key array per node. Plain records
+      // inherit nothing enumerable unless Object.prototype was extended.
+      const record = node as Record<string, unknown>;
+      const prototype: unknown = Object.getPrototypeOf(record);
+      if (!guardInherited && (prototype === Object.prototype || prototype === null)) {
+        for (const key in record) {
+          const child = record[key];
+          if (child !== null && typeof child === "object") visit(child, depth + 1);
+        }
+      } else {
+        for (const key in record) {
+          if (!Object.hasOwn(record, key)) continue;
+          const child = record[key];
+          if (child !== null && typeof child === "object") visit(child, depth + 1);
+        }
+      }
+    }
+    if (guarded) ancestors!.delete(node);
     Object.freeze(node);
   };
-  visit(value);
-  // Mark only after the whole walk succeeds: a cyclic child must not become
-  // trusted while pointing at a parent whose freeze failed.
-  for (const node of seen) {
-    // This is a traversal shortcut, never an authentication receipt. Forgetting
-    // old membership is safe: a later visit traverses and freezes that graph
-    // again. Bound the weak-table bookkeeping even when millions of source
-    // objects are still strongly retained by a large diagnostic dataset.
-    if (completedCount >= MAX_COMPLETED_MEMBERS) {
-      completedGraphs = new WeakSet<object>();
-      completedCount = 0;
-    }
-    completedGraphs.add(node);
-    completedCount++;
-  }
+  visit(value, 0);
+}
+
+/**
+ * Freeze an owned plain-data snapshot deeply. Every reachable child is visited
+ * and frozen, including children of an already frozen node, because a frozen
+ * root is no evidence that a caller-supplied child is immutable. The walk keeps
+ * no state between calls and allocates nothing for ordinary acyclic graphs.
+ */
+export function freezeDiagnosticGraph<T>(value: T): DiagnosticDeepReadonly<T> {
+  walk(value, false);
+  return value as DiagnosticDeepReadonly<T>;
+}
+
+/**
+ * Freeze a graph that the SDK built entirely itself, where every node that is
+ * already frozen was frozen complete: preparation attaches contributions,
+ * statistics, citation lists and shared empties only after freezing them and
+ * every child below them. Such nodes are skipped instead of re-walked once per
+ * reference. Never use this on a graph that may hold a caller-frozen node with
+ * mutable children; `freezeDiagnosticGraph` exists for that case.
+ */
+export function freezeOwnedDiagnosticGraph<T>(value: T): DiagnosticDeepReadonly<T> {
+  walk(value, true);
   return value as DiagnosticDeepReadonly<T>;
 }

package/src/diagnosticKeys.ts

@@ -0,0 +1,22 @@
+import { canonicalJson } from "./canonical.js";
+
+/**
+ * `canonicalJson` for a flat array of JSON scalars through the native
+ * serializer. Arrays keep their order and each finite number, string, boolean
+ * and null has exactly one canonical rendering, so the text is byte-identical
+ * to `canonicalJson(values)`. Any other element defers to `canonicalJson`,
+ * including its errors, so callers keep the same contract on every input.
+ */
+export function canonicalScalarArrayJson(values: readonly unknown[]): string {
+  for (const value of values) {
+    if (
+      typeof value === "string" ||
+      typeof value === "boolean" ||
+      value === null ||
+      (typeof value === "number" && Number.isFinite(value))
+    )
+      continue;
+    return canonicalJson(values);
+  }
+  return JSON.stringify(values);
+}

package/src/diagnosticOrdering.ts

@@ -77,15 +77,17 @@ export function compareDiagnosticFindings(
   );
 }
 
+// Tuple comparisons are written out field by field: the section 15 order of two
+// equal-length tuples is exactly the first non-zero field comparison, and this
+// avoids allocating two arrays for every comparison inside large sorts.
 export function compareDiagnosticContributions(
   left: DiagnosticMeasureContribution,
   right: DiagnosticMeasureContribution,
 ): number {
   return (
-    compareDiagnosticIdentityValues(
-      [left.sourceId, left.status, left.deduplicated],
-      [right.sourceId, right.status, right.deduplicated],
-    ) ||
+    compareDiagnosticIdentityValues(left.sourceId, right.sourceId) ||
+    compareDiagnosticIdentityValues(left.status, right.status) ||
+    compareDiagnosticIdentityValues(left.deduplicated, right.deduplicated) ||
     compareSources(left.sources, right.sources) ||
     compareDiagnosticIdentityValues(left, right)
   );
@@ -96,10 +98,9 @@ export function compareDiagnosticBlockers(
   right: DiagnosticStructuralBlocker,
 ): number {
   return (
-    compareDiagnosticIdentityValues(
-      [left.code, left.message, left.sourceIds],
-      [right.code, right.message, right.sourceIds],
-    ) ||
+    compareDiagnosticIdentityValues(left.code, right.code) ||
+    compareDiagnosticIdentityValues(left.message, right.message) ||
+    compareDiagnosticIdentityValues(left.sourceIds, right.sourceIds) ||
     compareSources(left.sources, right.sources) ||
     compareDiagnosticIdentityValues(left.finding, right.finding)
   );

package/src/diagnosticPeriods.ts

@@ -14,11 +14,28 @@ export interface DiagnosticNormalizedPeriod {
   readonly coordinate: number;
 }
 
+// Labels repeat across every row, cell and query of a definition, and each
+// normalized period is an immutable value. Cache per axis object and side,
+// bounded so adversarial label streams cannot grow the tables without limit.
+const MAX_MEMOIZED_LABELS = 100_000;
+const normalizedByAxis = new WeakMap<
+  DiagnosticPeriodAxis,
+  Record<DiagnosticPeriodSide, Map<string, DiagnosticNormalizedPeriod>>
+>();
+
 function normalizeWithAxis(
   axis: DiagnosticPeriodAxis,
   side: DiagnosticPeriodSide,
   label: string,
 ): DiagnosticNormalizedPeriod {
+  let tables = normalizedByAxis.get(axis);
+  if (!tables) {
+    tables = { origin: new Map(), valuation: new Map() };
+    normalizedByAxis.set(axis, tables);
+  }
+  const table = tables[side];
+  const cached = table.get(label);
+  if (cached !== undefined) return cached;
   const normalized = normalizeDiagnosticPeriodWithAxis(axis, side, label);
   if (!normalized)
     throw new DiagnosticValidationError([
@@ -32,7 +49,10 @@ function normalizeWithAxis(
             : `Unknown ordered-axis ${side} label ${JSON.stringify(label)}`,
       },
     ]);
-  return Object.freeze(normalized);
+  const frozen = Object.freeze(normalized);
+  if (table.size >= MAX_MEMOIZED_LABELS) table.clear();
+  table.set(label, frozen);
+  return frozen;
 }
 
 export function normalizeDiagnosticPeriod(