@actuarial-ts/core 0.4.0 → 0.6.0

package/src/diagnosticPeriods.ts

@@ -0,0 +1,117 @@
+import type { CompiledDiagnosticDefinition, DiagnosticPeriodAxis } from "./diagnosticDefinitions.js";
+import { assertCompiledDiagnosticDefinition } from "./diagnosticDefinitions.js";
+import { DiagnosticValidationError } from "./types.js";
+
+export interface DiagnosticNormalizedPeriod {
+  readonly label: string;
+  readonly coordinate: number;
+}
+
+type PeriodSide = "origin" | "valuation";
+
+function calendarCoordinate(
+  label: string,
+  cadence: "month" | "quarter" | "year",
+  anchor: "start" | "end",
+): number | null {
+  let year: number;
+  let start: number;
+  let width: number;
+  if (cadence === "year") {
+    const match = /^(\d{4})$/.exec(label);
+    if (!match) return null;
+    year = Number(match[1]);
+    start = year * 12;
+    width = 12;
+  } else if (cadence === "month") {
+    const match = /^(\d{4})-(0[1-9]|1[0-2])$/.exec(label);
+    if (!match) return null;
+    year = Number(match[1]);
+    start = year * 12 + Number(match[2]) - 1;
+    width = 1;
+  } else {
+    const compact = /^(\d{4})Q([1-4])$/.exec(label);
+    const hyphenated = /^(\d{4})-Q([1-4])$/.exec(label);
+    const first = /^Q([1-4]) (\d{4})$/.exec(label);
+    const match = compact ?? hyphenated ?? first;
+    if (!match) return null;
+    const quarterFirst = match === first;
+    year = Number(match[quarterFirst ? 2 : 1]);
+    const quarter = Number(match[quarterFirst ? 1 : 2]);
+    start = year * 12 + (quarter - 1) * 3;
+    width = 3;
+  }
+  if (year < 1 || year > 9999) return null;
+  return start + (anchor === "end" ? width : 0);
+}
+
+function normalizeWithAxis(
+  axis: DiagnosticPeriodAxis,
+  side: PeriodSide,
+  label: string,
+): DiagnosticNormalizedPeriod {
+  if (axis.kind === "calendar") {
+    const cadence = side === "origin" ? axis.originCadence : axis.valuationCadence;
+    const anchor = side === "origin" ? axis.originAnchor : axis.valuationAnchor;
+    const coordinate = calendarCoordinate(label, cadence, anchor);
+    if (coordinate === null) throw new DiagnosticValidationError([{
+      domain: "input",
+      code: "invalid-period",
+      path: `$.${side}`,
+      message: `Invalid ${cadence} ${side} label ${JSON.stringify(label)}`,
+    }]);
+    const canonicalLabel = cadence === "quarter"
+      ? (() => {
+          const startCoordinate = calendarCoordinate(label, cadence, "start")!;
+          const year = Math.floor(startCoordinate / 12);
+          return `${String(year).padStart(4, "0")}Q${Math.floor((startCoordinate % 12) / 3) + 1}`;
+        })()
+      : label;
+    return Object.freeze({ label: canonicalLabel, coordinate });
+  }
+  const catalog = side === "origin" ? axis.origins : axis.valuations;
+  const item = catalog.find((coordinate) => coordinate.label === label || coordinate.aliases?.includes(label));
+  if (!item) throw new DiagnosticValidationError([{
+    domain: "input",
+    code: "invalid-period",
+    path: `$.${side}`,
+    message: `Unknown ordered-axis ${side} label ${JSON.stringify(label)}`,
+  }]);
+  return Object.freeze({ label: item.label, coordinate: item.coordinate });
+}
+
+export function normalizeDiagnosticPeriod(
+  definition: CompiledDiagnosticDefinition,
+  side: PeriodSide,
+  label: string,
+): DiagnosticNormalizedPeriod {
+  assertCompiledDiagnosticDefinition(definition);
+  return normalizeWithAxis(definition.definition.periodAxis as DiagnosticPeriodAxis, side, label);
+}
+
+export function diagnosticDevelopmentAge(
+  definition: CompiledDiagnosticDefinition,
+  origin: string,
+  valuation: string,
+): { readonly origin: DiagnosticNormalizedPeriod; readonly valuation: DiagnosticNormalizedPeriod; readonly developmentAge: number; readonly ageUnit: string } {
+  const normalizedOrigin = normalizeDiagnosticPeriod(definition, "origin", origin);
+  const normalizedValuation = normalizeDiagnosticPeriod(definition, "valuation", valuation);
+  const axis = definition.definition.periodAxis;
+  const developmentAge = normalizedValuation.coordinate - normalizedOrigin.coordinate + axis.ageOffset;
+  if (!Number.isSafeInteger(developmentAge) || developmentAge < 0) throw new DiagnosticValidationError([{
+    domain: "input",
+    code: "invalid-period",
+    path: "$.valuation",
+    message: "Valuation period precedes origin period or development age is unsafe",
+  }]);
+  return Object.freeze({
+    origin: normalizedOrigin,
+    valuation: normalizedValuation,
+    developmentAge,
+    ageUnit: axis.ageUnit,
+  });
+}
+
+export function compareDiagnosticPeriods(left: DiagnosticNormalizedPeriod, right: DiagnosticNormalizedPeriod): number {
+  return left.coordinate - right.coordinate || (left.label < right.label ? -1 : left.label > right.label ? 1 : 0);
+}

package/src/diagnosticPreparation.ts

@@ -0,0 +1,233 @@
+import { canonicalJson, fnv1a64 } from "./canonical.js";
+import {
+  assertCompiledDiagnosticDefinition,
+  getCompiledDiagnosticDefinitionInternals,
+  type CompiledDiagnosticDefinition,
+  type DiagnosticDeepReadonly,
+  type DiagnosticSourceLocation,
+  type DiagnosticsFilter,
+  type JsonValue,
+} from "./diagnosticDefinitions.js";
+import { auditedDiagnosticContribution, finalizeDiagnosticContributions, type DiagnosticMeasureContribution, type DiagnosticStructuralBlocker } from "./diagnosticAggregation.js";
+import { deriveDiagnosticClaimMeasures } from "./diagnosticDerivations.js";
+import { diagnosticDevelopmentAge, normalizeDiagnosticPeriod } from "./diagnosticPeriods.js";
+import { reconcileDiagnosticExposures, type DiagnosticAuditedNumericValue, type DiagnosticExposureObservation, type ReconciledDiagnosticExposure, auditDiagnosticNumber } from "./diagnosticExposure.js";
+import type { DiagnosticMeasureStats } from "./diagnosticDefinitions.js";
+import type { DiagnosticMetricFinding } from "./diagnosticFormulas.js";
+import { DiagnosticValidationError, type DiagnosticValidationIssue } from "./types.js";
+
+export interface DiagnosticLossRecordBase {
+  readonly recordId: string;
+  readonly sourceGroup: string;
+  readonly origin: string;
+  readonly valuation: string;
+  readonly complete: boolean;
+  readonly source?: DiagnosticSourceLocation;
+  readonly measures: Readonly<Record<string, number | null>>;
+}
+export interface DiagnosticClaimObservation extends DiagnosticLossRecordBase { readonly rowType: "claim"; readonly claimId: string }
+export interface DiagnosticLossSnapshot extends DiagnosticLossRecordBase { readonly rowType: "aggregate" }
+export type DiagnosticLossInput = DiagnosticClaimObservation | DiagnosticLossSnapshot;
+
+export interface DiagnosticCompletePeriodCutoff { readonly sourceGroup: string; readonly originThrough: string | null; readonly valuationThrough: string | null }
+export interface DiagnosticExpectedCell { readonly sourceGroup: string; readonly origin: string; readonly valuation: string; readonly source?: DiagnosticSourceLocation }
+export interface PrepareDiagnosticDataInput {
+  readonly definition: CompiledDiagnosticDefinition;
+  readonly losses: readonly DiagnosticLossInput[];
+  readonly exposures: readonly DiagnosticExposureObservation[];
+  readonly filter?: DiagnosticsFilter;
+  readonly completePeriodCutoffs?: readonly DiagnosticCompletePeriodCutoff[];
+  readonly expectedCells?: readonly DiagnosticExpectedCell[];
+}
+
+export type DiagnosticInputDisposition = "invalid" | "complete-period-cutoff" | "filter" | "retained";
+export type DiagnosticInputAuditRecord =
+  | { readonly kind: "loss"; readonly disposition: DiagnosticInputDisposition; readonly record: DiagnosticDeepReadonly<DiagnosticLossInput> }
+  | { readonly kind: "exposure"; readonly disposition: DiagnosticInputDisposition; readonly record: DiagnosticDeepReadonly<DiagnosticExposureObservation> }
+  | { readonly kind: "expected-cell"; readonly disposition: Exclude<DiagnosticInputDisposition, "invalid">; readonly record: DiagnosticDeepReadonly<DiagnosticExpectedCell> };
+
+export interface PreparedDiagnosticSourceCell {
+  readonly sourceGroup: string;
+  readonly origin: string;
+  readonly valuation: string;
+  readonly developmentAge: number;
+  readonly ageUnit: string;
+  readonly lossRecordIds: readonly string[];
+  readonly contributions: Readonly<Record<string, readonly DiagnosticMeasureContribution[]>>;
+  readonly components: Readonly<Record<string, DiagnosticMeasureStats>>;
+  readonly structuralBlockers: Readonly<Record<string, readonly DiagnosticStructuralBlocker[]>>;
+  readonly findings: readonly DiagnosticMetricFinding[];
+}
+
+declare const preparedDiagnosticDataBrand: unique symbol;
+export interface PreparedDiagnosticData {
+  readonly [preparedDiagnosticDataBrand]: true;
+  readonly definition: CompiledDiagnosticDefinition;
+  readonly preparationFingerprint: string;
+  readonly filter: DiagnosticDeepReadonly<DiagnosticsFilter> | null;
+  readonly completePeriodCutoffs: readonly DiagnosticCompletePeriodCutoff[];
+  readonly inputAudit: readonly DiagnosticInputAuditRecord[];
+  readonly cells: readonly PreparedDiagnosticSourceCell[];
+  readonly exposures: readonly ReconciledDiagnosticExposure[];
+  readonly expectedCellsProvided: boolean;
+  readonly expectedCells: readonly DiagnosticExpectedCell[];
+  readonly findings: readonly DiagnosticMetricFinding[];
+}
+
+export interface NormalizedDiagnosticPreparationIdentity {
+  readonly definitionIntegrity: string;
+  readonly filter: DiagnosticDeepReadonly<DiagnosticsFilter> | null;
+  readonly completePeriodCutoffs: readonly DiagnosticCompletePeriodCutoff[];
+  readonly inputAudit: readonly DiagnosticInputAuditRecord[];
+  readonly cells: readonly PreparedDiagnosticSourceCell[];
+  readonly exposures: readonly ReconciledDiagnosticExposure[];
+  readonly expectedCellsProvided: boolean;
+  readonly expectedCells: readonly DiagnosticExpectedCell[];
+  readonly findings: readonly DiagnosticMetricFinding[];
+}
+
+const authentic = new WeakSet<object>();
+const identities = new WeakMap<object, DiagnosticDeepReadonly<NormalizedDiagnosticPreparationIdentity>>();
+
+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 codeUnit(left: string, right: string): number { return left < right ? -1 : left > right ? 1 : 0 }
+function own<T>(record: Readonly<Record<string, T>>, key: string): T | undefined { return Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined }
+
+function normalizeFilter(filter: DiagnosticsFilter | undefined): DiagnosticsFilter | null {
+  if (filter === undefined) return null;
+  const set = (values: readonly string[] | undefined) => values === undefined ? undefined : [...new Set(values)].sort(codeUnit);
+  return {
+    ...(filter.sourceGroups === undefined ? {} : { sourceGroups: set(filter.sourceGroups) }),
+    ...(filter.outputGroups === undefined ? {} : { outputGroups: set(filter.outputGroups) }),
+    ...(filter.origins === undefined ? {} : { origins: set(filter.origins) }),
+    ...(filter.originFrom === undefined ? {} : { originFrom: filter.originFrom }),
+    ...(filter.originThrough === undefined ? {} : { originThrough: filter.originThrough }),
+    ...(filter.valuations === undefined ? {} : { valuations: set(filter.valuations) }),
+    ...(filter.valuationFrom === undefined ? {} : { valuationFrom: filter.valuationFrom }),
+    ...(filter.valuationThrough === undefined ? {} : { valuationThrough: filter.valuationThrough }),
+    ...(filter.minDevelopmentAge === undefined ? {} : { minDevelopmentAge: filter.minDevelopmentAge }),
+    ...(filter.maxDevelopmentAge === undefined ? {} : { maxDevelopmentAge: filter.maxDevelopmentAge }),
+    ...(filter.instanceIds === undefined ? {} : { instanceIds: set(filter.instanceIds) }),
+  };
+}
+
+function selected(filter: DiagnosticsFilter | null, group: string, origin: string, valuation: string, age: number): boolean {
+  return (filter?.sourceGroups === undefined || filter.sourceGroups.includes(group)) &&
+    (filter?.origins === undefined || filter.origins.includes(origin)) &&
+    (filter?.valuations === undefined || filter.valuations.includes(valuation)) &&
+    (filter?.originFrom === undefined || origin >= filter.originFrom) &&
+    (filter?.originThrough === undefined || origin <= filter.originThrough) &&
+    (filter?.valuationFrom === undefined || valuation >= filter.valuationFrom) &&
+    (filter?.valuationThrough === undefined || valuation <= filter.valuationThrough) &&
+    (filter?.minDevelopmentAge === undefined || age >= filter.minDevelopmentAge) &&
+    (filter?.maxDevelopmentAge === undefined || age <= filter.maxDevelopmentAge);
+}
+
+export function prepareDiagnosticData(input: PrepareDiagnosticDataInput): PreparedDiagnosticData {
+  assertCompiledDiagnosticDefinition(input.definition);
+  const definition = input.definition;
+  const internals = getCompiledDiagnosticDefinitionInternals(definition);
+  const issues: DiagnosticValidationIssue[] = [];
+  const filter = normalizeFilter(input.filter);
+  for (const bound of [filter?.minDevelopmentAge, filter?.maxDevelopmentAge]) if (bound !== undefined && (!Number.isSafeInteger(bound) || bound < 0)) issues.push({ domain: "configuration", code: "invalid-configuration", path: "$.filter", message: "Development-age bounds must be nonnegative safe integers" });
+  if (filter?.minDevelopmentAge !== undefined && filter.maxDevelopmentAge !== undefined && filter.minDevelopmentAge > filter.maxDevelopmentAge) issues.push({ domain: "configuration", code: "invalid-configuration", path: "$.filter", message: "Minimum development age exceeds maximum" });
+  input.losses.forEach((row, index) => {
+    if (row.rowType !== definition.definition.lossRowGrain) issues.push({ domain: "input", code: "invalid-input-relationship", path: `$.losses[${index}].rowType`, message: "Loss row type does not match definition grain" });
+  });
+  input.exposures.forEach((row, index) => {
+    const measure = internals.measuresById.get(row.measureId);
+    if (measure?.exposureTiming === "valuation-specific" && row.valuation === undefined) issues.push({ domain: "input", code: "missing-required", path: `$.exposures[${index}].valuation`, message: "Valuation-specific exposure requires valuation" });
+  });
+  if (issues.length > 0) throw new DiagnosticValidationError(issues);
+
+  const normalizedLosses: DiagnosticLossInput[] = [];
+  const audit: DiagnosticInputAuditRecord[] = [];
+  for (const row of input.losses) {
+    let disposition: DiagnosticInputDisposition = "retained";
+    try {
+      const period = diagnosticDevelopmentAge(definition, row.origin, row.valuation);
+      const normalized = { ...row, origin: period.origin.label, valuation: period.valuation.label } as DiagnosticLossInput;
+      if (!selected(filter, row.sourceGroup, normalized.origin, normalized.valuation, period.developmentAge)) disposition = "filter";
+      if (disposition === "retained") normalizedLosses.push(normalized);
+      audit.push({ kind: "loss", disposition, record: normalized });
+    } catch { audit.push({ kind: "loss", disposition: "invalid", record: row }); }
+  }
+  const derivedLosses = definition.definition.lossRowGrain === "claim"
+    ? deriveDiagnosticClaimMeasures(normalizedLosses as DiagnosticClaimObservation[], definition) as readonly DiagnosticLossInput[]
+    : normalizedLosses;
+  const cells = new Map<string, DiagnosticLossInput[]>();
+  for (const row of derivedLosses) {
+    const key = `${row.sourceGroup}\u0000${row.origin}\u0000${row.valuation}`;
+    const list = cells.get(key) ?? [];
+    list.push(row);
+    cells.set(key, list);
+  }
+
+  const normalizedExposureInputs: DiagnosticExposureObservation[] = [];
+  for (const row of input.exposures) {
+    try {
+      const origin = normalizeDiagnosticPeriod(definition, "origin", row.origin).label;
+      const valuation = row.valuation === undefined ? undefined : normalizeDiagnosticPeriod(definition, "valuation", row.valuation).label;
+      const normalized = { ...row, origin, ...(valuation === undefined ? {} : { valuation }) };
+      const timing = internals.measuresById.get(row.measureId)?.exposureTiming;
+      const age = valuation === undefined ? 0 : diagnosticDevelopmentAge(definition, origin, valuation).developmentAge;
+      const keep = timing === "origin-static"
+        ? (filter?.sourceGroups === undefined || filter.sourceGroups.includes(row.sourceGroup)) && (filter?.origins === undefined || filter.origins.includes(origin))
+        : selected(filter, row.sourceGroup, origin, valuation ?? "", age);
+      audit.push({ kind: "exposure", disposition: keep ? "retained" : "filter", record: normalized });
+      if (keep) normalizedExposureInputs.push(normalized);
+    } catch { audit.push({ kind: "exposure", disposition: "invalid", record: row }); }
+  }
+  const timingByMeasure = Object.fromEntries(definition.definition.measures.filter((measure) => measure.kind === "exposure").map((measure) => [measure.id, measure.exposureTiming!])) as Record<string, "origin-static" | "valuation-specific">;
+  const exposures = reconcileDiagnosticExposures(normalizedExposureInputs, timingByMeasure);
+  const preparedCells: PreparedDiagnosticSourceCell[] = [];
+  for (const [key, rows] of cells) {
+    const [sourceGroup, origin, valuation] = key.split("\u0000") as [string, string, string];
+    const period = diagnosticDevelopmentAge(definition, origin, valuation);
+    const contributions: Record<string, DiagnosticMeasureContribution[]> = Object.create(null);
+    const blockers: Record<string, DiagnosticStructuralBlocker[]> = Object.create(null);
+    for (const measure of definition.definition.measures) { contributions[measure.id] = []; blockers[measure.id] = []; }
+    for (const row of rows) {
+      for (const measure of definition.definition.measures.filter((item) => item.source !== "exposure")) {
+        contributions[measure.id]!.push(auditedDiagnosticContribution(row.recordId, own(row.measures, measure.id), measure.missing, row.source ? [row.source] : []));
+      }
+    }
+    for (const exposure of exposures) {
+      if (exposure.status !== "valid" || exposure.sourceGroup !== sourceGroup || exposure.origin !== origin || (exposure.valuation !== undefined && exposure.valuation !== valuation)) continue;
+      contributions[exposure.measureId]!.push(auditedDiagnosticContribution(exposure.key, exposure.value, "unknown", exposure.sources, exposure.deduplicated));
+    }
+    for (const measure of definition.definition.measures.filter((item) => item.source === "exposure")) {
+      if (contributions[measure.id]!.length === 0) blockers[measure.id]!.push({ code: "loss-without-exposure", message: "Loss cell has no applicable exposure observation", sourceIds: rows.map((row) => row.recordId).sort(codeUnit), sources: [] });
+    }
+    const components = Object.fromEntries(definition.definition.measures.map((measure) => [measure.id, finalizeDiagnosticContributions(contributions[measure.id]!, measure.missing, blockers[measure.id])])) as Record<string, DiagnosticMeasureStats>;
+    preparedCells.push(deepFreeze({ sourceGroup, origin, valuation, developmentAge: period.developmentAge, ageUnit: period.ageUnit, lossRecordIds: rows.map((row) => row.recordId).sort(codeUnit), contributions, components, structuralBlockers: blockers, findings: [] }));
+  }
+  preparedCells.sort((a, b) => codeUnit(a.sourceGroup, b.sourceGroup) || codeUnit(a.origin, b.origin) || codeUnit(a.valuation, b.valuation));
+  const expectedCells = (input.expectedCells ?? []).map((item) => ({ ...item }));
+  for (const item of expectedCells) audit.push({ kind: "expected-cell", disposition: "retained", record: item });
+  const identity = deepFreeze({ definitionIntegrity: definition.definitionIntegrity, filter, completePeriodCutoffs: [...(input.completePeriodCutoffs ?? [])], inputAudit: audit, cells: preparedCells, exposures, expectedCellsProvided: input.expectedCells !== undefined, expectedCells, findings: [] });
+  const preparationFingerprint = `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({ identityVersion: 1, kind: "diagnostic-preparation", preparation: identity }))}`;
+  const preparedBase = { definition, preparationFingerprint, filter, completePeriodCutoffs: input.completePeriodCutoffs ?? [], inputAudit: audit, cells: preparedCells, exposures, expectedCellsProvided: input.expectedCells !== undefined, expectedCells, findings: [] };
+  const prepared = deepFreeze(preparedBase) as unknown as PreparedDiagnosticData;
+  authentic.add(prepared);
+  identities.set(prepared, identity);
+  return prepared;
+}
+
+export function assertPreparedDiagnosticData(value: unknown): asserts value is PreparedDiagnosticData {
+  if (value === null || typeof value !== "object" || !authentic.has(value)) throw new DiagnosticValidationError([{ domain: "input", code: "invalid-input-relationship", path: "$.prepared", message: "Value is not authentic prepared diagnostic data" }]);
+}
+export function getPreparedDiagnosticDataIdentity(value: PreparedDiagnosticData): DiagnosticDeepReadonly<NormalizedDiagnosticPreparationIdentity> { assertPreparedDiagnosticData(value); return identities.get(value)! }
+export function verifyPreparedDiagnosticDataIntegrity(value: PreparedDiagnosticData): void {
+  const identity = getPreparedDiagnosticDataIdentity(value);
+  const tag = `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({ identityVersion: 1, kind: "diagnostic-preparation", preparation: identity }))}`;
+  if (tag !== value.preparationFingerprint) throw new DiagnosticValidationError([{ domain: "input", code: "invalid-input-relationship", path: "$.prepared.preparationFingerprint", message: "Prepared diagnostic data integrity does not match its content" }]);
+}
+
+export type { JsonValue, DiagnosticAuditedNumericValue };

package/src/diagnosticReview.ts

@@ -0,0 +1,91 @@
+import { getCompiledDiagnosticDefinitionInternals, type DiagnosticReviewRule, type DiagnosticSourceLocation } from "./diagnosticDefinitions.js";
+import { evaluateDiagnosticMeasureExpression, type FinalizedDiagnosticMeasure } from "./diagnosticFormulas.js";
+import { assertPreparedDiagnosticData, type PreparedDiagnosticData } from "./diagnosticPreparation.js";
+import { classifyDiagnosticComparison, diagnosticPredicateMatches, type DiagnosticRuleNotEvaluatedReason } from "./diagnosticRules.js";
+
+export interface DiagnosticReviewCoordinate { readonly sourceGroup: string; readonly origin: string; readonly valuation: string; readonly developmentAge: number; readonly ageUnit: string }
+export type DiagnosticReviewEvaluationScope =
+  | { readonly kind: "cell"; readonly coordinate: DiagnosticReviewCoordinate; readonly sources: readonly DiagnosticSourceLocation[] }
+  | { readonly kind: "valuation-pair"; readonly previous: DiagnosticReviewCoordinate; readonly current: DiagnosticReviewCoordinate; readonly sources: readonly DiagnosticSourceLocation[] }
+  | { readonly kind: "control-total"; readonly selectedCellCount: number; readonly selectedContributionCount: number; readonly sources: readonly DiagnosticSourceLocation[] };
+export interface DiagnosticReviewRuleEvaluation {
+  readonly ruleId: string;
+  readonly kind: DiagnosticReviewRule["kind"];
+  readonly status: "pass" | "triggered" | "not-evaluated";
+  readonly severity: "warning" | "fail";
+  readonly triggerReason: "predicate" | "missing-input" | null;
+  readonly left: number | null;
+  readonly right: number | null;
+  readonly relation: "less" | "equal" | "greater" | null;
+  readonly notEvaluatedReasons: readonly DiagnosticRuleNotEvaluatedReason[];
+  readonly expressionOverflows: readonly { readonly expressionPath: string; readonly sources: readonly DiagnosticSourceLocation[] }[];
+  readonly reviewScope: DiagnosticReviewEvaluationScope;
+}
+
+function states(prepared: PreparedDiagnosticData, components: typeof prepared.cells[number]["components"]): Record<string, FinalizedDiagnosticMeasure> {
+  const internals = getCompiledDiagnosticDefinitionInternals(prepared.definition);
+  return Object.fromEntries(Object.entries(components).map(([id, stats]) => {
+    const measure = internals.measuresById.get(id)!;
+    const readiness: DiagnosticRuleNotEvaluatedReason[] = [];
+    if (stats.missing) readiness.push(stats.imputedZero ? "imputed" : "missing");
+    if (stats.nonFinite) readiness.push("non-finite");
+    if (stats.structural) readiness.push("structural-ambiguity");
+    if (stats.sum === null && !stats.nonFinite && !stats.structural) readiness.push("aggregation-overflow");
+    return [id, { quantity: { kind: measure.kind, unit: measure.unit, value: stats.value }, stats, readiness }];
+  }));
+}
+
+function coordinate(cell: PreparedDiagnosticData["cells"][number]): DiagnosticReviewCoordinate { return { sourceGroup: cell.sourceGroup, origin: cell.origin, valuation: cell.valuation, developmentAge: cell.developmentAge, ageUnit: cell.ageUnit } }
+
+function evaluation(rule: DiagnosticReviewRule, scope: DiagnosticReviewEvaluationScope, left: number|null, right: number|null, asserted: boolean, reasons: readonly DiagnosticRuleNotEvaluatedReason[] = []): DiagnosticReviewRuleEvaluation {
+  if (left === null || right === null || reasons.length) return { ruleId: rule.id, kind: rule.kind, status: rule.missingInput === "finding" ? "triggered" : "not-evaluated", severity: rule.severity, triggerReason: rule.missingInput === "finding" ? "missing-input" : null, left, right, relation: null, notEvaluatedReasons: reasons.length ? reasons : ["missing"], expressionOverflows: [], reviewScope: scope };
+  const compared = classifyDiagnosticComparison(left, right, rule.tolerance);
+  if (compared.status === "not-evaluated") return { ruleId: rule.id, kind: rule.kind, status: "not-evaluated", severity: rule.severity, triggerReason: null, left, right, relation: null, notEvaluatedReasons: [compared.reason], expressionOverflows: [], reviewScope: scope };
+  return { ruleId: rule.id, kind: rule.kind, status: asserted ? "pass" : "triggered", severity: rule.severity, triggerReason: asserted ? null : "predicate", left, right, relation: compared.relation, notEvaluatedReasons: [], expressionOverflows: [], reviewScope: scope };
+}
+
+/** Evaluates definition-owned semantic review rules over authenticated prepared cells. */
+export function evaluateDiagnosticReviewRules(prepared: PreparedDiagnosticData): readonly DiagnosticReviewRuleEvaluation[] {
+  assertPreparedDiagnosticData(prepared);
+  const results: DiagnosticReviewRuleEvaluation[] = [];
+  for (const rule of prepared.definition.definition.reviewRules as readonly DiagnosticReviewRule[]) {
+    if (rule.kind === "control-total") {
+      const values = prepared.cells.map((cell) => evaluateDiagnosticMeasureExpression(rule.expression, states(prepared, cell.components), "$.reviewRules.control-total").value);
+      const left = values.some((value) => value === null) ? null : values.reduce<number>((sum, value) => sum + value!, 0);
+      const scope = { kind: "control-total" as const, selectedCellCount: prepared.cells.length, selectedContributionCount: prepared.cells.reduce((sum, cell) => sum + Object.values(cell.contributions).reduce((n, items) => n + items.length, 0), 0), sources: [] };
+      const classified = classifyDiagnosticComparison(left, rule.expected, rule.tolerance);
+      results.push(evaluation(rule, scope, left, rule.expected, classified.status === "evaluated" && classified.relation === "equal"));
+      continue;
+    }
+    if (rule.kind === "monotonic") {
+      const groups = new Map<string, typeof prepared.cells>();
+      for (const cell of prepared.cells) { const key=`${cell.sourceGroup}\0${cell.origin}`; groups.set(key,[...(groups.get(key)??[]),cell]); }
+      for (const cells of groups.values()) {
+        const sorted=[...cells].sort((a,b)=>a.developmentAge-b.developmentAge);
+        for(let index=1;index<sorted.length;index++){
+          const previous=sorted[index-1]!,current=sorted[index]!;
+          const left=evaluateDiagnosticMeasureExpression(rule.expression,states(prepared,previous.components),"$.reviewRules.monotonic").value;
+          const right=evaluateDiagnosticMeasureExpression(rule.expression,states(prepared,current.components),"$.reviewRules.monotonic").value;
+          results.push(evaluation(rule,{kind:"valuation-pair",previous:coordinate(previous),current:coordinate(current),sources:[]},left,right,rule.direction==="nondecreasing"?left!==null&&right!==null&&left<=right:left!==null&&right!==null&&left>=right));
+        }
+      }
+      continue;
+    }
+    for (const cell of prepared.cells) {
+      const state=states(prepared,cell.components); const scope={kind:"cell" as const,coordinate:coordinate(cell),sources:[]};
+      if(rule.kind==="compare"){
+        const operand=(item:typeof rule.when.left)=>item.op==="constant"?item.value:evaluateDiagnosticMeasureExpression(item,state,"$.reviewRules.compare").value;
+        const left=operand(rule.when.left),right=operand(rule.when.right);const classified=classifyDiagnosticComparison(left,right,rule.tolerance);
+        results.push(evaluation(rule,scope,left,right,classified.status==="evaluated"&&!diagnosticPredicateMatches(rule.when.operator,classified.relation)));
+      } else if(rule.kind==="reconcile"){
+        const left=evaluateDiagnosticMeasureExpression(rule.actual,state,"$.reviewRules.reconcile.actual").value;
+        const right=rule.expected.op==="constant"?rule.expected.value:evaluateDiagnosticMeasureExpression(rule.expected,state,"$.reviewRules.reconcile.expected").value;
+        const classified=classifyDiagnosticComparison(left,right,rule.tolerance);results.push(evaluation(rule,scope,left,right,classified.status==="evaluated"&&classified.relation==="equal"));
+      } else {
+        const left=evaluateDiagnosticMeasureExpression(rule.narrower,state,"$.reviewRules.layer.narrower").value;const right=evaluateDiagnosticMeasureExpression(rule.broader,state,"$.reviewRules.layer.broader").value;
+        results.push(evaluation(rule,scope,left,right,left!==null&&right!==null&&left<=right));
+      }
+    }
+  }
+  return Object.freeze(results.map((item) => Object.freeze(item)));
+}

package/src/diagnosticRules.ts

@@ -0,0 +1,69 @@
+import type { DiagnosticComparisonPredicate, DiagnosticSourceLocation } from "./diagnosticDefinitions.js";
+
+export type DiagnosticComparisonClassification =
+  | { readonly status: "evaluated"; readonly relation: "less" | "equal" | "greater" }
+  | { readonly status: "not-evaluated"; readonly reason: "missing" | "non-finite" | "tolerance-overflow" };
+
+export type DiagnosticRuleNotEvaluatedReason =
+  | "missing"
+  | "imputed"
+  | "non-finite"
+  | "structural-ambiguity"
+  | "aggregation-overflow"
+  | "expression-overflow"
+  | "tolerance-overflow";
+
+export interface DiagnosticExpressionOverflow {
+  readonly expressionPath: string;
+  readonly sources: readonly DiagnosticSourceLocation[];
+}
+
+export interface DiagnosticRuleEvaluation {
+  readonly ruleId: string;
+  readonly status: "pass" | "triggered" | "not-evaluated";
+  readonly severity: "warning" | "fail";
+  readonly left: number | null;
+  readonly right: number | null;
+  readonly relation: "less" | "equal" | "greater" | null;
+  readonly notEvaluatedReasons: readonly DiagnosticRuleNotEvaluatedReason[];
+  readonly expressionOverflows: readonly DiagnosticExpressionOverflow[];
+  readonly code: string | null;
+  readonly message: string | null;
+}
+
+/** Pure, overflow-safe three-way comparison shared by metric and review rules. */
+export function classifyDiagnosticComparison(
+  left: number | null,
+  right: number | null,
+  tolerance: { readonly absolute?: number; readonly relative?: number } = {},
+): DiagnosticComparisonClassification {
+  if (left === null || right === null) return { status: "not-evaluated", reason: "missing" };
+  if (!Number.isFinite(left) || !Number.isFinite(right)) return { status: "not-evaluated", reason: "non-finite" };
+  const absolute = tolerance.absolute ?? 0;
+  const relative = tolerance.relative ?? 0;
+  const scale = Math.max(1, Math.abs(left), Math.abs(right));
+  const relativeTolerance = relative * scale;
+  const totalTolerance = absolute + relativeTolerance;
+  if (!Number.isFinite(absolute) || absolute < 0 || !Number.isFinite(relative) || relative < 0 ||
+      !Number.isFinite(relativeTolerance) || !Number.isFinite(totalTolerance)) {
+    return { status: "not-evaluated", reason: "tolerance-overflow" };
+  }
+  if (left === right) return { status: "evaluated", relation: "equal" };
+  const distance = left > right ? left - right : right - left;
+  if (Number.isFinite(distance) && distance <= totalTolerance) {
+    return { status: "evaluated", relation: "equal" };
+  }
+  return { status: "evaluated", relation: left < right ? "less" : "greater" };
+}
+
+export function diagnosticPredicateMatches(
+  predicate: DiagnosticComparisonPredicate["operator"],
+  relation: "less" | "equal" | "greater",
+): boolean {
+  return predicate === "lt" ? relation === "less"
+    : predicate === "lte" ? relation !== "greater"
+      : predicate === "eq" ? relation === "equal"
+        : predicate === "neq" ? relation !== "equal"
+          : predicate === "gte" ? relation !== "less"
+            : relation === "greater";
+}