@actuarial-ts/core 0.4.0 → 0.6.0

package/src/diagnosticRunner.ts

@@ -0,0 +1,110 @@
+import type { DiagnosticDeepReadonly, DiagnosticMeasureDefinition, DiagnosticMetricPresentation, DiagnosticsFilter, JsonValue } from "./diagnosticDefinitions.js";
+import { getCompiledDiagnosticDefinitionInternals } from "./diagnosticDefinitions.js";
+import { applyDiagnosticPresentation, diagnosticRawRatio, evaluateDiagnosticMeasureExpression, evaluateDiagnosticRoleExpression, type DiagnosticMetricFinding, type DiagnosticQuantity, type FinalizedDiagnosticMeasure } from "./diagnosticFormulas.js";
+import { classifyDiagnosticComparison, diagnosticPredicateMatches, type DiagnosticRuleEvaluation } from "./diagnosticRules.js";
+import { assertPreparedDiagnosticData, type PreparedDiagnosticData } from "./diagnosticPreparation.js";
+import type { DiagnosticMeasureStats } from "./diagnosticDefinitions.js";
+import { DiagnosticValidationError } from "./types.js";
+
+export interface RunMetricDiagnosticsInput { readonly prepared: PreparedDiagnosticData; readonly groupMap?: Readonly<Record<string, string>>; readonly groupDimensions?: Readonly<Record<string, JsonValue>> }
+export interface DiagnosticMetricEvaluation {
+  readonly instanceId: string; readonly instanceVersion: string; readonly formulaId: string; readonly formulaVersion: string;
+  readonly semanticReferences: { readonly amountBasisIds: readonly string[]; readonly countPopulationIds: readonly string[]; readonly exposureBasisIds: readonly string[] };
+  readonly formulaFingerprint: string; readonly calculationFingerprint: string; readonly definitionIntegrity: string;
+  readonly calculation: { readonly numerator: DiagnosticQuantity; readonly denominator: DiagnosticQuantity; readonly value: number | null };
+  readonly presentation: DiagnosticMetricPresentation & { readonly value: number | null };
+  readonly components: Readonly<Record<string, DiagnosticMeasureStats>>;
+  readonly rules: readonly DiagnosticRuleEvaluation[];
+  readonly findings: readonly DiagnosticMetricFinding[];
+}
+export interface DiagnosticEmergencePoint { readonly group: string; readonly sourceGroups: readonly string[]; readonly dimensions?: JsonValue; readonly origin: string; readonly valuation: string; readonly developmentAge: number; readonly ageUnit: string; readonly components: Readonly<Record<string, DiagnosticMeasureStats>>; readonly metrics: Readonly<Record<string, DiagnosticMetricEvaluation>>; readonly findings: readonly DiagnosticMetricFinding[] }
+export interface DiagnosticMetricTriangleCell { readonly origin: string; readonly valuation: string; readonly developmentAge: number; readonly ageUnit: string; readonly evaluation: DiagnosticMetricEvaluation }
+export interface DiagnosticMetricTriangle { readonly group: string; readonly instanceId: string; readonly origins: readonly string[]; readonly developmentAges: readonly number[]; readonly ageUnit: string; readonly calculationValues: readonly (readonly (number | null)[])[]; readonly presentationValues: readonly (readonly (number | null)[])[]; readonly cells: readonly (readonly (DiagnosticMetricTriangleCell | null)[])[] }
+export interface MetricDiagnosticsResult { readonly definitionIntegrity: string; readonly preparationFingerprint: string; readonly ageUnit: string; readonly emergence: readonly DiagnosticEmergencePoint[]; readonly triangles: readonly DiagnosticMetricTriangle[]; readonly latestDiagonal: readonly DiagnosticEmergencePoint[]; readonly findings: readonly DiagnosticMetricFinding[] }
+export interface CommonMaturityResult { readonly developmentAge: number | null; readonly ageUnit: string; readonly points: readonly DiagnosticDeepReadonly<DiagnosticEmergencePoint>[] }
+export type NormalizedDiagnosticResultIdentity = DiagnosticDeepReadonly<MetricDiagnosticsResult>;
+
+function codeUnit(a: string, b: string): number { return a < b ? -1 : a > b ? 1 : 0 }
+function deepFreeze<T>(value: T, seen = new WeakSet<object>()): DiagnosticDeepReadonly<T> { if (value === null || typeof value !== "object" || seen.has(value)) return value as DiagnosticDeepReadonly<T>; seen.add(value); for (const child of Object.values(value as Record<string, unknown>)) deepFreeze(child, seen); return Object.freeze(value) as DiagnosticDeepReadonly<T> }
+function quantity(measure: DiagnosticMeasureDefinition, value: number | null): DiagnosticQuantity { return { kind: measure.kind, unit: measure.unit, ...(measure.basisId ? { basisId: measure.basisId } : {}), ...(measure.countPopulationId ? { countPopulationId: measure.countPopulationId } : {}), ...(measure.exposureBasisId ? { exposureBasisId: measure.exposureBasisId } : {}), value } }
+
+export function validateDiagnosticGroupingConfiguration(input: RunMetricDiagnosticsInput): void {
+  assertPreparedDiagnosticData(input.prepared);
+  const sourceGroups = new Set(input.prepared.cells.map((cell) => cell.sourceGroup));
+  for (const [source, target] of Object.entries(input.groupMap ?? {})) {
+    if (!sourceGroups.has(source)) throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-configuration", path: `$.groupMap[${JSON.stringify(source)}]`, message: "Group map contains an unused source group" }]);
+    if (target.length === 0 || /^[\t-\r ]|[\t-\r ]$/.test(target)) throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-string", path: `$.groupMap[${JSON.stringify(source)}]`, message: "Output group must be a nonempty token" }]);
+  }
+  const outputGroups = new Set([...sourceGroups].map((source) => input.groupMap?.[source] ?? source));
+  for (const group of Object.keys(input.groupDimensions ?? {})) if (!outputGroups.has(group)) throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-configuration", path: `$.groupDimensions[${JSON.stringify(group)}]`, message: "Dimensions contain an unused output group" }]);
+  for (const group of input.prepared.filter?.outputGroups ?? []) if (!outputGroups.has(group)) throw new DiagnosticValidationError([{ domain: "configuration", code: "unknown-reference", path: "$.prepared.filter.outputGroups", message: `Unknown output group ${group}` }]);
+}
+
+function mergeStats(stats: readonly DiagnosticMeasureStats[]): DiagnosticMeasureStats {
+  if (stats.length === 0) return { value: null, sum: 0, observed: 0, missing: 0, nonFinite: 0, imputedZero: 0, deduplicated: 0, structural: 0 };
+  const count = (key: "observed" | "missing" | "nonFinite" | "imputedZero" | "deduplicated" | "structural") => stats.reduce((sum, item) => sum + item[key], 0);
+  const structural = count("structural"); const nonFinite = count("nonFinite");
+  const sums = stats.map((item) => item.sum);
+  const sum = structural > 0 || nonFinite > 0 || sums.some((value) => value === null) ? null : sums.reduce<number>((total, value) => total + value!, 0);
+  return { value: sum === null || stats.some((item) => item.value === null) ? null : sum, sum, observed: count("observed"), missing: count("missing"), nonFinite, imputedZero: count("imputedZero"), deduplicated: count("deduplicated"), structural };
+}
+
+function inferExpressionMeasure(expression: import("./diagnosticExpressions.js").DiagnosticMeasureExpression, measures: ReadonlyMap<string, DiagnosticMeasureDefinition>): DiagnosticMeasureDefinition {
+  const id = expression.op === "measure" ? expression.measureId : expression.op === "add" ? inferExpressionMeasure(expression.terms[0]!, measures).id : inferExpressionMeasure(expression.left, measures).id;
+  return measures.get(id)!;
+}
+
+function evaluatePoint(prepared: PreparedDiagnosticData, components: Readonly<Record<string, DiagnosticMeasureStats>>, instanceId: string): DiagnosticMetricEvaluation {
+  const definition = prepared.definition;
+  const internals = getCompiledDiagnosticDefinitionInternals(definition);
+  const instance = definition.definition.instances.find((item) => item.id === instanceId)!;
+  const formula = definition.definition.formulas.find((item) => item.id === instance.formulaId)!;
+  const measureStates: Record<string, FinalizedDiagnosticMeasure> = Object.create(null);
+  for (const [measureId, stats] of Object.entries(components)) {
+    const measure = internals.measuresById.get(measureId)!;
+    const readiness = [...(stats.missing > 0 ? [stats.imputedZero > 0 ? "imputed" as const : "missing" as const] : []), ...(stats.nonFinite > 0 ? ["non-finite" as const] : []), ...(stats.structural > 0 ? ["structural-ambiguity" as const] : []), ...(stats.sum === null && stats.nonFinite === 0 && stats.structural === 0 ? ["aggregation-overflow" as const] : [])];
+    measureStates[measureId] = { quantity: quantity(measure, stats.value), stats, readiness };
+  }
+  const bindings = Object.fromEntries(Object.entries(instance.bindings).map(([role, expression]) => [role, evaluateDiagnosticMeasureExpression(expression, measureStates, `$.instances[${JSON.stringify(instance.id)}].bindings[${JSON.stringify(role)}]`)]));
+  const numeratorResult = evaluateDiagnosticRoleExpression(formula.numerator, bindings, `$.formulas[${JSON.stringify(formula.id)}].numerator`);
+  const denominatorResult = evaluateDiagnosticRoleExpression(formula.denominator, bindings, `$.formulas[${JSON.stringify(formula.id)}].denominator`);
+  const raw = diagnosticRawRatio(numeratorResult.value, denominatorResult.value);
+  const presented = applyDiagnosticPresentation(raw, instance.presentation);
+  const numeratorMeasure = inferExpressionMeasure(instance.bindings[(formula.numerator.op === "role" ? formula.numerator.role : formula.numerator.op === "subtract" && formula.numerator.left.op === "role" ? formula.numerator.left.role : Object.keys(instance.bindings)[0])!]!, internals.measuresById);
+  const denominatorMeasure = inferExpressionMeasure(instance.bindings[(formula.denominator.op === "role" ? formula.denominator.role : Object.keys(instance.bindings)[0])!]!, internals.measuresById);
+  const ruleEvaluations: DiagnosticRuleEvaluation[] = [];
+  const findings: DiagnosticMetricFinding[] = presented.finding ? [{ ...presented.finding, instanceId: instance.id }] : [];
+  const operand = (item: typeof instance.rules[number]["when"]["left"]): number | null => item.source === "constant" ? item.value : item.source === "calculation" ? (item.field === "numerator" ? numeratorResult.value : denominatorResult.value) : evaluateDiagnosticMeasureExpression(item.expression, measureStates, "$.rule").value;
+  for (const rule of instance.rules) {
+    const left = operand(rule.when.left); const right = operand(rule.when.right); const classified = classifyDiagnosticComparison(left, right, rule.when.tolerance);
+    if (classified.status === "not-evaluated") ruleEvaluations.push({ ruleId: rule.id, status: "not-evaluated", severity: rule.severity, left: Number.isFinite(left) ? left : null, right: Number.isFinite(right) ? right : null, relation: null, notEvaluatedReasons: [classified.reason], expressionOverflows: [], code: "diagnostic-rule-not-evaluated", message: "Diagnostic metric rule was not evaluated" });
+    else {
+      const triggered = diagnosticPredicateMatches(rule.when.operator, classified.relation);
+      ruleEvaluations.push({ ruleId: rule.id, status: triggered ? "triggered" : "pass", severity: rule.severity, left, right, relation: classified.relation, notEvaluatedReasons: [], expressionOverflows: [], code: triggered ? rule.code : null, message: triggered ? rule.message : null });
+      if (triggered) findings.push({ code: rule.code, message: rule.message, severity: rule.severity, category: "rule", ruleId: rule.id, instanceId: instance.id, sources: [] });
+    }
+  }
+  const deps = internals.evaluationDependenciesByInstanceId.get(instance.id) ?? [];
+  const refs = { amountBasisIds: [...new Set(deps.flatMap((id) => internals.measuresById.get(id)?.basisId ? [internals.measuresById.get(id)!.basisId!] : []))].sort(codeUnit), countPopulationIds: [...new Set(deps.flatMap((id) => internals.measuresById.get(id)?.countPopulationId ? [internals.measuresById.get(id)!.countPopulationId!] : []))].sort(codeUnit), exposureBasisIds: [...new Set(deps.flatMap((id) => internals.measuresById.get(id)?.exposureBasisId ? [internals.measuresById.get(id)!.exposureBasisId!] : []))].sort(codeUnit) };
+  return deepFreeze({ instanceId: instance.id, instanceVersion: instance.version, formulaId: formula.id, formulaVersion: formula.version, semanticReferences: refs, formulaFingerprint: definition.formulaFingerprints[formula.id]!, calculationFingerprint: definition.calculationFingerprints[instance.id]!, definitionIntegrity: definition.definitionIntegrity, calculation: { numerator: quantity(numeratorMeasure, numeratorResult.value), denominator: quantity(denominatorMeasure, denominatorResult.value), value: raw }, presentation: { ...instance.presentation, value: presented.value }, components: Object.fromEntries(deps.map((id) => [id, components[id]!])), rules: ruleEvaluations, findings });
+}
+
+export function runMetricDiagnostics(input: RunMetricDiagnosticsInput): DiagnosticDeepReadonly<MetricDiagnosticsResult> {
+  validateDiagnosticGroupingConfiguration(input);
+  const prepared = input.prepared;
+  const buckets = new Map<string, typeof prepared.cells>();
+  for (const cell of prepared.cells) { const group = input.groupMap?.[cell.sourceGroup] ?? cell.sourceGroup; if (prepared.filter?.outputGroups !== undefined && !prepared.filter.outputGroups.includes(group)) continue; const key = `${group}\u0000${cell.origin}\u0000${cell.valuation}`; buckets.set(key, [...(buckets.get(key) ?? []), cell]); }
+  const selectedInstances = prepared.definition.definition.instances.filter((instance) => prepared.filter?.instanceIds === undefined || prepared.filter.instanceIds.includes(instance.id));
+  const emergence: DiagnosticEmergencePoint[] = [];
+  for (const [key, cells] of buckets) { const [group, origin, valuation] = key.split("\u0000") as [string,string,string]; const components = Object.fromEntries(prepared.definition.definition.measures.map((measure) => [measure.id, mergeStats(cells.map((cell) => cell.components[measure.id]!))])); const metrics = Object.fromEntries(selectedInstances.map((instance) => [instance.id, evaluatePoint(prepared, components, instance.id)])); emergence.push({ group, sourceGroups: [...new Set(cells.map((cell) => cell.sourceGroup))].sort(codeUnit), ...(input.groupDimensions && Object.prototype.hasOwnProperty.call(input.groupDimensions, group) ? { dimensions: input.groupDimensions[group] } : {}), origin, valuation, developmentAge: cells[0]!.developmentAge, ageUnit: cells[0]!.ageUnit, components, metrics, findings: Object.values(metrics).flatMap((metric) => metric.findings) }); }
+  emergence.sort((a,b) => codeUnit(a.group,b.group)||codeUnit(a.origin,b.origin)||a.developmentAge-b.developmentAge||codeUnit(a.valuation,b.valuation));
+  const groups = [...new Set(emergence.map((point) => point.group))].sort(codeUnit);
+  const triangles: DiagnosticMetricTriangle[] = [];
+  for (const group of groups) for (const instance of selectedInstances) { const points = emergence.filter((point) => point.group===group); const origins=[...new Set(points.map((point)=>point.origin))].sort(codeUnit); const ages=[...new Set(points.map((point)=>point.developmentAge))].sort((a,b)=>a-b); const cells=origins.map((origin)=>ages.map((age)=>{const point=points.find((item)=>item.origin===origin&&item.developmentAge===age); return point?{origin:point.origin,valuation:point.valuation,developmentAge:point.developmentAge,ageUnit:point.ageUnit,evaluation:point.metrics[instance.id]!}:null;})); triangles.push({group,instanceId:instance.id,origins,developmentAges:ages,ageUnit:prepared.definition.definition.periodAxis.ageUnit,calculationValues:cells.map((row)=>row.map((cell)=>cell?.evaluation.calculation.value??null)),presentationValues:cells.map((row)=>row.map((cell)=>cell?.evaluation.presentation.value??null)),cells}); }
+  const latestDiagonal = groups.flatMap((group)=>{const groupPoints=emergence.filter((point)=>point.group===group); return [...new Set(groupPoints.map((point)=>point.origin))].flatMap((origin)=>{const points=groupPoints.filter((point)=>point.origin===origin); return points.length?[points.reduce((latest,point)=>point.developmentAge>latest.developmentAge?point:latest)]:[];});});
+  return deepFreeze({ definitionIntegrity: prepared.definition.definitionIntegrity, preparationFingerprint: prepared.preparationFingerprint, ageUnit: prepared.definition.definition.periodAxis.ageUnit, emergence, triangles, latestDiagonal, findings: [...prepared.findings, ...emergence.flatMap((point)=>point.findings)] });
+}
+
+export function sameMaturity(result: DiagnosticDeepReadonly<MetricDiagnosticsResult>, developmentAge: number, outputGroups?: readonly string[]): readonly DiagnosticDeepReadonly<DiagnosticEmergencePoint>[] { if (!Number.isSafeInteger(developmentAge) || developmentAge < 0) throw new DiagnosticValidationError([{domain:"view",code:"invalid-number",path:"$.developmentAge",message:"Development age must be a nonnegative safe integer"}]); const groups=outputGroups===undefined?null:new Set(outputGroups); return result.emergence.filter((point)=>point.developmentAge===developmentAge&&(groups===null||groups.has(point.group))); }
+export function commonMaturity(result: DiagnosticDeepReadonly<MetricDiagnosticsResult>, outputGroups: readonly string[]): DiagnosticDeepReadonly<CommonMaturityResult> { const groups=[...new Set(outputGroups)].sort(codeUnit); const common=[...new Set(result.emergence.filter((p)=>p.group===groups[0]).map((p)=>p.developmentAge))].filter((age)=>groups.every((group)=>result.emergence.some((point)=>point.group===group&&point.developmentAge===age))).sort((a,b)=>b-a); const developmentAge=common[0]??null; return deepFreeze({developmentAge,ageUnit:result.ageUnit,points:developmentAge===null?[]:sameMaturity(result,developmentAge,groups)}); }
+export function getMetricDiagnosticsResultIdentity(result: DiagnosticDeepReadonly<MetricDiagnosticsResult>): NormalizedDiagnosticResultIdentity { return deepFreeze(result); }

package/src/index.ts

@@ -1,6 +1,162 @@
 export * from "./types.js";
 export * from "./util.js";
 export * from "./canonical.js";
+export * from "./version.js";
+export {
+  MAX_DIAGNOSTIC_DEFINITION_EXPRESSION_NODES,
+  MAX_DIAGNOSTIC_EXPRESSION_DEPTH,
+  MAX_DIAGNOSTIC_EXPRESSION_NODES,
+} from "./diagnosticExpressions.js";
+export type {
+  DiagnosticClaimExpression,
+  DiagnosticMeasureExpression,
+  DiagnosticRoleExpression,
+} from "./diagnosticExpressions.js";
+export {
+  assertCompiledDiagnosticDefinition,
+  compileDiagnosticDefinition,
+} from "./diagnosticDefinitions.js";
+export type {
+  AmountBasisComponent,
+  AmountBasisDefinition,
+  AmountLimitation,
+  AmountPerspective,
+  CompiledDiagnosticDefinition,
+  DiagnosticAggregation,
+  DiagnosticComparisonPredicate,
+  DiagnosticComparisonRule,
+  DiagnosticControlTotalProjection,
+  DiagnosticCountPopulationDefinition,
+  DiagnosticDeepReadonly,
+  DiagnosticDefinition,
+  DiagnosticDerivedMeasureDefinition,
+  DiagnosticDevelopmentSemantics,
+  DiagnosticExposureBasisDefinition,
+  DiagnosticExposureTiming,
+  DiagnosticFormulaRole,
+  DiagnosticFormulaTemplate,
+  DiagnosticMeasureDefinition,
+  DiagnosticMeasureKind,
+  DiagnosticMeasureSource,
+  DiagnosticMeasureStats,
+  DiagnosticMetricInstance,
+  DiagnosticMetricPresentation,
+  DiagnosticsFilter,
+  DiagnosticMissingPolicy,
+  DiagnosticPeriodAxis,
+  DiagnosticPeriodCoordinate,
+  DiagnosticReviewFilter,
+  DiagnosticReviewOperand,
+  DiagnosticReviewPredicate,
+  DiagnosticReviewRule,
+  DiagnosticRuleOperand,
+  DiagnosticSourceLocation,
+  JsonValue,
+} from "./diagnosticDefinitions.js";
+export type {
+  NormalizedAmountLimitationIdentity,
+  NormalizedDiagnosticCalculationScope,
+  NormalizedDiagnosticDefinitionIdentity,
+  NormalizedDiagnosticFormulaIdentity,
+  NormalizedDiagnosticPeriodAxisIdentity,
+  NormalizedDiagnosticReviewFilterIdentity,
+  NormalizedDiagnosticReviewRuleIdentity,
+  NormalizedDiagnosticSourceLocationIdentity,
+  NormalizedDiagnosticToleranceIdentity,
+} from "./diagnosticIdentity.js";
+export {
+  CASUALTY_FORMULA_TEMPLATES,
+  applyDiagnosticPresentation,
+  diagnosticRawRatio,
+} from "./diagnosticFormulas.js";
+export type {
+  DiagnosticMetricFinding,
+  DiagnosticQuantity,
+  DiagnosticQuantitySemantics,
+  FinalizedDiagnosticMeasure,
+} from "./diagnosticFormulas.js";
+export {
+  classifyDiagnosticComparison,
+} from "./diagnosticRules.js";
+export { deriveDiagnosticClaimMeasures } from "./diagnosticDerivations.js";
+export type {
+  DiagnosticMeasureValues,
+  DiagnosticRowWithDerivedMeasures,
+} from "./diagnosticDerivations.js";
+export {
+  compareDiagnosticPeriods,
+  diagnosticDevelopmentAge,
+  normalizeDiagnosticPeriod,
+} from "./diagnosticPeriods.js";
+export type { DiagnosticNormalizedPeriod } from "./diagnosticPeriods.js";
+export {
+  auditedDiagnosticContribution,
+  finalizeDiagnosticContributions,
+} from "./diagnosticAggregation.js";
+export type {
+  DiagnosticMeasureContribution,
+  DiagnosticMeasureContributionBase,
+  DiagnosticStructuralBlocker,
+} from "./diagnosticAggregation.js";
+export {
+  auditDiagnosticNumber,
+  reconcileDiagnosticExposures,
+} from "./diagnosticExposure.js";
+export {
+  assertPreparedDiagnosticData,
+  getPreparedDiagnosticDataIdentity,
+  prepareDiagnosticData,
+  verifyPreparedDiagnosticDataIntegrity,
+} from "./diagnosticPreparation.js";
+export type {
+  DiagnosticClaimObservation,
+  DiagnosticCompletePeriodCutoff,
+  DiagnosticExpectedCell,
+  DiagnosticInputAuditRecord,
+  DiagnosticInputDisposition,
+  DiagnosticLossInput,
+  DiagnosticLossRecordBase,
+  DiagnosticLossSnapshot,
+  NormalizedDiagnosticPreparationIdentity,
+  PrepareDiagnosticDataInput,
+  PreparedDiagnosticData,
+  PreparedDiagnosticSourceCell,
+} from "./diagnosticPreparation.js";
+export {
+  commonMaturity,
+  getMetricDiagnosticsResultIdentity,
+  runMetricDiagnostics,
+  sameMaturity,
+  validateDiagnosticGroupingConfiguration,
+} from "./diagnosticRunner.js";
+export { evaluateDiagnosticReviewRules } from "./diagnosticReview.js";
+export type {
+  DiagnosticReviewCoordinate,
+  DiagnosticReviewEvaluationScope,
+  DiagnosticReviewRuleEvaluation,
+} from "./diagnosticReview.js";
+export type {
+  CommonMaturityResult,
+  DiagnosticEmergencePoint,
+  DiagnosticMetricEvaluation,
+  DiagnosticMetricTriangle,
+  DiagnosticMetricTriangleCell,
+  MetricDiagnosticsResult,
+  NormalizedDiagnosticResultIdentity,
+  RunMetricDiagnosticsInput,
+} from "./diagnosticRunner.js";
+export type {
+  DiagnosticAuditedNumericValue,
+  DiagnosticExposureAuditObservation,
+  DiagnosticExposureObservation,
+  ReconciledDiagnosticExposure,
+} from "./diagnosticExposure.js";
+export type {
+  DiagnosticComparisonClassification,
+  DiagnosticExpressionOverflow,
+  DiagnosticRuleEvaluation,
+  DiagnosticRuleNotEvaluatedReason,
+} from "./diagnosticRules.js";
 export * from "./triangle.js";
 export * from "./factors.js";
 export * from "./chainladder.js";
@@ -15,7 +171,6 @@ export * from "./berquist.js";
 export * from "./clark.js";
 export * from "./diagnostics.js";
 export * from "./periods.js";
-export * from "./metricDiagnostics.js";
 export * from "./casualtyDiagnostics.js";
 export * from "./mack.js";
 export * from "./capping.js";

package/src/types.ts

@@ -295,6 +295,167 @@ export interface DiagnosticFinding {
   message: string;
 }
 
+export type DiagnosticValidationErrorCode =
+  | "INVALID_DIAGNOSTIC_DEFINITION"
+  | "INVALID_DIAGNOSTIC_INPUT"
+  | "INVALID_DIAGNOSTIC_CONFIGURATION"
+  | "INVALID_DIAGNOSTIC_VIEW";
+
+export type DiagnosticValidationIssueCode =
+  | "missing-required"
+  | "invalid-type"
+  | "unknown-key"
+  | "invalid-string"
+  | "invalid-number"
+  | "invalid-json-value"
+  | "duplicate-id"
+  | "unknown-reference"
+  | "incompatible-semantics"
+  | "invalid-period"
+  | "invalid-input-relationship"
+  | "invalid-configuration"
+  | "expression-limit"
+  | "cycle";
+
+export type DiagnosticValidationDomain =
+  | "definition"
+  | "input"
+  | "configuration"
+  | "view";
+
+export interface DiagnosticValidationIssue {
+  readonly domain: DiagnosticValidationDomain;
+  readonly code: DiagnosticValidationIssueCode;
+  /** Canonical singular JSONPath, rooted at `$`. */
+  readonly path: string;
+  readonly message: string;
+}
+
+const DIAGNOSTIC_DOMAIN_ORDER: readonly DiagnosticValidationDomain[] = [
+  "definition",
+  "input",
+  "configuration",
+  "view",
+];
+
+const DIAGNOSTIC_ISSUE_ORDER: readonly DiagnosticValidationIssueCode[] = [
+  "missing-required",
+  "invalid-type",
+  "unknown-key",
+  "invalid-string",
+  "invalid-number",
+  "invalid-json-value",
+  "duplicate-id",
+  "unknown-reference",
+  "incompatible-semantics",
+  "invalid-period",
+  "invalid-input-relationship",
+  "invalid-configuration",
+  "expression-limit",
+  "cycle",
+];
+
+function compareCodeUnits(left: string, right: string): number {
+  return left === right ? 0 : left < right ? -1 : 1;
+}
+
+type DiagnosticPathSegment =
+  | { readonly kind: "property"; readonly value: string }
+  | { readonly kind: "index"; readonly value: number };
+
+function diagnosticPathSegments(path: string): readonly DiagnosticPathSegment[] {
+  const segments: DiagnosticPathSegment[] = [];
+  let cursor = 1;
+  while (cursor < path.length) {
+    if (path[cursor] === ".") {
+      const start = ++cursor;
+      while (cursor < path.length && path[cursor] !== "." && path[cursor] !== "[") cursor++;
+      segments.push({ kind: "property", value: path.slice(start, cursor) });
+      continue;
+    }
+    if (path[cursor] === "[") {
+      const close = path.indexOf("]", cursor);
+      if (close < 0) return [{ kind: "property", value: path }];
+      const token = path.slice(cursor + 1, close);
+      if (/^\d+$/.test(token)) segments.push({ kind: "index", value: Number(token) });
+      else {
+        try {
+          segments.push({ kind: "property", value: JSON.parse(token) as string });
+        } catch {
+          return [{ kind: "property", value: path }];
+        }
+      }
+      cursor = close + 1;
+      continue;
+    }
+    return [{ kind: "property", value: path }];
+  }
+  return segments;
+}
+
+function compareDiagnosticPaths(left: string, right: string): number {
+  if (left === right) return 0;
+  const a = diagnosticPathSegments(left);
+  const b = diagnosticPathSegments(right);
+  const length = Math.min(a.length, b.length);
+  for (let index = 0; index < length; index++) {
+    const x = a[index]!;
+    const y = b[index]!;
+    if (x.kind !== y.kind) return x.kind === "property" ? -1 : 1;
+    const compared = x.kind === "index"
+      ? x.value - (y as Extract<DiagnosticPathSegment, { kind: "index" }>).value
+      : compareCodeUnits(
+          x.value,
+          (y as Extract<DiagnosticPathSegment, { kind: "property" }>).value,
+        );
+    if (compared !== 0) return compared;
+  }
+  return a.length - b.length;
+}
+
+function normalizeDiagnosticIssues(
+  issues: readonly DiagnosticValidationIssue[],
+): readonly DiagnosticValidationIssue[] {
+  if (issues.length === 0) {
+    throw new Error("DiagnosticValidationError requires at least one issue");
+  }
+  const unique = new Map<string, DiagnosticValidationIssue>();
+  for (const issue of issues) {
+    const normalized = Object.freeze({ ...issue });
+    const key = `${issue.domain}\u0000${issue.code}\u0000${issue.path}\u0000${issue.message}`;
+    if (!unique.has(key)) unique.set(key, normalized);
+  }
+  return Object.freeze([...unique.values()].sort((left, right) =>
+    DIAGNOSTIC_DOMAIN_ORDER.indexOf(left.domain) - DIAGNOSTIC_DOMAIN_ORDER.indexOf(right.domain) ||
+    DIAGNOSTIC_ISSUE_ORDER.indexOf(left.code) - DIAGNOSTIC_ISSUE_ORDER.indexOf(right.code) ||
+    compareDiagnosticPaths(left.path, right.path) ||
+    compareCodeUnits(left.code, right.code) ||
+    compareCodeUnits(left.message, right.message),
+  ));
+}
+
+/** Public, deterministic validation failure for every generalized diagnostic boundary. */
+export class DiagnosticValidationError extends Error {
+  readonly code: DiagnosticValidationErrorCode;
+  readonly path: string;
+  readonly issues: readonly DiagnosticValidationIssue[];
+
+  constructor(issues: readonly DiagnosticValidationIssue[]) {
+    const normalized = normalizeDiagnosticIssues(issues);
+    super(normalized[0]!.message);
+    this.name = "DiagnosticValidationError";
+    this.issues = normalized;
+    this.path = normalized[0]!.path;
+    this.code = {
+      definition: "INVALID_DIAGNOSTIC_DEFINITION",
+      input: "INVALID_DIAGNOSTIC_INPUT",
+      configuration: "INVALID_DIAGNOSTIC_CONFIGURATION",
+      view: "INVALID_DIAGNOSTIC_VIEW",
+    }[normalized[0]!.domain] as DiagnosticValidationErrorCode;
+    Object.freeze(this);
+  }
+}
+
 /**
  * Every machine-readable code a ReservingError can carry. This registry is
  * public contract: consumers may switch exhaustively on ReservingErrorCode,

package/src/version.ts

@@ -0,0 +1,2 @@
+/** This package's runtime version. A test pins it to package.json. */
+export const CORE_PACKAGE_VERSION = "0.6.0";

package/dist/metricDiagnostics.d.ts

@@ -1,212 +0,0 @@
-import { type DiagnosticFinding } from "./types.js";
-export type SparseValuePolicy = "preserve-null" | "zero-fill";
-export type DiagnosticMeasureMap = Readonly<Record<string, number | null | undefined>>;
-export type MeasureExpression = {
-    op: "measure";
-    measure: string;
-} | {
-    op: "add";
-    terms: readonly MeasureExpression[];
-} | {
-    op: "subtract";
-    left: MeasureExpression;
-    right: MeasureExpression;
-};
-export interface DiagnosticWarning {
-    code: "MISSING_COMPONENT" | "NON_FINITE_COMPONENT" | "NON_FINITE_NUMERATOR" | "NON_FINITE_RESULT" | "INVALID_DENOMINATOR" | "INCOMPLETE_EXPOSURE" | "CONFLICTING_EXPOSURE" | "DUPLICATE_EXPOSURE_KEY" | "PAID_EXCEEDS_INCURRED" | (string & {});
-    message: string;
-    component?: string;
-    exposureKey?: string;
-}
-/** Adapts structured metric warnings to the existing core diagnostic finding vocabulary. */
-export declare function diagnosticWarningToFinding(warning: DiagnosticWarning): DiagnosticFinding;
-export interface MetricWarningRule {
-    code: "PAID_EXCEEDS_INCURRED";
-    when: "numerator-greater-than-denominator";
-    message: string;
-    tolerance?: number;
-}
-export interface MetricDefinition {
-    id: string;
-    version: string;
-    displayName: string;
-    description: string;
-    unit: "count-per-million" | "ratio" | "currency-per-exposure" | "currency-per-claim" | (string & {});
-    scale: number;
-    numerator: MeasureExpression;
-    denominator: MeasureExpression;
-    numeratorLabel: string;
-    denominatorLabel: string;
-    basis: string;
-    requiredComponents: readonly string[];
-    warningRules?: readonly MetricWarningRule[];
-    /** Optional pure caller rule for domain warnings beyond the built-in comparisons. */
-    evaluateWarnings?: (context: MetricWarningContext) => readonly DiagnosticWarning[];
-}
-export interface MetricWarningContext {
-    definition: MetricDefinition;
-    components: Readonly<Record<string, number | null>>;
-    rawNumerator: number | null;
-    rawDenominator: number | null;
-    value: number | null;
-}
-export interface MetricEvaluation {
-    metricId: string;
-    metricVersion: string;
-    value: number | null;
-    rawNumerator: number | null;
-    rawDenominator: number | null;
-    numeratorLabel: string;
-    denominatorLabel: string;
-    unit: MetricDefinition["unit"];
-    scale: number;
-    basis: string;
-    rawComponents: Record<string, number | null>;
-    warnings: DiagnosticWarning[];
-}
-export interface MeasureAggregateCell {
-    sum: number;
-    observed: number;
-    missing: number;
-    nonFinite: number;
-}
-/** Mergeable sufficient statistics: grouping in stages gives the same result. */
-export interface MeasureAggregate {
-    components: Record<string, MeasureAggregateCell>;
-}
-export declare function aggregateMeasures(rows: readonly DiagnosticMeasureMap[]): MeasureAggregate;
-export declare function mergeMeasureAggregates(aggregates: readonly MeasureAggregate[]): MeasureAggregate;
-export interface FinalizedMeasures {
-    measures: Record<string, number | null>;
-    warnings: DiagnosticWarning[];
-}
-export declare function finalizeMeasureAggregate(aggregate: MeasureAggregate, sparsePolicy?: SparseValuePolicy): FinalizedMeasures;
-export declare function measureExpressionComponents(expression: MeasureExpression): string[];
-export declare function evaluateMetric(definition: MetricDefinition, components: DiagnosticMeasureMap, inheritedWarnings?: readonly DiagnosticWarning[]): MetricEvaluation;
-export type LayerExpression = {
-    op: "measure";
-    measure: string;
-} | {
-    op: "add";
-    terms: readonly LayerExpression[];
-} | {
-    op: "claim-cap";
-    measure: string;
-    limit: number;
-};
-export interface AmountLayerDefinition {
-    id: string;
-    displayName: string;
-    paidMeasure: string;
-    incurredMeasure: string;
-    paid: LayerExpression;
-    incurred: LayerExpression;
-    /** Documents whether inputs are already limited or this layer caps claim rows. */
-    basis: "pre-capped-additive" | "claim-level-cap" | "unlimited-additive";
-}
-export interface DiagnosticClaimRow<T = unknown> {
-    dimensions: T;
-    measures: DiagnosticMeasureMap;
-}
-/** Applies claim caps before aggregation; this function intentionally accepts claim rows, not aggregates. */
-export declare function deriveAmountLayers<T>(rows: readonly DiagnosticClaimRow<T>[], layers: readonly AmountLayerDefinition[]): DiagnosticClaimRow<T>[];
-export interface DiagnosticLossRow<TDimensions = unknown> {
-    id: string;
-    group: string;
-    origin: string;
-    valuation: string;
-    ageMonths: number;
-    /** Optional caller-mapped policy/fiscal period (for example a Q3-Q2 year). */
-    policyPeriod?: string;
-    /** Optional caller-owned grouping metadata; `group` remains the stable key. */
-    dimensions?: TDimensions;
-    measures: DiagnosticMeasureMap;
-}
-export interface DiagnosticExposureRow<TDimensions = unknown> {
-    /** Stable exposure identity. Repeated snapshots with the same key count once. */
-    key: string;
-    group: string;
-    origin: string;
-    valuation?: string;
-    measures: DiagnosticMeasureMap;
-    complete?: boolean;
-    dimensions?: TDimensions;
-}
-export interface DiagnosticsFilter {
-    groups?: readonly string[];
-    origins?: readonly string[];
-    originFrom?: string;
-    originThrough?: string;
-    valuations?: readonly string[];
-    valuationFrom?: string;
-    valuationThrough?: string;
-    policyPeriods?: readonly string[];
-    minAgeMonths?: number;
-    maxAgeMonths?: number;
-}
-export interface DiagnosticEmergencePoint<TDimensions = unknown> {
-    group: string;
-    dimensions?: TDimensions;
-    origin: string;
-    valuation: string;
-    ageMonths: number;
-    components: Record<string, number | null>;
-    componentWarnings: DiagnosticWarning[];
-    metrics: Record<string, MetricEvaluation>;
-}
-export interface DiagnosticMetricTriangle {
-    group: string;
-    metricId: string;
-    origins: string[];
-    ages: number[];
-    values: (number | null)[][];
-    cells: (MetricEvaluation | null)[][];
-}
-export interface MetricDiagnosticsResult<TDimensions = unknown> {
-    emergence: DiagnosticEmergencePoint<TDimensions>[];
-    triangles: DiagnosticMetricTriangle[];
-    latestDiagonal: DiagnosticEmergencePoint<TDimensions>[];
-}
-export interface RunMetricDiagnosticsInput<TDimensions = unknown> {
-    losses: readonly DiagnosticLossRow<TDimensions>[];
-    exposures?: readonly DiagnosticExposureRow<TDimensions>[];
-    metrics: readonly MetricDefinition[];
-    sparsePolicy?: SparseValuePolicy;
-    filter?: DiagnosticsFilter;
-    /** Maps source group keys to requested aggregate keys before summation. */
-    groupMap?: Readonly<Record<string, string>>;
-    /** Metadata for mapped/combined output groups. */
-    groupDimensions?: Readonly<Record<string, TDimensions>>;
-}
-export interface DiagnosticExposureReconciliationFinding {
-    code: "DUPLICATE_EXPOSURE_KEY" | "CONFLICTING_EXPOSURE";
-    exposureKey: string;
-    group: string;
-    origin: string;
-    message: string;
-}
-export interface ReconciledDiagnosticExposures<TDimensions = unknown> {
-    exposures: DiagnosticExposureRow<TDimensions>[];
-    findings: DiagnosticExposureReconciliationFinding[];
-}
-/**
- * Reconciles stable exposure keys before aggregation. Identical valuation
- * copies collapse to one row. Conflicting copies become one incomplete/null
- * row so exposure-based metrics fail closed rather than using a partial base.
- */
-export declare function reconcileDiagnosticExposureKeys<TDimensions = unknown>(rows: readonly DiagnosticExposureRow<TDimensions>[]): ReconciledDiagnosticExposures<TDimensions>;
-/**
- * Generic quarterly diagnostics engine. Loss rows aggregate by
- * group/origin/valuation; exposure rows aggregate once by stable exposure key;
- * every metric then divides the aggregated expressions exactly once.
- */
-export declare function runMetricDiagnostics<TDimensions = unknown>(input: RunMetricDiagnosticsInput<TDimensions>): MetricDiagnosticsResult<TDimensions>;
-export declare function metricTriangleFromEmergence(points: readonly DiagnosticEmergencePoint<unknown>[], metricId: string): DiagnosticMetricTriangle;
-export declare function sameMaturity<TDimensions>(result: MetricDiagnosticsResult<TDimensions>, ageMonths: number, groups?: readonly string[]): DiagnosticEmergencePoint<TDimensions>[];
-export interface CommonMaturityResult<TDimensions = unknown> {
-    ageMonths: number | null;
-    points: DiagnosticEmergencePoint<TDimensions>[];
-}
-/** Latest maturity present in every selected group; selection is caller-defined. */
-export declare function commonMaturity<TDimensions>(result: MetricDiagnosticsResult<TDimensions>, groups: readonly string[]): CommonMaturityResult<TDimensions>;
-//# sourceMappingURL=metricDiagnostics.d.ts.map