@insiderfinance/totalfinance 0.1.0

package/modules/backtest/dist/run-artifacts.js

@@ -0,0 +1,1843 @@
+/**
+ * `@insiderfinance/totalfinance/backtest/artifacts` (Stage 4.6, FC8 Decision 8): reproducible run artifacts over the
+ * Stage 4.5 grammar — an `AnalysisArtifact` of type `totalfinance.backtest-run` whose `result` is the
+ * typed {@link BacktestRunReport}: the run verbatim, the request with bulk row sets embedded or
+ * referenced by `TableHandle`, every execution and accounting model recorded by its description,
+ * the run's content hash, and the FC8 identity list (strategy and recipe version, dataset identity,
+ * universe id and history hash, point-in-time policy, conventions and calendar, engine and model
+ * labels/versions, seed, costs, benchmark, annualization). Four verbs: `backtestRunArtifact`,
+ * `readBacktestRun`, `replayBacktestRun`, `compareBacktestRuns`. Nothing here computes a number a
+ * run did not — the engine is the engine; the artifact is its record.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureKnownKeys, isQuantError, requireArgumentArray, requireArgumentObject, warning, WarningCode, } from '../../core/dist/index.js';
+import { ARTIFACT_WORK_LIMITS, applyReportMigrations, artifactReplayParity, canonicalJsonOf, contentHash, createAnalysisArtifact, fromCanonicalJson, isTableHandle, readAnalysisArtifact, requireComparisonTolerance, requireWorkLimit, scanCanonicalData, tableHandleForRows, verifyReferencedRows, } from '../../core/dist/artifacts/index.js';
+import { crossSectionalBacktest } from './cross-sectional/engine.js';
+import { crossSectionalBacktestGrid, requireCrossSectionalBacktestGridRequest, } from './cross-sectional/grid.js';
+import { requireCrossSectionalBacktestRequest } from './cross-sectional/validate.js';
+import { describeExecutionPolicy, execution as executionPolicies } from './execution/policy.js';
+import { optionsBacktest, requireOptionsBacktestConfig } from './options/engine.js';
+import { portfolioBacktest } from './portfolio/engine.js';
+import { requireEnvironmentEpisodeInput, runEnvironmentEpisode } from './environment/episode.js';
+import { requirePortfolioBacktestRequest } from './portfolio/validate.js';
+export const BACKTEST_RUN_ARTIFACT_TYPE = 'totalfinance.backtest-run';
+/** Decision 9's bounded-work table (core's `ARTIFACT_WORK_LIMITS`, re-exported for this subpath's callers). */
+export const BACKTEST_RUN_LIMITS = ARTIFACT_WORK_LIMITS;
+const rowSet = (label) => ({ label, path: label.split('.') });
+const resultRowSet = (label) => ({
+    label: `run.${label}`,
+    path: label.split('.'),
+});
+const CROSS_SECTIONAL_INPUT_ROW_SETS = [
+    'dataset.observations',
+    'dataset.returns',
+    'dataset.benchmarkReturns',
+    'universeHistory.members',
+];
+const CROSS_SECTIONAL_RESULT_ROW_SETS = [
+    'rebalances',
+    'holdings',
+    'points',
+    'returns',
+    'trades',
+    'fills',
+    'ledger.events',
+    'timeline.rows',
+    'attribution.perRebalance',
+];
+const CROSS_SECTIONAL_RUN_KEYS = [
+    'rebalances',
+    'holdings',
+    'points',
+    'returns',
+    'trades',
+    'fills',
+    'ledger',
+    'timeline',
+    'attribution',
+    'benchmark',
+    'performance',
+    'performanceConfidence',
+    'finalValue',
+    'runId',
+    'assumptions',
+    'diagnostics',
+];
+const GRID_RUN_KEYS = [
+    'sweepId',
+    'variations',
+    'runs',
+    'best',
+    'hygiene',
+    'assumptions',
+    'diagnostics',
+];
+function callbackAt(field, marker) {
+    const path = field.split('.');
+    return { field, path, strip: marker };
+}
+const SIGNAL_CALLBACK = (prefix) => callbackAt([...prefix, 'signal', 'callback'].join('.'), (record) => withPath(record, [...prefix, 'signal'], {
+    callback: '[caller function — not stored]',
+}));
+const SUPPLIED_WEIGHTS_CALLBACK = (prefix) => callbackAt([...prefix, 'portfolioConstruction', 'suppliedWeights'].join('.'), (record) => {
+    const construction = {
+        ...readPath(record, [...prefix, 'portfolioConstruction']),
+    };
+    delete construction['suppliedWeights'];
+    return withPath(record, [...prefix, 'portfolioConstruction'], construction);
+});
+function crossSectionalIdentity(run, storedInput, extra, requestRoot) {
+    const assumptions = run.assumptions;
+    const members = readPath(storedInput, [...requestRoot, 'universeHistory', 'members']);
+    const models = readPath(storedInput, requestRoot);
+    const costs = (models['transactionCostModel'] ?? null);
+    const signal = assumptions.signal;
+    return {
+        runId: extra.runId,
+        childRunIds: extra.childRunIds,
+        universeId: assumptions.universeId,
+        universeHistoryHash: isTableHandle(members) ? members.contentHash : contentHash(members),
+        strategy: { ...signal },
+        recipe: signal['kind'] === 'factor-recipe'
+            ? {
+                recipeName: String(signal['recipeName']),
+                recipeVersion: Number(signal['recipeVersion']),
+            }
+            : null,
+        pointInTimePolicy: 'a feature is visible to a decision instant only when availableTimestampMs ≤ the instant; a recipe lag counts trading sessions through the session index; universe membership is read at the instant',
+        conventions: {
+            conventionsVersion: assumptions.conventionsVersion,
+            sessionInstantConvention: assumptions.sessionInstantConvention,
+            pricing: assumptions.pricing,
+        },
+        calendar: {
+            sessions: run.diagnostics.sessionCount,
+            firstMarkTimestampMs: run.points.length > 0 ? run.points[0].timestampMs : null,
+            lastMarkTimestampMs: run.points.length > 0 ? run.points[run.points.length - 1].timestampMs : null,
+        },
+        engine: { operation: extra.operation, runVersion: extra.runVersion },
+        models: {
+            execution: models['execution'] ?? null,
+            commission: costs?.commission ?? null,
+            slippage: costs?.slippage ?? null,
+        },
+        seed: assumptions.seed,
+        benchmark: run.benchmark !== null,
+        annualization: {
+            periodsPerYear: assumptions.periodsPerYear,
+            riskFreeRate: assumptions.riskFreeRate,
+        },
+        initialCapital: assumptions.initialCapital,
+        baseCurrency: assumptions.baseCurrency,
+        variations: extra.variations,
+    };
+}
+const CROSS_SECTIONAL_SPEC = {
+    descriptor: Object.freeze({
+        kind: 'cross-sectional',
+        runVersion: 1,
+        operation: 'crossSectionalBacktest',
+        inputRowSets: CROSS_SECTIONAL_INPUT_ROW_SETS,
+        resultRowSets: CROSS_SECTIONAL_RESULT_ROW_SETS.map((label) => `run.${label}`),
+        callbackFields: ['signal.callback', 'portfolioConstruction.suppliedWeights'],
+        modelFields: ['execution', 'transactionCostModel'],
+    }),
+    inputRowSets: CROSS_SECTIONAL_INPUT_ROW_SETS.map(rowSet),
+    resultRowSets: CROSS_SECTIONAL_RESULT_ROW_SETS.map(resultRowSet),
+    callbacks: [SIGNAL_CALLBACK([]), SUPPLIED_WEIGHTS_CALLBACK([])],
+    modelRoot: [],
+    labeledModels: [],
+    dynamicCallbacks: () => [],
+    runKeys: CROSS_SECTIONAL_RUN_KEYS,
+    requireInput: (functionName, label, value) => {
+        requireCrossSectionalBacktestRequest(functionName, label, value);
+    },
+    run: crossSectionalBacktest,
+    identity: (run, storedInput) => crossSectionalIdentity(run, storedInput, {
+        runId: run.runId,
+        childRunIds: null,
+        variations: null,
+        operation: 'crossSectionalBacktest',
+        runVersion: 1,
+    }, []),
+};
+const GRID_SPEC = {
+    descriptor: Object.freeze({
+        kind: 'cross-sectional-grid',
+        runVersion: 1,
+        operation: 'crossSectionalBacktestGrid',
+        inputRowSets: CROSS_SECTIONAL_INPUT_ROW_SETS.map((label) => `request.${label}`),
+        resultRowSets: ['run.runs', 'run.variations'],
+        callbackFields: ['request.signal.callback', 'request.portfolioConstruction.suppliedWeights'],
+        modelFields: ['request.execution', 'request.transactionCostModel'],
+    }),
+    inputRowSets: CROSS_SECTIONAL_INPUT_ROW_SETS.map((label) => rowSet(`request.${label}`)),
+    resultRowSets: [resultRowSet('runs'), resultRowSet('variations')],
+    callbacks: [SIGNAL_CALLBACK(['request']), SUPPLIED_WEIGHTS_CALLBACK(['request'])],
+    modelRoot: ['request'],
+    labeledModels: [],
+    dynamicCallbacks: () => [],
+    runKeys: GRID_RUN_KEYS,
+    requireInput: (functionName, label, value) => {
+        requireCrossSectionalBacktestGridRequest(functionName, label, value);
+    },
+    run: crossSectionalBacktestGrid,
+    identity: (run, storedInput) => {
+        const child = run.runs[0];
+        if (child === undefined) {
+            fail('backtestRunArtifact', 'run.runs is empty — a grid always holds at least one child run.', ErrorCode.InputOutOfRange, { field: 'run.runs' });
+        }
+        const variations = readPath(storedInput, ['variations']).map((axis) => ({ path: axis.path, values: [...axis.values] }));
+        return crossSectionalIdentity(child, storedInput, {
+            runId: run.sweepId,
+            childRunIds: run.variations.map((row) => row.runId),
+            variations,
+            operation: 'crossSectionalBacktestGrid',
+            runVersion: 1,
+        }, ['request']);
+    },
+};
+const OPTIONS_INPUT_ROW_SETS = ['chains', 'corporateActions', 'dividends'];
+const OPTIONS_RESULT_ROW_SETS = [
+    'points',
+    'returns',
+    'trades',
+    'settlements',
+    'fills',
+    'limitRejections',
+    'fillRejections',
+    'surface',
+    'ledger.events',
+    'timeline.rows',
+];
+const OPTIONS_RUN_KEYS = [
+    'points',
+    'returns',
+    'trades',
+    'settlements',
+    'fills',
+    'finalValue',
+    'performance',
+    'limitRejections',
+    'fillRejections',
+    'surface',
+    'ledger',
+    'timeline',
+    'runId',
+    'assumptions',
+    'diagnostics',
+];
+/** The options request's callback-bearing members: every rule's `build` / function `when`, `exit.when`, `roll.when.when`. */
+function optionsCallbacks(record) {
+    const found = [];
+    const isBook = Array.isArray(record['rules']);
+    const rules = isBook ? [...record['rules']] : [record['entry']];
+    const marker = '[caller function — not stored]';
+    rules.forEach((rule, index) => {
+        if (rule === null || typeof rule !== 'object')
+            return;
+        const r = rule;
+        const at = (key) => (target) => {
+            if (isBook) {
+                const list = [...target['rules']];
+                list[index] = { ...list[index], [key]: marker };
+                return { ...target, rules: list };
+            }
+            return {
+                ...target,
+                entry: { ...target['entry'], [key]: marker },
+            };
+        };
+        const label = isBook ? `rules[${index}]` : 'entry';
+        if (typeof r['build'] === 'function')
+            found.push({ field: `${label}.build`, strip: at('build') });
+        if (typeof r['when'] === 'function')
+            found.push({ field: `${label}.when`, strip: at('when') });
+    });
+    const exit = record['exit'];
+    if (exit !== null && typeof exit === 'object' && typeof exit['when'] === 'function') {
+        found.push({
+            field: 'exit.when',
+            strip: (target) => ({
+                ...target,
+                exit: { ...target['exit'], when: marker },
+            }),
+        });
+    }
+    const roll = record['roll'];
+    const rollWhen = roll !== null && typeof roll === 'object'
+        ? roll['when']
+        : undefined;
+    if (rollWhen !== null && typeof rollWhen === 'object' && typeof rollWhen['when'] === 'function') {
+        found.push({
+            field: 'roll.when.when',
+            strip: (target) => ({
+                ...target,
+                roll: {
+                    ...target['roll'],
+                    when: { ...rollWhen, when: marker },
+                },
+            }),
+        });
+    }
+    return found;
+}
+const OPTIONS_SPEC = {
+    descriptor: Object.freeze({
+        kind: 'options',
+        runVersion: 1,
+        operation: 'optionsBacktest',
+        inputRowSets: OPTIONS_INPUT_ROW_SETS,
+        resultRowSets: OPTIONS_RESULT_ROW_SETS.map((label) => `run.${label}`),
+        callbackFields: [
+            'entry.build',
+            'entry.when',
+            'rules[].build',
+            'rules[].when',
+            'exit.when',
+            'roll.when.when',
+        ],
+        modelFields: ['commission', 'slippage', 'hedge.commission', 'hedge.slippage'],
+    }),
+    inputRowSets: OPTIONS_INPUT_ROW_SETS.map(rowSet),
+    resultRowSets: OPTIONS_RESULT_ROW_SETS.map(resultRowSet),
+    callbacks: [],
+    modelRoot: [],
+    labeledModels: ['commission', 'slippage', 'hedge.commission', 'hedge.slippage'],
+    dynamicCallbacks: optionsCallbacks,
+    runKeys: OPTIONS_RUN_KEYS,
+    requireInput: (functionName, label, value) => {
+        requireOptionsBacktestConfig(functionName, label, value);
+    },
+    run: optionsBacktest,
+    identity: (run, storedInput) => {
+        const assumptions = run.assumptions;
+        const chains = readPath(storedInput, ['chains']);
+        const underlying = run.trades[0]?.underlying ?? run.settlements[0]?.underlying ?? 'UNDERLYING';
+        return {
+            runId: run.runId,
+            childRunIds: null,
+            universeId: underlying,
+            universeHistoryHash: isTableHandle(chains) ? chains.contentHash : contentHash(chains),
+            strategy: {
+                kind: 'options-rules',
+                rules: assumptions.rules,
+                exit: readPath(storedInput, ['exit']) ?? null,
+                roll: readPath(storedInput, ['roll']) ?? null,
+            },
+            recipe: null,
+            pointInTimePolicy: 'each snapshot sees only its own chain; a leg marks from its exact current-snapshot contract quote under the marking policy; fills read the selected price side of the current quote and refuse a stale one',
+            conventions: {
+                conventionsVersion: assumptions.conventionsVersion,
+                sessionInstantConvention: 'the snapshot asOf; the ledger marks at the following midnight, one mark per calendar date',
+                pricing: `Black–Scholes marks from current quotes (${assumptions.marking.volatility}, missing mark: ${assumptions.marking.missingMark}); settlements at intrinsic`,
+            },
+            calendar: {
+                sessions: run.diagnostics.snapshotCount,
+                firstMarkTimestampMs: run.points.length > 0 ? run.points[0].timestampMs : null,
+                lastMarkTimestampMs: run.points.length > 0 ? run.points[run.points.length - 1].timestampMs : null,
+            },
+            engine: { operation: 'optionsBacktest', runVersion: 1 },
+            models: {
+                execution: null,
+                commission: assumptions.commission,
+                slippage: assumptions.slippage,
+            },
+            seed: null,
+            benchmark: false,
+            annualization: {
+                periodsPerYear: assumptions.periodsPerYear,
+                riskFreeRate: assumptions.riskFreeRate,
+            },
+            initialCapital: assumptions.initialCapital,
+            baseCurrency: assumptions.baseCurrency,
+            variations: null,
+        };
+    },
+};
+const PORTFOLIO_INPUT_ROW_SETS = [
+    'marketData.bars',
+    'marketData.quotes',
+    'marketData.trades',
+    'marketData.orderBooks',
+    'marketData.optionChains',
+    'marketData.fxRates',
+    'marketData.forwardRates',
+    'marketData.fundingRates',
+    'marketData.corporateActions',
+    'marketData.dividends',
+    'marketData.coupons',
+    'externalFlows',
+];
+const PORTFOLIO_RESULT_ROW_SETS = [
+    'orders',
+    'fills',
+    'rejections',
+    'liquidations',
+    'events',
+    'valuationMarks',
+    'points',
+    'returns',
+    'ledger.events',
+    'timeline.rows',
+];
+const PORTFOLIO_RUN_KEYS = [
+    'ledger',
+    'timeline',
+    'pnl',
+    'orders',
+    'fills',
+    'rejections',
+    'liquidations',
+    'events',
+    'valuationMarks',
+    'points',
+    'returns',
+    'performance',
+    'finalValue',
+    'runId',
+    'assumptions',
+    'diagnostics',
+];
+/** A custom instrument's adapter is a function-bearing object: recorded by kind and version, never stored. */
+function portfolioCallbacks(record) {
+    const found = [];
+    const instruments = record['instruments'];
+    if (instruments !== null && typeof instruments === 'object') {
+        for (const [id, spec] of Object.entries(instruments)) {
+            const adapter = spec?.adapter;
+            if (adapter === null || typeof adapter !== 'object')
+                continue;
+            found.push({
+                field: `instruments.${id}.adapter`,
+                strip: (target) => {
+                    const specs = { ...target['instruments'] };
+                    const own = specs[id];
+                    const a = own['adapter'];
+                    specs[id] = {
+                        ...own,
+                        adapter: {
+                            kind: a.kind,
+                            version: a.version,
+                            methods: '[caller functions — not stored]',
+                        },
+                    };
+                    return { ...target, instruments: specs };
+                },
+            });
+        }
+    }
+    return found;
+}
+const PORTFOLIO_SPEC = {
+    descriptor: Object.freeze({
+        kind: 'portfolio',
+        runVersion: 1,
+        operation: 'portfolioBacktest',
+        inputRowSets: PORTFOLIO_INPUT_ROW_SETS,
+        resultRowSets: PORTFOLIO_RESULT_ROW_SETS.map((label) => `run.${label}`),
+        callbackFields: ['strategy.onSession', 'instruments.<id>.adapter'],
+        modelFields: ['execution'],
+    }),
+    inputRowSets: PORTFOLIO_INPUT_ROW_SETS.map(rowSet),
+    resultRowSets: PORTFOLIO_RESULT_ROW_SETS.map(resultRowSet),
+    callbacks: [
+        callbackAt('strategy.onSession', (record) => withPath(record, ['strategy'], { onSession: '[caller function — not stored]' })),
+    ],
+    modelRoot: [],
+    labeledModels: [],
+    dynamicCallbacks: portfolioCallbacks,
+    runKeys: PORTFOLIO_RUN_KEYS,
+    requireInput: (functionName, label, value) => {
+        requirePortfolioBacktestRequest(functionName, label, value);
+    },
+    run: portfolioBacktest,
+    identity: (run, storedInput) => {
+        const assumptions = run.assumptions;
+        const models = readPath(storedInput, []);
+        const instruments = readPath(storedInput, ['instruments']);
+        return {
+            runId: run.runId,
+            childRunIds: null,
+            universeId: `portfolio:${assumptions.instruments.length}`,
+            universeHistoryHash: contentHash(instruments),
+            strategy: { ...assumptions.strategy },
+            recipe: null,
+            pointInTimePolicy: assumptions.sessionConvention,
+            conventions: {
+                conventionsVersion: assumptions.conventionsVersion,
+                sessionInstantConvention: assumptions.sessionConvention,
+                pricing: assumptions.markConvention,
+            },
+            calendar: {
+                sessions: run.diagnostics.sessionCount,
+                firstMarkTimestampMs: run.points.length > 0 ? run.points[0].timestampMs : null,
+                lastMarkTimestampMs: run.points.length > 0 ? run.points[run.points.length - 1].timestampMs : null,
+            },
+            engine: { operation: 'portfolioBacktest', runVersion: 1 },
+            models: {
+                execution: models['execution'] ?? null,
+                commission: assumptions.execution.costs.commission,
+                slippage: assumptions.execution.costs.slippage,
+            },
+            seed: assumptions.seed,
+            benchmark: false,
+            annualization: { periodsPerYear: assumptions.periodsPerYear, riskFreeRate: 0 },
+            initialCapital: run.points.length > 0 ? run.points[0].equity : 0,
+            baseCurrency: assumptions.baseCurrency,
+            variations: null,
+        };
+    },
+};
+const ENVIRONMENT_INPUT_ROW_SETS = [
+    ...PORTFOLIO_INPUT_ROW_SETS.map((label) => `definition.${label}`),
+    'actions',
+];
+const ENVIRONMENT_RESULT_ROW_SETS = [
+    'steps',
+    'rewards',
+    ...PORTFOLIO_RESULT_ROW_SETS.map((label) => `result.${label}`),
+];
+const ENVIRONMENT_RUN_KEYS = [
+    'runId',
+    'engineRunId',
+    'definitionHash',
+    'seed',
+    'traceHash',
+    'steps',
+    'rewards',
+    'rewardTotal',
+    'terminated',
+    'truncated',
+    'reason',
+    'result',
+    'assumptions',
+    'diagnostics',
+];
+const ENVIRONMENT_SPEC = {
+    descriptor: Object.freeze({
+        kind: 'environment',
+        runVersion: 1,
+        operation: 'runEnvironmentEpisode',
+        inputRowSets: ENVIRONMENT_INPUT_ROW_SETS,
+        resultRowSets: ENVIRONMENT_RESULT_ROW_SETS.map((label) => `run.${label}`),
+        callbackFields: ['definition.reward.goal', 'definition.instruments.<id>.adapter'],
+        modelFields: ['definition.execution'],
+    }),
+    inputRowSets: ENVIRONMENT_INPUT_ROW_SETS.map(rowSet),
+    resultRowSets: ENVIRONMENT_RESULT_ROW_SETS.map(resultRowSet),
+    callbacks: [
+        callbackAt('definition.reward.goal', (record) => {
+            const reward = { ...readPath(record, ['definition', 'reward']) };
+            reward['goal'] = '[caller function — not stored]';
+            return withPath(record, ['definition', 'reward'], reward);
+        }),
+    ],
+    modelRoot: ['definition'],
+    labeledModels: [],
+    dynamicCallbacks: (record) => {
+        const definition = record['definition'];
+        if (definition === null || typeof definition !== 'object')
+            return [];
+        return portfolioCallbacks(definition).map((callback) => ({
+            field: `definition.${callback.field}`,
+            strip: (target) => ({
+                ...target,
+                definition: callback.strip(target['definition']),
+            }),
+        }));
+    },
+    runKeys: ENVIRONMENT_RUN_KEYS,
+    requireInput: (functionName, label, value) => {
+        requireEnvironmentEpisodeInput(functionName, label, value);
+    },
+    run: runEnvironmentEpisode,
+    identity: (run, storedInput) => {
+        const engine = run.result.assumptions;
+        const definition = readPath(storedInput, ['definition']);
+        return {
+            runId: run.runId,
+            childRunIds: [run.engineRunId],
+            universeId: `environment:${engine.instruments.length}`,
+            universeHistoryHash: contentHash(readPath(definition, ['instruments'])),
+            strategy: { kind: 'environment', actions: run.steps.length, traceHash: run.traceHash },
+            recipe: null,
+            pointInTimePolicy: run.assumptions.nextObservationLaw,
+            conventions: {
+                conventionsVersion: run.assumptions.conventionsVersion,
+                sessionInstantConvention: engine.sessionConvention,
+                pricing: engine.markConvention,
+            },
+            calendar: {
+                sessions: run.result.diagnostics.sessionCount,
+                firstMarkTimestampMs: run.result.points.length > 0 ? run.result.points[0].timestampMs : null,
+                lastMarkTimestampMs: run.result.points.length > 0
+                    ? run.result.points[run.result.points.length - 1].timestampMs
+                    : null,
+            },
+            engine: { operation: 'runEnvironmentEpisode', runVersion: 1 },
+            models: {
+                execution: definition['execution'] ?? null,
+                commission: engine.execution.costs.commission,
+                slippage: engine.execution.costs.slippage,
+            },
+            seed: run.seed,
+            benchmark: definition['reward']?.benchmark !== undefined,
+            annualization: { periodsPerYear: engine.periodsPerYear, riskFreeRate: 0 },
+            initialCapital: run.result.points.length > 0 ? run.result.points[0].equity : 0,
+            baseCurrency: engine.baseCurrency,
+            variations: null,
+        };
+    },
+};
+const KIND_SPECS = {
+    'cross-sectional': CROSS_SECTIONAL_SPEC,
+    'cross-sectional-grid': GRID_SPEC,
+    options: OPTIONS_SPEC,
+    portfolio: PORTFOLIO_SPEC,
+    environment: ENVIRONMENT_SPEC,
+};
+export const BACKTEST_RUN_KIND_LIST = Object.freeze([
+    'cross-sectional',
+    'cross-sectional-grid',
+    'options',
+    'portfolio',
+    'environment',
+]);
+/** The frozen data projection of the kind table — what an agent reads before choosing a kind. */
+export const BACKTEST_RUN_KINDS = Object.freeze({
+    'cross-sectional': CROSS_SECTIONAL_SPEC.descriptor,
+    'cross-sectional-grid': GRID_SPEC.descriptor,
+    options: OPTIONS_SPEC.descriptor,
+    portfolio: PORTFOLIO_SPEC.descriptor,
+    environment: ENVIRONMENT_SPEC.descriptor,
+});
+// ─────────────────────────────────────────── helpers ────────────────────────────────────────────
+const REPORT_KEYS = [
+    'kind',
+    'runVersion',
+    'run',
+    'inputs',
+    'referencedData',
+    'runHash',
+    'identity',
+    'hygiene',
+    'execution',
+    'assumptions',
+    'diagnostics',
+];
+const ASSUMPTION_KEYS = [
+    'conventionsVersion',
+    'kind',
+    'runVersion',
+    'operation',
+    'replayable',
+    'nonReplayableField',
+    'inputPolicy',
+    'embeddedRowLimit',
+    'modelPolicy',
+    'projection',
+];
+const DIAGNOSTIC_KEYS = ['warnings', 'embeddedRows', 'referencedRows', 'runWarningCount'];
+const HYGIENE_KEYS = ['researchProtocol', 'deflatedSharpe', 'backtestOverfitting'];
+const HYGIENE_REQUIRED = {
+    researchProtocol: 'deflatedSharpe',
+    deflatedSharpe: 'deflatedSharpe',
+    backtestOverfitting: 'backtestOverfittingProbability',
+};
+const MODEL_POLICY = 'execution is stored as describeExecutionPolicy(policy); commission and slippage as their labels; replay takes the live models back as `models` and verifies each against its recorded description before the run';
+const PROJECTION = 'run = the verb result verbatim with referenced result row sets replaced by table handles; inputs = the request with bulk row sets embedded or replaced by verified table handles, caller functions omitted (recorded as nonReplayableField), and models by description';
+const METRIC_NAMES = [
+    'totalReturn',
+    'annualizedReturn',
+    'annualizedVolatility',
+    'sharpe',
+    'sortino',
+    'calmar',
+    'maxDrawdown',
+    'hitRate',
+    'profitFactor',
+    'finalValue',
+    'meanTurnover',
+    'totalCosts',
+];
+function fail(functionName, message, code, context = {}) {
+    throw new InputError(`${functionName}: ${message}`, {
+        code,
+        context: { function: functionName, ...context },
+    });
+}
+function detach(value) {
+    return fromCanonicalJson(canonicalJsonOf(value));
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const member of Object.values(value))
+            deepFreeze(member);
+    }
+    return value;
+}
+function isArtifact(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        value.kind === 'totalfinance.analysis-artifact');
+}
+function hasOwn(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+function readPath(record, path) {
+    let cursor = record;
+    for (const segment of path) {
+        if (cursor === null || typeof cursor !== 'object')
+            return undefined;
+        cursor = cursor[segment];
+    }
+    return cursor;
+}
+/** Copy-on-write along one path; every other reference is shared. */
+function withPath(record, path, value) {
+    if (path.length === 0)
+        return value;
+    const [head, ...rest] = path;
+    const base = record !== null && typeof record === 'object' && !Array.isArray(record)
+        ? record
+        : {};
+    return { ...base, [head]: withPath(base[head], rest, value) };
+}
+function scanEmbedded(functionName, label, value, maximumEmbeddedBytes) {
+    try {
+        scanCanonicalData(value, {
+            functionName,
+            label,
+            maximumWorkUnits: maximumEmbeddedBytes,
+            requireFiniteNumbers: true,
+        });
+    }
+    catch (error) {
+        if (isQuantError(error, ErrorCode.InputOutOfRange) &&
+            error.message.includes('data-work limit')) {
+            fail(functionName, `the embedded ${label} exceeds the embedded budget (${maximumEmbeddedBytes.toLocaleString()} work units ≈ canonical bytes) — reference its bulk row sets (referenceRowSets) or raise limits.maximumEmbeddedBytes up to ${BACKTEST_RUN_LIMITS.maximumEmbeddedBytes.maximum.toLocaleString()}.`, ErrorCode.ArtifactEmbeddedInputTooLarge, { field: label, maximumEmbeddedBytes });
+        }
+        throw error;
+    }
+}
+function requireKind(functionName, value) {
+    if (typeof value !== 'string' || !(value in KIND_SPECS)) {
+        fail(functionName, `kind must be one of ${BACKTEST_RUN_KIND_LIST.map((k) => `'${k}'`).join(' | ')}. Received ${value === null ? 'null' : JSON.stringify(value)}.`, ErrorCode.InputInvalidEnum, { field: 'kind' });
+    }
+    return value;
+}
+function specOf(kind) {
+    return KIND_SPECS[kind];
+}
+function requireSnapshotHash(functionName, value) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string' || !value.startsWith('sha256:')) {
+        fail(functionName, 'snapshotHash must be a `sha256:` content hash when present.', ErrorCode.InputWrongType, { field: 'snapshotHash' });
+    }
+    return value;
+}
+function requireHygieneBlock(functionName, field, value) {
+    requireArgumentObject(functionName, field, value);
+    const block = value;
+    ensureKnownKeys(functionName, field, block, HYGIENE_KEYS);
+    for (const key of HYGIENE_KEYS) {
+        if (!hasOwn(block, key))
+            continue;
+        const member = block[key];
+        requireArgumentObject(functionName, `${field}.${key}`, member);
+        const required = HYGIENE_REQUIRED[key];
+        const probe = member[required];
+        if (typeof probe !== 'number' || !Number.isFinite(probe)) {
+            fail(functionName, `${field}.${key}.${required} must be the finite number the @insiderfinance/totalfinance/risk verb reported — attach the verdict verbatim.`, ErrorCode.InputWrongType, { field: `${field}.${key}.${required}` });
+        }
+    }
+    return value;
+}
+function requireRunShape(functionName, field, spec, value) {
+    requireArgumentObject(functionName, field, value);
+    const record = value;
+    ensureKnownKeys(functionName, field, record, spec.runKeys);
+    for (const key of spec.runKeys) {
+        if (!hasOwn(record, key)) {
+            fail(functionName, `${field}.${key} is missing — a '${spec.descriptor.kind}' run is the verbatim result of ${spec.descriptor.operation}, which always reports it.`, ErrorCode.InputMissingField, { field: `${field}.${key}` });
+        }
+    }
+    requireArgumentObject(functionName, `${field}.assumptions`, record['assumptions']);
+    requireArgumentObject(functionName, `${field}.diagnostics`, record['diagnostics']);
+}
+/** Models → descriptions and labels. Present-but-invalid models are refused (they could not have produced the run). */
+function recordModels(functionName, input, root) {
+    const request = readPath(input, root);
+    let working = { ...request };
+    if (hasOwn(working, 'execution') && working['execution'] !== undefined) {
+        const policy = working['execution'];
+        if (policy === null ||
+            typeof policy !== 'object' ||
+            typeof policy.label !== 'string') {
+            fail(functionName, `input.${[...root, 'execution'].join('.')} must be an execution policy (execution.simplified() or execution.declared(...)).`, ErrorCode.InputWrongType, { field: 'input.execution' });
+        }
+        working = { ...working, execution: describeExecutionPolicy(policy) };
+    }
+    if (hasOwn(working, 'transactionCostModel') && working['transactionCostModel'] !== undefined) {
+        const models = working['transactionCostModel'];
+        requireArgumentObject(functionName, `input.${[...root, 'transactionCostModel'].join('.')}`, models);
+        const record = models;
+        const labels = {};
+        for (const key of ['commission', 'slippage']) {
+            if (!hasOwn(record, key) || record[key] === undefined)
+                continue;
+            const label = record[key]?.label;
+            if (typeof label !== 'string' || label.length === 0) {
+                fail(functionName, `input.${[...root, 'transactionCostModel', key].join('.')} must be a labeled ${key} model (fees.* / slippage.*).`, ErrorCode.InputWrongType, { field: `input.transactionCostModel.${key}` });
+            }
+            labels[key] = label;
+        }
+        working = { ...working, transactionCostModel: labels };
+    }
+    return withPath(input, root, working);
+}
+/** Labeled cost models (fees.* / slippage.*) → their labels, at the kind's dotted paths. */
+function recordLabeledModels(functionName, input, paths) {
+    let working = input;
+    for (const dotted of paths) {
+        const path = dotted.split('.');
+        const model = readPath(working, path);
+        if (model === undefined)
+            continue;
+        const label = model?.label;
+        if (typeof label !== 'string' || label.length === 0) {
+            fail(functionName, `input.${dotted} must be a labeled cost model (fees.* / slippage.*).`, ErrorCode.InputWrongType, { field: `input.${dotted}` });
+        }
+        working = withPath(working, path, { label });
+    }
+    return working;
+}
+function projectRun(run, spec, referenced, locators) {
+    let stored = run;
+    const handles = {};
+    const rowCounts = {};
+    let embeddedRows = 0;
+    for (const set of spec.resultRowSets) {
+        const rows = readPath(run, set.path);
+        if (!Array.isArray(rows))
+            continue;
+        rowCounts[set.label] = rows.length;
+        if (referenced.includes(set.label)) {
+            const handle = tableHandleForRows({
+                rows,
+                ...(locators?.[set.label] !== undefined ? { locator: locators[set.label] } : {}),
+            });
+            handles[set.label] = handle;
+            stored = withPath(stored, set.path, handle);
+        }
+        else {
+            embeddedRows += rows.length;
+        }
+    }
+    return { stored, handles, embeddedRows, rowCounts };
+}
+function buildReport(input) {
+    const { spec } = input;
+    const runHash = contentHash(input.storedRun);
+    const referencedRows = Object.values(input.referencedData).reduce((sum, handle) => sum + handle.rowCount, 0);
+    const runWarnings = input.run['diagnostics'].warnings;
+    return {
+        kind: spec.descriptor.kind,
+        runVersion: spec.descriptor.runVersion,
+        run: input.storedRun,
+        inputs: input.storedInput,
+        referencedData: input.referencedData,
+        runHash,
+        identity: spec.identity(input.run, input.storedInput),
+        hygiene: input.hygiene,
+        execution: { completed: true },
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            kind: spec.descriptor.kind,
+            runVersion: spec.descriptor.runVersion,
+            operation: spec.descriptor.operation,
+            replayable: input.nonReplayableField === null,
+            nonReplayableField: input.nonReplayableField,
+            inputPolicy: Object.keys(input.referencedData).length > 0 ? 'referenced' : 'embedded',
+            embeddedRowLimit: input.embeddedRowLimit,
+            modelPolicy: MODEL_POLICY,
+            projection: PROJECTION,
+        },
+        diagnostics: {
+            warnings: [],
+            embeddedRows: input.embeddedRows,
+            referencedRows,
+            runWarningCount: Array.isArray(runWarnings) ? runWarnings.length : 0,
+        },
+    };
+}
+const IDENTITY_KEYS = [
+    'runId',
+    'childRunIds',
+    'universeId',
+    'universeHistoryHash',
+    'strategy',
+    'recipe',
+    'pointInTimePolicy',
+    'conventions',
+    'calendar',
+    'engine',
+    'models',
+    'seed',
+    'benchmark',
+    'annualization',
+    'initialCapital',
+    'baseCurrency',
+    'variations',
+];
+function requireIdentity(functionName, identity) {
+    ensureKnownKeys(functionName, 'report.identity', identity, IDENTITY_KEYS);
+    for (const key of IDENTITY_KEYS) {
+        if (!hasOwn(identity, key))
+            fail(functionName, `report.identity.${key} is missing.`, ErrorCode.InputMissingField, {
+                field: `report.identity.${key}`,
+            });
+    }
+    const nonEmpty = (key) => {
+        if (typeof identity[key] !== 'string' || identity[key].length === 0) {
+            fail(functionName, `report.identity.${key} must be a non-empty string. Received ${identity[key] === null ? 'null' : typeof identity[key]}.`, ErrorCode.InputWrongType, { field: `report.identity.${key}` });
+        }
+    };
+    for (const key of [
+        'runId',
+        'universeId',
+        'universeHistoryHash',
+        'pointInTimePolicy',
+        'baseCurrency',
+    ])
+        nonEmpty(key);
+    if (!identity['runId'].startsWith('sha256:') ||
+        !identity['universeHistoryHash'].startsWith('sha256:')) {
+        fail(functionName, 'report.identity.runId and universeHistoryHash must be `sha256:` content hashes.', ErrorCode.InputWrongType, { field: 'report.identity.runId' });
+    }
+    const objectOrNull = (key, nullable) => {
+        const value = identity[key];
+        if (value === null && nullable)
+            return;
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            fail(functionName, `report.identity.${key} must be an object${nullable ? ' or null' : ''}. Received ${value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value}.`, ErrorCode.InputWrongType, { field: `report.identity.${key}` });
+        }
+    };
+    for (const key of ['strategy', 'conventions', 'calendar', 'engine', 'models', 'annualization'])
+        objectOrNull(key, false);
+    objectOrNull('recipe', true);
+    for (const key of ['childRunIds', 'variations']) {
+        const value = identity[key];
+        if (value !== null && !Array.isArray(value))
+            fail(functionName, `report.identity.${key} must be an array or null.`, ErrorCode.InputWrongType, { field: `report.identity.${key}` });
+    }
+    if (identity['seed'] !== null && !Number.isSafeInteger(identity['seed']))
+        fail(functionName, 'report.identity.seed must be a safe integer or null.', ErrorCode.InputWrongType, { field: 'report.identity.seed' });
+    if (typeof identity['benchmark'] !== 'boolean')
+        fail(functionName, 'report.identity.benchmark must be a boolean.', ErrorCode.InputWrongType, {
+            field: 'report.identity.benchmark',
+        });
+    if (typeof identity['initialCapital'] !== 'number' ||
+        !Number.isFinite(identity['initialCapital']) ||
+        identity['initialCapital'] <= 0) {
+        fail(functionName, 'report.identity.initialCapital must be a positive finite number.', ErrorCode.InputOutOfRange, { field: 'report.identity.initialCapital' });
+    }
+    const conventions = identity['conventions'];
+    ensureKnownKeys(functionName, 'report.identity.conventions', conventions, [
+        'conventionsVersion',
+        'sessionInstantConvention',
+        'pricing',
+    ]);
+    for (const key of ['conventionsVersion', 'sessionInstantConvention', 'pricing']) {
+        if (typeof conventions[key] !== 'string' || conventions[key].length === 0)
+            fail(functionName, `report.identity.conventions.${key} must be a non-empty string.`, ErrorCode.InputWrongType, { field: `report.identity.conventions.${key}` });
+    }
+    const engine = identity['engine'];
+    ensureKnownKeys(functionName, 'report.identity.engine', engine, ['operation', 'runVersion']);
+    if (typeof engine['operation'] !== 'string' || !Number.isSafeInteger(engine['runVersion']))
+        fail(functionName, 'report.identity.engine must carry the operation name and an integer runVersion.', ErrorCode.InputWrongType, { field: 'report.identity.engine' });
+    const calendar = identity['calendar'];
+    ensureKnownKeys(functionName, 'report.identity.calendar', calendar, [
+        'sessions',
+        'firstMarkTimestampMs',
+        'lastMarkTimestampMs',
+    ]);
+    if (!Number.isSafeInteger(calendar['sessions']) || calendar['sessions'] < 0)
+        fail(functionName, 'report.identity.calendar.sessions must be a non-negative safe integer.', ErrorCode.InputOutOfRange, { field: 'report.identity.calendar.sessions' });
+    for (const key of ['firstMarkTimestampMs', 'lastMarkTimestampMs']) {
+        const value = calendar[key];
+        if (value !== null && (typeof value !== 'number' || !Number.isFinite(value)))
+            fail(functionName, `report.identity.calendar.${key} must be a finite number or null.`, ErrorCode.InputWrongType, { field: `report.identity.calendar.${key}` });
+    }
+    const annualization = identity['annualization'];
+    ensureKnownKeys(functionName, 'report.identity.annualization', annualization, [
+        'periodsPerYear',
+        'riskFreeRate',
+    ]);
+    if (typeof annualization['periodsPerYear'] !== 'number' ||
+        !(annualization['periodsPerYear'] > 0) ||
+        typeof annualization['riskFreeRate'] !== 'number' ||
+        !Number.isFinite(annualization['riskFreeRate'])) {
+        fail(functionName, 'report.identity.annualization must carry a positive periodsPerYear and a finite riskFreeRate.', ErrorCode.InputOutOfRange, { field: 'report.identity.annualization' });
+    }
+    const models = identity['models'];
+    ensureKnownKeys(functionName, 'report.identity.models', models, [
+        'execution',
+        'commission',
+        'slippage',
+    ]);
+    for (const key of ['commission', 'slippage']) {
+        const value = models[key];
+        if (value !== null && (typeof value !== 'string' || value.length === 0))
+            fail(functionName, `report.identity.models.${key} must be a label or null.`, ErrorCode.InputWrongType, { field: `report.identity.models.${key}` });
+    }
+    if (models['execution'] !== null &&
+        (typeof models['execution'] !== 'object' || Array.isArray(models['execution'])))
+        fail(functionName, 'report.identity.models.execution must be an execution-policy description or null.', ErrorCode.InputWrongType, { field: 'report.identity.models.execution' });
+}
+function requireReport(functionName, value) {
+    requireArgumentObject(functionName, 'report', value);
+    const record = value;
+    ensureKnownKeys(functionName, 'report', record, REPORT_KEYS);
+    for (const key of REPORT_KEYS) {
+        if (!hasOwn(record, key))
+            fail(functionName, `report.${key} is missing — not a backtest-run report.`, ErrorCode.InputMissingField, { field: `report.${key}` });
+    }
+    const kind = requireKind(functionName, record['kind']);
+    const spec = specOf(kind);
+    if (record['runVersion'] !== spec.descriptor.runVersion) {
+        fail(functionName, `report.runVersion is ${String(record['runVersion'])}; this library reads '${kind}' runs at version ${spec.descriptor.runVersion} — register a migration.`, ErrorCode.InputOutOfRange, { field: 'report.runVersion' });
+    }
+    requireArgumentObject(functionName, 'report.run', record['run']);
+    ensureKnownKeys(functionName, 'report.run', record['run'], spec.runKeys);
+    requireArgumentObject(functionName, 'report.inputs', record['inputs']);
+    requireArgumentObject(functionName, 'report.referencedData', record['referencedData']);
+    for (const [label, handle] of Object.entries(record['referencedData'])) {
+        if (!isTableHandle(handle))
+            fail(functionName, `report.referencedData.${label} is not a table handle.`, ErrorCode.InputWrongType, { field: `report.referencedData.${label}` });
+    }
+    if (typeof record['runHash'] !== 'string' || !record['runHash'].startsWith('sha256:')) {
+        fail(functionName, 'report.runHash must be a `sha256:` content hash.', ErrorCode.InputWrongType, { field: 'report.runHash' });
+    }
+    // The hash is the stored projection's: a report whose referenced result rows were restored by
+    // the read door still verifies, because the handles stand in for the rows again here.
+    let projection = record['run'];
+    for (const [label, handle] of Object.entries(record['referencedData'])) {
+        const set = spec.resultRowSets.find((candidate) => candidate.label === label);
+        if (set !== undefined && !isTableHandle(readPath(projection, set.path))) {
+            projection = withPath(projection, set.path, handle);
+        }
+    }
+    const recomputedHash = contentHash(projection);
+    if (recomputedHash !== record['runHash']) {
+        fail(functionName, `report.runHash (${record['runHash'].slice(0, 18)}…) does not match the stored run (${recomputedHash.slice(0, 18)}…) — the report was altered after it was written.`, ErrorCode.ArtifactIdMismatch, { field: 'report.runHash' });
+    }
+    requireArgumentObject(functionName, 'report.identity', record['identity']);
+    requireIdentity(functionName, record['identity']);
+    if (record['hygiene'] !== null)
+        requireHygieneBlock(functionName, 'report.hygiene', record['hygiene']);
+    requireArgumentObject(functionName, 'report.execution', record['execution']);
+    ensureKnownKeys(functionName, 'report.execution', record['execution'], ['completed']);
+    if (record['execution'].completed !== true) {
+        fail(functionName, 'report.execution.completed must be true — a partial run is a Stage 7B format and cannot be read yet.', ErrorCode.InputOutOfRange, { field: 'report.execution.completed' });
+    }
+    requireArgumentObject(functionName, 'report.assumptions', record['assumptions']);
+    ensureKnownKeys(functionName, 'report.assumptions', record['assumptions'], ASSUMPTION_KEYS);
+    const assumptions = record['assumptions'];
+    for (const key of ASSUMPTION_KEYS) {
+        if (!hasOwn(assumptions, key))
+            fail(functionName, `report.assumptions.${key} is missing.`, ErrorCode.InputMissingField, {
+                field: `report.assumptions.${key}`,
+            });
+    }
+    for (const key of ['conventionsVersion', 'operation', 'modelPolicy', 'projection']) {
+        if (typeof assumptions[key] !== 'string' || assumptions[key].length === 0) {
+            fail(functionName, `report.assumptions.${key} must be a non-empty string. Received ${assumptions[key] === null ? 'null' : typeof assumptions[key]}.`, ErrorCode.InputWrongType, { field: `report.assumptions.${key}` });
+        }
+    }
+    if (assumptions['kind'] !== kind)
+        fail(functionName, `report.assumptions.kind must repeat report.kind ('${kind}').`, ErrorCode.InputOutOfRange, { field: 'report.assumptions.kind' });
+    if (assumptions['runVersion'] !== record['runVersion'])
+        fail(functionName, 'report.assumptions.runVersion must repeat report.runVersion.', ErrorCode.InputOutOfRange, { field: 'report.assumptions.runVersion' });
+    if (assumptions['operation'] !== spec.descriptor.operation)
+        fail(functionName, `report.assumptions.operation must be '${spec.descriptor.operation}' for a '${kind}' run.`, ErrorCode.InputOutOfRange, { field: 'report.assumptions.operation' });
+    if (typeof assumptions['replayable'] !== 'boolean')
+        fail(functionName, 'report.assumptions.replayable must be a boolean.', ErrorCode.InputWrongType, { field: 'report.assumptions.replayable' });
+    if (assumptions['nonReplayableField'] !== null &&
+        (typeof assumptions['nonReplayableField'] !== 'string' ||
+            assumptions['nonReplayableField'].length === 0)) {
+        fail(functionName, 'report.assumptions.nonReplayableField must be a field path or null.', ErrorCode.InputWrongType, { field: 'report.assumptions.nonReplayableField' });
+    }
+    if ((assumptions['replayable'] === true) !== (assumptions['nonReplayableField'] === null)) {
+        fail(functionName, 'report.assumptions.replayable contradicts nonReplayableField — a run is replayable exactly when no callback field is recorded.', ErrorCode.InputOutOfRange, { field: 'report.assumptions.replayable' });
+    }
+    if (assumptions['inputPolicy'] !== 'embedded' && assumptions['inputPolicy'] !== 'referenced') {
+        fail(functionName, `report.assumptions.inputPolicy must be 'embedded' | 'referenced'. Received ${JSON.stringify(assumptions['inputPolicy'])}.`, ErrorCode.InputInvalidEnum, { field: 'report.assumptions.inputPolicy' });
+    }
+    if ((assumptions['inputPolicy'] === 'referenced') !==
+        Object.keys(record['referencedData']).length > 0) {
+        fail(functionName, 'report.assumptions.inputPolicy contradicts referencedData — the policy is referenced exactly when a row set travels by handle.', ErrorCode.InputOutOfRange, { field: 'report.assumptions.inputPolicy' });
+    }
+    requireArgumentObject(functionName, 'report.diagnostics', record['diagnostics']);
+    const diagnostics = record['diagnostics'];
+    ensureKnownKeys(functionName, 'report.diagnostics', diagnostics, DIAGNOSTIC_KEYS);
+    for (const key of ['embeddedRows', 'referencedRows', 'runWarningCount']) {
+        const count = diagnostics[key];
+        if (!Number.isSafeInteger(count) || count < 0) {
+            fail(functionName, `report.diagnostics.${key} must be a non-negative safe integer. Received ${count === null ? 'null' : String(count)}.`, ErrorCode.InputOutOfRange, { field: `report.diagnostics.${key}` });
+        }
+    }
+    if (!Array.isArray(diagnostics['warnings'])) {
+        fail(functionName, 'report.diagnostics.warnings must be an array.', ErrorCode.InputWrongType, {
+            field: 'report.diagnostics.warnings',
+        });
+    }
+    const embeddedRowLimit = assumptions['embeddedRowLimit'];
+    if (!Number.isSafeInteger(embeddedRowLimit) || embeddedRowLimit < 1) {
+        fail(functionName, `report.assumptions.embeddedRowLimit must be a positive safe integer. Received ${embeddedRowLimit === null ? 'null' : String(embeddedRowLimit)}.`, ErrorCode.InputOutOfRange, { field: 'report.assumptions.embeddedRowLimit' });
+    }
+    return value;
+}
+// ─────────────────────────────────────────── the verbs ──────────────────────────────────────────
+/**
+ * Describe a run and save it as an identified, immutable artifact.
+ *
+ * @example
+ * ```ts
+ * const run = crossSectionalBacktest(request);
+ * const artifact = backtestRunArtifact({
+ *   kind: 'cross-sectional',
+ *   run,
+ *   input: request,
+ *   referenceRowSets: ['dataset.returns', 'run.ledger.events'],
+ * });
+ * ```
+ */
+export function backtestRunArtifact(input) {
+    const functionName = 'backtestRunArtifact';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, [
+        'kind',
+        'run',
+        'input',
+        'referenceRowSets',
+        'locators',
+        'hygiene',
+        'snapshotHash',
+        'libraryVersion',
+        'createdFrom',
+        'provenance',
+        'limits',
+    ]);
+    const kind = requireKind(functionName, input.kind);
+    const spec = specOf(kind);
+    if (input.limits !== undefined) {
+        requireArgumentObject(functionName, 'limits', input.limits);
+        ensureKnownKeys(functionName, 'limits', input.limits, [
+            'maximumEmbeddedBytes',
+            'embeddedRowLimit',
+        ]);
+    }
+    const maximumEmbeddedBytes = requireWorkLimit({
+        functionName,
+        field: 'limits.maximumEmbeddedBytes',
+        value: input.limits?.maximumEmbeddedBytes,
+        law: BACKTEST_RUN_LIMITS.maximumEmbeddedBytes,
+    });
+    const embeddedRowLimit = requireWorkLimit({
+        functionName,
+        field: 'limits.embeddedRowLimit',
+        value: input.limits?.embeddedRowLimit,
+        law: BACKTEST_RUN_LIMITS.embeddedRowLimit,
+    });
+    const snapshotHash = requireSnapshotHash(functionName, input.snapshotHash);
+    if (input.libraryVersion !== undefined &&
+        (typeof input.libraryVersion !== 'string' || input.libraryVersion.length === 0)) {
+        fail(functionName, 'libraryVersion must be a non-empty version string when present.', ErrorCode.InputWrongType, { field: 'libraryVersion' });
+    }
+    if (input.createdFrom !== undefined)
+        requireArgumentArray(functionName, 'createdFrom', input.createdFrom);
+    if (input.referenceRowSets !== undefined)
+        requireArgumentArray(functionName, 'referenceRowSets', input.referenceRowSets);
+    const referenceRowSets = input.referenceRowSets ?? [];
+    const knownLabels = [
+        ...spec.inputRowSets.map((s) => s.label),
+        ...spec.resultRowSets.map((s) => s.label),
+    ];
+    for (const name of referenceRowSets) {
+        if (typeof name !== 'string' || !knownLabels.includes(name)) {
+            fail(functionName, `referenceRowSets names ${JSON.stringify(name)}, which is not a bulk row set of a '${kind}' run — its row sets are ${knownLabels.join(', ')}.`, ErrorCode.InputInvalidEnum, { field: 'referenceRowSets', kind });
+        }
+    }
+    if (input.locators !== undefined) {
+        requireArgumentObject(functionName, 'locators', input.locators);
+        for (const [name, locator] of Object.entries(input.locators)) {
+            if (!referenceRowSets.includes(name))
+                fail(functionName, `locators.${name} names a row set that is not being referenced — list it in referenceRowSets.`, ErrorCode.InputUnknownField, { field: `locators.${name}` });
+            if (typeof locator !== 'string' || locator.length === 0)
+                fail(functionName, `locators.${name} must be a non-empty storage locator string.`, ErrorCode.InputWrongType, { field: `locators.${name}` });
+        }
+    }
+    // The run: the verb's result, a plain acyclic finite value.
+    requireRunShape(functionName, 'run', spec, input.run);
+    const projected = projectRun(input.run, spec, referenceRowSets, input.locators);
+    for (const [label, count] of Object.entries(projected.rowCounts)) {
+        if (!referenceRowSets.includes(label) && count > embeddedRowLimit) {
+            fail(functionName, `${label} has ${count} rows, above the embedded row limit ${embeddedRowLimit} — nothing is truncated silently. Reference the row set (referenceRowSets: ['${label}'], which stores its content hash and row count) or raise limits.embeddedRowLimit up to ${BACKTEST_RUN_LIMITS.embeddedRowLimit.maximum}.`, ErrorCode.ArtifactEmbeddedInputTooLarge, { field: label, rows: count, embeddedRowLimit });
+        }
+    }
+    scanEmbedded(functionName, 'run', projected.stored, maximumEmbeddedBytes);
+    const storedRun = detach(projected.stored);
+    // The request: the verb's own guard first (an artifact stores only a request the verb accepts),
+    // then callbacks recorded and stripped, models by description, rows embedded or referenced.
+    requireArgumentObject(functionName, 'input', input.input);
+    spec.requireInput(functionName, 'input', input.input);
+    let working = { ...input.input };
+    let nonReplayableField = null;
+    for (const callback of spec.callbacks) {
+        const value = readPath(working, callback.path);
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'function') {
+            fail(functionName, `input.${callback.field} is present but not a function — ${spec.descriptor.operation} would have refused this request, so it cannot be the request that produced the run.`, ErrorCode.InputWrongType, { field: `input.${callback.field}` });
+        }
+        nonReplayableField = nonReplayableField ?? callback.field;
+        working = callback.strip(working);
+    }
+    for (const callback of spec.dynamicCallbacks(working)) {
+        nonReplayableField = nonReplayableField ?? callback.field;
+        working = callback.strip(working);
+    }
+    working = recordModels(functionName, working, spec.modelRoot);
+    working = recordLabeledModels(functionName, working, spec.labeledModels);
+    scanEmbedded(functionName, 'input', working, maximumEmbeddedBytes);
+    let storedInput = detach(working);
+    const referencedData = { ...projected.handles };
+    let embeddedRows = projected.embeddedRows;
+    for (const set of spec.inputRowSets) {
+        const rows = readPath(storedInput, set.path);
+        if (rows === undefined) {
+            if (referenceRowSets.includes(set.label))
+                fail(functionName, `referenceRowSets names '${set.label}', which this request does not carry.`, ErrorCode.InputInvalidEnum, { field: 'referenceRowSets' });
+            continue;
+        }
+        if (!Array.isArray(rows))
+            fail(functionName, `input.${set.label} must be the row array ${spec.descriptor.operation} consumed. Received ${rows === null ? 'null' : typeof rows}.`, ErrorCode.InputWrongType, { field: `input.${set.label}` });
+        if (referenceRowSets.includes(set.label)) {
+            const handle = tableHandleForRows({
+                rows,
+                ...(input.locators?.[set.label] !== undefined
+                    ? { locator: input.locators[set.label] }
+                    : {}),
+            });
+            referencedData[set.label] = handle;
+            storedInput = withPath(storedInput, set.path, handle);
+        }
+        else if (rows.length > embeddedRowLimit) {
+            fail(functionName, `input.${set.label} has ${rows.length} rows, above the embedded row limit ${embeddedRowLimit} — nothing is truncated silently. Reference the row set (referenceRowSets: ['${set.label}']) or raise limits.embeddedRowLimit up to ${BACKTEST_RUN_LIMITS.embeddedRowLimit.maximum}.`, ErrorCode.ArtifactEmbeddedInputTooLarge, { field: `input.${set.label}`, rows: rows.length, embeddedRowLimit });
+        }
+        else {
+            embeddedRows += rows.length;
+        }
+    }
+    const storedBytes = canonicalJsonOf(storedInput).length + canonicalJsonOf(storedRun).length;
+    if (storedBytes > maximumEmbeddedBytes) {
+        fail(functionName, `the embedded request and run are ${storedBytes.toLocaleString()} canonical bytes, above the limit ${maximumEmbeddedBytes.toLocaleString()} — reference the bulk row sets (referenceRowSets) or raise limits.maximumEmbeddedBytes up to ${BACKTEST_RUN_LIMITS.maximumEmbeddedBytes.maximum.toLocaleString()}.`, ErrorCode.ArtifactEmbeddedInputTooLarge, { field: 'input', bytes: storedBytes, maximumEmbeddedBytes });
+    }
+    // Hygiene: a single run takes the caller's verdicts verbatim; a grid carries its own.
+    let hygiene = null;
+    if (kind === 'cross-sectional-grid') {
+        if (input.hygiene !== undefined)
+            fail(functionName, "a 'cross-sectional-grid' run carries its own hygiene at run.hygiene — omit input.hygiene.", ErrorCode.InputUnknownField, { field: 'hygiene' });
+        const own = input.run.hygiene;
+        const block = {
+            ...(own.researchProtocol !== null
+                ? { researchProtocol: detach(own.researchProtocol) }
+                : {}),
+            ...(own.deflatedSharpe !== null
+                ? { deflatedSharpe: detach(own.deflatedSharpe) }
+                : {}),
+            ...(own.backtestOverfitting !== null
+                ? {
+                    backtestOverfitting: detach(own.backtestOverfitting),
+                }
+                : {}),
+        };
+        hygiene = Object.keys(block).length > 0 ? block : null;
+    }
+    else if (input.hygiene !== undefined) {
+        hygiene = detach(requireHygieneBlock(functionName, 'hygiene', input.hygiene));
+    }
+    const report = buildReport({
+        spec,
+        run: input.run,
+        storedRun,
+        storedInput,
+        referencedData,
+        hygiene,
+        nonReplayableField,
+        embeddedRows,
+        embeddedRowLimit,
+    });
+    const referenced = Object.fromEntries(Object.keys(referencedData)
+        .sort()
+        .map((label) => [label, referencedData[label].contentHash]));
+    return createAnalysisArtifact({
+        artifactType: BACKTEST_RUN_ARTIFACT_TYPE,
+        producedBy: {
+            operation: spec.descriptor.operation,
+            ...(input.libraryVersion !== undefined ? { libraryVersion: input.libraryVersion } : {}),
+        },
+        inputs: {
+            ...(snapshotHash !== null ? { snapshotHash } : {}),
+            parameters: {
+                kind,
+                runVersion: spec.descriptor.runVersion,
+                runHash: report.runHash,
+                runId: report.identity.runId,
+                referenced,
+            },
+        },
+        ...(input.createdFrom !== undefined ? { createdFrom: input.createdFrom } : {}),
+        result: report,
+        ...(Object.keys(referencedData).length > 0 ? { tables: referencedData } : {}),
+        ...(input.provenance !== undefined ? { provenance: input.provenance } : {}),
+    });
+}
+/** Restore referenced row sets into a report from supplied rows, each verified against its handle. */
+function restoreRows(functionName, report, referencedData, required) {
+    const spec = specOf(report.kind);
+    let run = report.run;
+    let inputs = report.inputs;
+    const restored = [];
+    for (const label of Object.keys(report.referencedData).sort()) {
+        const handle = report.referencedData[label];
+        const rows = referencedData?.[label];
+        if (rows === undefined) {
+            if (required && !label.startsWith('run.'))
+                fail(functionName, `the artifact references its '${label}' row set by table handle (${handle.rowCount} rows, ${handle.contentHash.slice(0, 18)}…) — supply the rows as referencedData['${label}'] to replay.`, ErrorCode.InputMissingField, { field: `referencedData.${label}` });
+            continue;
+        }
+        const verified = detach(verifyReferencedRows({ functionName, label, handle, rows }));
+        const resultSet = spec.resultRowSets.find((s) => s.label === label);
+        if (resultSet !== undefined)
+            run = withPath(run, resultSet.path, verified);
+        else {
+            const inputSet = spec.inputRowSets.find((s) => s.label === label);
+            inputs = withPath(inputs, inputSet.path, verified);
+        }
+        restored.push(label);
+    }
+    if (referencedData !== undefined) {
+        for (const label of Object.keys(referencedData)) {
+            if (!(label in report.referencedData))
+                fail(functionName, `referencedData['${label}'] names a row set the artifact does not reference — its referenced row sets are ${Object.keys(report.referencedData).sort().join(', ') || 'none'}.`, ErrorCode.InputUnknownField, { field: `referencedData.${label}` });
+        }
+    }
+    return { report: { ...report, run, inputs }, restored };
+}
+/**
+ * Restore a run artifact: Gate B's read door, a foreign-type refusal, the run-level migration policy,
+ * the report re-validated (its run hash recomputed), and any supplied referenced rows verified by
+ * hash and restored into the report.
+ */
+export function readBacktestRun(input) {
+    const functionName = 'readBacktestRun';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, ['artifact', 'migrations', 'referencedData']);
+    if (input.referencedData !== undefined)
+        requireArgumentObject(functionName, 'referencedData', input.referencedData);
+    const read = readAnalysisArtifact({
+        artifact: input.artifact,
+        ...(input.migrations !== undefined ? { migrations: input.migrations } : {}),
+    });
+    const artifact = read.artifact;
+    if (artifact.artifactType !== BACKTEST_RUN_ARTIFACT_TYPE) {
+        fail(functionName, `the artifact's type is '${artifact.artifactType}', not '${BACKTEST_RUN_ARTIFACT_TYPE}' — this reader restores backtest runs only; ${artifact.artifactType.startsWith('research.') ? 'use @insiderfinance/totalfinance/research/artifacts' : artifact.artifactType.startsWith('volatility.') ? 'use @insiderfinance/totalfinance/volatility/artifacts' : artifact.artifactType.startsWith('fixed-income.') ? 'use @insiderfinance/totalfinance/fixed-income/artifacts' : 'read it with the package that owns that type'}.`, ErrorCode.ArtifactFamilyMismatch, { artifactType: artifact.artifactType });
+    }
+    const raw = artifact.result;
+    const kind = requireKind(functionName, raw['kind']);
+    const migrated = applyReportMigrations({
+        functionName,
+        kind: `${BACKTEST_RUN_ARTIFACT_TYPE}:${kind}`,
+        report: raw,
+        storedVersion: raw['runVersion'],
+        currentVersion: specOf(kind).descriptor.runVersion,
+        versionField: 'runVersion',
+        subject: `'${kind}' run`,
+        ...(input.migrations !== undefined ? { migrations: input.migrations } : {}),
+    });
+    const validated = requireReport(functionName, migrated.report);
+    const { report, restored } = restoreRows(functionName, detach(validated), input.referencedData, false);
+    return {
+        report: deepFreeze(report),
+        artifact,
+        migrationsApplied: read.migrationsApplied,
+        modelMigrationsApplied: migrated.modelMigrationsApplied,
+        restoredRowSets: restored,
+    };
+}
+function liveModels(functionName, report, models) {
+    const spec = specOf(report.kind);
+    let request = report.inputs;
+    const recorded = readPath(request, spec.modelRoot);
+    let executionMode = 'none';
+    let costMode = 'none';
+    if (models !== undefined) {
+        requireArgumentObject(functionName, 'models', models);
+        ensureKnownKeys(functionName, 'models', models, [
+            'execution',
+            'transactionCostModel',
+            'labeled',
+        ]);
+    }
+    // The options kind's labeled models: each recorded label must be supplied by a model carrying it.
+    const labeledSupplied = models?.labeled ?? {};
+    if (models?.labeled !== undefined)
+        requireArgumentObject(functionName, 'models.labeled', models.labeled);
+    for (const dotted of spec.labeledModels) {
+        const recordedLabel = readPath(request, dotted.split('.'))
+            ?.label;
+        const model = labeledSupplied[dotted];
+        if (recordedLabel === undefined) {
+            if (model !== undefined)
+                fail(functionName, `models.labeled['${dotted}'] was supplied but the run recorded no model there — omit it.`, ErrorCode.InputUnknownField, { field: `models.labeled.${dotted}` });
+            continue;
+        }
+        if (model === undefined)
+            fail(functionName, `the run recorded the model '${String(recordedLabel)}' at ${dotted} that no artifact can carry — supply the live model as models.labeled['${dotted}']; its label is verified before the run.`, ErrorCode.InputMissingField, { field: `models.labeled.${dotted}`, label: recordedLabel });
+        if (model.label !== recordedLabel)
+            fail(functionName, `models.labeled['${dotted}'] is '${model.label}'; the run recorded '${String(recordedLabel)}'. A replay runs the models the run ran.`, ErrorCode.BacktestAdapterNonconformant, { field: `models.labeled.${dotted}`, recorded: recordedLabel, supplied: model.label });
+        request = withPath(request, dotted.split('.'), model);
+    }
+    for (const key of Object.keys(labeledSupplied)) {
+        if (!spec.labeledModels.includes(key))
+            fail(functionName, `models.labeled['${key}'] names no model path of a '${report.kind}' run — its model paths are ${spec.labeledModels.join(', ') || 'none'}.`, ErrorCode.InputUnknownField, { field: `models.labeled.${key}` });
+    }
+    const executionField = [...spec.modelRoot, 'execution'].join('.');
+    if (recorded['execution'] !== undefined) {
+        const description = recorded['execution'];
+        let policy;
+        if (models?.execution !== undefined) {
+            policy = models.execution;
+            executionMode = 'supplied';
+        }
+        else if (description.realism === 'simplified') {
+            policy = executionPolicies.simplified();
+            executionMode = 'recorded-default';
+        }
+        else {
+            fail(functionName, `the run recorded a declared execution policy ('${description.label}') that no artifact can carry — supply the live policy as models.execution; it is verified against the recorded description before the run.`, ErrorCode.InputMissingField, { field: 'models.execution', label: description.label });
+        }
+        const supplied = describeExecutionPolicy(policy);
+        if (canonicalJsonOf(supplied) !== canonicalJsonOf(description)) {
+            fail(functionName, `models.execution does not match the recorded execution policy — recorded '${description.label}' (${description.realism}), supplied '${supplied.label}' (${supplied.realism}). A replay runs the policy the run ran.`, ErrorCode.BacktestAdapterNonconformant, { field: 'models.execution', recorded: description.label, supplied: supplied.label });
+        }
+        request = withPath(request, [...spec.modelRoot, 'execution'], policy);
+    }
+    else if (models?.execution !== undefined) {
+        fail(functionName, `models.execution was supplied but the run recorded no execution policy at ${executionField} (it ran the simplified default) — omit models.execution.`, ErrorCode.InputUnknownField, { field: 'models.execution' });
+    }
+    if (recorded['transactionCostModel'] !== undefined) {
+        const labels = recorded['transactionCostModel'];
+        const supplied = models?.transactionCostModel;
+        if (supplied === undefined) {
+            fail(functionName, `the run recorded transaction-cost models by label (${Object.entries(labels)
+                .map(([k, v]) => `${k}: ${v}`)
+                .join(', ')}) that no artifact can carry — supply the live models as models.transactionCostModel; each label is verified before the run.`, ErrorCode.InputMissingField, { field: 'models.transactionCostModel', labels });
+        }
+        requireArgumentObject(functionName, 'models.transactionCostModel', supplied);
+        ensureKnownKeys(functionName, 'models.transactionCostModel', supplied, [
+            'commission',
+            'slippage',
+        ]);
+        const live = {};
+        for (const key of ['commission', 'slippage']) {
+            const recordedLabel = labels[key];
+            const model = supplied[key];
+            if (recordedLabel === undefined) {
+                if (model !== undefined)
+                    fail(functionName, `models.transactionCostModel.${key} was supplied but the run recorded no ${key} model — omit it.`, ErrorCode.InputUnknownField, { field: `models.transactionCostModel.${key}` });
+                continue;
+            }
+            if (model === undefined)
+                fail(functionName, `models.transactionCostModel.${key} is missing — the run recorded '${recordedLabel}'.`, ErrorCode.InputMissingField, { field: `models.transactionCostModel.${key}` });
+            if (model.label !== recordedLabel)
+                fail(functionName, `models.transactionCostModel.${key} is '${model.label}'; the run recorded '${recordedLabel}'. A replay runs the models the run ran.`, ErrorCode.BacktestAdapterNonconformant, {
+                    field: `models.transactionCostModel.${key}`,
+                    recorded: recordedLabel,
+                    supplied: model.label,
+                });
+            live[key] = model;
+        }
+        request = withPath(request, [...spec.modelRoot, 'transactionCostModel'], live);
+        costMode = 'supplied';
+    }
+    else if (models?.transactionCostModel !== undefined) {
+        fail(functionName, 'models.transactionCostModel was supplied but the run recorded no transaction-cost models — omit it.', ErrorCode.InputUnknownField, { field: 'models.transactionCostModel' });
+    }
+    return { request, execution: executionMode, transactionCostModel: costMode };
+}
+/**
+ * Re-issue the run's verb from the stored request (referenced rows supplied and re-verified, models
+ * taken back and verified against their recorded descriptions) and compare the recomputed run hash
+ * with the saved one. A run that recorded a caller function refuses by name.
+ */
+export function replayBacktestRun(input) {
+    const functionName = 'replayBacktestRun';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, [
+        'artifact',
+        'migrations',
+        'referencedData',
+        'models',
+        'libraryVersion',
+        'limits',
+    ]);
+    if (input.referencedData !== undefined)
+        requireArgumentObject(functionName, 'referencedData', input.referencedData);
+    const read = readBacktestRun({
+        artifact: input.artifact,
+        ...(input.migrations !== undefined ? { migrations: input.migrations } : {}),
+    });
+    const report = read.report;
+    const spec = specOf(report.kind);
+    if (!report.assumptions.replayable) {
+        fail(functionName, `the '${report.kind}' run is not replayable: its request carried a caller function at ${report.assumptions.nonReplayableField ?? '(unrecorded)'} that no artifact can store — re-run ${spec.descriptor.operation} with the declarative form of that input and save that run.`, ErrorCode.ArtifactNotReplayable, { kind: report.kind, field: report.assumptions.nonReplayableField });
+    }
+    const restored = restoreRows(functionName, report, input.referencedData, true).report;
+    const referencedResultSets = Object.keys(report.referencedData).filter((label) => label.startsWith('run.'));
+    const models = liveModels(functionName, restored, input.models);
+    const recomputedRun = spec.run(models.request);
+    const projected = projectRun(recomputedRun, spec, referencedResultSets, undefined);
+    const recomputedReport = buildReport({
+        spec,
+        run: recomputedRun,
+        storedRun: detach(projected.stored),
+        storedInput: report.inputs,
+        referencedData: { ...report.referencedData, ...projected.handles },
+        hygiene: report.hygiene,
+        nonReplayableField: report.assumptions.nonReplayableField,
+        embeddedRows: report.diagnostics.embeddedRows,
+        embeddedRowLimit: report.assumptions.embeddedRowLimit,
+    });
+    const parity = artifactReplayParity({
+        saved: report.run,
+        recomputed: recomputedReport.run,
+        ...(input.limits !== undefined ? { limits: input.limits } : {}),
+    });
+    const warnings = [];
+    const saved = read.artifact.producedBy.libraryVersion ?? null;
+    const current = input.libraryVersion ?? null;
+    if (saved !== null && current !== null && saved !== current) {
+        warnings.push(warning(WarningCode.ArtifactLibraryVersionDiffers, `${functionName}: the artifact was produced by library version ${saved}; this replay runs ${current} — a parity difference may be a library change rather than a data change.`, 'warn', { saved, current }));
+    }
+    if (!parity.identical) {
+        warnings.push(warning(WarningCode.ArtifactLibraryVersionDiffers, `${functionName}: replay parity FAILED for '${report.kind}' — ${parity.differenceCount} difference${parity.differenceCount === 1 ? '' : 's'} between the saved run and the recomputation (first at ${parity.differences[0]?.path ?? parity.addedPaths[0] ?? parity.removedPaths[0] ?? '(unknown)'}). An engine is deterministic given its inputs, so this is a finding: a changed engine, dependency, model, or platform.`, 'warn', { differenceCount: parity.differenceCount }));
+    }
+    return deepFreeze({
+        kind: report.kind,
+        artifactId: read.artifact.id,
+        recomputed: deepFreeze(recomputedReport),
+        runHash: { saved: report.runHash, recomputed: recomputedReport.runHash },
+        matches: report.runHash === recomputedReport.runHash,
+        parity,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            kind: report.kind,
+            runVersion: report.runVersion,
+            operation: spec.descriptor.operation,
+            libraryVersion: { saved, current },
+            referencedRowSets: Object.keys(report.referencedData).sort(),
+            models: { execution: models.execution, transactionCostModel: models.transactionCostModel },
+        },
+        diagnostics: { warnings },
+    });
+}
+// ─────────────────────────────────────────── comparison ─────────────────────────────────────────
+function resolveRun(functionName, value, field) {
+    if (isArtifact(value)) {
+        const read = readBacktestRun({ artifact: value });
+        return { report: read.report, artifactId: read.artifact.id };
+    }
+    requireArgumentObject(functionName, field, value);
+    return { report: requireReport(functionName, value), artifactId: null };
+}
+/** The run as stored: referenced result row sets as their handles (a hydrated report projects back). */
+function storedProjection(report) {
+    const spec = specOf(report.kind);
+    let projection = report.run;
+    for (const [label, handle] of Object.entries(report.referencedData)) {
+        const set = spec.resultRowSets.find((candidate) => candidate.label === label);
+        if (set !== undefined && !isTableHandle(readPath(projection, set.path))) {
+            projection = withPath(projection, set.path, handle);
+        }
+    }
+    return projection;
+}
+function idList(ids, listedIds) {
+    const sorted = [...ids].sort();
+    return {
+        count: sorted.length,
+        ids: sorted.slice(0, listedIds),
+        remainderCount: Math.max(0, sorted.length - listedIds),
+    };
+}
+function membership(baseline, candidate, listedIds) {
+    const left = new Set(baseline);
+    const right = new Set(candidate);
+    return {
+        entered: idList([...right].filter((id) => !left.has(id)), listedIds),
+        exited: idList([...left].filter((id) => !right.has(id)), listedIds),
+        kept: idList([...left].filter((id) => right.has(id)), listedIds),
+    };
+}
+function finiteOrNull(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function metricsOf(report) {
+    const run = report.run;
+    if (report.kind === 'cross-sectional-grid') {
+        const best = run['best'];
+        const variations = run['variations'];
+        const row = best !== null && Array.isArray(variations)
+            ? variations[best.index]
+            : undefined;
+        const metrics = row?.metrics ?? {};
+        return Object.fromEntries(METRIC_NAMES.map((name) => [name, finiteOrNull(metrics[name])]));
+    }
+    // an environment episode carries the engine's own result under `result`
+    const root = report.kind === 'environment' ? (run['result'] ?? {}) : run;
+    const performance = (root['performance'] ?? {});
+    const rebalances = root['rebalances'];
+    let turnover = null;
+    let costs = null;
+    if (Array.isArray(rebalances)) {
+        let t = 0;
+        let c = 0;
+        for (const r of rebalances) {
+            t += finiteOrNull(r.turnover) ?? 0;
+            c += finiteOrNull(r.costs) ?? 0;
+        }
+        turnover = rebalances.length > 0 ? t / rebalances.length : null;
+        costs = c;
+    }
+    return {
+        ...Object.fromEntries(METRIC_NAMES.filter((n) => n !== 'finalValue' && n !== 'meanTurnover' && n !== 'totalCosts').map((name) => [name, finiteOrNull(performance[name])])),
+        finalValue: finiteOrNull(root['finalValue']),
+        meanTurnover: turnover,
+        totalCosts: costs,
+    };
+}
+function finalHoldings(report) {
+    const holdings = report.run['holdings'];
+    const rebalances = report.run['rebalances'];
+    if (!Array.isArray(holdings) || !Array.isArray(rebalances) || rebalances.length === 0)
+        return null;
+    const last = rebalances.length - 1;
+    return holdings
+        .filter((h) => h.rebalanceIndex === last && h.quantity !== 0)
+        .map((h) => h.instrumentId);
+}
+function hygieneVerdict(report) {
+    const verdict = report.hygiene?.researchProtocol?.['verdict'];
+    return typeof verdict === 'string' ? verdict : null;
+}
+/** Compare two runs of one kind: metric deltas, holdings membership, rebalance-by-rebalance turnover and cost deltas, grid variation deltas, the hygiene verdict, and the structural diff. */
+export function compareBacktestRuns(input) {
+    const functionName = 'compareBacktestRuns';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, ['baseline', 'candidate', 'tolerance', 'limits']);
+    const tolerance = requireComparisonTolerance({ functionName, tolerance: input.tolerance });
+    if (input.limits !== undefined) {
+        requireArgumentObject(functionName, 'limits', input.limits);
+        ensureKnownKeys(functionName, 'limits', input.limits, [
+            'maximumDifferences',
+            'maximumLeaves',
+            'listedIds',
+        ]);
+    }
+    const listedIds = requireWorkLimit({
+        functionName,
+        field: 'limits.listedIds',
+        value: input.limits?.listedIds,
+        law: BACKTEST_RUN_LIMITS.listedIds,
+    });
+    const maximumDifferences = requireWorkLimit({
+        functionName,
+        field: 'limits.maximumDifferences',
+        value: input.limits?.maximumDifferences,
+        law: BACKTEST_RUN_LIMITS.maximumDifferences,
+    });
+    const maximumLeaves = requireWorkLimit({
+        functionName,
+        field: 'limits.maximumLeaves',
+        value: input.limits?.maximumLeaves,
+        law: BACKTEST_RUN_LIMITS.maximumLeaves,
+    });
+    const left = resolveRun(functionName, input.baseline, 'baseline');
+    const right = resolveRun(functionName, input.candidate, 'candidate');
+    if (left.report.kind !== right.report.kind) {
+        fail(functionName, `baseline is a '${left.report.kind}' run and candidate a '${right.report.kind}' run — compare runs of one kind.`, ErrorCode.InputOutOfRange, { baseline: left.report.kind, candidate: right.report.kind });
+    }
+    const kind = left.report.kind;
+    const warnings = [];
+    const within = (delta, base) => {
+        if (tolerance === null)
+            return null;
+        if (delta === null)
+            return base === null;
+        return Math.abs(delta) <= tolerance.absolute + tolerance.relative * Math.abs(base ?? 0);
+    };
+    const leftMetrics = metricsOf(left.report);
+    const rightMetrics = metricsOf(right.report);
+    const metrics = METRIC_NAMES.map((name) => {
+        const b = leftMetrics[name] ?? null;
+        const c = rightMetrics[name] ?? null;
+        const delta = b !== null && c !== null ? c - b : null;
+        return {
+            name,
+            baselineValue: b,
+            candidateValue: c,
+            absoluteDelta: delta,
+            withinTolerance: b === null && c === null ? (tolerance === null ? null : true) : within(delta, b),
+        };
+    });
+    let holdings = null;
+    let rebalances = null;
+    let variations = null;
+    if (kind === 'cross-sectional') {
+        const b = finalHoldings(left.report);
+        const c = finalHoldings(right.report);
+        holdings = b !== null && c !== null ? membership(b, c, listedIds) : null;
+        const lb = left.report.run['rebalances'];
+        const rb = right.report.run['rebalances'];
+        if (Array.isArray(lb) && Array.isArray(rb)) {
+            const compared = Math.min(lb.length, rb.length);
+            const rows = [];
+            for (let i = 0; i < compared; i += 1) {
+                const x = lb[i];
+                const y = rb[i];
+                rows.push({
+                    rebalanceIndex: i,
+                    sessionDate: { baseline: x.sessionDate, candidate: y.sessionDate },
+                    turnover: {
+                        baseline: x.turnover,
+                        candidate: y.turnover,
+                        absoluteDelta: y.turnover - x.turnover,
+                    },
+                    costs: { baseline: x.costs, candidate: y.costs, absoluteDelta: y.costs - x.costs },
+                    longCount: { baseline: x.longCount, candidate: y.longCount },
+                    shortCount: { baseline: x.shortCount, candidate: y.shortCount },
+                });
+            }
+            rebalances = {
+                compared,
+                rows: rows.slice(0, listedIds),
+                remainderCount: Math.max(0, rows.length - listedIds),
+            };
+            if (lb.length !== rb.length)
+                warnings.push(warning(WarningCode.ArtifactLibraryVersionDiffers, `${functionName}: the runs have ${lb.length} and ${rb.length} rebalances; the first ${compared} were compared index by index.`, 'info', { baseline: lb.length, candidate: rb.length }));
+        }
+        else {
+            warnings.push(warning(WarningCode.ArtifactLibraryVersionDiffers, `${functionName}: a rebalance row set is referenced by table handle on at least one side — supply it through readBacktestRun's referencedData to compare rebalance by rebalance.`, 'info', {}));
+        }
+    }
+    else {
+        const lv = left.report.run['variations'];
+        const rv = right.report.run['variations'];
+        const metric = String(left.report.run['assumptions'].selectionMetric ?? 'sharpe');
+        if (Array.isArray(lv) && Array.isArray(rv)) {
+            const key = (row) => canonicalJsonOf(row.parameters);
+            const rightByKey = new Map(rv.map((row) => [key(row), row]));
+            const rows = [];
+            let matched = 0;
+            for (const row of lv) {
+                const other = rightByKey.get(key(row));
+                if (other === undefined)
+                    continue;
+                matched += 1;
+                const b = finiteOrNull(row.metrics[metric]);
+                const c = finiteOrNull(other.metrics[metric]);
+                rows.push({
+                    parameters: row.parameters,
+                    metric,
+                    baselineValue: b,
+                    candidateValue: c,
+                    absoluteDelta: b !== null && c !== null ? c - b : null,
+                });
+            }
+            rows.sort((x, y) => Math.abs(y.absoluteDelta ?? 0) - Math.abs(x.absoluteDelta ?? 0) ||
+                canonicalJsonOf(x.parameters).localeCompare(canonicalJsonOf(y.parameters)));
+            const lbest = left.report.run['best'];
+            const rbest = right.report.run['best'];
+            const lkey = lbest === null
+                ? null
+                : key(lv[lbest.index]);
+            const rkey = rbest === null
+                ? null
+                : key(rv[rbest.index]);
+            variations = {
+                matched,
+                baselineOnly: lv.length - matched,
+                candidateOnly: rv.length - matched,
+                rows: rows.slice(0, listedIds),
+                remainderCount: Math.max(0, rows.length - listedIds),
+                best: {
+                    baseline: lbest?.index ?? null,
+                    candidate: rbest?.index ?? null,
+                    moved: lkey !== rkey,
+                },
+            };
+        }
+        else {
+            warnings.push(warning(WarningCode.ArtifactLibraryVersionDiffers, `${functionName}: the variations row set is referenced by table handle on at least one side — supply it through readBacktestRun's referencedData to compare variation by variation.`, 'info', {}));
+        }
+    }
+    const lv = hygieneVerdict(left.report);
+    const rv = hygieneVerdict(right.report);
+    const hygiene = lv === null && rv === null ? null : { baseline: lv, candidate: rv, changed: lv !== rv };
+    const parity = artifactReplayParity({
+        saved: storedProjection(left.report),
+        recomputed: storedProjection(right.report),
+        limits: { maximumDifferences, maximumLeaves },
+    });
+    const li = left.report.identity;
+    const ri = right.report.identity;
+    const same = (a, b) => canonicalJsonOf(a) === canonicalJsonOf(b);
+    return deepFreeze({
+        kind,
+        artifactIds: { baseline: left.artifactId, candidate: right.artifactId },
+        runHashes: { baseline: left.report.runHash, candidate: right.report.runHash },
+        identical: left.report.runHash === right.report.runHash,
+        sameInputs: same(left.report.inputs, right.report.inputs) &&
+            same(left.report.referencedData, right.report.referencedData),
+        sameUniverse: li.universeId === ri.universeId && li.universeHistoryHash === ri.universeHistoryHash,
+        sameStrategy: same(li.strategy, ri.strategy),
+        sameModels: same(li.models, ri.models),
+        sameConventions: same(li.conventions, ri.conventions),
+        metrics,
+        holdings,
+        rebalances,
+        variations,
+        hygiene,
+        run: {
+            differenceCount: parity.differenceCount,
+            retainedDifferences: parity.differences.length,
+            addedPaths: parity.addedPaths,
+            removedPaths: parity.removedPaths,
+            truncated: parity.truncated,
+        },
+        withinTolerance: tolerance === null ? null : metrics.every((m) => m.withinTolerance === true),
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            kind,
+            tolerance,
+            limits: { maximumDifferences, maximumLeaves, listedIds },
+        },
+        diagnostics: { warnings },
+    });
+}
+//# sourceMappingURL=run-artifacts.js.map