@actuarial-ts/core 0.5.0 → 0.6.1

package/src/diagnosticExpressions.ts

@@ -0,0 +1,255 @@
+import type {
+  DiagnosticValidationIssue,
+  DiagnosticValidationIssueCode,
+} from "./types.js";
+import {
+  isDiagnosticPlainRecord,
+  isDiagnosticToken,
+} from "./diagnosticRuntime.js";
+
+export const MAX_DIAGNOSTIC_EXPRESSION_DEPTH = 64;
+export const MAX_DIAGNOSTIC_EXPRESSION_NODES = 10_000;
+export const MAX_DIAGNOSTIC_DEFINITION_EXPRESSION_NODES = 100_000;
+
+export type DiagnosticMeasureExpression =
+  | { op: "measure"; measureId: string }
+  | { op: "add"; terms: readonly DiagnosticMeasureExpression[] }
+  | {
+      op: "subtract";
+      left: DiagnosticMeasureExpression;
+      right: DiagnosticMeasureExpression;
+    };
+
+export type DiagnosticRoleExpression =
+  | { op: "role"; role: string }
+  | { op: "add"; terms: readonly DiagnosticRoleExpression[] }
+  | {
+      op: "subtract";
+      left: DiagnosticRoleExpression;
+      right: DiagnosticRoleExpression;
+    };
+
+export type DiagnosticClaimExpression =
+  | { op: "measure"; measureId: string }
+  | { op: "add"; terms: readonly DiagnosticClaimExpression[] }
+  | {
+      op: "subtract";
+      left: DiagnosticClaimExpression;
+      right: DiagnosticClaimExpression;
+    }
+  | {
+      op: "claim-layer";
+      measureId: string;
+      attachment: number;
+      /** Layer width; null means unlimited above attachment. */
+      limit: number | null;
+    };
+
+export type DiagnosticExpressionKind = "measure" | "role" | "claim";
+
+export interface DiagnosticExpressionWalk {
+  readonly dependencies: readonly string[];
+  readonly nodeCount: number;
+  readonly maxDepth: number;
+}
+
+interface WalkFrame {
+  readonly value: unknown;
+  readonly path: string;
+  readonly depth: number;
+  readonly ancestors: readonly object[];
+}
+
+function issue(
+  issues: DiagnosticValidationIssue[],
+  code: DiagnosticValidationIssueCode,
+  path: string,
+  message: string,
+): void {
+  issues.push({ domain: "definition", code, path, message });
+}
+
+function propertyPath(parent: string, key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+    ? `${parent}.${key}`
+    : `${parent}[${JSON.stringify(key)}]`;
+}
+
+function rejectUnknownKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string,
+  issues: DiagnosticValidationIssue[],
+): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {
+      issue(
+        issues,
+        "unknown-key",
+        propertyPath(path, key),
+        `Unknown expression key ${key}`,
+      );
+    }
+  }
+}
+
+/**
+ * Iterative structural/resource walk used before recursive normalization. It
+ * deliberately accepts unknown so hostile inputs cannot overflow the host
+ * stack before the compiler can return a typed issue.
+ */
+export function walkDiagnosticExpression(
+  value: unknown,
+  kind: DiagnosticExpressionKind,
+  path: string,
+  issues: DiagnosticValidationIssue[],
+  initialDepth = 1,
+): DiagnosticExpressionWalk {
+  const dependencies = new Set<string>();
+  const stack: WalkFrame[] = [
+    { value, path, depth: initialDepth, ancestors: [] },
+  ];
+  let nodeCount = 0;
+  let maxDepth = 0;
+  while (stack.length > 0) {
+    const frame = stack.pop()!;
+    nodeCount++;
+    maxDepth = Math.max(maxDepth, frame.depth);
+    if (frame.depth > MAX_DIAGNOSTIC_EXPRESSION_DEPTH) {
+      issue(
+        issues,
+        "expression-limit",
+        frame.path,
+        `Expression depth exceeds ${MAX_DIAGNOSTIC_EXPRESSION_DEPTH}`,
+      );
+      continue;
+    }
+    if (nodeCount > MAX_DIAGNOSTIC_EXPRESSION_NODES) {
+      issue(
+        issues,
+        "expression-limit",
+        path,
+        `Expression node count exceeds ${MAX_DIAGNOSTIC_EXPRESSION_NODES}`,
+      );
+      break;
+    }
+    if (!isDiagnosticPlainRecord(frame.value)) {
+      issue(
+        issues,
+        "invalid-type",
+        frame.path,
+        "Expression node must be a plain object",
+      );
+      continue;
+    }
+    if (frame.ancestors.includes(frame.value)) {
+      issue(issues, "cycle", frame.path, "Expression contains a cycle");
+      continue;
+    }
+    const op = frame.value.op;
+    const nextAncestors = [...frame.ancestors, frame.value];
+    if (kind === "role" && op === "role") {
+      rejectUnknownKeys(frame.value, ["op", "role"], frame.path, issues);
+      if (isDiagnosticToken(frame.value.role))
+        dependencies.add(frame.value.role);
+      else
+        issue(
+          issues,
+          typeof frame.value.role === "string"
+            ? "invalid-string"
+            : "invalid-type",
+          `${frame.path}.role`,
+          "Role reference must be a nonempty token",
+        );
+      continue;
+    }
+    if ((kind === "measure" || kind === "claim") && op === "measure") {
+      rejectUnknownKeys(frame.value, ["op", "measureId"], frame.path, issues);
+      if (isDiagnosticToken(frame.value.measureId))
+        dependencies.add(frame.value.measureId);
+      else
+        issue(
+          issues,
+          typeof frame.value.measureId === "string"
+            ? "invalid-string"
+            : "invalid-type",
+          `${frame.path}.measureId`,
+          "Measure reference must be a nonempty token",
+        );
+      continue;
+    }
+    if (kind === "claim" && op === "claim-layer") {
+      rejectUnknownKeys(
+        frame.value,
+        ["op", "measureId", "attachment", "limit"],
+        frame.path,
+        issues,
+      );
+      if (isDiagnosticToken(frame.value.measureId))
+        dependencies.add(frame.value.measureId);
+      else
+        issue(
+          issues,
+          typeof frame.value.measureId === "string"
+            ? "invalid-string"
+            : "invalid-type",
+          `${frame.path}.measureId`,
+          "Measure reference must be a nonempty token",
+        );
+      continue;
+    }
+    if (op === "add") {
+      rejectUnknownKeys(frame.value, ["op", "terms"], frame.path, issues);
+      if (!Array.isArray(frame.value.terms) || frame.value.terms.length === 0) {
+        issue(
+          issues,
+          "invalid-type",
+          `${frame.path}.terms`,
+          "Add expression requires at least one term",
+        );
+        continue;
+      }
+      for (let index = frame.value.terms.length - 1; index >= 0; index--) {
+        stack.push({
+          value: frame.value.terms[index],
+          path: `${frame.path}.terms[${index}]`,
+          depth: frame.depth + 1,
+          ancestors: nextAncestors,
+        });
+      }
+      continue;
+    }
+    if (op === "subtract") {
+      rejectUnknownKeys(
+        frame.value,
+        ["op", "left", "right"],
+        frame.path,
+        issues,
+      );
+      stack.push({
+        value: frame.value.right,
+        path: `${frame.path}.right`,
+        depth: frame.depth + 1,
+        ancestors: nextAncestors,
+      });
+      stack.push({
+        value: frame.value.left,
+        path: `${frame.path}.left`,
+        depth: frame.depth + 1,
+        ancestors: nextAncestors,
+      });
+      continue;
+    }
+    issue(
+      issues,
+      "invalid-type",
+      `${frame.path}.op`,
+      `Unknown ${kind} expression operator`,
+    );
+  }
+  return {
+    dependencies: [...dependencies].sort(),
+    nodeCount,
+    maxDepth,
+  };
+}

package/src/diagnosticFormulas.ts

@@ -0,0 +1,350 @@
+import { safeRatio } from "./util.js";
+import type {
+  DiagnosticDeepReadonly,
+  DiagnosticFormulaTemplate,
+  DiagnosticMeasureKind,
+  DiagnosticMeasureStats,
+  DiagnosticMetricPresentation,
+} from "./diagnosticDefinitions.js";
+import type {
+  DiagnosticMeasureExpression,
+  DiagnosticRoleExpression,
+} from "./diagnosticExpressions.js";
+import type {
+  DiagnosticExpressionOverflow,
+  DiagnosticRuleNotEvaluatedReason,
+} from "./diagnosticRules.js";
+import { normalizeDiagnosticSourceLocations } from "./diagnosticSourceOrdering.js";
+import { hasDiagnosticOwn } from "./diagnosticRuntime.js";
+
+export const CASUALTY_FORMULA_TEMPLATES = Object.freeze([
+  {
+    id: "frequency",
+    version: "1.0.0",
+    roles: { claims: { kind: "count" }, exposure: { kind: "exposure" } },
+    numerator: { op: "role", role: "claims" },
+    denominator: { op: "role", role: "exposure" },
+    denominatorPolicy: "positive-or-null",
+  },
+  {
+    id: "share",
+    version: "1.0.0",
+    roles: {
+      part: { kind: "count", compatibilityGroup: "count-population" },
+      whole: { kind: "count", compatibilityGroup: "count-population" },
+    },
+    numerator: { op: "role", role: "part" },
+    denominator: { op: "role", role: "whole" },
+    denominatorPolicy: "positive-or-null",
+  },
+  {
+    id: "paid-to-incurred",
+    version: "1.0.0",
+    roles: {
+      paid: {
+        kind: "amount",
+        compatibilityGroup: "amount-basis",
+        developmentSemantics: "cumulative",
+      },
+      incurred: {
+        kind: "amount",
+        compatibilityGroup: "amount-basis",
+        developmentSemantics: "cumulative",
+      },
+    },
+    numerator: { op: "role", role: "paid" },
+    denominator: { op: "role", role: "incurred" },
+    denominatorPolicy: "positive-or-null",
+  },
+  {
+    id: "amount-per-exposure",
+    version: "1.0.0",
+    roles: { amount: { kind: "amount" }, exposure: { kind: "exposure" } },
+    numerator: { op: "role", role: "amount" },
+    denominator: { op: "role", role: "exposure" },
+    denominatorPolicy: "positive-or-null",
+  },
+  {
+    id: "amount-per-claim",
+    version: "1.0.0",
+    roles: { amount: { kind: "amount" }, claims: { kind: "count" } },
+    numerator: { op: "role", role: "amount" },
+    denominator: { op: "role", role: "claims" },
+    denominatorPolicy: "positive-or-null",
+  },
+  {
+    id: "case-per-open",
+    version: "1.0.0",
+    roles: {
+      incurred: {
+        kind: "amount",
+        compatibilityGroup: "amount-basis",
+        developmentSemantics: "cumulative",
+      },
+      paid: {
+        kind: "amount",
+        compatibilityGroup: "amount-basis",
+        developmentSemantics: "cumulative",
+      },
+      open: { kind: "count", developmentSemantics: "point-in-time" },
+    },
+    numerator: {
+      op: "subtract",
+      left: { op: "role", role: "incurred" },
+      right: { op: "role", role: "paid" },
+    },
+    denominator: { op: "role", role: "open" },
+    denominatorPolicy: "positive-or-null",
+  },
+] as const satisfies readonly DiagnosticFormulaTemplate[]);
+
+export interface DiagnosticQuantitySemantics {
+  readonly kind: DiagnosticMeasureKind;
+  readonly unit: string;
+  readonly basisId?: string;
+  readonly countPopulationId?: string;
+  readonly exposureBasisId?: string;
+}
+
+export interface DiagnosticQuantity extends DiagnosticQuantitySemantics {
+  readonly value: number | null;
+}
+
+export interface DiagnosticMetricFinding {
+  readonly code: string;
+  readonly message: string;
+  readonly severity: "info" | "warning" | "fail";
+  readonly category:
+    | "structural"
+    | "aggregation"
+    | "calculation"
+    | "rule"
+    | "presentation";
+  readonly ruleId?: string;
+  readonly measureId?: string;
+  readonly instanceId?: string;
+  readonly expressionPath?: string;
+  readonly offendingKey?: string;
+  readonly sourceGroup?: string;
+  readonly group?: string;
+  readonly origin?: string;
+  readonly valuation?: string;
+  readonly developmentAge?: number;
+  readonly ageUnit?: string;
+  readonly recordId?: string;
+  readonly claimId?: string;
+  readonly exposureKey?: string;
+  readonly sources: readonly import("./diagnosticDefinitions.js").DiagnosticSourceLocation[];
+}
+
+export interface FinalizedDiagnosticMeasure {
+  readonly quantity: DiagnosticQuantity;
+  readonly stats: DiagnosticMeasureStats;
+  readonly readiness: readonly DiagnosticRuleNotEvaluatedReason[];
+  readonly expressionOverflows?: readonly DiagnosticExpressionOverflow[];
+  readonly sources?: readonly import("./diagnosticDefinitions.js").DiagnosticSourceLocation[];
+}
+
+interface ExpressionResult {
+  readonly value: number | null;
+  readonly reasons: readonly DiagnosticRuleNotEvaluatedReason[];
+  readonly overflows: readonly DiagnosticExpressionOverflow[];
+  readonly sources: readonly import("./diagnosticDefinitions.js").DiagnosticSourceLocation[];
+}
+
+function neumaier(values: readonly number[]): number | null {
+  let sum = 0;
+  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;
+    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;
+}
+
+function uniqueReasons(
+  values: readonly DiagnosticRuleNotEvaluatedReason[],
+): readonly DiagnosticRuleNotEvaluatedReason[] {
+  const order: readonly DiagnosticRuleNotEvaluatedReason[] = [
+    "missing",
+    "imputed",
+    "non-finite",
+    "structural-ambiguity",
+    "aggregation-overflow",
+    "expression-overflow",
+    "tolerance-overflow",
+  ];
+  return order.filter((reason) => values.includes(reason));
+}
+
+function pointer(path: string, segment: string | number): string {
+  const escaped = String(segment).replaceAll("~", "~0").replaceAll("/", "~1");
+  return `${path}/${escaped}`;
+}
+
+export function evaluateDiagnosticMeasureExpression(
+  expression: DiagnosticDeepReadonly<DiagnosticMeasureExpression>,
+  measures: Readonly<Record<string, FinalizedDiagnosticMeasure>>,
+  path: string,
+): ExpressionResult {
+  if (expression.op === "measure") {
+    const value = hasDiagnosticOwn(measures, expression.measureId)
+      ? measures[expression.measureId]
+      : undefined;
+    return value
+      ? {
+          value: value.quantity.value,
+          reasons: value.readiness,
+          overflows: value.expressionOverflows ?? [],
+          sources: value.sources ?? [],
+        }
+      : { value: null, reasons: ["missing"], overflows: [], 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);
+  const sources = normalizeDiagnosticSourceLocations(
+    children.flatMap((child) => child.sources),
+  );
+  if (children.some((child) => child.value === null))
+    return { value: null, reasons, overflows, sources };
+  const value =
+    expression.op === "add"
+      ? neumaier(children.map((child) => child.value!))
+      : children[0]!.value! - children[1]!.value!;
+  if (value === null || !Number.isFinite(value)) {
+    return {
+      value: null,
+      reasons: uniqueReasons([...reasons, "expression-overflow"]),
+      overflows: [...overflows, { expressionPath: path, sources }],
+      sources,
+    };
+  }
+  return {
+    value: Object.is(value, -0) ? 0 : value,
+    reasons,
+    overflows,
+    sources,
+  };
+}
+
+export function evaluateDiagnosticRoleExpression(
+  expression: DiagnosticDeepReadonly<DiagnosticRoleExpression>,
+  bindings: Readonly<Record<string, ExpressionResult>>,
+  path: string,
+): ExpressionResult {
+  if (expression.op === "role")
+    return hasDiagnosticOwn(bindings, expression.role)
+      ? bindings[expression.role]!
+      : { value: null, reasons: ["missing"], overflows: [], sources: [] };
+  const children =
+    expression.op === "add"
+      ? expression.terms.map((term, index) =>
+          evaluateDiagnosticRoleExpression(
+            term,
+            bindings,
+            pointer(pointer(path, "terms"), index),
+          ),
+        )
+      : [
+          evaluateDiagnosticRoleExpression(
+            expression.left,
+            bindings,
+            pointer(path, "left"),
+          ),
+          evaluateDiagnosticRoleExpression(
+            expression.right,
+            bindings,
+            pointer(path, "right"),
+          ),
+        ];
+  const reasons = uniqueReasons(children.flatMap((child) => child.reasons));
+  const overflows = children.flatMap((child) => child.overflows);
+  const sources = normalizeDiagnosticSourceLocations(
+    children.flatMap((child) => child.sources),
+  );
+  if (children.some((child) => child.value === null))
+    return { value: null, reasons, overflows, sources };
+  const value =
+    expression.op === "add"
+      ? neumaier(children.map((child) => child.value!))
+      : children[0]!.value! - children[1]!.value!;
+  if (value === null || !Number.isFinite(value))
+    return {
+      value: null,
+      reasons: uniqueReasons([...reasons, "expression-overflow"]),
+      overflows: [...overflows, { expressionPath: path, sources }],
+      sources,
+    };
+  return {
+    value: Object.is(value, -0) ? 0 : value,
+    reasons,
+    overflows,
+    sources,
+  };
+}
+
+export function diagnosticRawRatio(
+  numerator: number | null,
+  denominator: number | null,
+): number | null {
+  if (
+    numerator === null ||
+    denominator === null ||
+    !Number.isFinite(numerator) ||
+    !Number.isFinite(denominator) ||
+    denominator <= 0
+  )
+    return null;
+  const ratio = safeRatio(numerator, denominator);
+  return ratio !== null && Number.isFinite(ratio) ? ratio : null;
+}
+
+export function applyDiagnosticPresentation(
+  rawValue: number | null,
+  presentation: DiagnosticDeepReadonly<DiagnosticMetricPresentation>,
+): {
+  readonly value: number | null;
+  readonly finding: DiagnosticMetricFinding | null;
+} {
+  if (rawValue === null) return { value: null, finding: null };
+  const value = rawValue * presentation.scale;
+  return Number.isFinite(value)
+    ? { value: Object.is(value, -0) ? 0 : value, finding: null }
+    : {
+        value: null,
+        finding: {
+          code: "diagnostic-presentation-overflow",
+          message: "Diagnostic presentation scaling overflowed",
+          severity: "fail",
+          category: "presentation",
+          sources: [],
+        },
+      };
+}