@insiderfinance/totalfinance 0.1.0

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

@@ -0,0 +1,766 @@
+/**
+ * `@insiderfinance/totalfinance/research/artifacts` — the four verbs of Stage 4.5 Decision 4 over the eleven FC3 run
+ * kinds, riding the Gate B spine and the shared fitted-model kit in core: `researchRunArtifact`,
+ * `readResearchRun`, `replayResearchRun`, `compareResearchRuns`. A screen is not a model: there is
+ * no evaluator, warm start, stability, or holdout here.
+ *
+ * A run is the direct operation's result, VERBATIM, plus the input that reproduces it — bulk row
+ * sets embedded under the row limit or referenced by content-hashed table handles — an optional
+ * statistical-hygiene block the caller attaches (computed by `@insiderfinance/totalfinance/risk`, never here), and the
+ * versioned `FactorRecipe` the caller says produced the factor. Replay re-issues the operation with
+ * the stored input (referenced rows re-verified by hash) and compares canonical bytes; a run whose
+ * input carried a caller function is recorded as non-replayable and refuses replay by name.
+ */
+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, requireWorkLimit, scanCanonicalData, tableHandleForRows, verifyReferencedRows, } from '../../core/dist/artifacts/index.js';
+import { requireHygieneBlock } from './research-hygiene.js';
+import { KIND_SPECS, RESEARCH_RUN_KIND_LIST, pathOfLabel, resolveRowSets, withPath, } from './research-run-kinds.js';
+export const RESEARCH_RUN_ARTIFACT_TYPE = 'research.run';
+/** Decision 9's bounded-work table (core's `ARTIFACT_WORK_LIMITS`, re-exported for this subpath's callers). */
+export const RESEARCH_RUN_LIMITS = ARTIFACT_WORK_LIMITS;
+const REPORT_KEYS = [
+    'kind',
+    'runVersion',
+    'run',
+    'inputs',
+    'referencedData',
+    'hygiene',
+    'recipe',
+    'assumptions',
+    'diagnostics',
+];
+const ASSUMPTION_KEYS = [
+    'conventionsVersion',
+    'kind',
+    'runVersion',
+    'operation',
+    'replayable',
+    'nonReplayableField',
+    'inputPolicy',
+    'embeddedRowLimit',
+    'projection',
+];
+const DIAGNOSTIC_KEYS = ['warnings', 'embeddedRows', 'referencedRows', 'runWarningCount'];
+const RECIPE_KEYS = [
+    'recipeName',
+    'recipeVersion',
+    'disclosure',
+    'direction',
+    'features',
+    'lagTradingSessions',
+    'neutralization',
+    'missingValuePolicy',
+];
+const PROJECTION = 'run = the direct operation result verbatim (no field dropped, renamed, or recomputed); inputs = the operation input with bulk row sets embedded or replaced by verified table handles and any caller function omitted; hygiene and recipe stored verbatim as the caller attached them';
+function fail(functionName, message, code, context = {}) {
+    throw new InputError(`${functionName}: ${message}`, {
+        code,
+        context: { function: functionName, ...context },
+    });
+}
+function requireKind(functionName, value) {
+    if (typeof value !== 'string' || !RESEARCH_RUN_KIND_LIST.includes(value)) {
+        fail(functionName, `kind must be one of ${RESEARCH_RUN_KIND_LIST.join(', ')}. Received ${typeof value === 'string' ? JSON.stringify(value) : value === null ? 'null' : typeof value}.`, value === undefined ? ErrorCode.InputMissingField : ErrorCode.InputInvalidEnum, { field: 'kind' });
+    }
+    return value;
+}
+function specOf(kind) {
+    return KIND_SPECS[kind];
+}
+function requireLimit(functionName, field, value, law) {
+    return requireWorkLimit({ functionName, field, value, law });
+}
+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');
+}
+/** A bounded scan whose budget refusal is THIS door's "too large" — re-voiced with the referencing teaching. */
+function scanEmbedded(functionName, label, value, maximumEmbeddedBytes, requireFiniteNumbers) {
+    try {
+        scanCanonicalData(value, {
+            functionName,
+            label,
+            maximumWorkUnits: maximumEmbeddedBytes,
+            requireFiniteNumbers,
+        });
+    }
+    catch (error) {
+        if (isQuantError(error, ErrorCode.InputOutOfRange) &&
+            error.message.includes('data-work limit')) {
+            fail(functionName, `the embedded ${label} exceeds the embedded-input budget (${maximumEmbeddedBytes.toLocaleString()} work units ≈ canonical bytes) — reference the bulk row sets (referenceRowSets) or raise limits.maximumEmbeddedBytes up to ${RESEARCH_RUN_LIMITS.maximumEmbeddedBytes.maximum.toLocaleString()}.`, ErrorCode.ArtifactEmbeddedInputTooLarge, { field: label, maximumEmbeddedBytes });
+        }
+        throw error;
+    }
+}
+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 (spec.optionalRunKeys.includes(key))
+            continue;
+        if (!Object.prototype.hasOwnProperty.call(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']);
+    const assumptions = record['assumptions'];
+    for (const key of spec.requiredAssumptionKeys) {
+        if (!Object.prototype.hasOwnProperty.call(assumptions, key)) {
+            fail(functionName, `${field}.assumptions.${key} is missing — ${spec.descriptor.operation} always reports it, so this is not a '${spec.descriptor.kind}' run (a result of another operation cannot be saved under this kind).`, ErrorCode.InputMissingField, { field: `${field}.assumptions.${key}` });
+        }
+    }
+    requireArgumentObject(functionName, `${field}.diagnostics`, record['diagnostics']);
+    if (!Array.isArray(record['diagnostics']['warnings'])) {
+        fail(functionName, `${field}.diagnostics.warnings must be an array (the operation's own warnings, verbatim).`, ErrorCode.InputWrongType, { field: `${field}.diagnostics.warnings` });
+    }
+}
+function requireRecipe(functionName, field, value) {
+    requireArgumentObject(functionName, field, value);
+    const record = value;
+    ensureKnownKeys(functionName, field, record, RECIPE_KEYS);
+    for (const key of ['recipeName', 'disclosure']) {
+        if (typeof record[key] !== 'string' || record[key].length === 0) {
+            fail(functionName, `${field}.${key} must be a non-empty string.`, record[key] === undefined ? ErrorCode.InputMissingField : ErrorCode.InputWrongType, { field: `${field}.${key}` });
+        }
+    }
+    for (const [key, floor] of [
+        ['recipeVersion', 1],
+        ['lagTradingSessions', 0],
+    ]) {
+        const number = record[key];
+        if (typeof number !== 'number' || !Number.isSafeInteger(number) || number < floor) {
+            fail(functionName, `${field}.${key} must be an integer ≥ ${floor}.`, number === undefined ? ErrorCode.InputMissingField : ErrorCode.InputOutOfRange, { field: `${field}.${key}` });
+        }
+    }
+    const enums = [
+        ['direction', ['higher-is-better', 'lower-is-better']],
+        ['neutralization', ['none', 'sector', 'sector-and-size']],
+        ['missingValuePolicy', ['exclude', 'renormalize-weights']],
+    ];
+    for (const [key, allowed] of enums) {
+        if (typeof record[key] !== 'string' || !allowed.includes(record[key])) {
+            fail(functionName, `${field}.${key} must be one of ${allowed.join(', ')}.`, record[key] === undefined ? ErrorCode.InputMissingField : ErrorCode.InputInvalidEnum, { field: `${field}.${key}` });
+        }
+    }
+    requireArgumentArray(functionName, `${field}.features`, record['features']);
+    record['features'].forEach((feature, index) => {
+        const label = `${field}.features[${index}]`;
+        requireArgumentObject(functionName, label, feature);
+        const entry = feature;
+        ensureKnownKeys(functionName, label, entry, ['field', 'transform', 'weight']);
+        if (typeof entry['field'] !== 'string' || entry['field'].length === 0) {
+            fail(functionName, `${label}.field must be a non-empty field name.`, ErrorCode.InputWrongType, {
+                field: `${label}.field`,
+            });
+        }
+        const transforms = ['raw', 'winsorize-then-z-score', 'percentile-rank'];
+        if (typeof entry['transform'] !== 'string' || !transforms.includes(entry['transform'])) {
+            fail(functionName, `${label}.transform must be one of ${transforms.join(', ')}.`, ErrorCode.InputInvalidEnum, { field: `${label}.transform` });
+        }
+        if (typeof entry['weight'] !== 'number' || !Number.isFinite(entry['weight'])) {
+            fail(functionName, `${label}.weight must be a finite number.`, ErrorCode.InputWrongType, {
+                field: `${label}.weight`,
+            });
+        }
+    });
+    return value;
+}
+/** Validate a restored report structurally (closed keys, known kind/version, the run shape, handles, block, recipe). */
+function requireReport(functionName, value) {
+    requireArgumentObject(functionName, 'artifact.result', value);
+    const record = value;
+    ensureKnownKeys(functionName, 'artifact.result', record, REPORT_KEYS);
+    for (const key of REPORT_KEYS) {
+        if (!Object.prototype.hasOwnProperty.call(record, key)) {
+            fail(functionName, `artifact.result.${key} is missing — this is not a research-run report.`, ErrorCode.InputMissingField, { field: `artifact.result.${key}` });
+        }
+    }
+    const kind = requireKind(functionName, record['kind']);
+    const spec = specOf(kind);
+    if (record['runVersion'] !== spec.descriptor.runVersion) {
+        fail(functionName, `artifact.result.runVersion is ${String(record['runVersion'])}; this build reads '${kind}' runs at version ${spec.descriptor.runVersion}.`, ErrorCode.ArtifactModelVersionUnsupported, { field: 'artifact.result.runVersion' });
+    }
+    requireRunShape(functionName, 'artifact.result.run', spec, record['run']);
+    requireArgumentObject(functionName, 'artifact.result.inputs', record['inputs']);
+    requireArgumentObject(functionName, 'artifact.result.referencedData', record['referencedData']);
+    for (const [name, handle] of Object.entries(record['referencedData'])) {
+        if (!isTableHandle(handle)) {
+            fail(functionName, `artifact.result.referencedData.${name} is not a table handle.`, ErrorCode.InputWrongType, { field: `artifact.result.referencedData.${name}` });
+        }
+    }
+    if (record['hygiene'] !== null)
+        requireHygieneBlock(functionName, 'artifact.result.hygiene', record['hygiene']);
+    if (record['recipe'] !== null)
+        requireRecipe(functionName, 'artifact.result.recipe', record['recipe']);
+    const assumptions = record['assumptions'];
+    requireArgumentObject(functionName, 'artifact.result.assumptions', assumptions);
+    ensureKnownKeys(functionName, 'artifact.result.assumptions', assumptions, ASSUMPTION_KEYS);
+    const a = assumptions;
+    if (a['kind'] !== kind) {
+        fail(functionName, `artifact.result.assumptions.kind (${JSON.stringify(a['kind'])}) does not name the report's kind '${kind}'.`, ErrorCode.InputWrongShape, { field: 'artifact.result.assumptions.kind' });
+    }
+    if (typeof a['replayable'] !== 'boolean') {
+        fail(functionName, `artifact.result.assumptions.replayable must be a boolean.`, ErrorCode.InputWrongType, { field: 'artifact.result.assumptions.replayable' });
+    }
+    if (a['nonReplayableField'] !== null &&
+        (typeof a['nonReplayableField'] !== 'string' || a['nonReplayableField'].length === 0)) {
+        fail(functionName, `artifact.result.assumptions.nonReplayableField must be null or the callback field's name.`, ErrorCode.InputWrongType, { field: 'artifact.result.assumptions.nonReplayableField' });
+    }
+    if ((a['replayable'] === true) !== (a['nonReplayableField'] === null)) {
+        fail(functionName, `artifact.result.assumptions.replayable and nonReplayableField disagree — a run is non-replayable exactly when a callback field is named.`, ErrorCode.InputWrongShape, { field: 'artifact.result.assumptions.replayable' });
+    }
+    if (a['inputPolicy'] !== 'embedded' && a['inputPolicy'] !== 'referenced') {
+        fail(functionName, `artifact.result.assumptions.inputPolicy must be 'embedded' or 'referenced'.`, ErrorCode.InputInvalidEnum, { field: 'artifact.result.assumptions.inputPolicy' });
+    }
+    const diagnostics = record['diagnostics'];
+    requireArgumentObject(functionName, 'artifact.result.diagnostics', diagnostics);
+    ensureKnownKeys(functionName, 'artifact.result.diagnostics', diagnostics, DIAGNOSTIC_KEYS);
+    if (!Array.isArray(diagnostics['warnings'])) {
+        fail(functionName, `artifact.result.diagnostics.warnings must be an array.`, ErrorCode.InputWrongType, { field: 'artifact.result.diagnostics.warnings' });
+    }
+    return record;
+}
+function requireSnapshotHash(functionName, value) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(value)) {
+        fail(functionName, `snapshotHash must be a 'sha256:<64 hex>' string — use marketSnapshotContentHash(snapshot).`, ErrorCode.InputWrongType, { field: 'snapshotHash' });
+    }
+    return value;
+}
+/** Build the report for a (kind, run, stored input, handles) — the one projection law. */
+function buildReport(functionName, spec, run, stored, referencedData, hygiene, recipe, nonReplayableField, embeddedRows, embeddedRowLimit) {
+    const runWarnings = run.diagnostics?.warnings;
+    const referencedRowSets = Object.keys(referencedData).sort();
+    const referencedRows = referencedRowSets.reduce((total, label) => total + referencedData[label].rowCount, 0);
+    const report = {
+        kind: spec.descriptor.kind,
+        runVersion: spec.descriptor.runVersion,
+        run,
+        inputs: stored,
+        referencedData,
+        hygiene,
+        recipe,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            kind: spec.descriptor.kind,
+            runVersion: spec.descriptor.runVersion,
+            operation: spec.descriptor.operation,
+            replayable: nonReplayableField === null,
+            nonReplayableField,
+            inputPolicy: referencedRowSets.length > 0 ? 'referenced' : 'embedded',
+            embeddedRowLimit,
+            projection: PROJECTION,
+        },
+        diagnostics: {
+            warnings: [],
+            embeddedRows,
+            referencedRows,
+            runWarningCount: Array.isArray(runWarnings) ? runWarnings.length : 0,
+        },
+    };
+    void functionName;
+    return { report: report, inputsHash: contentHash(stored) };
+}
+// ──────────────────────────────────────────── the verbs ─────────────────────────────────────────────
+/**
+ * Describe a direct research operation's result and save it as an identified, immutable artifact.
+ *
+ * @example
+ * ```ts
+ * const run = screenUniverse(input);
+ * const artifact = researchRunArtifact({ kind: 'screen', run, input, referenceRowSets: ['observations'] });
+ * ```
+ */
+export function researchRunArtifact(input) {
+    const functionName = 'researchRunArtifact';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, [
+        'kind',
+        'run',
+        'input',
+        'referenceRowSets',
+        'locators',
+        'hygiene',
+        'recipe',
+        'snapshotHash',
+        'libraryVersion',
+        'createdFrom',
+        'provenance',
+        'limits',
+    ]);
+    const kind = requireKind(functionName, input.kind);
+    const spec = specOf(kind);
+    const limits = input.limits;
+    if (limits !== undefined) {
+        requireArgumentObject(functionName, 'limits', limits);
+        ensureKnownKeys(functionName, 'limits', limits, ['maximumEmbeddedBytes', 'embeddedRowLimit']);
+    }
+    const maximumEmbeddedBytes = requireLimit(functionName, 'limits.maximumEmbeddedBytes', limits?.maximumEmbeddedBytes, RESEARCH_RUN_LIMITS.maximumEmbeddedBytes);
+    const embeddedRowLimit = requireLimit(functionName, 'limits.embeddedRowLimit', limits?.embeddedRowLimit, RESEARCH_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);
+    }
+    // The run: the operation's result, a plain acyclic value (a null coefficient is a legal RESULT).
+    requireRunShape(functionName, 'run', spec, input.run);
+    scanEmbedded(functionName, 'run', input.run, maximumEmbeddedBytes, false);
+    const run = detach(input.run);
+    // The input: callbacks recorded and stripped, rows embedded or referenced, the rest verbatim.
+    requireArgumentObject(functionName, 'input', input.input);
+    let working = { ...input.input };
+    let nonReplayableField = null;
+    for (const callback of spec.callbacks) {
+        if (!callback.isPresent(working))
+            continue;
+        const value = callback.read(working);
+        if (typeof value !== 'function') {
+            fail(functionName, `input.${callback.field} is present but not a function — ${spec.descriptor.operation} would have refused this input, so it cannot be the input that produced the run.`, ErrorCode.InputWrongType, { field: `input.${callback.field}` });
+        }
+        nonReplayableField = callback.field;
+        working = callback.strip(working);
+    }
+    scanEmbedded(functionName, 'input', working, maximumEmbeddedBytes, true);
+    const resolved = resolveRowSets(functionName, spec, working);
+    const labels = resolved.map((rowSet) => rowSet.label);
+    if (input.referenceRowSets !== undefined) {
+        requireArgumentArray(functionName, 'referenceRowSets', input.referenceRowSets);
+    }
+    const referenceRowSets = input.referenceRowSets ?? [];
+    for (const name of referenceRowSets) {
+        if (typeof name !== 'string' || !labels.includes(name)) {
+            fail(functionName, `referenceRowSets names ${JSON.stringify(name)}, which is not a bulk row set of this '${kind}' input — its row sets are ${labels.length > 0 ? labels.join(', ') : 'none'} (patterns: ${spec.descriptor.bulkRowSets.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}` });
+        }
+    }
+    let stored = detach(working);
+    const referencedData = {};
+    let embeddedRows = 0;
+    for (const rowSet of resolved) {
+        if (!Array.isArray(rowSet.rows)) {
+            fail(functionName, `input.${rowSet.label} must be the row array ${spec.descriptor.operation} consumed. Received ${rowSet.rows === null ? 'null' : typeof rowSet.rows}.`, ErrorCode.InputWrongType, { field: `input.${rowSet.label}` });
+        }
+        if (referenceRowSets.includes(rowSet.label)) {
+            const handle = tableHandleForRows({
+                rows: rowSet.rows,
+                ...(input.locators?.[rowSet.label] !== undefined
+                    ? { locator: input.locators[rowSet.label] }
+                    : {}),
+            });
+            referencedData[rowSet.label] = handle;
+            stored = withPath(stored, rowSet.path, handle);
+        }
+        else if (rowSet.rows.length > embeddedRowLimit) {
+            fail(functionName, `input.${rowSet.label} has ${rowSet.rows.length} rows, above the embedded row limit ${embeddedRowLimit} — nothing is truncated silently. Either reference the row set (referenceRowSets: ['${rowSet.label}'], which stores its content hash and row count and expects the rows again at replay) or raise limits.embeddedRowLimit up to ${RESEARCH_RUN_LIMITS.embeddedRowLimit.maximum}.`, ErrorCode.ArtifactEmbeddedInputTooLarge, { field: `input.${rowSet.label}`, rows: rowSet.rows.length, embeddedRowLimit });
+        }
+        else {
+            embeddedRows += rowSet.rows.length;
+        }
+    }
+    const storedBytes = canonicalJsonOf(stored).length;
+    if (storedBytes > maximumEmbeddedBytes) {
+        fail(functionName, `the embedded input is ${storedBytes.toLocaleString()} canonical bytes, above the limit ${maximumEmbeddedBytes.toLocaleString()} — reference the bulk row sets (referenceRowSets) or raise limits.maximumEmbeddedBytes up to ${RESEARCH_RUN_LIMITS.maximumEmbeddedBytes.maximum.toLocaleString()}.`, ErrorCode.ArtifactEmbeddedInputTooLarge, { field: 'input', bytes: storedBytes, maximumEmbeddedBytes });
+    }
+    // The hygiene block and the recipe: validated structurally, stored verbatim. null is NOT omission.
+    const hygiene = input.hygiene === undefined
+        ? null
+        : detach(requireHygieneBlock(functionName, 'hygiene', input.hygiene));
+    const recipe = input.recipe === undefined ? null : detach(requireRecipe(functionName, 'recipe', input.recipe));
+    const built = buildReport(functionName, spec, run, stored, referencedData, hygiene, recipe, nonReplayableField, embeddedRows, embeddedRowLimit);
+    const referenced = Object.fromEntries(Object.keys(referencedData)
+        .sort()
+        .map((label) => [label, referencedData[label].contentHash]));
+    return createAnalysisArtifact({
+        artifactType: RESEARCH_RUN_ARTIFACT_TYPE,
+        producedBy: {
+            operation: spec.descriptor.operation,
+            ...(input.libraryVersion !== undefined ? { libraryVersion: input.libraryVersion } : {}),
+        },
+        inputs: {
+            ...(snapshotHash !== null ? { snapshotHash } : {}),
+            parameters: {
+                kind,
+                runVersion: spec.descriptor.runVersion,
+                inputsHash: built.inputsHash,
+                referenced,
+            },
+        },
+        ...(input.createdFrom !== undefined ? { createdFrom: input.createdFrom } : {}),
+        result: built.report,
+        ...(Object.keys(referencedData).length > 0 ? { tables: referencedData } : {}),
+        ...(input.provenance !== undefined ? { provenance: input.provenance } : {}),
+    });
+}
+/**
+ * Restore a research-run artifact: Gate B's read door, a foreign-type refusal, then the caller's
+ * registry applied a second time at the run level under `research.run:<kind>` (Decision 5), then
+ * the report re-validated.
+ */
+export function readResearchRun(input) {
+    const functionName = 'readResearchRun';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, ['artifact', 'migrations']);
+    const read = readAnalysisArtifact({
+        artifact: input.artifact,
+        ...(input.migrations !== undefined ? { migrations: input.migrations } : {}),
+    });
+    const artifact = read.artifact;
+    if (artifact.artifactType !== RESEARCH_RUN_ARTIFACT_TYPE) {
+        fail(functionName, `the artifact's type is '${artifact.artifactType}', not '${RESEARCH_RUN_ARTIFACT_TYPE}' — this reader restores research runs only; ${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: `${RESEARCH_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);
+    return {
+        report: deepFreeze(detach(validated)),
+        artifact,
+        migrationsApplied: read.migrationsApplied,
+        modelMigrationsApplied: migrated.modelMigrationsApplied,
+    };
+}
+function resolveRun(functionName, value, field) {
+    if (isArtifact(value)) {
+        const read = readResearchRun({ artifact: value });
+        return { report: read.report, artifactId: read.artifact.id };
+    }
+    requireArgumentObject(functionName, field, value);
+    return { report: requireReport(functionName, value), artifactId: null };
+}
+/** The full input behind a report: embedded rows as stored, referenced rows supplied and re-verified. */
+function fullInput(functionName, report, referencedData) {
+    let inputs = report.inputs;
+    for (const label of Object.keys(report.referencedData).sort()) {
+        const handle = report.referencedData[label];
+        const rows = referencedData?.[label];
+        if (rows === undefined) {
+            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}` });
+        }
+        inputs = withPath(inputs, pathOfLabel(label), detach(verifyReferencedRows({ functionName, label, handle, rows })));
+    }
+    return inputs;
+}
+/**
+ * Re-issue the run's direct operation from the stored input and compare canonical bytes with the
+ * saved run (Decision 7). Referenced row sets must be supplied and re-verify by hash; a run that
+ * recorded a caller callback refuses by name.
+ */
+export function replayResearchRun(input) {
+    const functionName = 'replayResearchRun';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, [
+        'artifact',
+        'migrations',
+        'referencedData',
+        'libraryVersion',
+        'limits',
+    ]);
+    if (input.referencedData !== undefined)
+        requireArgumentObject(functionName, 'referencedData', input.referencedData);
+    const read = readResearchRun({
+        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 input carried a caller function at ${report.assumptions.nonReplayableField ?? '(unrecorded)'} that no artifact can store — re-run ${spec.descriptor.operation} with the serializable form of that input and save that run.`, ErrorCode.ArtifactNotReplayable, { kind: report.kind, field: report.assumptions.nonReplayableField });
+    }
+    const inputs = fullInput(functionName, report, input.referencedData);
+    const recomputedRun = spec.run(inputs);
+    const recomputed = buildReport(functionName, spec, detach(recomputedRun), report.inputs, { ...report.referencedData }, report.hygiene, report.recipe, report.assumptions.nonReplayableField, report.diagnostics.embeddedRows, report.assumptions.embeddedRowLimit);
+    const parity = artifactReplayParity({
+        saved: report.run,
+        recomputed: recomputed.report.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)'}). A research operation is deterministic given its inputs, so this is a finding: a changed operation, dependency, or platform.`, 'warn', { differenceCount: parity.differenceCount }));
+    }
+    return deepFreeze({
+        kind: report.kind,
+        artifactId: read.artifact.id,
+        recomputed: deepFreeze(recomputed.report),
+        parity,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            kind: report.kind,
+            runVersion: report.runVersion,
+            operation: spec.descriptor.operation,
+            libraryVersion: { saved, current },
+            referencedRowSets: Object.keys(report.referencedData).sort(),
+        },
+        diagnostics: { warnings },
+    });
+}
+// ─────────────────────────────────────── comparison sections ─────────────────────────────────────
+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 membershipOf(baseline, candidate, listedIds) {
+    const before = new Set(baseline);
+    const after = new Set(candidate);
+    return {
+        entered: idList([...after].filter((id) => !before.has(id)), listedIds),
+        exited: idList([...before].filter((id) => !after.has(id)), listedIds),
+        kept: idList([...after].filter((id) => before.has(id)), listedIds),
+    };
+}
+function rankMovesOf(baseline, candidate, listedIds) {
+    const moves = [];
+    for (const [instrumentId, baselineRank] of baseline) {
+        const candidateRank = candidate.get(instrumentId);
+        if (candidateRank === undefined || candidateRank === baselineRank)
+            continue;
+        moves.push({ instrumentId, baselineRank, candidateRank, delta: candidateRank - baselineRank });
+    }
+    moves.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta) || a.instrumentId.localeCompare(b.instrumentId));
+    return {
+        movedCount: moves.length,
+        movers: moves.slice(0, listedIds),
+        remainderCount: Math.max(0, moves.length - listedIds),
+    };
+}
+function scoreDeltasOf(baseline, candidate, listedIds) {
+    const deltas = [];
+    for (const [instrumentId, baselineValue] of baseline) {
+        const candidateValue = candidate.get(instrumentId);
+        if (candidateValue === undefined)
+            continue;
+        deltas.push({
+            instrumentId,
+            baselineValue,
+            candidateValue,
+            absoluteDelta: candidateValue - baselineValue,
+        });
+    }
+    deltas.sort((a, b) => Math.abs(b.absoluteDelta) - Math.abs(a.absoluteDelta) ||
+        a.instrumentId.localeCompare(b.instrumentId));
+    const magnitudes = deltas.map((delta) => Math.abs(delta.absoluteDelta));
+    return {
+        count: deltas.length,
+        meanAbsoluteDelta: magnitudes.length === 0 ? null : magnitudes.reduce((a, b) => a + b, 0) / magnitudes.length,
+        maximumAbsoluteDelta: magnitudes.length === 0 ? null : Math.max(...magnitudes),
+        perInstrument: deltas.slice(0, listedIds),
+        remainderCount: Math.max(0, deltas.length - listedIds),
+    };
+}
+function countDeltasOf(baseline, candidate) {
+    const reasons = [...new Set([...Object.keys(baseline), ...Object.keys(candidate)])].sort();
+    return reasons.map((reason) => {
+        const baselineCount = baseline[reason] ?? 0;
+        const candidateCount = candidate[reason] ?? 0;
+        return { reason, baselineCount, candidateCount, delta: candidateCount - baselineCount };
+    });
+}
+const delta = (a, b) => typeof a === 'number' && typeof b === 'number' ? b - a : null;
+function namedDeltasOf(baseline, candidate) {
+    return Object.keys(baseline).map((name) => ({
+        name,
+        baselineValue: baseline[name] ?? null,
+        candidateValue: candidate[name] ?? null,
+        absoluteDelta: delta(baseline[name], candidate[name]),
+    }));
+}
+function keyedDeltasOf(baseline, candidate) {
+    const before = new Map(baseline.map((row) => [row.key, row.value]));
+    const after = new Map(candidate.map((row) => [row.key, row.value]));
+    const keys = [...new Set([...before.keys(), ...after.keys()])].sort((a, b) => typeof a === 'number' && typeof b === 'number' ? a - b : String(a).localeCompare(String(b)));
+    return keys.map((key) => ({
+        key,
+        baselineValue: before.get(key) ?? null,
+        candidateValue: after.get(key) ?? null,
+        absoluteDelta: delta(before.get(key), after.get(key)),
+    }));
+}
+function abnormalReturnDeltasOf(baseline, candidate) {
+    const before = new Map(baseline.map((row) => [row.tradingSessionOffset, row]));
+    const after = new Map(candidate.map((row) => [row.tradingSessionOffset, row]));
+    const offsets = [...new Set([...before.keys(), ...after.keys()])].sort((a, b) => a - b);
+    return offsets.map((tradingSessionOffset) => {
+        const b = before.get(tradingSessionOffset);
+        const c = after.get(tradingSessionOffset);
+        return {
+            tradingSessionOffset,
+            baselineAverageAbnormalReturn: b?.averageAbnormalReturn ?? null,
+            candidateAverageAbnormalReturn: c?.averageAbnormalReturn ?? null,
+            absoluteDelta: delta(b?.averageAbnormalReturn, c?.averageAbnormalReturn),
+            baselineCumulativeAverageAbnormalReturn: b?.cumulativeAverageAbnormalReturn ?? null,
+            candidateCumulativeAverageAbnormalReturn: c?.cumulativeAverageAbnormalReturn ?? null,
+            cumulativeAbsoluteDelta: delta(b?.cumulativeAverageAbnormalReturn, c?.cumulativeAverageAbnormalReturn),
+        };
+    });
+}
+function portfoliosOf(baseline, candidate, listedIds) {
+    const before = new Map(baseline.map((portfolio) => [portfolio.quantileIndex, portfolio.instrumentIds]));
+    const after = new Map(candidate.map((portfolio) => [portfolio.quantileIndex, portfolio.instrumentIds]));
+    const indices = [...new Set([...before.keys(), ...after.keys()])].sort((a, b) => a - b);
+    return indices.map((quantileIndex) => ({
+        quantileIndex,
+        membership: membershipOf(before.get(quantileIndex) ?? [], after.get(quantileIndex) ?? [], listedIds),
+    }));
+}
+const sameCanonical = (a, b) => a === null || a === undefined || b === null || b === undefined
+    ? a === b
+        ? null
+        : false
+    : canonicalJsonOf(a) === canonicalJsonOf(b);
+/**
+ * Compare two research runs of one kind: identity (universe, as-of, filter / rank field /
+ * components), membership, rank moves, score deltas, exclusion-reason deltas, coefficient deltas,
+ * abnormal-return deltas per session offset, per-quantile and per-horizon deltas, the hygiene
+ * verdict change, and the structural diff of the two verbatim runs (Decision 6). Baseline and
+ * candidate are named, never "a" and "b"; nothing is a single similarity score.
+ */
+export function compareResearchRuns(input) {
+    const functionName = 'compareResearchRuns';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, ['baseline', 'candidate', 'limits']);
+    if (input.limits !== undefined) {
+        requireArgumentObject(functionName, 'limits', input.limits);
+        ensureKnownKeys(functionName, 'limits', input.limits, [
+            'maximumDifferences',
+            'maximumLeaves',
+            'listedIds',
+        ]);
+    }
+    const maximumDifferences = requireLimit(functionName, 'limits.maximumDifferences', input.limits?.maximumDifferences, RESEARCH_RUN_LIMITS.maximumDifferences);
+    const maximumLeaves = requireLimit(functionName, 'limits.maximumLeaves', input.limits?.maximumLeaves, RESEARCH_RUN_LIMITS.maximumLeaves);
+    const listedIds = requireLimit(functionName, 'limits.listedIds', input.limits?.listedIds, RESEARCH_RUN_LIMITS.listedIds);
+    const baseline = resolveRun(functionName, input.baseline, 'baseline');
+    const candidate = resolveRun(functionName, input.candidate, 'candidate');
+    if (baseline.report.kind !== candidate.report.kind) {
+        fail(functionName, `the runs are of different kinds — baseline is '${baseline.report.kind}', candidate is '${candidate.report.kind}'; their sections do not share a meaning. For a structural diff of two artifacts of one type use compareAnalysisArtifacts.`, ErrorCode.ArtifactFamilyMismatch, { baseline: baseline.report.kind, candidate: candidate.report.kind });
+    }
+    const kind = baseline.report.kind;
+    const spec = specOf(kind);
+    const warnings = [];
+    const baselineIdentity = spec.identity(baseline.report.inputs);
+    const candidateIdentity = spec.identity(candidate.report.inputs);
+    const sameUniverse = baselineIdentity.universe === null || candidateIdentity.universe === null
+        ? null
+        : baselineIdentity.universe === candidateIdentity.universe;
+    const sameAsOf = baselineIdentity.asOf === null || candidateIdentity.asOf === null
+        ? null
+        : baselineIdentity.asOf === candidateIdentity.asOf;
+    if (sameUniverse === false || sameAsOf === false) {
+        warnings.push(warning(WarningCode.ArtifactComparisonDifferentUniverse, `${functionName}: the runs were computed over ${sameUniverse === false ? `different universes ('${baselineIdentity.universe}' vs '${candidateIdentity.universe}')` : 'the same universe'}${sameAsOf === false ? ` and different as-of dates (${baselineIdentity.asOf} vs ${candidateIdentity.asOf})` : ''} — membership and rank moves below mix a population change with a signal change.`, 'warn', {
+            baselineUniverse: baselineIdentity.universe,
+            candidateUniverse: candidateIdentity.universe,
+            baselineAsOf: baselineIdentity.asOf,
+            candidateAsOf: candidateIdentity.asOf,
+        }));
+    }
+    const baselineRun = baseline.report.run;
+    const candidateRun = candidate.report.run;
+    const baselineProtocol = baseline.report.hygiene?.protocol?.verdict ?? null;
+    const candidateProtocol = candidate.report.hygiene?.protocol?.verdict ?? null;
+    const runDiff = artifactReplayParity({
+        saved: baselineRun,
+        recomputed: candidateRun,
+        limits: { maximumDifferences, maximumLeaves },
+    });
+    return deepFreeze({
+        kind,
+        artifactIds: { baseline: baseline.artifactId, candidate: candidate.artifactId },
+        sameUniverse,
+        sameAsOf,
+        sameFilter: sameCanonical(baselineIdentity.filter, candidateIdentity.filter),
+        sameRankBy: sameCanonical(baselineIdentity.rankBy, candidateIdentity.rankBy),
+        sameComponents: sameCanonical(baselineIdentity.components, candidateIdentity.components),
+        sameInputs: contentHash(baseline.report.inputs) === contentHash(candidate.report.inputs),
+        membership: spec.members === null
+            ? null
+            : membershipOf(spec.members(baselineRun), spec.members(candidateRun), listedIds),
+        rankMoves: spec.ranks === null
+            ? null
+            : rankMovesOf(spec.ranks(baselineRun), spec.ranks(candidateRun), listedIds),
+        scoreDeltas: spec.scores === null
+            ? null
+            : scoreDeltasOf(spec.scores(baselineRun), spec.scores(candidateRun), listedIds),
+        exclusionReasons: spec.exclusionReasons === null
+            ? null
+            : countDeltasOf(spec.exclusionReasons(baselineRun), spec.exclusionReasons(candidateRun)),
+        coefficients: spec.coefficients === null
+            ? null
+            : namedDeltasOf(spec.coefficients(baselineRun), spec.coefficients(candidateRun)),
+        averageAbnormalReturns: spec.abnormalReturns === null
+            ? null
+            : abnormalReturnDeltasOf(spec.abnormalReturns(baselineRun), spec.abnormalReturns(candidateRun)),
+        quantiles: spec.quantiles === null
+            ? null
+            : keyedDeltasOf(spec.quantiles(baselineRun), spec.quantiles(candidateRun)),
+        horizons: spec.horizons === null
+            ? null
+            : keyedDeltasOf(spec.horizons(baselineRun), spec.horizons(candidateRun)),
+        portfolios: spec.portfolios === null
+            ? null
+            : portfoliosOf(spec.portfolios(baselineRun), spec.portfolios(candidateRun), listedIds),
+        hygieneVerdict: baselineProtocol === null || candidateProtocol === null
+            ? null
+            : {
+                baseline: baselineProtocol,
+                candidate: candidateProtocol,
+                changed: baselineProtocol !== candidateProtocol,
+            },
+        run: {
+            differenceCount: runDiff.differenceCount,
+            retainedDifferences: runDiff.differences.length,
+            addedPaths: runDiff.addedPaths,
+            removedPaths: runDiff.removedPaths,
+            truncated: runDiff.truncated,
+        },
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            kind,
+            limits: { maximumDifferences, maximumLeaves, listedIds },
+        },
+        diagnostics: { warnings },
+    });
+}
+//# sourceMappingURL=research-run-artifacts.js.map