@actuarial-ts/core 0.5.0 → 0.6.1

package/src/capping.ts

@@ -39,7 +39,10 @@ function accidentYear(snap: ClaimSnapshot): number {
  * diverge from what the exhibits report; services should resolve it once via
  * this helper and pass baseYear explicitly to both.
  */
-export function latestAccidentYear(claims: ClaimSnapshot[], asOfDate?: string): number {
+export function latestAccidentYear(
+  claims: ClaimSnapshot[],
+  asOfDate?: string,
+): number {
   const asOf = asOfDate ?? "9999-12-31";
   let year = -Infinity;
   for (const snap of claims) {
@@ -56,25 +59,61 @@ export function latestAccidentYear(claims: ClaimSnapshot[], asOfDate?: string):
 }
 
 /** The effective cap for one accident year under the index. */
-export function effectiveCap(options: Required<CapOptions>, year: number): number {
-  return options.cap * Math.pow(1 + options.indexRate, year - options.baseYear);
+export function effectiveCap(
+  options: Required<CapOptions>,
+  year: number,
+): number {
+  if (
+    !isNum(options.cap) ||
+    options.cap <= 0 ||
+    !isNum(options.indexRate) ||
+    options.indexRate <= -1 ||
+    !Number.isSafeInteger(options.baseYear) ||
+    !Number.isSafeInteger(year)
+  ) {
+    throw new ReservingError(
+      "BAD_CAP",
+      "Cap, index rate, base year, and accident year must define a finite positive layer",
+    );
+  }
+  const value =
+    options.cap * Math.pow(1 + options.indexRate, year - options.baseYear);
+  if (!Number.isFinite(value) || value <= 0)
+    throw new ReservingError(
+      "BAD_CAP",
+      "Indexed effective cap must be finite and positive",
+    );
+  return value;
 }
 
-function resolveOptions(claims: ClaimSnapshot[], options: CapOptions): Required<CapOptions> {
+function resolveOptions(
+  claims: ClaimSnapshot[],
+  options: CapOptions,
+): Required<CapOptions> {
   if (!isNum(options.cap) || options.cap <= 0) {
-    throw new ReservingError("BAD_CAP", "The per-occurrence cap must be a positive number");
+    throw new ReservingError(
+      "BAD_CAP",
+      "The per-occurrence cap must be a positive number",
+    );
   }
   const indexRate = options.indexRate ?? 0;
   if (!isNum(indexRate) || indexRate <= -1) {
-    throw new ReservingError("BAD_CAP", "The cap index rate must be a number greater than -100%");
+    throw new ReservingError(
+      "BAD_CAP",
+      "The cap index rate must be a number greater than -100%",
+    );
   }
   let baseYear = options.baseYear ?? null;
   if (baseYear === null) {
     baseYear = -Infinity;
-    for (const snap of claims) baseYear = Math.max(baseYear, accidentYear(snap));
+    for (const snap of claims)
+      baseYear = Math.max(baseYear, accidentYear(snap));
   }
-  if (!isNum(baseYear) || !Number.isFinite(baseYear)) {
-    throw new ReservingError("BAD_CAP", "Could not resolve a base year for the cap index");
+  if (!isNum(baseYear) || !Number.isSafeInteger(baseYear)) {
+    throw new ReservingError(
+      "BAD_CAP",
+      "Could not resolve a base year for the cap index",
+    );
   }
   return { cap: options.cap, indexRate, baseYear };
 }
@@ -86,14 +125,18 @@ function resolveOptions(claims: ClaimSnapshot[], options: CapOptions): Required<
  * negative by construction). Claim counts and statuses are untouched - the
  * cap limits dollars, not claims.
  */
-export function capClaims(claims: ClaimSnapshot[], options: CapOptions): ClaimSnapshot[] {
+export function capClaims(
+  claims: ClaimSnapshot[],
+  options: CapOptions,
+): ClaimSnapshot[] {
   const resolved = resolveOptions(claims, options);
   return claims.map((snap) => {
     const capY = effectiveCap(resolved, accidentYear(snap));
     const incurred = snap.paidToDate + snap.caseReserve;
     const cappedIncurred = Math.min(incurred, capY);
     const cappedPaid = Math.min(snap.paidToDate, capY);
-    if (cappedIncurred === incurred && cappedPaid === snap.paidToDate) return snap;
+    if (cappedIncurred === incurred && cappedPaid === snap.paidToDate)
+      return snap;
     return {
       ...snap,
       paidToDate: cappedPaid,
@@ -161,7 +204,10 @@ const PERCENTILES = [0.5, 0.75, 0.9, 0.95, 0.99];
 // interpolated refinement in stochastic.ts's percentileOfSorted buys nothing.
 function percentile(sorted: number[], p: number): number {
   if (sorted.length === 0) return 0;
-  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1));
+  const idx = Math.min(
+    sorted.length - 1,
+    Math.max(0, Math.ceil(p * sorted.length) - 1),
+  );
   return sorted[idx]!;
 }
 
@@ -183,7 +229,10 @@ export function claimSizeDiagnostics(
   options: ClaimSizeDiagnosticsOptions = {},
 ): ClaimSizeDiagnostics {
   if (claims.length === 0) {
-    throw new ReservingError("NO_CLAIMS", "Cannot analyze claim sizes with no claims");
+    throw new ReservingError(
+      "NO_CLAIMS",
+      "Cannot analyze claim sizes with no claims",
+    );
   }
   const asOf = options.asOfDate ?? "9999-12-31";
   // Latest evaluation per claim on or before the analysis date.
@@ -191,20 +240,48 @@ export function claimSizeDiagnostics(
   for (const snap of claims) {
     if (snap.evaluationDate > asOf) continue;
     const prev = latest.get(snap.claimId);
-    if (!prev || snap.evaluationDate > prev.evaluationDate) latest.set(snap.claimId, snap);
+    if (!prev || snap.evaluationDate > prev.evaluationDate)
+      latest.set(snap.claimId, snap);
   }
 
   const byYear = new Map<number, number[]>();
   for (const snap of latest.values()) {
     const year = accidentYear(snap);
     const incurred = snap.paidToDate + snap.caseReserve;
+    if (
+      !Number.isSafeInteger(year) ||
+      year < 1 ||
+      year > 9999 ||
+      !Number.isFinite(incurred) ||
+      incurred < 0
+    ) {
+      throw new ReservingError(
+        "BAD_LOSSES",
+        "Claim-size diagnostics require valid accident years and finite nonnegative incurred amounts",
+      );
+    }
     let arr = byYear.get(year);
     if (!arr) byYear.set(year, (arr = []));
     arr.push(incurred);
   }
   const years = [...byYear.keys()].sort((a, b) => a - b);
   const indexRate = options.indexRate ?? 0;
+  if (years.length === 0)
+    throw new ReservingError(
+      "NO_CLAIMS",
+      "No claim snapshots on or before the analysis date; cannot analyze claim sizes",
+    );
+  if (!isNum(indexRate) || indexRate <= -1)
+    throw new ReservingError(
+      "BAD_CAP",
+      "The cap index rate must be finite and greater than -100%",
+    );
   const baseYear = options.baseYear ?? years[years.length - 1]!;
+  if (!Number.isSafeInteger(baseYear))
+    throw new ReservingError(
+      "BAD_CAP",
+      "The cap base year must be a safe integer",
+    );
 
   const yearRows: ClaimSizeYearRow[] = years.map((year) => {
     const sorted = [...byYear.get(year)!].sort((a, b) => a - b);
@@ -213,7 +290,10 @@ export function claimSizeDiagnostics(
       claimCount: sorted.length,
       totalIncurred: sorted.reduce((a, v) => a + v, 0),
       maxClaim: sorted[sorted.length - 1] ?? 0,
-      percentiles: PERCENTILES.map((p) => ({ p, value: percentile(sorted, p) })),
+      percentiles: PERCENTILES.map((p) => ({
+        p,
+        value: percentile(sorted, p),
+      })),
     };
   });
 
@@ -223,6 +303,16 @@ export function claimSizeDiagnostics(
   // incurred is deflated to that level before taking percentiles - otherwise
   // a nominal anchor re-indexed forward overshoots the whole distribution
   // and every derived candidate reads near-zero pierce.
+  for (const [label, values] of [
+    ["candidateCaps", options.candidateCaps],
+    ["extraCaps", options.extraCaps],
+  ] as const) {
+    if (values?.some((value) => !isNum(value) || value <= 0))
+      throw new ReservingError(
+        "BAD_CAP",
+        `${label} must contain only finite positive caps`,
+      );
+  }
   let candidateCaps = options.candidateCaps;
   if (!candidateCaps || candidateCaps.length === 0) {
     const pooled = [...latest.values()]
@@ -251,7 +341,7 @@ export function claimSizeDiagnostics(
     let totalExcess = 0;
     let totalIncurred = 0;
     const cells: CapCandidateYearCell[] = years.map((year) => {
-      const capY = cap * Math.pow(1 + resolved.indexRate, year - resolved.baseYear);
+      const capY = effectiveCap({ ...resolved, cap }, year);
       const values = byYear.get(year)!;
       let pierce = 0;
       let excess = 0;
@@ -289,7 +379,8 @@ export function claimSizeDiagnostics(
     candidates,
     baseYear,
     indexRate,
-    nonZeroClaimCount: [...latest.values()].filter((s) => s.paidToDate + s.caseReserve > 0)
-      .length,
+    nonZeroClaimCount: [...latest.values()].filter(
+      (s) => s.paidToDate + s.caseReserve > 0,
+    ).length,
   };
 }

package/src/casualtyDiagnostics.ts

@@ -1,204 +1,94 @@
-import {
-  measureExpressionComponents,
-  type AmountLayerDefinition,
-  type MeasureExpression,
-  type MetricDefinition,
-  type MetricWarningRule,
-} from "./metricDiagnostics.js";
-import { ReservingError } from "./types.js";
+import { CASUALTY_FORMULA_TEMPLATES } from "./diagnosticFormulas.js";
+import { DiagnosticValidationError } from "./types.js";
+import type { DiagnosticMetricInstance, DiagnosticMetricPresentation } from "./diagnosticDefinitions.js";
 
-const m = (measure: string): MeasureExpression => ({ op: "measure", measure });
-const sub = (left: MeasureExpression, right: MeasureExpression): MeasureExpression => ({ op: "subtract", left, right });
+export { CASUALTY_FORMULA_TEMPLATES };
 
-function definedProperties<T extends object>(value: T | undefined): Partial<T> {
-  if (value === undefined) return {};
-  return Object.fromEntries(
-    Object.entries(value).filter(([, item]) => item !== undefined),
-  ) as Partial<T>;
+export interface CasualtyCountBindings { readonly reported: string; readonly open: string; readonly closedNoPay: string; readonly closedWithPay: string }
+export interface CasualtyAmountBinding { readonly id: string; readonly paid: string; readonly incurred: string }
+export type DiagnosticMetricPresentationOverride = Partial<DiagnosticMetricPresentation>;
+export interface CreateCasualtyMetricInstancesInput {
+  readonly counts: CasualtyCountBindings;
+  readonly exposure: string;
+  readonly amountBindings: readonly CasualtyAmountBinding[];
+  readonly presentationOverrides?: Readonly<Record<string, DiagnosticMetricPresentationOverride>>;
 }
 
-export interface CasualtyDiagnosticComponentKeys {
-  reported: string;
-  open: string;
-  closedNoPay: string;
-  closedWithPay: string;
-  exposure: string;
-  paid250: string;
-  incurred250: string;
-  paidPrimary: string;
-  incurredPrimary: string;
-}
-
-export const CASUALTY_DIAGNOSTIC_COMPONENTS: Readonly<CasualtyDiagnosticComponentKeys> = {
-  reported: "reportedCount",
-  open: "openCount",
-  closedNoPay: "closedNoPayCount",
-  closedWithPay: "closedWithPayCount",
-  exposure: "exposure",
-  paid250: "paid250",
-  incurred250: "incurred250",
-  paidPrimary: "paidPrimary",
-  incurredPrimary: "incurredPrimary",
-} as const;
-
-type MetricDisplayOverride = Partial<Pick<
-  MetricDefinition,
-  "displayName" | "description" | "unit" | "numeratorLabel" | "denominatorLabel" | "basis"
->>;
+type Spec = readonly [suffix: string, formulaId: string, numerator: import("./diagnosticExpressions.js").DiagnosticMeasureExpression, denominator: import("./diagnosticExpressions.js").DiagnosticMeasureExpression, presentation: DiagnosticMetricPresentation];
+const m = (measureId: string) => ({ op: "measure" as const, measureId });
+const sub = (left: ReturnType<typeof m>, right: ReturnType<typeof m>) => ({ op: "subtract" as const, left, right });
 
-export interface CasualtyMetricPresetOptions {
-  /** Caller source/output measure keys, including the exposure key. */
-  components?: Partial<CasualtyDiagnosticComponentKeys>;
-  frequencyScale?: number;
-  frequencyUnit?: MetricDefinition["unit"];
-  definitionVersion?: string;
-  basisLabels?: { limited250?: string; primary?: string; counts?: string };
-  /** Per-metric display/basis overrides; formulas remain the documented preset formulas. */
-  displayOverrides?: Readonly<Record<string, MetricDisplayOverride>>;
-}
-
-function metric(
-  id: string,
-  displayName: string,
-  description: string,
-  unit: MetricDefinition["unit"],
-  scale: number,
-  numerator: MeasureExpression,
-  denominator: MeasureExpression,
-  numeratorLabel: string,
-  denominatorLabel: string,
-  basis: string,
-  version: string,
-  override: MetricDisplayOverride | undefined,
-  warningRules?: readonly MetricWarningRule[],
-): MetricDefinition {
-  const definition: MetricDefinition = {
-    id,
-    version,
-    displayName,
-    description,
-    unit,
-    scale,
-    numerator,
-    denominator,
-    numeratorLabel,
-    denominatorLabel,
-    basis,
-    requiredComponents: [...new Set([
-      ...measureExpressionComponents(numerator),
-      ...measureExpressionComponents(denominator),
-    ])],
-    warningRules,
-  };
-  return { ...definition, ...definedProperties(override) };
+function validToken(value: string): boolean {
+  if (value.length === 0 || /^[\t-\r ]|[\t-\r ]$/.test(value) || value.includes("\0")) return false;
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) { const next = value.charCodeAt(++index); if (!(next >= 0xdc00 && next <= 0xdfff)) return false; }
+    else if (code >= 0xdc00 && code <= 0xdfff) return false;
+  }
+  return true;
 }
 
-const paidWarning: readonly MetricWarningRule[] = [{
-  code: "PAID_EXCEEDS_INCURRED",
-  when: "numerator-greater-than-denominator",
-  message: "Paid exceeds incurred on the selected amount basis",
-  tolerance: 1e-9,
-}];
+function encodeBindingId(value: string): string { return encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`); }
 
-/** Builds the optional 22-metric reference preset from caller-selected keys and display metadata. */
-export function createCasualtyQuarterlyMetrics(
-  options: CasualtyMetricPresetOptions = {},
-): readonly MetricDefinition[] {
-  const C = {
-    ...CASUALTY_DIAGNOSTIC_COMPONENTS,
-    ...definedProperties(options.components),
-  };
-  const frequencyScale = options.frequencyScale ?? 1_000_000;
-  if (!Number.isFinite(frequencyScale) || frequencyScale <= 0) {
-    throw new ReservingError("BAD_RATIO", `Casualty frequency scale must be positive; got ${frequencyScale}`);
-  }
-  const version = options.definitionVersion ?? "casualty-quarterly-v1";
-  const frequencyUnit = options.frequencyUnit ?? (frequencyScale === 1_000_000
-    ? "count-per-million"
-    : "count-per-exposure-scale");
-  const limitedBasis = options.basisLabels?.limited250 ?? "$250K pre-capped total";
-  const primaryBasis = options.basisLabels?.primary ?? "$1M capped indemnity plus unlimited expense";
-  const countBasis = options.basisLabels?.counts ?? "count";
-  const override = (id: string) => options.displayOverrides?.[id];
-  const nonClosedNoPay = sub(m(C.reported), m(C.closedNoPay));
-  return [
-    metric("reported-frequency", "Reported claim frequency", "Reported claims per scaled exposure units", frequencyUnit, frequencyScale, m(C.reported), m(C.exposure), "reported claims", "exposure", countBasis, version, override("reported-frequency")),
-    metric("open-frequency", "Open claim frequency", "Open claims per scaled exposure units", frequencyUnit, frequencyScale, m(C.open), m(C.exposure), "open claims", "exposure", countBasis, version, override("open-frequency")),
-    metric("closed-no-pay-frequency", "Closed-no-pay frequency", "Closed-no-pay claims per scaled exposure units", frequencyUnit, frequencyScale, m(C.closedNoPay), m(C.exposure), "closed-no-pay claims", "exposure", countBasis, version, override("closed-no-pay-frequency")),
-    metric("closed-with-pay-frequency", "Closed-with-pay frequency", "Closed-with-pay claims per scaled exposure units", frequencyUnit, frequencyScale, m(C.closedWithPay), m(C.exposure), "closed-with-pay claims", "exposure", countBasis, version, override("closed-with-pay-frequency")),
-    metric("non-closed-no-pay-frequency", "Non-closed-no-pay frequency", "Reported less closed-no-pay claims per scaled exposure units", frequencyUnit, frequencyScale, nonClosedNoPay, m(C.exposure), "reported less closed-no-pay claims", "exposure", countBasis, version, override("non-closed-no-pay-frequency")),
-    metric("closed-no-pay-share", "Closed-no-pay share", "Closed-no-pay claims divided by reported claims", "ratio", 1, m(C.closedNoPay), m(C.reported), "closed-no-pay claims", "reported claims", countBasis, version, override("closed-no-pay-share")),
-    metric("closed-with-pay-share", "Closed-with-pay share", "Closed-with-pay claims divided by reported claims", "ratio", 1, m(C.closedWithPay), m(C.reported), "closed-with-pay claims", "reported claims", countBasis, version, override("closed-with-pay-share")),
-    metric("closed-with-pay-share-of-non-cnp", "Closed-with-pay share of non-CNP claims", "Closed-with-pay claims divided by reported less closed-no-pay claims", "ratio", 1, m(C.closedWithPay), nonClosedNoPay, "closed-with-pay claims", "reported less closed-no-pay claims", countBasis, version, override("closed-with-pay-share-of-non-cnp")),
-    metric("open-share", "Open share", "Open claims divided by reported claims", "ratio", 1, m(C.open), m(C.reported), "open claims", "reported claims", countBasis, version, override("open-share")),
-    metric("open-share-of-non-cnp", "Open share of non-CNP claims", "Open claims divided by reported less closed-no-pay claims", "ratio", 1, m(C.open), nonClosedNoPay, "open claims", "reported less closed-no-pay claims", countBasis, version, override("open-share-of-non-cnp")),
-    metric("paid-to-incurred-250", "Paid-to-incurred ($250K)", "Paid divided by incurred on the pre-capped $250K basis", "ratio", 1, m(C.paid250), m(C.incurred250), "$250K paid", "$250K incurred", limitedBasis, version, override("paid-to-incurred-250"), paidWarning),
-    metric("paid-to-incurred-primary", "Paid-to-incurred (primary)", "Paid divided by incurred on the primary basis", "ratio", 1, m(C.paidPrimary), m(C.incurredPrimary), "primary paid", "primary incurred", primaryBasis, version, override("paid-to-incurred-primary"), paidWarning),
-    metric("incurred-250-per-exposure", "Incurred per exposure ($250K)", "$250K incurred divided by exposure", "currency-per-exposure", 1, m(C.incurred250), m(C.exposure), "$250K incurred", "exposure", limitedBasis, version, override("incurred-250-per-exposure")),
-    metric("incurred-primary-per-exposure", "Incurred per exposure (primary)", "Primary incurred divided by exposure", "currency-per-exposure", 1, m(C.incurredPrimary), m(C.exposure), "primary incurred", "exposure", primaryBasis, version, override("incurred-primary-per-exposure")),
-    metric("incurred-250-per-non-cnp", "Incurred severity ($250K)", "$250K incurred divided by reported less closed-no-pay claims", "currency-per-claim", 1, m(C.incurred250), nonClosedNoPay, "$250K incurred", "reported less closed-no-pay claims", limitedBasis, version, override("incurred-250-per-non-cnp")),
-    metric("incurred-primary-per-non-cnp", "Incurred severity (primary)", "Primary incurred divided by reported less closed-no-pay claims", "currency-per-claim", 1, m(C.incurredPrimary), nonClosedNoPay, "primary incurred", "reported less closed-no-pay claims", primaryBasis, version, override("incurred-primary-per-non-cnp")),
-    metric("paid-250-per-exposure", "Paid per exposure ($250K)", "$250K paid divided by exposure", "currency-per-exposure", 1, m(C.paid250), m(C.exposure), "$250K paid", "exposure", limitedBasis, version, override("paid-250-per-exposure")),
-    metric("paid-primary-per-exposure", "Paid per exposure (primary)", "Primary paid divided by exposure", "currency-per-exposure", 1, m(C.paidPrimary), m(C.exposure), "primary paid", "exposure", primaryBasis, version, override("paid-primary-per-exposure")),
-    metric("paid-250-per-closed-with-pay", "Paid severity ($250K)", "$250K paid divided by closed-with-pay claims", "currency-per-claim", 1, m(C.paid250), m(C.closedWithPay), "$250K paid", "closed-with-pay claims", limitedBasis, version, override("paid-250-per-closed-with-pay")),
-    metric("paid-primary-per-closed-with-pay", "Paid severity (primary)", "Primary paid divided by closed-with-pay claims", "currency-per-claim", 1, m(C.paidPrimary), m(C.closedWithPay), "primary paid", "closed-with-pay claims", primaryBasis, version, override("paid-primary-per-closed-with-pay")),
-    metric("case-250-per-open", "Case reserve per open claim ($250K)", "$250K incurred less paid divided by open claims", "currency-per-claim", 1, sub(m(C.incurred250), m(C.paid250)), m(C.open), "$250K incurred less paid", "open claims", limitedBasis, version, override("case-250-per-open")),
-    metric("case-primary-per-open", "Case reserve per open claim (primary)", "Primary incurred less paid divided by open claims", "currency-per-claim", 1, sub(m(C.incurredPrimary), m(C.paidPrimary)), m(C.open), "primary incurred less paid", "open claims", primaryBasis, version, override("case-primary-per-open")),
-  ];
+function presentation(displayName: string, description: string, displayUnit: string, numeratorLabel: string, denominatorLabel: string): DiagnosticMetricPresentation {
+  return { displayName, description, displayUnit, scale: 1, numeratorLabel, denominatorLabel };
 }
 
-export const CASUALTY_QUARTERLY_METRICS = createCasualtyQuarterlyMetrics();
-
-export interface CasualtyAmountLayerOptions {
-  components?: Partial<Pick<CasualtyDiagnosticComponentKeys, "paid250" | "incurred250" | "paidPrimary" | "incurredPrimary">>;
-  limited250?: {
-    id?: string;
-    displayName?: string;
-    paidSourceMeasure?: string;
-    incurredSourceMeasure?: string;
-  };
-  primary?: {
-    id?: string;
-    displayName?: string;
-    indemnityPaidMeasure?: string;
-    indemnityIncurredMeasure?: string;
-    expensePaidMeasure?: string;
-    expenseIncurredMeasure?: string;
-    indemnityLimit?: number;
-  };
+function overridePresentation(id: string, base: DiagnosticMetricPresentation, overrides: CreateCasualtyMetricInstancesInput["presentationOverrides"]): DiagnosticMetricPresentation {
+  const override = overrides?.[id];
+  if (!override) return base;
+  for (const [key, value] of Object.entries(override)) if (value === undefined) throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-type", path: `$.presentationOverrides[${JSON.stringify(id)}].${key}`, message: "Presentation override cannot contain undefined" }]);
+  const result = { ...base, ...override };
+  if (!Number.isFinite(result.scale) || result.scale <= 0) throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-number", path: `$.presentationOverrides[${JSON.stringify(id)}].scale`, message: "Presentation scale must be finite and positive" }]);
+  return result;
 }
 
-export function createCasualtyAmountLayers(
-  options: CasualtyAmountLayerOptions = {},
-): readonly AmountLayerDefinition[] {
-  const C = {
-    ...CASUALTY_DIAGNOSTIC_COMPONENTS,
-    ...definedProperties(options.components),
-  };
-  const limit = options.primary?.indemnityLimit ?? 1_000_000;
-  if (!Number.isFinite(limit) || limit <= 0) {
-    throw new ReservingError("BAD_CAP", `Primary indemnity limit must be positive; got ${limit}`);
+export function createCasualtyMetricInstances(input: CreateCasualtyMetricInstancesInput): readonly DiagnosticMetricInstance[] {
+  for (const [key, value] of Object.entries({ ...input.counts, exposure: input.exposure })) if (!validToken(value)) throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-string", path: `$.${key}`, message: "Measure binding must be a token" }]);
+  const ids = new Set<string>();
+  for (const [index, binding] of input.amountBindings.entries()) {
+    if (!validToken(binding.id) || !validToken(binding.paid) || !validToken(binding.incurred)) throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-string", path: `$.amountBindings[${index}]`, message: "Amount binding fields must be tokens" }]);
+    if (ids.has(binding.id)) throw new DiagnosticValidationError([{ domain: "configuration", code: "duplicate-id", path: `$.amountBindings[${index}].id`, message: `Duplicate amount binding ${binding.id}` }]);
+    ids.add(binding.id);
   }
-  return [
-  {
-    id: options.limited250?.id ?? "250k-pre-capped-total",
-    displayName: options.limited250?.displayName ?? "$250K pre-capped total",
-    paidMeasure: C.paid250,
-    incurredMeasure: C.incurred250,
-    paid: { op: "measure", measure: options.limited250?.paidSourceMeasure ?? "preCapped250Paid" },
-    incurred: { op: "measure", measure: options.limited250?.incurredSourceMeasure ?? "preCapped250Incurred" },
-    basis: "pre-capped-additive",
-  },
-  {
-    id: options.primary?.id ?? "primary-1m-indemnity-plus-expense",
-    displayName: options.primary?.displayName ?? "Primary: $1M capped indemnity plus unlimited expense",
-    paidMeasure: C.paidPrimary,
-    incurredMeasure: C.incurredPrimary,
-    paid: { op: "add", terms: [{ op: "claim-cap", measure: options.primary?.indemnityPaidMeasure ?? "indemnityPaid", limit }, { op: "measure", measure: options.primary?.expensePaidMeasure ?? "expensePaid" }] },
-    incurred: { op: "add", terms: [{ op: "claim-cap", measure: options.primary?.indemnityIncurredMeasure ?? "indemnityIncurred", limit }, { op: "measure", measure: options.primary?.expenseIncurredMeasure ?? "expenseIncurred" }] },
-    basis: "claim-level-cap",
-  },
+  const nonClosedNoPay = sub(m(input.counts.reported), m(input.counts.closedNoPay));
+  const countSpecs: Spec[] = [
+    ["reported-frequency", "frequency", m(input.counts.reported), m(input.exposure), presentation("Reported frequency", "Reported count divided by exposure", "count per exposure", "reported", "exposure")],
+    ["open-frequency", "frequency", m(input.counts.open), m(input.exposure), presentation("Open frequency", "Open count divided by exposure", "count per exposure", "open", "exposure")],
+    ["closed-no-pay-frequency", "frequency", m(input.counts.closedNoPay), m(input.exposure), presentation("Closed-no-pay frequency", "Closed-no-pay count divided by exposure", "count per exposure", "closed-no-pay", "exposure")],
+    ["closed-with-pay-frequency", "frequency", m(input.counts.closedWithPay), m(input.exposure), presentation("Closed-with-pay frequency", "Closed-with-pay count divided by exposure", "count per exposure", "closed-with-pay", "exposure")],
+    ["non-closed-no-pay-frequency", "frequency", nonClosedNoPay, m(input.exposure), presentation("Non-closed-no-pay frequency", "Reported less closed-no-pay count divided by exposure", "count per exposure", "reported less closed-no-pay", "exposure")],
+    ["closed-no-pay-share", "share", m(input.counts.closedNoPay), m(input.counts.reported), presentation("Closed-no-pay share", "Closed-no-pay count divided by reported count", "ratio", "closed-no-pay", "reported")],
+    ["closed-with-pay-share", "share", m(input.counts.closedWithPay), m(input.counts.reported), presentation("Closed-with-pay share", "Closed-with-pay count divided by reported count", "ratio", "closed-with-pay", "reported")],
+    ["closed-with-pay-share-of-non-closed-no-pay", "share", m(input.counts.closedWithPay), nonClosedNoPay, presentation("Closed-with-pay share of non-closed-no-pay", "Closed-with-pay count divided by reported less closed-no-pay count", "ratio", "closed-with-pay", "reported less closed-no-pay")],
+    ["open-share", "share", m(input.counts.open), m(input.counts.reported), presentation("Open share", "Open count divided by reported count", "ratio", "open", "reported")],
+    ["open-share-of-non-closed-no-pay", "share", m(input.counts.open), nonClosedNoPay, presentation("Open share of non-closed-no-pay", "Open count divided by reported less closed-no-pay count", "ratio", "open", "reported less closed-no-pay")],
   ];
+  const specs: { id: string; formulaId: string; bindings: Record<string, import("./diagnosticExpressions.js").DiagnosticMeasureExpression>; presentation: DiagnosticMetricPresentation; rules: DiagnosticMetricInstance["rules"] }[] = [];
+  for (const [suffix, formulaId, numerator, denominator, display] of countSpecs) {
+    const id = `casualty/count/${suffix}`;
+    const bindings: Record<string, import("./diagnosticExpressions.js").DiagnosticMeasureExpression> = formulaId === "frequency"
+      ? { claims: numerator, exposure: denominator }
+      : { part: numerator, whole: denominator };
+    specs.push({ id, formulaId, bindings, presentation: display, rules: [] });
+  }
+  for (const binding of input.amountBindings) {
+    const prefix = `casualty/amount/${encodeBindingId(binding.id)}`;
+    const amountSpecs = [
+      ["paid-to-incurred", "paid-to-incurred", { paid: m(binding.paid), incurred: m(binding.incurred) }, presentation("Paid to incurred", "Paid divided by incurred on the bound amount basis", "ratio", "paid", "incurred")],
+      ["incurred-per-exposure", "amount-per-exposure", { amount: m(binding.incurred), exposure: m(input.exposure) }, presentation("Incurred per exposure", "Incurred divided by exposure", "amount per exposure", "incurred", "exposure")],
+      ["incurred-per-non-closed-no-pay-claim", "amount-per-claim", { amount: m(binding.incurred), claims: nonClosedNoPay }, presentation("Incurred per non-closed-no-pay claim", "Incurred divided by reported less closed-no-pay count", "amount per claim", "incurred", "reported less closed-no-pay")],
+      ["paid-per-exposure", "amount-per-exposure", { amount: m(binding.paid), exposure: m(input.exposure) }, presentation("Paid per exposure", "Paid divided by exposure", "amount per exposure", "paid", "exposure")],
+      ["paid-per-closed-with-pay-claim", "amount-per-claim", { amount: m(binding.paid), claims: m(input.counts.closedWithPay) }, presentation("Paid per closed-with-pay claim", "Paid divided by closed-with-pay count", "amount per claim", "paid", "closed-with-pay")],
+      ["case-per-open-claim", "case-per-open", { incurred: m(binding.incurred), paid: m(binding.paid), open: m(input.counts.open) }, presentation("Case reserve per open claim", "Incurred less paid divided by open count", "amount per claim", "incurred less paid", "open")],
+    ] as const;
+    for (const [suffix, formulaId, bindings, display] of amountSpecs) {
+      const id = `${prefix}/${suffix}`;
+      const rules = suffix === "paid-to-incurred" ? [{ id: `${id}/rule/paid-exceeds-incurred`, code: "paid-exceeds-incurred", message: "Paid exceeds incurred on the bound amount basis", severity: "warning" as const, when: { left: { source: "calculation" as const, field: "numerator" as const }, operator: "gt" as const, right: { source: "calculation" as const, field: "denominator" as const }, tolerance: { absolute: 0, relative: 0 } } }] : suffix === "case-per-open-claim" ? [{ id: `${id}/rule/negative-case`, code: "negative-case", message: "Incurred less paid is negative on the bound amount basis", severity: "warning" as const, when: { left: { source: "calculation" as const, field: "numerator" as const }, operator: "lt" as const, right: { source: "constant" as const, value: 0 }, tolerance: { absolute: 0, relative: 0 } } }] : [];
+      specs.push({ id, formulaId, bindings: { ...bindings }, presentation: display, rules });
+    }
+  }
+  const validIds = new Set(specs.map((spec) => spec.id));
+  for (const key of Object.keys(input.presentationOverrides ?? {})) if (!validIds.has(key)) throw new DiagnosticValidationError([{ domain: "configuration", code: "unknown-reference", path: `$.presentationOverrides[${JSON.stringify(key)}]`, message: "Presentation override names an unknown generated instance" }]);
+  return Object.freeze(specs.map((spec) => Object.freeze({ id: spec.id, version: "1.0.0", formulaId: spec.formulaId, bindings: spec.bindings, presentation: overridePresentation(spec.id, spec.presentation, input.presentationOverrides), rules: spec.rules })));
 }
-
-export const CASUALTY_AMOUNT_LAYERS = createCasualtyAmountLayers();

package/src/diagnosticAggregation.ts

@@ -0,0 +1,128 @@
+import type {
+  DiagnosticMeasureStats,
+  DiagnosticMissingPolicy,
+  DiagnosticSourceLocation,
+} from "./diagnosticDefinitions.js";
+import type { DiagnosticMetricFinding } from "./diagnosticFormulas.js";
+import { compareDiagnosticContributions } from "./diagnosticOrdering.js";
+
+export interface DiagnosticStructuralBlocker {
+  readonly code: string;
+  readonly message: string;
+  readonly sourceIds: readonly string[];
+  readonly sources: readonly DiagnosticSourceLocation[];
+  /** Exact preparation finding whose dependency this blocker represents. */
+  readonly finding?: DiagnosticMetricFinding;
+}
+
+export interface DiagnosticMeasureContributionBase {
+  readonly sourceId: string;
+  readonly sources: readonly DiagnosticSourceLocation[];
+  readonly deduplicated: number;
+}
+
+export type DiagnosticMeasureContribution =
+  | (DiagnosticMeasureContributionBase & {
+      readonly status: "observed";
+      readonly value: number;
+    })
+  | (DiagnosticMeasureContributionBase & {
+      readonly status: "imputed-zero";
+      readonly value: 0;
+    })
+  | (DiagnosticMeasureContributionBase & {
+      readonly status: "missing";
+      readonly value: null;
+    })
+  | (DiagnosticMeasureContributionBase & {
+      readonly status: "non-finite";
+      readonly value: null;
+      readonly nonFiniteKind: "nan" | "positive-infinity" | "negative-infinity";
+    });
+
+export function auditedDiagnosticContribution(
+  sourceId: string,
+  value: number | null | undefined,
+  missing: DiagnosticMissingPolicy,
+  sources: readonly DiagnosticSourceLocation[] = [],
+  deduplicated = 0,
+): DiagnosticMeasureContribution {
+  const base = {
+    sourceId,
+    sources: Object.freeze([...sources]),
+    deduplicated,
+  } as const;
+  if (value === null || value === undefined)
+    return missing === "zero"
+      ? Object.freeze({
+          ...base,
+          status: "imputed-zero" as const,
+          value: 0 as const,
+        })
+      : Object.freeze({ ...base, status: "missing" as const, value: null });
+  if (!Number.isFinite(value))
+    return Object.freeze({
+      ...base,
+      status: "non-finite" as const,
+      value: null,
+      nonFiniteKind: Number.isNaN(value)
+        ? ("nan" as const)
+        : value > 0
+          ? ("positive-infinity" as const)
+          : ("negative-infinity" as const),
+    });
+  return Object.freeze({
+    ...base,
+    status: "observed" as const,
+    value: Object.is(value, -0) ? 0 : value,
+  });
+}
+
+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;
+}
+
+export function finalizeDiagnosticContributions(
+  contributions: readonly DiagnosticMeasureContribution[],
+  missingPolicy: DiagnosticMissingPolicy,
+  blockers: readonly DiagnosticStructuralBlocker[] = [],
+): DiagnosticMeasureStats {
+  const ordered = [...contributions].sort(compareDiagnosticContributions);
+  const observed = ordered.filter((item) => item.status === "observed");
+  const imputed = ordered.filter((item) => item.status === "imputed-zero");
+  const missing =
+    ordered.filter((item) => item.status === "missing").length + imputed.length;
+  const nonFinite = ordered.filter(
+    (item) => item.status === "non-finite",
+  ).length;
+  const finiteSum = neumaier([
+    ...observed.map((item) => item.value),
+    ...imputed.map(() => 0),
+  ]);
+  const blocked = blockers.length > 0;
+  const sum = nonFinite > 0 || blocked || finiteSum === null ? null : finiteSum;
+  const value =
+    sum === null || (missingPolicy === "unknown" && missing > 0) ? null : sum;
+  return Object.freeze({
+    value,
+    sum,
+    observed: observed.length,
+    missing,
+    nonFinite,
+    imputedZero: imputed.length,
+    deduplicated: ordered.reduce((total, item) => total + item.deduplicated, 0),
+    structural: blockers.length,
+  });
+}