@actuarial-ts/core 0.7.0 → 0.8.0

package/src/analysisRecipe.ts

@@ -0,0 +1,696 @@
+import { canonicalJson, fnv1a64 } from "./canonical.js";
+import type {
+  AnalysisDefinition,
+  AnalysisPredicate,
+  AnalysisRecipe,
+  AnalysisResult,
+  AnalysisResultValue,
+  AnalysisScenario,
+  AnalysisScenarioChange,
+  AnalysisScenarioGrid,
+  AnalysisScenarioDifference,
+  AnalysisScenarioRun,
+  AnalysisRollForward,
+  AnalysisScenarioBridgeStep,
+  AnalysisResultCache,
+  CustomizationResourceLimits,
+  CustomizationCapabilityFinding,
+  CustomizationExposureObservation,
+  ExposureAllocationTarget,
+  ExposureRevisionSelection,
+  HistoricalDatasetInput,
+  PreparedHistoricalObservation,
+} from "./customizationContracts.js";
+import { calculateAnalysisStatistic } from "./descriptiveStatistics.js";
+import { isDiagnosticToken, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { earnAndAllocateExposure } from "./exposureEarning.js";
+import { selectExposureRevisions, selectExposureValuation } from "./exposureRevisions.js";
+import { applyFinancialTerms } from "./financialTerms.js";
+import { applyFinancialPipeline } from "./financialPipeline.js";
+import { prepareHistoricalDataset } from "./historyPreparation.js";
+import { assignAnalysisOrigin } from "./policyPeriods.js";
+import { evaluateAnalysisScope } from "./populations.js";
+import { DiagnosticValidationError, type DiagnosticValidationIssue } from "./types.js";
+
+function key(observation: PreparedHistoricalObservation): string {
+  return canonicalJson([observation.sourceNamespace, observation.claimId]);
+}
+
+function recipeIssues(
+  recipe: AnalysisRecipe,
+  definition: AnalysisDefinition,
+  history: HistoricalDatasetInput,
+): DiagnosticValidationIssue[] {
+  const issues: DiagnosticValidationIssue[] = [];
+  if (recipe.analysisDefinitionId !== definition.id)
+    issues.push({ domain: "configuration", code: "invalid-input-relationship", path: "$.recipe.analysisDefinitionId", message: "Recipe and analysis definition IDs do not match" });
+  if (recipe.steps[0]?.kind !== "prepare-history")
+    issues.push({ domain: "configuration", code: "invalid-configuration", path: "$.recipe.steps", message: "Recipe must begin with prepare-history" });
+  const supported = new Set(["prepare-history", "assign-periods", "earn-exposure", "apply-financial-terms", "apply-financial-pipeline", "calculate"]);
+  let priorOrder = -1;
+  let hasCalculate = false;
+  const stepOrder: Readonly<Record<string, number>> = {
+    "prepare-history": 0,
+    "assign-periods": 1,
+    "earn-exposure": 2,
+    "apply-financial-terms": 3,
+    "apply-financial-pipeline": 3,
+    calculate: 4,
+  };
+  recipe.steps.forEach((step, index) => {
+    if (!supported.has(step.kind))
+      issues.push({ domain: "configuration", code: "invalid-configuration", path: `$.recipe.steps[${index}]`, message: `Recipe step ${step.kind} is not executable by this runner` });
+    const order = stepOrder[step.kind];
+    if (order !== undefined && order < priorOrder)
+      issues.push({ domain: "configuration", code: "invalid-configuration", path: `$.recipe.steps[${index}]`, message: "Recipe steps are out of execution order" });
+    if (order !== undefined) priorOrder = order;
+    if (step.kind === "prepare-history" && step.historyContractId !== history.datasetId)
+      issues.push({ domain: "configuration", code: "unknown-reference", path: `$.recipe.steps[${index}].historyContractId`, message: "prepare-history references another history contract" });
+    if (step.kind === "assign-periods" && step.analysisDefinitionId !== definition.id)
+      issues.push({ domain: "configuration", code: "unknown-reference", path: `$.recipe.steps[${index}].analysisDefinitionId`, message: "assign-periods references another definition" });
+    if (step.kind === "calculate")
+      hasCalculate = true;
+    if (step.kind === "calculate")
+      step.measureIds.forEach((id) => {
+        if (!definition.measures.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")
+      step.exposureMeasureIds.forEach((id) => {
+        if (!definition.exposures.some((exposure) => exposure.id === id))
+          issues.push({ domain: "configuration", code: "unknown-reference", path: `$.recipe.steps[${index}].exposureMeasureIds`, message: `Unknown exposure measure ${id}` });
+      });
+    if (step.kind === "apply-financial-terms")
+      step.termIds.forEach((id) => {
+        if (!definition.financialTerms.some((term) => term.id === id))
+          issues.push({ domain: "configuration", code: "unknown-reference", path: `$.recipe.steps[${index}].termIds`, message: `Unknown financial term ${id}` });
+      });
+    if (step.kind === "apply-financial-pipeline") {
+      const stageIds = new Set([...(definition.financialAdjustments ?? []).map((item) => item.id), ...definition.financialTerms.map((item) => item.id)]);
+      step.stageIds.forEach((id) => {
+        if (!stageIds.has(id)) issues.push({ domain: "configuration", code: "unknown-reference", path: `$.recipe.steps[${index}].stageIds`, message: `Unknown financial pipeline stage ${id}` });
+      });
+    }
+  });
+  if (recipe.steps.filter((step) => step.kind === "apply-financial-terms" || step.kind === "apply-financial-pipeline").length > 1)
+    issues.push({ domain: "configuration", code: "invalid-configuration", path: "$.recipe.steps", message: "Recipe permits one financial application step" });
+  if (!hasCalculate)
+    issues.push({ domain: "configuration", code: "missing-required", path: "$.recipe.steps", message: "Recipe requires a calculate step" });
+  return issues;
+}
+
+function selectedAt(
+  observations: readonly PreparedHistoricalObservation[],
+  evaluationDate: string,
+  mode: "exact" | "latest-on-or-before",
+): readonly PreparedHistoricalObservation[] {
+  if (mode === "exact") return observations.filter((observation) => observation.evaluationDate === evaluationDate);
+  const selected = new Map<string, PreparedHistoricalObservation>();
+  for (const observation of observations) {
+    if (observation.evaluationDate > evaluationDate) continue;
+    const observationKey = key(observation);
+    const prior = selected.get(observationKey);
+    if (prior === undefined || prior.evaluationDate < observation.evaluationDate) selected.set(observationKey, observation);
+  }
+  return [...selected.values()];
+}
+
+function histories(observations: readonly PreparedHistoricalObservation[]): ReadonlyMap<string, readonly PreparedHistoricalObservation[]> {
+  const result = new Map<string, PreparedHistoricalObservation[]>();
+  for (const observation of observations) {
+    const observationKey = key(observation);
+    const existing = result.get(observationKey);
+    if (existing === undefined) result.set(observationKey, [observation]);
+    else existing.push(observation);
+  }
+  return result;
+}
+
+function selectScope(
+  definition: AnalysisDefinition,
+  scope: AnalysisDefinition["scopes"]["financial"],
+  observations: readonly PreparedHistoricalObservation[],
+  historyByClaim: ReadonlyMap<string, readonly PreparedHistoricalObservation[]>,
+): { matches: PreparedHistoricalObservation[]; findings: CustomizationCapabilityFinding[] } {
+  const matches: PreparedHistoricalObservation[] = [];
+  const findings: CustomizationCapabilityFinding[] = [];
+  for (const observation of observations) {
+    const membership = evaluateAnalysisScope({
+      scope,
+      observation,
+      claimHistory: historyByClaim.get(key(observation)) ?? [],
+      dimensions: definition.dimensions,
+    });
+    if (membership.outcome === "match") matches.push(observation);
+    else if (membership.outcome === "unknown" && membership.finding !== null) findings.push(membership.finding);
+  }
+  return { matches, findings };
+}
+
+function maxEvaluationDate(observations: readonly PreparedHistoricalObservation[]): string {
+  return observations.reduce((latest, observation) => observation.evaluationDate > latest ? observation.evaluationDate : latest, "0000-01-01");
+}
+
+/** Executes the closed, deterministic recipe vocabulary over loss history and exposure inputs. */
+export function runAnalysisRecipe(input: {
+  readonly history: HistoricalDatasetInput;
+  readonly definition: AnalysisDefinition;
+  readonly recipe: AnalysisRecipe;
+  readonly exposureObservations?: readonly CustomizationExposureObservation[];
+  readonly exposureTargets?: readonly ExposureAllocationTarget[];
+  readonly exposureRevisionSelection?: ExposureRevisionSelection;
+  readonly evaluationDate?: string;
+}): AnalysisResult {
+  const issues = recipeIssues(input.recipe, input.definition, input.history);
+  if (issues.length > 0) throw new DiagnosticValidationError(issues);
+  const prepared = prepareHistoricalDataset(input.history);
+  const evaluationDate = input.evaluationDate ?? maxEvaluationDate(prepared.observations);
+  const selected = selectedAt(prepared.observations, evaluationDate, input.definition.period.observationSelection);
+  const byHistory = histories(prepared.observations);
+  const financialSelection = selectScope(input.definition, input.definition.scopes.financial, selected, byHistory);
+  const reportingSelection = selectScope(input.definition, input.definition.scopes.reporting, selected, byHistory);
+  const financialPopulation = financialSelection.matches;
+  const reportingPopulation = reportingSelection.matches;
+  const reportingKeys = new Set(reportingPopulation.map(key));
+  let effective = financialPopulation;
+  let financialExecutionFindings: readonly CustomizationCapabilityFinding[] = [...financialSelection.findings];
+  const reportingExecutionFindings: readonly CustomizationCapabilityFinding[] = [...reportingSelection.findings];
+
+  const financialStep = input.recipe.steps.find((step) => step.kind === "apply-financial-terms");
+  if (financialStep?.kind === "apply-financial-terms") {
+    const terms = financialStep.termIds.map((id) => input.definition.financialTerms.find((term) => term.id === id)!);
+    const applied = applyFinancialTerms({
+      observations: financialPopulation,
+      terms,
+      completeFinancialPopulation: true,
+      measureDefinitions: input.definition.measures,
+      reportingClaims: reportingPopulation.map((observation) => ({ sourceNamespace: observation.sourceNamespace, claimId: observation.claimId })),
+    });
+    if (applied.status === "available") {
+      const allocated = new Map(applied.claims.map((claim) => [canonicalJson([claim.sourceNamespace, claim.claimId]), claim]));
+      const sourceMeasureIds = new Set(
+        terms.flatMap((term) => {
+          const measure = input.definition.measures.find((candidate) => candidate.id === term.measureId);
+          return measure?.statistic.kind === "sum" ? [measure.statistic.measureId] : [];
+        }),
+      );
+      effective = financialPopulation.map((observation) => {
+        const result = allocated.get(key(observation));
+        if (result === undefined) return observation;
+        const measures = { ...observation.measures };
+        sourceMeasureIds.forEach((id) => { measures[id] = result.outputAmount; });
+        return snapshotDiagnosticJson({ ...observation, measures });
+      });
+    } else financialExecutionFindings = [...financialExecutionFindings, ...applied.findings];
+  }
+  const pipelineStep = input.recipe.steps.find((step) => step.kind === "apply-financial-pipeline");
+  if (pipelineStep?.kind === "apply-financial-pipeline") {
+    const stages = pipelineStep.stageIds.map((id) => {
+      const adjustment = input.definition.financialAdjustments?.find((candidate) => candidate.id === id);
+      return adjustment === undefined
+        ? { kind: "terms" as const, id, terms: [input.definition.financialTerms.find((candidate) => candidate.id === id)!] }
+        : { kind: "adjustment" as const, adjustment };
+    });
+    const applied = applyFinancialPipeline({
+      observations: financialPopulation,
+      amountMeasureId: pipelineStep.amountMeasureId,
+      inputUnit: input.definition.measures.find((measure) => measure.statistic.kind === "sum" && measure.statistic.measureId === pipelineStep.amountMeasureId)?.unit ?? "unknown-unit",
+      stages,
+      completeFinancialPopulation: true,
+      reportingClaims: reportingPopulation.map((observation) => ({ sourceNamespace: observation.sourceNamespace, claimId: observation.claimId })),
+    });
+    if (applied.status === "available") {
+      const amounts = new Map(applied.claims.map((claim) => [canonicalJson([claim.sourceNamespace, claim.claimId]), claim.outputAmount]));
+      effective = financialPopulation.map((observation) => {
+        const outputAmount = amounts.get(key(observation));
+        return outputAmount === undefined
+          ? observation
+          : snapshotDiagnosticJson({ ...observation, measures: { ...observation.measures, [pipelineStep.amountMeasureId]: outputAmount } });
+      });
+    } else financialExecutionFindings = [...financialExecutionFindings, ...applied.findings];
+  }
+
+  const exposedByTarget = new Map<string, Map<string, number>>();
+  const exposureFindingsByMeasure = new Map<string, CustomizationCapabilityFinding[]>();
+  const exposureCalculationRevisions: string[] = [];
+  const exposureLineageRevisions: string[] = [];
+  for (const step of input.recipe.steps) {
+    if (step.kind !== "earn-exposure") continue;
+    for (const id of step.exposureMeasureIds) {
+      const definition = input.definition.exposures.find((candidate) => candidate.id === id);
+      if (definition === undefined) continue;
+      const scope = input.definition.scopes.exposure.find((candidate) => candidate.id === definition.scopeId)!;
+      const measureFindings = exposureFindingsByMeasure.get(id) ?? [];
+      const valuation = selectExposureValuation({ observations: (input.exposureObservations ?? []).filter((candidate) => candidate.measureId === id), scope, evaluationDate });
+      measureFindings.push(...valuation.findings);
+      const revisions = selectExposureRevisions({
+        observations: valuation.observations,
+        selection: input.exposureRevisionSelection ?? { revisionView: { kind: "restated" }, revisionPrecedence: "sequence" },
+      });
+      measureFindings.push(...revisions.findings);
+      exposureCalculationRevisions.push(`${id}:${revisions.calculationRevisionId}`);
+      exposureLineageRevisions.push(`${id}:${revisions.lineageRevisionId}`);
+      for (const observation of revisions.observations) {
+        const result = earnAndAllocateExposure({ definition, scope, observation, targets: input.exposureTargets ?? [] });
+        measureFindings.push(...result.findings);
+        for (const allocation of result.allocations) {
+          const measures = exposedByTarget.get(allocation.targetId) ?? new Map<string, number>();
+          measures.set(id, (measures.get(id) ?? 0) + allocation.value);
+          exposedByTarget.set(allocation.targetId, measures);
+        }
+      }
+      exposureFindingsByMeasure.set(id, measureFindings);
+    }
+  }
+
+  const groups = new Map<string, { label: string; observations: PreparedHistoricalObservation[] }>();
+  const originFailures: { observation: PreparedHistoricalObservation; finding: CustomizationCapabilityFinding }[] = [];
+  for (const observation of effective) {
+    const origin = assignAnalysisOrigin(observation, input.definition.period, input.definition.policySchedule);
+    if (origin.status !== "assigned" || origin.originId === null || origin.label === null) {
+      if (origin.finding !== null) originFailures.push({ observation, finding: origin.finding });
+      continue;
+    }
+    const group = groups.get(origin.originId);
+    if (group === undefined) groups.set(origin.originId, { label: origin.label, observations: [observation] });
+    else group.observations.push(observation);
+  }
+  const measureIds = new Set(
+    input.recipe.steps.filter((step) => step.kind === "calculate").flatMap((step) => step.measureIds),
+  );
+  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))) {
+      let measureObservations = measure.populationScopeId === input.definition.scopes.financial.id
+        ? group.observations
+        : group.observations.filter((observation) => reportingKeys.has(key(observation)));
+      const conditionFindings: CustomizationCapabilityFinding[] = [];
+      if (measure.condition !== undefined)
+        measureObservations = measureObservations.filter((observation) => {
+          const membership = evaluateAnalysisScope({
+            scope: { id: `measure-${measure.id}`, subject: "claim", predicate: measure.condition!, classification: { kind: "as-observed" } },
+            observation,
+            claimHistory: byHistory.get(key(observation)) ?? [],
+            dimensions: input.definition.dimensions,
+          });
+          if (membership.outcome === "unknown" && membership.finding !== null) conditionFindings.push(membership.finding);
+          return membership.outcome === "match";
+        });
+      const exposureFindings = measure.statistic.kind === "ratio"
+        ? exposureFindingsByMeasure.get(measure.statistic.denominatorMeasureId) ?? []
+        : [];
+      const scopeFindings = measure.populationScopeId === input.definition.scopes.financial.id
+        ? financialExecutionFindings
+        : [...financialExecutionFindings, ...reportingExecutionFindings];
+      const blockingFindings = [...scopeFindings, ...conditionFindings, ...exposureFindings];
+      if (blockingFindings.length > 0) {
+        values.push({
+          measureId: measure.id,
+          unit: measure.unit,
+          coordinates: { originId, originLabel: group.label, evaluationDate },
+          value: null,
+          status: "unavailable",
+          contributingObservations: 0,
+          excludedObservations: measureObservations.length,
+          exact: true,
+          numerator: null,
+          denominator: null,
+          findings: blockingFindings,
+        });
+        continue;
+      }
+      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" } });
+        }
+      } else {
+        statistic = calculateAnalysisStatistic({
+          measure,
+          observations: measureObservations,
+          selection: { kind: "evaluation-date", evaluationDate, observationSelection: "exact" },
+        });
+      }
+      values.push({
+        measureId: measure.id,
+        unit: measure.unit,
+        coordinates: { originId, originLabel: group.label, evaluationDate },
+        value: statistic.value,
+        status: statistic.status,
+        contributingObservations: statistic.contributingObservations,
+        excludedObservations: statistic.excludedObservations,
+        exact: true,
+        numerator: statistic.numerator,
+        denominator: statistic.denominator,
+        findings: statistic.findings,
+      });
+    }
+  }
+  if (originFailures.length > 0) {
+    for (const measure of input.definition.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);
+      if (originFindings.length === 0) continue;
+      values.push({
+        measureId: measure.id,
+        unit: measure.unit,
+        coordinates: { originId: "unassigned", originLabel: "Unavailable origin", evaluationDate },
+        value: null,
+        status: "unavailable",
+        contributingObservations: 0,
+        excludedObservations: originFailures.length,
+        exact: true,
+        numerator: null,
+        denominator: null,
+        findings: originFindings,
+      });
+    }
+  }
+  const calculationInput = {
+    historyRevisionId: prepared.calculationRevisionId,
+    definition: input.definition,
+    recipe: input.recipe,
+    evaluationDate,
+    exposureRevisionIds: exposureCalculationRevisions.sort(),
+  };
+  const lineageInput = {
+    historyRevisionId: prepared.lineageRevisionId,
+    exposureRevisionIds: exposureLineageRevisions.sort(),
+    calculationIdentity: `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(calculationInput))}`,
+  };
+  return snapshotDiagnosticJson({
+    resultContractVersion: "actuarial-result/1",
+    datasetRevisionId: prepared.datasetRevisionId,
+    analysisDefinitionId: input.definition.id,
+    recipeId: input.recipe.id,
+    calculationIdentity: lineageInput.calculationIdentity,
+    lineageIdentity: `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(lineageInput))}`,
+    values,
+  });
+}
+
+export function applyAnalysisScenario(
+  definition: AnalysisDefinition,
+  scenario: AnalysisScenario,
+): AnalysisDefinition {
+  const scenarioIssues: DiagnosticValidationIssue[] = [];
+  if (!isDiagnosticToken(scenario.id))
+    scenarioIssues.push({ domain: "configuration", code: "invalid-string", path: "$.scenario.id", message: "Scenario id is invalid" });
+  for (const [index, change] of scenario.changes.entries()) {
+    if (change.kind !== "reporting-predicate" && !definition.financialTerms.some((term) => term.id === change.termId))
+      scenarioIssues.push({ domain: "configuration", code: "unknown-reference", path: `$.scenario.changes[${index}].termId`, message: `Unknown financial term ${change.termId}` });
+    if (change.kind === "financial-term-limit" && change.limit !== null && (!(change.limit > 0) || !Number.isFinite(change.limit)))
+      scenarioIssues.push({ domain: "configuration", code: "invalid-number", path: `$.scenario.changes[${index}].limit`, message: "Scenario term limit must be positive finite or null" });
+    if (change.kind === "financial-term-attachment" && (!(change.amount >= 0) || !Number.isFinite(change.amount)))
+      scenarioIssues.push({ domain: "configuration", code: "invalid-number", path: `$.scenario.changes[${index}].amount`, message: "Scenario attachment must be nonnegative finite" });
+  }
+  if (scenarioIssues.length > 0) throw new DiagnosticValidationError(scenarioIssues);
+  let reportingPredicate: AnalysisPredicate = definition.scopes.reporting.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")
+        current = current.kind === "policy-aggregate" ? { ...current, deductible: change.amount } : { ...current, attachment: change.amount };
+    }
+    return current;
+  });
+  return snapshotDiagnosticJson({
+    ...definition,
+    version: `${definition.version}+scenario.${scenario.id}`,
+    scopes: { ...definition.scopes, reporting: { ...definition.scopes.reporting, predicate: reportingPredicate } },
+    financialTerms: terms,
+  });
+}
+
+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;
+  readonly definition: AnalysisDefinition;
+  readonly recipe: AnalysisRecipe;
+  readonly scenarios: readonly AnalysisScenario[];
+  readonly limits: Pick<CustomizationResourceLimits, "maximumActiveScenarios">;
+  readonly exposureObservations?: readonly CustomizationExposureObservation[];
+  readonly exposureTargets?: readonly ExposureAllocationTarget[];
+  readonly exposureRevisionSelection?: ExposureRevisionSelection;
+  readonly evaluationDate?: string;
+}): readonly AnalysisScenarioRun[] {
+  const maximumActiveScenarios = maximumActiveScenarioLimit(input.limits);
+  if (input.scenarios.length > maximumActiveScenarios)
+    throw new DiagnosticValidationError([{
+      domain: "configuration",
+      code: "expression-limit",
+      path: "$.scenarios",
+      message: `Scenario count exceeds maximumActiveScenarios ${maximumActiveScenarios}`,
+    }]);
+  if (new Set(input.scenarios.map((scenario) => scenario.id)).size !== input.scenarios.length)
+    throw new DiagnosticValidationError([{
+      domain: "configuration",
+      code: "duplicate-id",
+      path: "$.scenarios",
+      message: "Scenario IDs must be unique",
+    }]);
+  const common = {
+    history: input.history,
+    recipe: input.recipe,
+    ...(input.exposureObservations === undefined ? {} : { exposureObservations: input.exposureObservations }),
+    ...(input.exposureTargets === undefined ? {} : { exposureTargets: input.exposureTargets }),
+    ...(input.exposureRevisionSelection === undefined ? {} : { exposureRevisionSelection: input.exposureRevisionSelection }),
+    ...(input.evaluationDate === undefined ? {} : { evaluationDate: input.evaluationDate }),
+  };
+  const baseline = runAnalysisRecipe({ ...common, definition: input.definition });
+  return snapshotDiagnosticJson(input.scenarios.map((scenario) => {
+    const result = runAnalysisRecipe({ ...common, definition: applyAnalysisScenario(input.definition, scenario) });
+    return { scenarioId: scenario.id, result, differences: compareAnalysisResults(baseline, result) };
+  }));
+}
+
+function scenarioChangeTarget(change: AnalysisScenarioChange): string {
+  if (change.kind === "reporting-predicate") return "reporting-predicate";
+  return `${change.kind}:${change.termId}`;
+}
+
+function maximumActiveScenarioLimit(
+  limits: Pick<CustomizationResourceLimits, "maximumActiveScenarios">,
+): number {
+  const maximum = limits?.maximumActiveScenarios;
+  if (!Number.isSafeInteger(maximum) || maximum < 1)
+    throw new DiagnosticValidationError([{
+      domain: "configuration",
+      code: "expression-limit",
+      path: "$.limits.maximumActiveScenarios",
+      message: "maximumActiveScenarios must be a positive safe integer",
+    }]);
+  return maximum;
+}
+
+/** Expands a closed Cartesian parameter grid after proving its product is bounded. */
+export function expandAnalysisScenarioGrid(
+  grid: AnalysisScenarioGrid,
+  limits: Pick<CustomizationResourceLimits, "maximumActiveScenarios">,
+): readonly AnalysisScenario[] {
+  const issues: DiagnosticValidationIssue[] = [];
+  let maximumActiveScenarios: number;
+  try {
+    maximumActiveScenarios = maximumActiveScenarioLimit(limits);
+  } catch (error) {
+    if (error instanceof DiagnosticValidationError) issues.push(...error.issues);
+    maximumActiveScenarios = 0;
+  }
+  if (!isDiagnosticToken(grid.id))
+    issues.push({ domain: "configuration", code: "invalid-string", path: "$.grid.id", message: "Scenario grid id is invalid" });
+  if (grid.axes.length === 0)
+    issues.push({ domain: "configuration", code: "missing-required", path: "$.grid.axes", message: "Scenario grid requires at least one axis" });
+  if (new Set(grid.axes.map((axis) => axis.id)).size !== grid.axes.length)
+    issues.push({ domain: "configuration", code: "duplicate-id", path: "$.grid.axes", message: "Scenario grid axis IDs must be unique" });
+  const axisTargets = new Set<string>();
+  let product = 1;
+  grid.axes.forEach((axis, axisIndex) => {
+    const path = `$.grid.axes[${axisIndex}]`;
+    if (!isDiagnosticToken(axis.id))
+      issues.push({ domain: "configuration", code: "invalid-string", path: `${path}.id`, message: "Scenario grid axis id is invalid" });
+    if (axis.options.length === 0)
+      issues.push({ domain: "configuration", code: "missing-required", path: `${path}.options`, message: "Scenario grid axis requires at least one option" });
+    if (new Set(axis.options.map((option) => option.id)).size !== axis.options.length)
+      issues.push({ domain: "configuration", code: "duplicate-id", path: `${path}.options`, message: "Scenario grid option IDs must be unique within an axis" });
+    axis.options.forEach((option, optionIndex) => {
+      if (!isDiagnosticToken(option.id))
+        issues.push({ domain: "configuration", code: "invalid-string", path: `${path}.options[${optionIndex}].id`, message: "Scenario grid option id is invalid" });
+    });
+    const targets = new Set(axis.options.flatMap((option) => option.change === null ? [] : [scenarioChangeTarget(option.change)]));
+    if (targets.size > 1)
+      issues.push({ domain: "configuration", code: "incompatible-semantics", path: `${path}.options`, message: "Every non-baseline option on one grid axis must change the same parameter" });
+    const target = [...targets][0];
+    if (target !== undefined && axisTargets.has(target))
+      issues.push({ domain: "configuration", code: "incompatible-semantics", path, message: `Multiple grid axes change ${target}` });
+    if (target !== undefined) axisTargets.add(target);
+    if (axis.options.length > 0) {
+      if (product > Math.floor(maximumActiveScenarios / axis.options.length))
+        product = maximumActiveScenarios + 1;
+      else product *= axis.options.length;
+    }
+  });
+  if (maximumActiveScenarios > 0 && product > maximumActiveScenarios)
+    issues.push({ domain: "configuration", code: "expression-limit", path: "$.grid.axes", message: `Scenario grid product exceeds maximumActiveScenarios ${maximumActiveScenarios}` });
+  if (issues.length > 0) throw new DiagnosticValidationError(issues);
+
+  let combinations: { readonly ids: readonly string[]; readonly changes: readonly AnalysisScenarioChange[] }[] = [{ ids: [], changes: [] }];
+  for (const axis of grid.axes) {
+    combinations = combinations.flatMap((combination) => axis.options.map((option) => ({
+      ids: [...combination.ids, `${axis.id}-${option.id}`],
+      changes: option.change === null ? combination.changes : [...combination.changes, option.change],
+    })));
+  }
+  const scenarios = combinations.map((combination) => ({
+    id: `${grid.id}-${combination.ids.join("-")}`,
+    changes: combination.changes,
+  }));
+  if (scenarios.some((scenario) => !isDiagnosticToken(scenario.id)))
+    throw new DiagnosticValidationError([{
+      domain: "configuration",
+      code: "invalid-string",
+      path: "$.grid",
+      message: "Expanded scenario grid IDs must be valid diagnostic tokens",
+    }]);
+  return snapshotDiagnosticJson(scenarios);
+}
+
+/** Expands and runs a bounded parameter grid against one immutable baseline. */
+export function runAnalysisScenarioGrid(
+  input: Omit<Parameters<typeof runAnalysisScenarios>[0], "scenarios"> & {
+    readonly grid: AnalysisScenarioGrid;
+  },
+): readonly AnalysisScenarioRun[] {
+  const { grid, ...common } = input;
+  return runAnalysisScenarios({
+    ...common,
+    scenarios: expandAnalysisScenarioGrid(grid, input.limits),
+  });
+}
+
+/** 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 }))}`;
+}
+
+/** Uses caller-owned cache storage; a hit is returned only for the complete dependency identity. */
+export function runAnalysisRecipeCached(input: Parameters<typeof runAnalysisRecipe>[0] & {
+  readonly cache: AnalysisResultCache;
+}): { readonly cacheStatus: "hit" | "miss"; readonly dependencyIdentity: string; readonly result: AnalysisResult } {
+  const { cache, ...runInput } = input;
+  const dependencyIdentity = analysisRecipeDependencyIdentity(runInput);
+  const existing = cache.get(dependencyIdentity);
+  if (existing !== undefined)
+    return snapshotDiagnosticJson({ cacheStatus: "hit", dependencyIdentity, result: existing });
+  const result = runAnalysisRecipe(runInput);
+  cache.set(dependencyIdentity, result);
+  return snapshotDiagnosticJson({ cacheStatus: "miss", dependencyIdentity, result });
+}
+
+/** Preserves the prior result and recipe while executing a later immutable valuation. */
+export function rollForwardAnalysisRecipe(input: Parameters<typeof runAnalysisRecipe>[0] & {
+  readonly priorEvaluationDate: string;
+  readonly currentEvaluationDate: string;
+}): AnalysisRollForward {
+  if (input.currentEvaluationDate <= input.priorEvaluationDate)
+    throw new DiagnosticValidationError([{
+      domain: "configuration",
+      code: "invalid-period",
+      path: "$.currentEvaluationDate",
+      message: "Roll-forward currentEvaluationDate must be after priorEvaluationDate",
+    }]);
+  const { priorEvaluationDate, currentEvaluationDate, ...common } = input;
+  const priorResult = runAnalysisRecipe({ ...common, evaluationDate: priorEvaluationDate });
+  const currentResult = runAnalysisRecipe({ ...common, evaluationDate: currentEvaluationDate });
+  return snapshotDiagnosticJson({
+    kind: "roll-forward",
+    priorEvaluationDate,
+    currentEvaluationDate,
+    priorResult,
+    currentResult,
+    differences: compareAnalysisResults(priorResult, currentResult),
+  });
+}
+
+/** Applies explicitly ordered, one-change scenario steps and reports each incremental bridge. */
+export function runAnalysisScenarioBridge(input: Parameters<typeof runAnalysisRecipe>[0] & {
+  readonly scenarios: readonly AnalysisScenario[];
+  readonly limits: Pick<CustomizationResourceLimits, "maximumActiveScenarios">;
+}): { readonly baseline: AnalysisResult; readonly steps: readonly AnalysisScenarioBridgeStep[] } {
+  const maximumActiveScenarios = maximumActiveScenarioLimit(input.limits);
+  if (input.scenarios.length > maximumActiveScenarios)
+    throw new DiagnosticValidationError([{
+      domain: "configuration", code: "expression-limit", path: "$.scenarios",
+      message: `Scenario bridge exceeds maximumActiveScenarios ${maximumActiveScenarios}`,
+    }]);
+  const { scenarios, limits: _limits, ...common } = input;
+  const baseline = runAnalysisRecipe(common);
+  let prior = baseline;
+  let effectiveDefinition = input.definition;
+  const steps: AnalysisScenarioBridgeStep[] = [];
+  for (const scenario of scenarios) {
+    if (scenario.changes.length !== 1)
+      throw new DiagnosticValidationError([{
+        domain: "configuration", code: "invalid-configuration", path: `$.scenarios.${scenario.id}.changes`,
+        message: "Each bridge scenario must contain exactly one change",
+      }]);
+    effectiveDefinition = applyAnalysisScenario(effectiveDefinition, scenario);
+    const result = runAnalysisRecipe({ ...common, definition: effectiveDefinition });
+    steps.push({
+      scenarioId: scenario.id,
+      fromCalculationIdentity: prior.calculationIdentity,
+      result,
+      differences: compareAnalysisResults(prior, result),
+    });
+    prior = result;
+  }
+  return snapshotDiagnosticJson({ baseline, steps });
+}