@actuarial-ts/core 0.5.0 → 0.6.0

package/src/diagnosticDerivations.ts

@@ -0,0 +1,89 @@
+import {
+  assertCompiledDiagnosticDefinition,
+  getCompiledDiagnosticDefinitionInternals,
+  type CompiledDiagnosticDefinition,
+} from "./diagnosticDefinitions.js";
+import type { DiagnosticClaimExpression } from "./diagnosticExpressions.js";
+import { DiagnosticValidationError, type DiagnosticValidationIssue } from "./types.js";
+
+export type DiagnosticMeasureValues = Readonly<Record<string, number | null>>;
+
+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;
+  }
+  let sum = 0;
+  let correction = 0;
+  for (const term of expression.terms) {
+    const value = evaluateClaimExpression(term, measures);
+    if (value === null) return null;
+    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;
+}
+
+/** 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);
+  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" });
+  }
+  if (!Array.isArray(rows)) {
+    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" });
+        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 (issues.length > 0) throw new DiagnosticValidationError(issues);
+
+  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>;
+  }));
+}

package/src/diagnosticExposure.ts

@@ -0,0 +1,91 @@
+import type { DiagnosticSourceLocation } from "./diagnosticDefinitions.js";
+
+export interface DiagnosticExposureObservation {
+  readonly key: string;
+  readonly sourceGroup: string;
+  readonly origin: string;
+  readonly valuation?: string;
+  readonly measureId: string;
+  readonly value: number | null;
+  readonly complete: boolean;
+  readonly source?: DiagnosticSourceLocation;
+}
+
+export type DiagnosticAuditedNumericValue =
+  | { 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 DiagnosticExposureAuditObservation {
+  readonly sourceGroup: string;
+  readonly origin: string;
+  readonly valuation?: string;
+  readonly value: DiagnosticAuditedNumericValue;
+  readonly complete: boolean;
+  readonly source?: DiagnosticSourceLocation;
+}
+
+export type ReconciledDiagnosticExposure =
+  | { readonly measureId: string; readonly key: string; readonly status: "valid"; readonly sourceGroup: string; readonly origin: string; readonly valuation?: string; readonly value: number; readonly deduplicated: number; readonly sources: readonly DiagnosticSourceLocation[] }
+  | { readonly measureId: string; readonly key: string; readonly status: "invalid"; readonly issues: readonly ("missing" | "incomplete" | "non-finite" | "duplicate" | "conflict")[]; readonly value: null; readonly observations: readonly DiagnosticExposureAuditObservation[] };
+
+export function auditDiagnosticNumber(value: number | null): DiagnosticAuditedNumericValue {
+  if (value === null) return { status: "missing", value: null };
+  if (!Number.isFinite(value)) return { status: "non-finite", value: null, nonFiniteKind: Number.isNaN(value) ? "nan" : value > 0 ? "positive-infinity" : "negative-infinity" };
+  return { status: "observed", value: Object.is(value, -0) ? 0 : value };
+}
+
+function equalAudit(left: DiagnosticExposureAuditObservation, right: DiagnosticExposureAuditObservation): boolean {
+  return left.sourceGroup === right.sourceGroup && left.origin === right.origin && left.complete === right.complete &&
+    JSON.stringify(left.value) === JSON.stringify(right.value);
+}
+
+export function reconcileDiagnosticExposures(
+  observations: readonly DiagnosticExposureObservation[],
+  timingByMeasure: Readonly<Record<string, "origin-static" | "valuation-specific">>,
+): readonly ReconciledDiagnosticExposure[] {
+  const cohorts = new Map<string, DiagnosticExposureObservation[]>();
+  for (const observation of observations) {
+    const timing = timingByMeasure[observation.measureId];
+    const identity = timing === "valuation-specific"
+      ? `${observation.measureId}\u0000${observation.key}\u0000${observation.valuation ?? ""}`
+      : `${observation.measureId}\u0000${observation.key}`;
+    const cohort = cohorts.get(identity) ?? [];
+    cohort.push(observation);
+    cohorts.set(identity, cohort);
+  }
+  return Object.freeze([...cohorts.values()].map((cohort): ReconciledDiagnosticExposure => {
+    const first = cohort[0]!;
+    const timing = timingByMeasure[first.measureId];
+    const audited = cohort.map((item): DiagnosticExposureAuditObservation => ({
+      sourceGroup: item.sourceGroup,
+      origin: item.origin,
+      ...(item.valuation === undefined ? {} : { valuation: item.valuation }),
+      value: auditDiagnosticNumber(item.value),
+      complete: item.complete,
+      ...(item.source === undefined ? {} : { source: item.source }),
+    }));
+    const issues: ("missing" | "incomplete" | "non-finite" | "duplicate" | "conflict")[] = [];
+    if (audited.some((item) => item.value.status === "missing")) issues.push("missing");
+    if (audited.some((item) => !item.complete)) issues.push("incomplete");
+    if (audited.some((item) => item.value.status === "non-finite")) issues.push("non-finite");
+    if (timing === "valuation-specific" && audited.length > 1) issues.push("duplicate");
+    if (audited.slice(1).some((item) => !equalAudit(audited[0]!, item))) issues.push("conflict");
+    const validStaticCopies = timing === "origin-static" && issues.length === 0;
+    if (issues.length > 0) return Object.freeze({ measureId: first.measureId, key: first.key, status: "invalid", issues: Object.freeze(issues), value: null, observations: Object.freeze(audited) });
+    const value = audited[0]!.value;
+    if (value.status !== "observed") throw new Error("unreachable invalid exposure state");
+    const sources = audited.flatMap((item) => item.source ? [item.source] : []).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    return Object.freeze({
+      measureId: first.measureId,
+      key: first.key,
+      status: "valid",
+      sourceGroup: first.sourceGroup,
+      origin: first.origin,
+      ...(timing === "valuation-specific" ? { valuation: first.valuation! } : {}),
+      value: value.value,
+      deduplicated: validStaticCopies ? audited.length - 1 : 0,
+      sources: Object.freeze(sources),
+    });
+  }).sort((left, right) => `${left.measureId}\u0000${left.key}` < `${right.measureId}\u0000${right.key}` ? -1 : 1));
+}

package/src/diagnosticExpressions.ts

@@ -0,0 +1,173 @@
+import type {
+  DiagnosticValidationIssue,
+  DiagnosticValidationIssueCode,
+} from "./types.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 isRecord(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;
+}
+
+function issue(
+  issues: DiagnosticValidationIssue[],
+  code: DiagnosticValidationIssueCode,
+  path: string,
+  message: string,
+): void {
+  issues.push({ domain: "definition", code, path, message });
+}
+
+/**
+ * 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[],
+): DiagnosticExpressionWalk {
+  const dependencies = new Set<string>();
+  const stack: WalkFrame[] = [{ value, path, depth: 1, 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 (!isRecord(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") {
+      if (typeof frame.value.role === "string") dependencies.add(frame.value.role);
+      else issue(issues, "invalid-type", `${frame.path}.role`, "Role reference must be a string");
+      continue;
+    }
+    if ((kind === "measure" || kind === "claim") && op === "measure") {
+      if (typeof frame.value.measureId === "string") dependencies.add(frame.value.measureId);
+      else issue(issues, "invalid-type", `${frame.path}.measureId`, "Measure reference must be a string");
+      continue;
+    }
+    if (kind === "claim" && op === "claim-layer") {
+      if (typeof frame.value.measureId === "string") dependencies.add(frame.value.measureId);
+      else issue(issues, "invalid-type", `${frame.path}.measureId`, "Measure reference must be a string");
+      continue;
+    }
+    if (op === "add") {
+      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") {
+      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,150 @@
+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";
+
+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 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[];
+}
+
+interface ExpressionResult {
+  readonly value: number | null;
+  readonly reasons: readonly DiagnosticRuleNotEvaluatedReason[];
+  readonly overflows: readonly DiagnosticExpressionOverflow[];
+}
+
+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));
+}
+
+export function evaluateDiagnosticMeasureExpression(
+  expression: DiagnosticDeepReadonly<DiagnosticMeasureExpression>,
+  measures: Readonly<Record<string, FinalizedDiagnosticMeasure>>,
+  path: string,
+): ExpressionResult {
+  if (expression.op === "measure") {
+    const value = measures[expression.measureId];
+    return value
+      ? { value: value.quantity.value, reasons: value.readiness, overflows: value.expressionOverflows ?? [] }
+      : { value: null, reasons: ["missing"], overflows: [] };
+  }
+  const children = expression.op === "add"
+    ? expression.terms.map((term, index) => evaluateDiagnosticMeasureExpression(term, measures, `${path}.terms[${index}]`))
+    : [
+        evaluateDiagnosticMeasureExpression(expression.left, measures, `${path}.left`),
+        evaluateDiagnosticMeasureExpression(expression.right, measures, `${path}.right`),
+      ];
+  const reasons = uniqueReasons(children.flatMap((child) => child.reasons));
+  const overflows = children.flatMap((child) => child.overflows);
+  if (children.some((child) => child.value === null)) return { value: null, reasons, overflows };
+  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: [] }],
+    };
+  }
+  return { value: Object.is(value, -0) ? 0 : value, reasons, overflows };
+}
+
+export function evaluateDiagnosticRoleExpression(
+  expression: DiagnosticDeepReadonly<DiagnosticRoleExpression>,
+  bindings: Readonly<Record<string, ExpressionResult>>,
+  path: string,
+): ExpressionResult {
+  if (expression.op === "role") return bindings[expression.role] ?? { value: null, reasons: ["missing"], overflows: [] };
+  const children = expression.op === "add"
+    ? expression.terms.map((term, index) => evaluateDiagnosticRoleExpression(term, bindings, `${path}.terms[${index}]`))
+    : [evaluateDiagnosticRoleExpression(expression.left, bindings, `${path}.left`), evaluateDiagnosticRoleExpression(expression.right, bindings, `${path}.right`)];
+  const reasons = uniqueReasons(children.flatMap((child) => child.reasons));
+  const overflows = children.flatMap((child) => child.overflows);
+  if (children.some((child) => child.value === null)) return { value: null, reasons, overflows };
+  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: [] }] };
+  return { value: Object.is(value, -0) ? 0 : value, reasons, overflows };
+}
+
+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: [] } };
+}