@actuarial-ts/core 0.7.0 → 0.8.0

package/dist/analysisRecipe.js

@@ -0,0 +1,627 @@
+import { canonicalJson, fnv1a64 } from "./canonical.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 } from "./types.js";
+function key(observation) {
+    return canonicalJson([observation.sourceNamespace, observation.claimId]);
+}
+function recipeIssues(recipe, definition, history) {
+    const issues = [];
+    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 = {
+        "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, evaluationDate, mode) {
+    if (mode === "exact")
+        return observations.filter((observation) => observation.evaluationDate === evaluationDate);
+    const selected = new Map();
+    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) {
+    const result = new Map();
+    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, scope, observations, historyByClaim) {
+    const matches = [];
+    const findings = [];
+    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) {
+    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) {
+    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 = [...financialSelection.findings];
+    const reportingExecutionFindings = [...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", id, terms: [input.definition.financialTerms.find((candidate) => candidate.id === id)] }
+                : { kind: "adjustment", 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();
+    const exposureFindingsByMeasure = new Map();
+    const exposureCalculationRevisions = [];
+    const exposureLineageRevisions = [];
+    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();
+                    measures.set(id, (measures.get(id) ?? 0) + allocation.value);
+                    exposedByTarget.set(allocation.targetId, measures);
+                }
+            }
+            exposureFindingsByMeasure.set(id, measureFindings);
+        }
+    }
+    const groups = new Map();
+    const originFailures = [];
+    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 = [];
+    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 = [];
+            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, scenario) {
+    const scenarioIssues = [];
+    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 = 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, scenario) {
+    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) {
+    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) {
+    if (change.kind === "reporting-predicate")
+        return "reporting-predicate";
+    return `${change.kind}:${change.termId}`;
+}
+function maximumActiveScenarioLimit(limits) {
+    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, limits) {
+    const issues = [];
+    let maximumActiveScenarios;
+    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();
+    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 = [{ 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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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 = [];
+    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 });
+}
+//# sourceMappingURL=analysisRecipe.js.map