@actuarial-ts/core 0.8.0 → 0.9.0

package/src/analysisExpressions.ts

@@ -0,0 +1,223 @@
+import type {
+  AnalysisDefinition, AnalysisDerivedMeasureDefinition, AnalysisMeasureExpression,
+  AnalysisResultValue, AnalysisDerivedComponent, CustomizationCapabilityFinding,
+} from "./customizationContracts.js";
+import { canonicalJson } from "./canonical.js";
+import { isDiagnosticPlainRecord, isDiagnosticToken, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { DiagnosticValidationError } from "./types.js";
+
+type Factors = Readonly<Record<string, number>>;
+export type CompiledAnalysisExpression = { readonly definition: AnalysisDerivedMeasureDefinition; readonly unit: string; readonly unitFactors: Factors; readonly dependencies: readonly string[] };
+const invalid = (message: string, path = "$.definition.derivedMeasures", code: "invalid-configuration" | "unknown-reference" | "incompatible-semantics" | "expression-limit" | "cycle" = "invalid-configuration"): never => {
+  throw new DiagnosticValidationError([{ domain: "definition", code, path, message }]);
+};
+
+function normalizedFactors(raw: unknown): Factors {
+  if (!isDiagnosticPlainRecord(raw) || Object.keys(raw).length > 32) return invalid("Unit factors require a bounded record of integer powers");
+  const result: [string, number][] = [];
+  for (const [unit, power] of Object.entries(raw)) {
+    if (!isDiagnosticToken(unit) || typeof power !== "number" || !Number.isSafeInteger(power) || Math.abs(power) > 32)
+      return invalid("Unit factors require valid unit names and integer powers between -32 and 32");
+    if (power !== 0) result.push([unit, power]);
+  }
+  return Object.fromEntries(result.sort(([a], [b]) => a.localeCompare(b)));
+}
+function combine(left: Factors, right: Factors, direction: 1 | -1): Factors {
+  const result = new Map(Object.entries(left));
+  for (const [unit, power] of Object.entries(right)) result.set(unit, (result.get(unit) ?? 0) + direction * power);
+  return normalizedFactors(Object.fromEntries(result));
+}
+export function formatAnalysisUnit(factors: Factors): string {
+  const normalized = normalizedFactors(factors);
+  const part = (sign: 1 | -1) => Object.entries(normalized).filter(([, power]) => power * sign > 0).map(([unit, power]) => {
+    const atom = /[*/^()[\]{}]/.test(unit) ? `[${unit}]` : unit;
+    return Math.abs(power) === 1 ? atom : `${atom}^${Math.abs(power)}`;
+  }).join("*");
+  const numerator = part(1) || "1";
+  const denominator = part(-1);
+  return denominator ? `${numerator}/${denominator.includes("*") ? `(${denominator})` : denominator}` : numerator;
+}
+
+/** Validates a bounded dependency graph and resolves dimensions without evaluating any values. */
+export function compileAnalysisExpressions(definition: AnalysisDefinition): readonly CompiledAnalysisExpression[] {
+  const derived = definition.derivedMeasures ?? [];
+  if (derived.length > 64) return invalid("At most 64 derived measures are supported", undefined, "expression-limit");
+  const base = new Map(definition.measures.map((m) => [m.id, m]));
+  const declarations = new Map(derived.map((m) => [m.id, m]));
+  if (base.size !== definition.measures.length || declarations.size !== derived.length || derived.some((m) => !isDiagnosticToken(m.id) || base.has(m.id)))
+    return invalid("Base and derived measure IDs must be distinct valid tokens");
+  const compiled = new Map<string, CompiledAnalysisExpression>();
+  const visiting = new Set<string>();
+  let totalNodes = 0;
+  const resolve = (id: string): Factors => {
+    const raw = base.get(id);
+    if (raw) return normalizedFactors(raw.unitFactors ?? { [raw.unit]: 1 });
+    const prior = compiled.get(id);
+    if (prior) return prior.unitFactors;
+    const measure = declarations.get(id);
+    if (!measure) return invalid(`Unknown measure ${id}`, undefined, "unknown-reference");
+    if (visiting.has(id)) return invalid(`Derived measure cycle at ${id}`, undefined, "cycle");
+    visiting.add(id);
+    const dependencies = new Set<string>();
+    const walk = (raw: unknown, depth: number, ancestors: ReadonlySet<object>): Factors => {
+      if (++totalNodes > 1024 || depth > 16) return invalid("Derived expressions exceed 1024 total nodes or 16 nested levels", undefined, "expression-limit");
+      if (!isDiagnosticPlainRecord(raw)) return invalid("Expression nodes must be objects");
+      if (ancestors.has(raw)) return invalid("Expression contains an object cycle", undefined, "cycle");
+      const next = new Set(ancestors).add(raw);
+      const keys: Record<string, string[]> = { measure: ["op", "measureId"], exposure: ["op", "exposureId"], constant: ["op", "value", "unitFactors"], add: ["op", "terms"], subtract: ["op", "left", "right"], multiply: ["op", "left", "right"], divide: ["op", "numerator", "denominator"] };
+      const allowed = typeof raw.op === "string" && Object.hasOwn(keys, raw.op) ? keys[raw.op] : undefined;
+      if (!allowed || Object.keys(raw).some((key) => !allowed.includes(key))) return invalid("Unknown expression operator or field");
+      if (raw.op === "measure") {
+        if (!isDiagnosticToken(raw.measureId)) return invalid("Invalid measure reference");
+        dependencies.add(raw.measureId);
+        return resolve(raw.measureId);
+      }
+      if (raw.op === "exposure") {
+        const exposure = definition.exposures.find((item) => item.id === raw.exposureId);
+        if (!exposure) return invalid(`Unknown exposure ${String(raw.exposureId)}`, undefined, "unknown-reference");
+        return normalizedFactors({ [exposure.unit]: 1 });
+      }
+      if (raw.op === "constant") {
+        if (typeof raw.value !== "number" || !Number.isFinite(raw.value)) return invalid("Constants must be finite numbers");
+        return normalizedFactors(raw.unitFactors);
+      }
+      if (raw.op === "add") {
+        if (!Array.isArray(raw.terms) || raw.terms.length < 1 || raw.terms.length > 32) return invalid("Addition requires 1 to 32 terms");
+        const terms = raw.terms.map((term) => walk(term, depth + 1, next));
+        if (terms.some((term) => canonicalJson(term) !== canonicalJson(terms[0]))) return invalid("Addition requires matching units", undefined, "incompatible-semantics");
+        return terms[0]!;
+      }
+      const left = walk(raw.op === "divide" ? raw.numerator : raw.left, depth + 1, next);
+      const right = walk(raw.op === "divide" ? raw.denominator : raw.right, depth + 1, next);
+      if (raw.op === "subtract") {
+        if (canonicalJson(left) !== canonicalJson(right)) return invalid("Subtraction requires matching units", undefined, "incompatible-semantics");
+        return left;
+      }
+      return combine(left, right, raw.op === "divide" ? -1 : 1);
+    };
+    const unitFactors = walk(measure.expression, 0, new Set());
+    if (measure.developmentSemantics !== "point-in-time") {
+      const dimensionlessConstant = (expression: AnalysisMeasureExpression) => expression.op === "constant" && Object.keys(normalizedFactors(expression.unitFactors)).length === 0;
+      const checkStage = (expression: AnalysisMeasureExpression): void => {
+        if (expression.op === "constant") return;
+        if (expression.op === "measure") {
+          const referenced = base.get(expression.measureId) ?? declarations.get(expression.measureId)!;
+          if (referenced.developmentSemantics !== measure.developmentSemantics)
+            invalid("Cumulative/incremental expressions require components with matching development meaning", undefined, "incompatible-semantics");
+          return;
+        }
+        if (expression.op === "add") { expression.terms.forEach(checkStage); return; }
+        if (expression.op === "subtract") { checkStage(expression.left); checkStage(expression.right); return; }
+        if (expression.op === "multiply" && dimensionlessConstant(expression.left)) { checkStage(expression.right); return; }
+        if (expression.op === "multiply" && dimensionlessConstant(expression.right)) { checkStage(expression.left); return; }
+        if (expression.op === "divide" && dimensionlessConstant(expression.denominator)) { checkStage(expression.numerator); return; }
+        invalid("Ratios, products and exposure expressions require point-in-time development meaning unless scaling by a dimensionless constant", undefined, "incompatible-semantics");
+      };
+      checkStage(measure.expression);
+    }
+    compiled.set(id, { definition: measure, unit: formatAnalysisUnit(unitFactors), unitFactors, dependencies: [...dependencies].sort() });
+    visiting.delete(id);
+    return unitFactors;
+  };
+  for (const measure of derived) resolve(measure.id);
+  return snapshotDiagnosticJson([...compiled.values()]);
+}
+
+/** Resolves requested outputs and their transitive statistic dependencies. */
+export function analysisExpressionDependencies(compiled: readonly CompiledAnalysisExpression[], requested: ReadonlySet<string>): ReadonlySet<string> {
+  const dependencies = new Set(requested);
+  const pending = [...requested];
+  while (pending.length) {
+    const id = pending.pop()!;
+    for (const dependency of compiled.find((item) => item.definition.id === id)?.dependencies ?? []) {
+      if (!dependencies.has(dependency)) { dependencies.add(dependency); pending.push(dependency); }
+    }
+  }
+  return dependencies;
+}
+
+/** Executes post-aggregation expressions on one exact origin/evaluation coordinate. */
+export function evaluateAnalysisExpressions(input: {
+  readonly definition: AnalysisDefinition;
+  readonly values: readonly AnalysisResultValue[];
+  readonly coordinates: AnalysisResultValue["coordinates"];
+  readonly exposures: ReadonlyMap<string, number>;
+  readonly exposureFindings: ReadonlyMap<string, readonly CustomizationCapabilityFinding[]>;
+  readonly requested: ReadonlySet<string>;
+}): readonly AnalysisResultValue[] {
+  const compiled = compileAnalysisExpressions(input.definition);
+  if (compiled.length === 0) return [];
+  for (const id of input.requested)
+    if (!input.definition.measures.some((measure) => measure.id === id) && !compiled.some((item) => item.definition.id === id))
+      return invalid(`Unknown requested measure ${id}`, undefined, "unknown-reference");
+  const required = analysisExpressionDependencies(compiled, input.requested);
+  for (const value of input.values) {
+    if (canonicalJson(value.coordinates) !== canonicalJson(input.coordinates))
+      return invalid("Expression components must share the exact origin/evaluation coordinate", undefined, "incompatible-semantics");
+    const measure = input.definition.measures.find((m) => m.id === value.measureId);
+    if (!measure || value.unit !== measure.unit || (value.value !== null && !Number.isFinite(value.value)))
+      return invalid("Expression components must match declared base measures, units and finite values", undefined, "incompatible-semantics");
+  }
+  if (new Set(input.values.map((value) => value.measureId)).size !== input.values.length)
+    return invalid("Expression components contain duplicate measure results");
+  const values = new Map(input.values.map((value) => [value.measureId, value]));
+  const output: AnalysisResultValue[] = [];
+  for (const item of compiled) {
+    if (!required.has(item.definition.id)) continue;
+    const components = new Map<string, AnalysisDerivedComponent>();
+    const findings: CustomizationCapabilityFinding[] = [];
+    const unavailable = (message: string): null => {
+      findings.push({ code: "missing-prerequisite", capability: "derived-analysis-measures", path: `$.derivedMeasures.${item.definition.id}`, message });
+      return null;
+    };
+    let numerator: number | null = null;
+    let denominator: number | null = null;
+    const evaluate = (expression: AnalysisMeasureExpression, root = false): number | null => {
+      if (expression.op === "constant") return expression.value;
+      if (expression.op === "measure") {
+        const value = values.get(expression.measureId);
+        if (value) {
+          components.set(`measure:${expression.measureId}`, { kind: "measure", id: expression.measureId, unit: value.unit, value: value.value, status: value.status, contributingObservations: value.contributingObservations, excludedObservations: value.excludedObservations });
+          findings.push(...value.findings);
+        } else {
+          const unit = input.definition.measures.find((m) => m.id === expression.measureId)?.unit ?? compiled.find((m) => m.definition.id === expression.measureId)!.unit;
+          components.set(`measure:${expression.measureId}`, { kind: "measure", id: expression.measureId, unit, value: null, status: "unavailable", contributingObservations: 0, excludedObservations: 0 });
+        }
+        return !value || value.status !== "available" || value.value === null || value.excludedObservations > 0
+          ? unavailable(`Measure ${expression.measureId} requires a complete available result`) : value.value;
+      }
+      if (expression.op === "exposure") {
+        const value = input.exposures.get(expression.exposureId);
+        const exposureFindings = input.exposureFindings.get(expression.exposureId) ?? [];
+        findings.push(...exposureFindings);
+        const available = value !== undefined && Number.isFinite(value) && exposureFindings.length === 0;
+        components.set(`exposure:${expression.exposureId}`, { kind: "exposure", id: expression.exposureId, unit: input.definition.exposures.find((e) => e.id === expression.exposureId)!.unit, value: available ? value : null, status: available ? "available" : "unavailable", contributingObservations: 0, excludedObservations: 0 });
+        return available ? value : unavailable(`Exposure ${expression.exposureId} requires an available allocated result`);
+      }
+      let value: number;
+      if (expression.op === "add") {
+        const terms = expression.terms.map((term) => evaluate(term));
+        if (terms.some((term) => term === null)) return null;
+        value = terms.reduce<number>((sum, term) => sum + term!, 0);
+      } else {
+        const left = evaluate(expression.op === "divide" ? expression.numerator : expression.left);
+        const right = evaluate(expression.op === "divide" ? expression.denominator : expression.right);
+        if (root && expression.op === "divide") { numerator = left; denominator = right; }
+        if (left === null || right === null) return null;
+        if (expression.op === "divide" && right <= 0) return unavailable("Division requires a strictly positive denominator");
+        value = expression.op === "subtract" ? left - right : expression.op === "multiply" ? left * right : left / right;
+      }
+      return Number.isFinite(value) ? value : unavailable("Expression arithmetic overflowed; no finite result is available");
+    };
+    const value = evaluate(item.definition.expression, true);
+    const result: AnalysisResultValue = {
+      measureId: item.definition.id, unit: item.unit, coordinates: input.coordinates, value,
+      status: value === null ? "unavailable" : "available", contributingObservations: 0, excludedObservations: 0, exact: true,
+      numerator, denominator, findings: [...new Map(findings.map((finding) => [canonicalJson(finding), finding])).values()],
+      derivation: { stage: "post-aggregation", unitFactors: item.unitFactors, components: [...components.values()] },
+    };
+    values.set(result.measureId, result);
+    output.push(result);
+  }
+  return snapshotDiagnosticJson(output);
+}

package/src/analysisFinancialUnits.ts

@@ -0,0 +1,55 @@
+import type { AnalysisDefinition, AnalysisRecipe } from "./customizationContracts.js";
+import { formatAnalysisUnit } from "./analysisExpressions.js";
+import { DiagnosticValidationError } from "./types.js";
+
+const incompatible = (message: string): never => {
+  throw new DiagnosticValidationError([{ domain: "configuration", code: "incompatible-semantics", path: "$.recipe.steps", message }]);
+};
+
+/** Resolves the declared output units of an ordered financial pipeline before calculating results. */
+export function resolveAnalysisFinancialUnits(definition: AnalysisDefinition, recipe: AnalysisRecipe): AnalysisDefinition {
+  const step = recipe.steps.find((item) => item.kind === "apply-financial-pipeline");
+  if (step?.kind !== "apply-financial-pipeline") return definition;
+  const stages = step.stageIds.map((id) => definition.financialAdjustments?.find((item) => item.id === id));
+  if (!stages.some((stage) => stage?.kind === "currency")) return definition;
+  const rawUnits = new Map<string, Set<string>>();
+  for (const measure of definition.measures) {
+    if (measure.statistic.kind !== "sum") continue;
+    const id = measure.statistic.measureId;
+    const units = rawUnits.get(id) ?? new Set<string>();
+    units.add(measure.unit);
+    rawUnits.set(id, units);
+  }
+  const rawUnit = (id: string): string => {
+    const units = rawUnits.get(id);
+    if (!units || units.size !== 1) return incompatible(`Currency conversion needs one declared sum unit for ${id}`);
+    return [...units][0]!;
+  };
+  const initialUnit = rawUnit(step.amountMeasureId);
+  let outputUnit = initialUnit;
+  for (const stage of stages) {
+    if (!stage) continue;
+    if (stage.kind === "currency") {
+      if (stage.fromUnit !== outputUnit) return incompatible(`Currency stage ${stage.id} expects ${stage.fromUnit}, not ${outputUnit}`);
+      outputUnit = stage.toUnit;
+    } else if (stage.kind === "include-expense" || stage.kind === "exclude-expense" || stage.kind === "net-recovery") {
+      const id = stage.kind === "net-recovery" ? stage.recoveryMeasureId : stage.expenseMeasureId;
+      if (rawUnit(id) !== outputUnit) return incompatible(`Financial component ${id} must use the current pipeline unit ${outputUnit}`);
+    }
+  }
+  const effectiveUnit = (id: string): string => id === step.amountMeasureId ? outputUnit : definition.exposures.find((e) => e.id === id)?.unit ?? rawUnit(id);
+  const measures = definition.measures.map((measure) => {
+    const statistic = measure.statistic;
+    if (statistic.kind === "ratio") {
+      if (statistic.numeratorMeasureId !== step.amountMeasureId && statistic.denominatorMeasureId !== step.amountMeasureId) return measure;
+      const numerator = effectiveUnit(statistic.numeratorMeasureId);
+      const denominator = effectiveUnit(statistic.denominatorMeasureId);
+      const factors = numerator === denominator ? {} : { [numerator]: 1, [denominator]: -1 };
+      return { ...measure, unit: numerator === denominator ? "ratio" : formatAnalysisUnit(factors), unitFactors: factors };
+    }
+    if ("measureId" in statistic && statistic.measureId === step.amountMeasureId)
+      return { ...measure, unit: outputUnit, unitFactors: { [outputUnit]: 1 } };
+    return measure;
+  });
+  return { ...definition, measures };
+}

package/src/analysisRecipe.ts

@@ -1,4 +1,5 @@
 import { canonicalJson, fnv1a64 } from "./canonical.js";
+import { CORE_PACKAGE_VERSION } from "./version.js";
 import type {
   AnalysisDefinition,
   AnalysisPredicate,
@@ -8,7 +9,6 @@ import type {
   AnalysisScenario,
   AnalysisScenarioChange,
   AnalysisScenarioGrid,
-  AnalysisScenarioDifference,
   AnalysisScenarioRun,
   AnalysisRollForward,
   AnalysisScenarioBridgeStep,
@@ -22,6 +22,11 @@ import type {
   PreparedHistoricalObservation,
 } from "./customizationContracts.js";
 import { calculateAnalysisStatistic } from "./descriptiveStatistics.js";
+import { calculateRecipeExposureRatio } from "./analysisRecipeStatistics.js";
+import { compileAnalysisExpressions, analysisExpressionDependencies, evaluateAnalysisExpressions } from "./analysisExpressions.js";
+import { resolveAnalysisFinancialUnits } from "./analysisFinancialUnits.js";
+import { compareAnalysisEvaluations, compareAnalysisResults } from "./analysisComparison.js";
+export { compareAnalysisResults } from "./analysisComparison.js";
 import { isDiagnosticToken, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
 import { earnAndAllocateExposure } from "./exposureEarning.js";
 import { selectExposureRevisions, selectExposureValuation } from "./exposureRevisions.js";
@@ -72,7 +77,7 @@ function recipeIssues(
       hasCalculate = true;
     if (step.kind === "calculate")
       step.measureIds.forEach((id) => {
-        if (!definition.measures.some((measure) => measure.id === id))
+        if (![...definition.measures, ...(definition.derivedMeasures ?? [])].some((measure) => measure.id === id))
           issues.push({ domain: "configuration", code: "unknown-reference", path: `$.recipe.steps[${index}].measureIds`, message: `Unknown measure ${id}` });
       });
     if (step.kind === "earn-exposure")
@@ -163,6 +168,8 @@ export function runAnalysisRecipe(input: {
 }): AnalysisResult {
   const issues = recipeIssues(input.recipe, input.definition, input.history);
   if (issues.length > 0) throw new DiagnosticValidationError(issues);
+  const outputDefinition = resolveAnalysisFinancialUnits(input.definition, input.recipe);
+  const expressions = compileAnalysisExpressions(outputDefinition);
   const prepared = prepareHistoricalDataset(input.history);
   const evaluationDate = input.evaluationDate ?? maxEvaluationDate(prepared.observations);
   const selected = selectedAt(prepared.observations, evaluationDate, input.definition.period.observationSelection);
@@ -173,7 +180,9 @@ export function runAnalysisRecipe(input: {
   const reportingPopulation = reportingSelection.matches;
   const reportingKeys = new Set(reportingPopulation.map(key));
   let effective = financialPopulation;
-  let financialExecutionFindings: readonly CustomizationCapabilityFinding[] = [...financialSelection.findings];
+  // A conflicted or incomplete history cannot authorize arithmetic over the
+  // surviving subset as though it were the complete financial population.
+  let financialExecutionFindings: readonly CustomizationCapabilityFinding[] = [...prepared.findings, ...financialSelection.findings];
   const reportingExecutionFindings: readonly CustomizationCapabilityFinding[] = [...reportingSelection.findings];
 
   const financialStep = input.recipe.steps.find((step) => step.kind === "apply-financial-terms");
@@ -182,7 +191,7 @@ export function runAnalysisRecipe(input: {
     const applied = applyFinancialTerms({
       observations: financialPopulation,
       terms,
-      completeFinancialPopulation: true,
+      completeFinancialPopulation: financialExecutionFindings.length === 0,
       measureDefinitions: input.definition.measures,
       reportingClaims: reportingPopulation.map((observation) => ({ sourceNamespace: observation.sourceNamespace, claimId: observation.claimId })),
     });
@@ -216,7 +225,7 @@ export function runAnalysisRecipe(input: {
       amountMeasureId: pipelineStep.amountMeasureId,
       inputUnit: input.definition.measures.find((measure) => measure.statistic.kind === "sum" && measure.statistic.measureId === pipelineStep.amountMeasureId)?.unit ?? "unknown-unit",
       stages,
-      completeFinancialPopulation: true,
+      completeFinancialPopulation: financialExecutionFindings.length === 0,
       reportingClaims: reportingPopulation.map((observation) => ({ sourceNamespace: observation.sourceNamespace, claimId: observation.claimId })),
     });
     if (applied.status === "available") {
@@ -275,12 +284,18 @@ export function runAnalysisRecipe(input: {
     if (group === undefined) groups.set(origin.originId, { label: origin.label, observations: [observation] });
     else group.observations.push(observation);
   }
-  const measureIds = new Set(
+  const requestedMeasureIds = new Set(
     input.recipe.steps.filter((step) => step.kind === "calculate").flatMap((step) => step.measureIds),
   );
+  const measureIds = analysisExpressionDependencies(expressions, requestedMeasureIds);
+  // When preparation excluded every observation, retain visible unavailable
+  // output instead of hiding the preparation findings in an empty result.
+  if (groups.size === 0 && prepared.findings.length > 0)
+    groups.set("unassigned", { label: "Unavailable history", observations: [] });
   const values: AnalysisResultValue[] = [];
   for (const [originId, group] of [...groups].sort(([left], [right]) => left.localeCompare(right))) {
-    for (const measure of input.definition.measures.filter((candidate) => measureIds.has(candidate.id))) {
+    const start = values.length;
+    for (const measure of outputDefinition.measures.filter((candidate) => measureIds.has(candidate.id))) {
       let measureObservations = measure.populationScopeId === input.definition.scopes.financial.id
         ? group.observations
         : group.observations.filter((observation) => reportingKeys.has(key(observation)));
@@ -321,27 +336,17 @@ export function runAnalysisRecipe(input: {
       }
       let statistic;
       if (measure.statistic.kind === "ratio" && exposedByTarget.get(originId)?.has(measure.statistic.denominatorMeasureId)) {
-        const ratio = measure.statistic;
-        const numerator = measureObservations.reduce((total, observation) => {
-          const value = observation.measures[ratio.numeratorMeasureId];
-          return total + (typeof value === "number" ? value : 0);
-        }, 0);
-        const denominator = exposedByTarget.get(originId)!.get(ratio.denominatorMeasureId)!;
-        const seed = measureObservations[0];
-        if (seed === undefined) {
-          statistic = calculateAnalysisStatistic({ measure, observations: [], selection: { kind: "all-observations" } });
-        } else {
-        const synthetic = snapshotDiagnosticJson({ ...seed, measures: {
-          [ratio.numeratorMeasureId]: numerator,
-          [ratio.denominatorMeasureId]: denominator,
-        } });
-        statistic = calculateAnalysisStatistic({ measure, observations: [synthetic], selection: { kind: "all-observations" } });
-        }
+        statistic = calculateRecipeExposureRatio({
+          measure,
+          observations: measureObservations,
+          selection: { kind: "evaluation-date", evaluationDate, observationSelection: input.definition.period.observationSelection },
+          exposure: exposedByTarget.get(originId)!.get(measure.statistic.denominatorMeasureId)!,
+        });
       } else {
         statistic = calculateAnalysisStatistic({
           measure,
           observations: measureObservations,
-          selection: { kind: "evaluation-date", evaluationDate, observationSelection: "exact" },
+          selection: { kind: "evaluation-date", evaluationDate, observationSelection: input.definition.period.observationSelection },
         });
       }
       values.push({
@@ -358,9 +363,18 @@ export function runAnalysisRecipe(input: {
         findings: statistic.findings,
       });
     }
+    values.push(...evaluateAnalysisExpressions({
+      definition: outputDefinition,
+      values: values.slice(start),
+      coordinates: { originId, originLabel: group.label, evaluationDate },
+      exposures: exposedByTarget.get(originId) ?? new Map(),
+      exposureFindings: exposureFindingsByMeasure,
+      requested: requestedMeasureIds,
+    }));
   }
   if (originFailures.length > 0) {
-    for (const measure of input.definition.measures.filter((candidate) => measureIds.has(candidate.id))) {
+    const start = values.length;
+    for (const measure of outputDefinition.measures.filter((candidate) => measureIds.has(candidate.id))) {
       const originFindings = originFailures
         .filter(({ observation }) => measure.populationScopeId === input.definition.scopes.financial.id || reportingKeys.has(key(observation)))
         .map(({ finding }) => finding);
@@ -379,13 +393,22 @@ export function runAnalysisRecipe(input: {
         findings: originFindings,
       });
     }
+    values.push(...evaluateAnalysisExpressions({
+      definition: outputDefinition,
+      values: values.slice(start),
+      coordinates: { originId: "unassigned", originLabel: "Unavailable origin", evaluationDate },
+      exposures: new Map(), exposureFindings: exposureFindingsByMeasure, requested: requestedMeasureIds,
+    }));
   }
   const calculationInput = {
+    corePackageVersion: CORE_PACKAGE_VERSION,
     historyRevisionId: prepared.calculationRevisionId,
+    historyFindings: prepared.findings,
     definition: input.definition,
     recipe: input.recipe,
     evaluationDate,
     exposureRevisionIds: exposureCalculationRevisions.sort(),
+    exposureTargets: input.exposureTargets ?? [],
   };
   const lineageInput = {
     historyRevisionId: prepared.lineageRevisionId,
@@ -420,12 +443,13 @@ export function applyAnalysisScenario(
   }
   if (scenarioIssues.length > 0) throw new DiagnosticValidationError(scenarioIssues);
   let reportingPredicate: AnalysisPredicate = definition.scopes.reporting.predicate;
+  for (const change of scenario.changes)
+    if (change.kind === "reporting-predicate") reportingPredicate = change.predicate;
   const terms = definition.financialTerms.map((term) => {
     let current = term;
     for (const change of scenario.changes) {
-      if (change.kind === "reporting-predicate") reportingPredicate = change.predicate;
-      else if (change.termId === term.id && change.kind === "financial-term-limit") current = { ...current, limit: change.limit };
-      else if (change.termId === term.id && change.kind === "financial-term-attachment")
+      if (change.kind === "financial-term-limit" && change.termId === term.id) current = { ...current, limit: change.limit };
+      else if (change.kind === "financial-term-attachment" && change.termId === term.id)
         current = current.kind === "policy-aggregate" ? { ...current, deductible: change.amount } : { ...current, attachment: change.amount };
     }
     return current;
@@ -438,39 +462,6 @@ export function applyAnalysisScenario(
   });
 }
 
-export function compareAnalysisResults(
-  baseline: AnalysisResult,
-  scenario: AnalysisResult,
-): readonly AnalysisScenarioDifference[] {
-  const scenarioValues = new Map(scenario.values.map((value) => [canonicalJson([value.measureId, value.coordinates]), value]));
-  return snapshotDiagnosticJson(baseline.values.map((value) => {
-    const compared = scenarioValues.get(canonicalJson([value.measureId, value.coordinates]));
-    if (compared !== undefined && compared.unit !== value.unit)
-      throw new DiagnosticValidationError([{
-        domain: "configuration",
-        code: "incompatible-semantics",
-        path: `$.values.${value.measureId}.unit`,
-        message: `Cannot compare ${value.unit} with ${compared.unit}`,
-      }]);
-    const baselineValue = value.value;
-    const scenarioValue = compared?.value ?? null;
-    const absoluteDifference = baselineValue === null || scenarioValue === null ? null : scenarioValue - baselineValue;
-    const percentageDifference =
-      absoluteDifference === null || baselineValue === null || baselineValue === 0
-        ? null
-        : absoluteDifference / baselineValue;
-    return {
-      measureId: value.measureId,
-      unit: value.unit,
-      coordinates: value.coordinates,
-      baselineValue,
-      scenarioValue,
-      absoluteDifference,
-      percentageDifference,
-    };
-  }));
-}
-
 /** Runs a bounded list of controlled scenarios against one immutable baseline. */
 export function runAnalysisScenarios(input: {
   readonly history: HistoricalDatasetInput;
@@ -618,7 +609,7 @@ export function runAnalysisScenarioGrid(
 
 /** Complete dependency identity for exact full-result reuse, including lineage. */
 export function analysisRecipeDependencyIdentity(input: Parameters<typeof runAnalysisRecipe>[0]): string {
-  return `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({ kind: "analysis-recipe-dependencies", input }))}`;
+  return `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({ kind: "analysis-recipe-dependencies", corePackageVersion: CORE_PACKAGE_VERSION, input }))}`;
 }
 
 /** Uses caller-owned cache storage; a hit is returned only for the complete dependency identity. */
@@ -656,7 +647,7 @@ export function rollForwardAnalysisRecipe(input: Parameters<typeof runAnalysisRe
     currentEvaluationDate,
     priorResult,
     currentResult,
-    differences: compareAnalysisResults(priorResult, currentResult),
+    differences: compareAnalysisEvaluations(priorResult, currentResult, priorEvaluationDate, currentEvaluationDate),
   });
 }
 

package/src/analysisRecipeStatistics.ts

@@ -0,0 +1,59 @@
+import type {
+  AnalysisMeasureDefinitionV1,
+  AnalysisObservationSelection,
+  AnalysisStatisticResult,
+  PreparedHistoricalObservation,
+} from "./customizationContracts.js";
+import { calculateAnalysisStatistic } from "./descriptiveStatistics.js";
+import { snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+
+/** A separate exposure population contributes its denominator once per origin. */
+export function calculateRecipeExposureRatio(input: {
+  readonly measure: AnalysisMeasureDefinitionV1;
+  readonly observations: readonly PreparedHistoricalObservation[];
+  readonly selection: Extract<AnalysisObservationSelection, { kind: "evaluation-date" }>;
+  readonly exposure: number;
+}): AnalysisStatisticResult {
+  const { measure, observations, selection, exposure } = input;
+  if (measure.statistic.kind !== "ratio") throw new Error("An exposure ratio requires a ratio statistic");
+  const numerator = calculateAnalysisStatistic({
+    measure: { ...measure, statistic: { kind: "sum", measureId: measure.statistic.numeratorMeasureId } },
+    observations,
+    selection,
+  });
+  // Unknown amounts cannot be treated as zeros while the complete exposure
+  // population still contributes to the denominator.
+  if (numerator.status !== "available" || numerator.excludedObservations > 0) {
+    return snapshotDiagnosticJson({
+      ...numerator,
+      value: null,
+      status: "unavailable" as const,
+      numerator: numerator.value,
+      denominator: exposure,
+      findings: [...numerator.findings, {
+        capability: "descriptive-statistics" as const,
+        code: "missing-prerequisite" as const,
+        path: "$.measure.statistic.numeratorMeasureId",
+        message: "An exposure ratio requires observed numerator amounts for the selected population",
+      }],
+    });
+  }
+  const aggregate: PreparedHistoricalObservation = {
+    ...observations[0]!,
+    evaluationDate: selection.evaluationDate,
+    measures: {
+      [measure.statistic.numeratorMeasureId]: numerator.value,
+      [measure.statistic.denominatorMeasureId]: exposure,
+    },
+  };
+  const ratio = calculateAnalysisStatistic({
+    measure,
+    observations: [aggregate],
+    selection: { ...selection, observationSelection: "exact" },
+  });
+  return snapshotDiagnosticJson({
+    ...ratio,
+    contributingObservations: numerator.contributingObservations,
+    excludedObservations: numerator.excludedObservations,
+  });
+}

package/src/customizationContracts.ts

@@ -13,6 +13,7 @@ export const CUSTOMIZATION_CAPABILITIES = [
   "exposure-earning",
   "typed-populations",
   "descriptive-statistics",
+  "derived-analysis-measures",
   "reserving-triangle-adapter",
   "bounded-execution",
   "shared-financial-terms",
@@ -426,12 +427,39 @@ export type AnalysisStatisticDefinition =
 export interface AnalysisMeasureDefinitionV1 {
   readonly id: string;
   readonly unit: string;
+  /** Optional explicit dimensions for composing already-derived units. Unit labels are otherwise opaque atoms. */
+  readonly unitFactors?: Readonly<Record<string, number>>;
   readonly developmentSemantics: "cumulative" | "incremental" | "point-in-time";
   readonly statistic: AnalysisStatisticDefinition;
   readonly populationScopeId: string;
   readonly condition?: AnalysisPredicate;
 }
 
+export type AnalysisMeasureExpression =
+  | { readonly op: "measure"; readonly measureId: string }
+  | { readonly op: "exposure"; readonly exposureId: string }
+  | { readonly op: "constant"; readonly value: number; readonly unitFactors: Readonly<Record<string, number>> }
+  | { readonly op: "add"; readonly terms: readonly AnalysisMeasureExpression[] }
+  | { readonly op: "subtract" | "multiply"; readonly left: AnalysisMeasureExpression; readonly right: AnalysisMeasureExpression }
+  | { readonly op: "divide"; readonly numerator: AnalysisMeasureExpression; readonly denominator: AnalysisMeasureExpression };
+
+/** Post-aggregation arithmetic. Each referenced statistic retains its own population and condition. */
+export interface AnalysisDerivedMeasureDefinition {
+  readonly id: string;
+  readonly expression: AnalysisMeasureExpression;
+  readonly developmentSemantics: "point-in-time" | "cumulative" | "incremental";
+}
+
+export interface AnalysisDerivedComponent {
+  readonly kind: "measure" | "exposure";
+  readonly id: string;
+  readonly unit: string;
+  readonly value: number | null;
+  readonly status: "available" | "unavailable";
+  readonly contributingObservations: number;
+  readonly excludedObservations: number;
+}
+
 export type AnalysisObservationSelection =
   | {
       readonly kind: "evaluation-date";
@@ -562,6 +590,7 @@ export interface AnalysisDefinition {
   readonly period: AnalysisPeriodDefinition;
   readonly exposures: readonly ExposureMeasureDefinitionV1[];
   readonly measures: readonly AnalysisMeasureDefinitionV1[];
+  readonly derivedMeasures?: readonly AnalysisDerivedMeasureDefinition[];
   readonly financialTerms: readonly FinancialTermDefinition[];
   readonly financialAdjustments?: readonly FinancialAmountAdjustment[];
 }
@@ -672,6 +701,12 @@ export interface AnalysisResultValue {
   readonly numerator: number | null;
   readonly denominator: number | null;
   readonly findings: readonly CustomizationCapabilityFinding[];
+  /** Counts on a derived value are not additive population counts; inspect each component instead. */
+  readonly derivation?: {
+    readonly stage: "post-aggregation";
+    readonly unitFactors: Readonly<Record<string, number>>;
+    readonly components: readonly AnalysisDerivedComponent[];
+  };
 }
 
 export interface AnalysisResult {