@actuarial-ts/core 0.6.0 → 0.7.0

package/src/diagnosticDerivations.ts

@@ -4,86 +4,318 @@ import {
   type CompiledDiagnosticDefinition,
 } from "./diagnosticDefinitions.js";
 import type { DiagnosticClaimExpression } from "./diagnosticExpressions.js";
-import { DiagnosticValidationError, type DiagnosticValidationIssue } from "./types.js";
+import type { DiagnosticExpressionOverflow } from "./diagnosticRules.js";
+import {
+  DiagnosticValidationError,
+  type DiagnosticValidationIssue,
+} from "./types.js";
+import {
+  diagnosticRecord,
+  hasDiagnosticOwn,
+  isDiagnosticPlainRecord,
+  normalizeDiagnosticNumber,
+} from "./diagnosticRuntime.js";
 
 export type DiagnosticMeasureValues = Readonly<Record<string, number | null>>;
 
-export type DiagnosticRowWithDerivedMeasures<TRow extends { measures: DiagnosticMeasureValues }> =
-  Omit<TRow, "measures"> & { readonly measures: DiagnosticMeasureValues };
+export type DiagnosticRowWithDerivedMeasures<
+  TRow extends { measures: DiagnosticMeasureValues },
+> = Omit<TRow, "measures"> & { readonly measures: DiagnosticMeasureValues };
 
-function evaluateClaimExpression(
-  expression: DiagnosticClaimExpression,
-  measures: Readonly<Record<string, number | null>>,
-): number | null {
-  if (expression.op === "measure") {
-    const value = measures[expression.measureId];
-    return typeof value === "number" && Number.isFinite(value) ? value : null;
-  }
-  if (expression.op === "claim-layer") {
-    const value = measures[expression.measureId];
-    if (typeof value !== "number" || !Number.isFinite(value)) return null;
-    const excess = Math.max(value - expression.attachment, 0);
-    const result = expression.limit === null ? excess : Math.min(excess, expression.limit);
-    return Number.isFinite(result) ? (Object.is(result, -0) ? 0 : result) : null;
-  }
-  if (expression.op === "subtract") {
-    const left = evaluateClaimExpression(expression.left, measures);
-    const right = evaluateClaimExpression(expression.right, measures);
-    if (left === null || right === null) return null;
-    const result = left - right;
-    return Number.isFinite(result) ? (Object.is(result, -0) ? 0 : result) : null;
-  }
+export type DiagnosticDerivedValueAudit =
+  | { readonly status: "observed"; readonly value: number }
+  | { readonly status: "missing"; readonly value: null }
+  | {
+      readonly status: "non-finite";
+      readonly value: null;
+      readonly nonFiniteKind: "nan" | "positive-infinity" | "negative-infinity";
+    };
+
+export interface DiagnosticDerivedRowAudit<
+  TRow extends { measures: DiagnosticMeasureValues },
+> {
+  readonly row: DiagnosticRowWithDerivedMeasures<TRow>;
+  readonly derived: Readonly<Record<string, DiagnosticDerivedValueAudit>>;
+  readonly expressionOverflows: Readonly<
+    Record<string, readonly DiagnosticExpressionOverflow[]>
+  >;
+}
+
+interface ClaimExpressionAudit {
+  readonly state: DiagnosticDerivedValueAudit;
+  readonly overflows: readonly DiagnosticExpressionOverflow[];
+}
+
+function nonFiniteKind(
+  value: number,
+): "nan" | "positive-infinity" | "negative-infinity" {
+  return Number.isNaN(value)
+    ? "nan"
+    : value > 0
+      ? "positive-infinity"
+      : "negative-infinity";
+}
+
+function mergeNonFiniteKinds(
+  values: readonly ("nan" | "positive-infinity" | "negative-infinity")[],
+): "nan" | "positive-infinity" | "negative-infinity" {
+  const unique = new Set(values);
+  return unique.size === 1 ? values[0]! : "nan";
+}
+
+function neumaier(values: readonly number[]): {
+  readonly value: number | null;
+  readonly nonFiniteKind?: "nan" | "positive-infinity" | "negative-infinity";
+} {
   let sum = 0;
   let correction = 0;
-  for (const term of expression.terms) {
-    const value = evaluateClaimExpression(term, measures);
-    if (value === null) return null;
+  for (const value of values) {
     const next = sum + value;
-    correction += Math.abs(sum) >= Math.abs(value) ? (sum - next) + value : (value - next) + sum;
+    if (!Number.isFinite(next))
+      return { value: null, nonFiniteKind: nonFiniteKind(next) };
+    const nextCorrection =
+      correction +
+      (Math.abs(sum) >= Math.abs(value)
+        ? sum - next + value
+        : value - next + sum);
+    if (!Number.isFinite(nextCorrection))
+      return { value: null, nonFiniteKind: nonFiniteKind(nextCorrection) };
+    correction = nextCorrection;
     sum = next;
-    if (!Number.isFinite(sum) || !Number.isFinite(correction)) return null;
   }
   const result = sum + correction;
-  return Number.isFinite(result) ? (Object.is(result, -0) ? 0 : result) : null;
+  return Number.isFinite(result)
+    ? { value: Object.is(result, -0) ? 0 : result }
+    : { value: null, nonFiniteKind: nonFiniteKind(result) };
 }
 
-/** Materializes compiler-approved claim-level measures without mutating caller rows. */
-export function deriveDiagnosticClaimMeasures<TRow extends { measures: DiagnosticMeasureValues }>(
+function evaluateClaimExpressionAudit(
+  expression: DiagnosticClaimExpression,
+  states: Readonly<Record<string, DiagnosticDerivedValueAudit>>,
+  path: string,
+): ClaimExpressionAudit {
+  if (expression.op === "measure")
+    return {
+      state: hasDiagnosticOwn(states, expression.measureId)
+        ? states[expression.measureId]!
+        : { status: "missing", value: null },
+      overflows: [],
+    };
+  if (expression.op === "claim-layer") {
+    const source = hasDiagnosticOwn(states, expression.measureId)
+      ? states[expression.measureId]!
+      : { status: "missing" as const, value: null };
+    if (source.status !== "observed") return { state: source, overflows: [] };
+    const value =
+      source.value <= expression.attachment
+        ? 0
+        : expression.limit === null
+          ? source.value - expression.attachment
+          : Math.min(source.value - expression.attachment, expression.limit);
+    if (Number.isFinite(value))
+      return {
+        state: { status: "observed", value: normalizeDiagnosticNumber(value) },
+        overflows: [],
+      };
+    return {
+      state: {
+        status: "non-finite",
+        value: null,
+        nonFiniteKind: nonFiniteKind(value),
+      },
+      overflows: [{ expressionPath: path, sources: [] }],
+    };
+  }
+  const children =
+    expression.op === "add"
+      ? expression.terms.map((term, index) =>
+          evaluateClaimExpressionAudit(term, states, `${path}/terms/${index}`),
+        )
+      : [
+          evaluateClaimExpressionAudit(expression.left, states, `${path}/left`),
+          evaluateClaimExpressionAudit(
+            expression.right,
+            states,
+            `${path}/right`,
+          ),
+        ];
+  const overflows = children.flatMap((child) => child.overflows);
+  const nonFinite = children.flatMap((child) =>
+    child.state.status === "non-finite" ? [child.state.nonFiniteKind] : [],
+  );
+  if (nonFinite.length > 0)
+    return {
+      state: {
+        status: "non-finite",
+        value: null,
+        nonFiniteKind: mergeNonFiniteKinds(nonFinite),
+      },
+      overflows,
+    };
+  if (children.some((child) => child.state.status === "missing"))
+    return { state: { status: "missing", value: null }, overflows };
+  const values = children.map((child) => child.state.value!);
+  const calculation =
+    expression.op === "add"
+      ? neumaier(values)
+      : { value: values[0]! - values[1]! };
+  if (calculation.value !== null && Number.isFinite(calculation.value)) {
+    return {
+      state: {
+        status: "observed",
+        value: normalizeDiagnosticNumber(calculation.value),
+      },
+      overflows,
+    };
+  }
+  const failedKind =
+    calculation.nonFiniteKind ?? nonFiniteKind(calculation.value ?? Number.NaN);
+  return {
+    state: { status: "non-finite", value: null, nonFiniteKind: failedKind },
+    overflows: [...overflows, { expressionPath: path, sources: [] }],
+  };
+}
+
+function validateRows<TRow extends { measures: DiagnosticMeasureValues }>(
   rows: readonly TRow[],
   definition: CompiledDiagnosticDefinition,
-): readonly DiagnosticRowWithDerivedMeasures<TRow>[] {
-  assertCompiledDiagnosticDefinition(definition);
+): void {
   const internals = getCompiledDiagnosticDefinitionInternals(definition);
   const issues: DiagnosticValidationIssue[] = [];
   if (definition.definition.lossRowGrain !== "claim") {
-    issues.push({ domain: "input", code: "invalid-input-relationship", path: "$.definition.lossRowGrain", message: "Claim derivation requires a claim-grain definition" });
+    issues.push({
+      domain: "input",
+      code: "invalid-input-relationship",
+      path: "$.definition.lossRowGrain",
+      message: "Claim derivation requires a claim-grain definition",
+    });
   }
   if (!Array.isArray(rows)) {
-    issues.push({ domain: "input", code: "invalid-type", path: "$.rows", message: "Claim rows must be an array" });
+    issues.push({
+      domain: "input",
+      code: "invalid-type",
+      path: "$.rows",
+      message: "Claim rows must be an array",
+    });
   } else {
     rows.forEach((row, rowIndex) => {
       const measures = row?.measures;
-      if (measures === null || typeof measures !== "object" || Array.isArray(measures)) {
-        issues.push({ domain: "input", code: "invalid-type", path: `$.rows[${rowIndex}].measures`, message: "Row measures must be a plain record" });
+      if (!isDiagnosticPlainRecord(measures)) {
+        issues.push({
+          domain: "input",
+          code: "invalid-type",
+          path: `$.rows[${rowIndex}].measures`,
+          message: "Row measures must be a plain record",
+        });
         return;
       }
       for (const [measureId, value] of Object.entries(measures)) {
         const measure = internals.measuresById.get(measureId);
         const path = `$.rows[${rowIndex}].measures[${JSON.stringify(measureId)}]`;
-        if (!measure) issues.push({ domain: "input", code: "unknown-reference", path, message: `Unknown measure ${measureId}` });
-        else if (measure.source !== "loss") issues.push({ domain: "input", code: "invalid-input-relationship", path, message: `Caller rows cannot supply ${measure.source} measure ${measureId}` });
-        if (value !== null && typeof value !== "number") issues.push({ domain: "input", code: "invalid-type", path, message: "Measure value must be a number or null" });
+        if (!measure)
+          issues.push({
+            domain: "input",
+            code: "unknown-reference",
+            path,
+            message: `Unknown measure ${measureId}`,
+          });
+        else if (measure.source !== "loss")
+          issues.push({
+            domain: "input",
+            code: "invalid-input-relationship",
+            path,
+            message: `Caller rows cannot supply ${measure.source} measure ${measureId}`,
+          });
+        if (value !== null && typeof value !== "number")
+          issues.push({
+            domain: "input",
+            code: "invalid-type",
+            path,
+            message: "Measure value must be a number or null",
+          });
       }
     });
   }
   if (issues.length > 0) throw new DiagnosticValidationError(issues);
+}
 
+/** @internal Shared with diagnostic preparation to preserve derivation quality. */
+export function deriveDiagnosticClaimMeasuresWithAudit<
+  TRow extends { measures: DiagnosticMeasureValues },
+>(
+  rows: readonly TRow[],
+  definition: CompiledDiagnosticDefinition,
+): readonly DiagnosticDerivedRowAudit<TRow>[] {
+  assertCompiledDiagnosticDefinition(definition);
+  validateRows(rows, definition);
+  const internals = getCompiledDiagnosticDefinitionInternals(definition);
   const plan = [...internals.derivationsByOutputMeasureId.values()];
-  return Object.freeze(rows.map((row) => {
-    const measures: Record<string, number | null> = { ...row.measures };
-    for (const derivation of plan) {
-      measures[derivation.outputMeasureId] = evaluateClaimExpression(derivation.expression, measures);
-    }
-    return Object.freeze({ ...row, measures: Object.freeze(measures) }) as DiagnosticRowWithDerivedMeasures<TRow>;
-  }));
+  const normalizedIndex = new Map(
+    definition.definition.derivedMeasures.map((derivation, index) => [
+      derivation.outputMeasureId,
+      index,
+    ]),
+  );
+  return Object.freeze(
+    rows.map((row) => {
+      const measures = diagnosticRecord<number | null>();
+      const states = diagnosticRecord<DiagnosticDerivedValueAudit>();
+      for (const [id, value] of Object.entries(row.measures)) {
+        measures[id] = value;
+        states[id] =
+          value === null || value === undefined
+            ? { status: "missing" as const, value: null }
+            : Number.isFinite(value)
+              ? {
+                  status: "observed" as const,
+                  value: normalizeDiagnosticNumber(value),
+                }
+              : {
+                  status: "non-finite" as const,
+                  value: null,
+                  nonFiniteKind: nonFiniteKind(value),
+                };
+      }
+      const derived = diagnosticRecord<DiagnosticDerivedValueAudit>();
+      const expressionOverflows =
+        diagnosticRecord<readonly DiagnosticExpressionOverflow[]>();
+      for (const derivation of plan) {
+        const index = normalizedIndex.get(derivation.outputMeasureId)!;
+        const evaluated = evaluateClaimExpressionAudit(
+          derivation.expression,
+          states,
+          `/derivedMeasures/${index}/expression`,
+        );
+        states[derivation.outputMeasureId] = evaluated.state;
+        derived[derivation.outputMeasureId] = evaluated.state;
+        expressionOverflows[derivation.outputMeasureId] = Object.freeze([
+          ...evaluated.overflows,
+        ]);
+        measures[derivation.outputMeasureId] = evaluated.state.value;
+      }
+      return Object.freeze({
+        row: Object.freeze({
+          ...row,
+          measures: Object.freeze(measures),
+        }) as DiagnosticRowWithDerivedMeasures<TRow>,
+        derived: Object.freeze(derived),
+        expressionOverflows: Object.freeze(expressionOverflows),
+      });
+    }),
+  );
+}
+
+/** Materializes compiler-approved claim-level measures without mutating caller rows. */
+export function deriveDiagnosticClaimMeasures<
+  TRow extends { measures: DiagnosticMeasureValues },
+>(
+  rows: readonly TRow[],
+  definition: CompiledDiagnosticDefinition,
+): readonly DiagnosticRowWithDerivedMeasures<TRow>[] {
+  assertCompiledDiagnosticDefinition(definition);
+  return Object.freeze(
+    deriveDiagnosticClaimMeasuresWithAudit(rows, definition).map(
+      (item) => item.row,
+    ),
+  );
 }

package/src/diagnosticEvidenceIntern.ts

@@ -0,0 +1,151 @@
+/**
+ * Private, invocation-scoped sharing of small, newly owned evidence nodes.
+ * This is not a validation boundary: callers must finish normalizing/cloning
+ * every child first, and must never submit caller-owned objects or SDK brands.
+ */
+export interface DiagnosticEvidenceInternOptions {
+  readonly maxEntries?: number;
+  readonly maxSignatureCharacters?: number;
+  readonly maxCandidateProperties?: number;
+}
+
+type EvidenceMode = "plain" | "source" | "free";
+
+const DEFAULT_MAX_ENTRIES = 100_000;
+const DEFAULT_MAX_SIGNATURE_CHARACTERS = 16 * 1024 * 1024;
+// Wide result envelopes are usually unique; focus the budget on their small
+// repeated coordinates, sources, scopes, states, and short child lists.
+const DEFAULT_MAX_CANDIDATE_PROPERTIES = 10;
+const MAX_CANDIDATE_STRING_CHARACTERS = 4096;
+
+function sameOwnedNode(left: object, right: object): boolean {
+  if (Object.getPrototypeOf(left) !== Object.getPrototypeOf(right))
+    return false;
+  const leftKeys = Reflect.ownKeys(left);
+  const rightKeys = Reflect.ownKeys(right);
+  if (leftKeys.length !== rightKeys.length) return false;
+  return leftKeys.every((key, index) => {
+    if (key !== rightKeys[index]) return false;
+    const a = Object.getOwnPropertyDescriptor(left, key)!;
+    const b = Object.getOwnPropertyDescriptor(right, key)!;
+    return (
+      "value" in a &&
+      "value" in b &&
+      a.enumerable === b.enumerable &&
+      a.configurable === b.configurable &&
+      a.writable === b.writable &&
+      Object.is(a.value, b.value)
+    );
+  });
+}
+
+export function createDiagnosticEvidenceInterner(
+  options: DiagnosticEvidenceInternOptions = {},
+): {
+  internOwned<T extends object>(candidate: T, mode: EvidenceMode): T;
+} {
+  const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const maxSignatureCharacters =
+    options.maxSignatureCharacters ?? DEFAULT_MAX_SIGNATURE_CHARACTERS;
+  const maxCandidateProperties =
+    options.maxCandidateProperties ?? DEFAULT_MAX_CANDIDATE_PROPERTIES;
+  const pool = new Map<string, object>();
+  const childIds = new WeakMap<object, number>();
+  let nextChildId = 1;
+  let signatureCharacters = 0;
+
+  return {
+    internOwned<T extends object>(candidate: T, mode: EvidenceMode): T {
+      if (!Object.isFrozen(candidate)) return candidate;
+      const prototype = Object.getPrototypeOf(candidate);
+      const array = Array.isArray(candidate);
+      if (
+        array
+          ? prototype !== Array.prototype
+          : prototype !== null && prototype !== Object.prototype
+      )
+        return candidate;
+      if (array && candidate.length >= maxCandidateProperties) return candidate;
+      const keys = Reflect.ownKeys(candidate);
+      if (keys.length > maxCandidateProperties) return candidate;
+      const signatureParts: unknown[] = [
+        mode,
+        array ? "array" : prototype === null ? "null" : "object",
+      ];
+      // A declined candidate must not grow persistent bookkeeping. Stage at
+      // most this small candidate's children, including repeated references,
+      // and commit their IDs only if the candidate enters the bounded pool.
+      let pendingChildIds: Map<object, number> | undefined;
+      let stringCharacters = 0;
+      for (const key of keys) {
+        // Diagnostic JSON does not contain symbols. Declining unexpected
+        // shapes is harmless and never invokes an accessor or caller method.
+        if (typeof key !== "string") return candidate;
+        const descriptor = Object.getOwnPropertyDescriptor(candidate, key)!;
+        if (!("value" in descriptor)) return candidate;
+        const value: unknown = descriptor.value;
+        let tokenType: string;
+        let tokenValue: unknown;
+        if (value === null) {
+          tokenType = "null";
+          tokenValue = null;
+        } else if (typeof value === "object") {
+          if (!Object.isFrozen(value)) return candidate;
+          tokenType = "object";
+          const existingId = childIds.get(value);
+          if (existingId !== undefined) tokenValue = existingId;
+          else {
+            pendingChildIds ??= new Map();
+            let pendingId = pendingChildIds.get(value);
+            if (pendingId === undefined) {
+              pendingId = nextChildId + pendingChildIds.size;
+              pendingChildIds.set(value, pendingId);
+            }
+            tokenValue = pendingId;
+          }
+        } else if (typeof value === "number") {
+          if (!Number.isFinite(value)) return candidate;
+          tokenType = "number";
+          tokenValue = Object.is(value, -0) ? "-0" : value;
+        } else if (
+          typeof value === "string" ||
+          typeof value === "boolean" ||
+          value === undefined
+        ) {
+          tokenType = typeof value;
+          tokenValue = value;
+          if (typeof value === "string") stringCharacters += value.length;
+        } else return candidate;
+        stringCharacters += key.length;
+        if (stringCharacters > MAX_CANDIDATE_STRING_CHARACTERS)
+          return candidate;
+        // Frozen data properties are necessarily non-configurable and
+        // non-writable. Keep the varying enumerability bit (including array
+        // length) and a fixed four-slot typed tuple, without temporary nested
+        // arrays. The independent equality check still verifies every flag.
+        signatureParts.push(key, descriptor.enumerable, tokenType, tokenValue);
+      }
+      const signature = JSON.stringify(signatureParts);
+      // An unseen child cannot occur in an existing entry: every admitted
+      // entry committed all its child IDs. No equality hit is skipped here.
+      const existing = pendingChildIds ? undefined : pool.get(signature);
+      // Signatures encode exact children and descriptor/order information;
+      // independently check equality before sharing rather than treating a
+      // fingerprint as proof of equality.
+      if (existing !== undefined && sameOwnedNode(existing, candidate))
+        return existing as T;
+      if (
+        pool.size < maxEntries &&
+        signatureCharacters + signature.length <= maxSignatureCharacters
+      ) {
+        if (pendingChildIds) {
+          for (const [child, id] of pendingChildIds) childIds.set(child, id);
+          nextChildId += pendingChildIds.size;
+        }
+        pool.set(signature, candidate);
+        signatureCharacters += signature.length;
+      }
+      return candidate;
+    },
+  };
+}