@actuarial-ts/core 0.5.0 → 0.6.0

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,79 @@
+import type { DiagnosticMeasureStats, DiagnosticMissingPolicy, DiagnosticSourceLocation } from "./diagnosticDefinitions.js";
+
+export interface DiagnosticStructuralBlocker {
+  readonly code: string;
+  readonly message: string;
+  readonly sourceIds: readonly string[];
+  readonly sources: readonly DiagnosticSourceLocation[];
+}
+
+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((left, right) => left.sourceId < right.sourceId ? -1 : left.sourceId > right.sourceId ? 1 : 0);
+  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,
+  });
+}