@actuarial-ts/compliance 0.5.0 → 0.6.1

package/dist/diagnosticRun.js

@@ -0,0 +1,798 @@
+import { CORE_PACKAGE_VERSION, DiagnosticValidationError, canonicalJson, compileDiagnosticDefinition, fnv1a64, getMetricDiagnosticsResultIdentity, getPreparedDiagnosticDataIdentity, runMetricDiagnostics, verifyPreparedDiagnosticDataIntegrity, } from "@actuarial-ts/core";
+import { DATA_PACKAGE_VERSION, assertCompletedValidatedMetricDiagnosticsRun, reviewPreparedDiagnosticData, runValidatedMetricDiagnostics, validateDiagnosticRunInput, } from "@actuarial-ts/data";
+import { ComplianceError } from "./errors.js";
+import { COMPLIANCE_PACKAGE_VERSION } from "./version.js";
+const verified = new WeakMap();
+const token = (value, path) => {
+    if (value.length === 0 ||
+        /^[\t-\r ]|[\t-\r ]$/.test(value) ||
+        value.includes("\0"))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `${path} must be a nonempty token`, path);
+    for (let index = 0; index < value.length; index++) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `${path} contains malformed Unicode`, path);
+            index++;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff)
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `${path} contains malformed Unicode`, path);
+    }
+};
+function freeze(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== "object" || seen.has(value))
+        return value;
+    seen.add(value);
+    for (const child of Object.values(value))
+        freeze(child, seen);
+    return Object.freeze(value);
+}
+function tag(kind, key, value) {
+    return `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({ identityVersion: 1, kind, [key]: value }))}`;
+}
+function manifestIdentity(manifest) {
+    return {
+        ...manifest,
+        executionPolicy: {
+            gate: manifest.executionPolicy.gate,
+            review: {
+                body: manifest.executionPolicy.review.identityBody,
+                reportFingerprint: manifest.executionPolicy.review.reportFingerprint,
+            },
+        },
+    };
+}
+function bindingTag(runFingerprint, resultFingerprint) {
+    return `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({ identityVersion: 1, kind: "diagnostic-run-result", runFingerprint, resultFingerprint }))}`;
+}
+function plain(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function exactKeys(value, allowed, path) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Unknown field ${key}`, `${path}.${key}`);
+}
+function snapshotArtifacts(evidence, scope, path) {
+    if (!Array.isArray(evidence))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `${path} must be an array`, path);
+    const seen = new Set();
+    const result = [];
+    for (const [index, item] of evidence.entries()) {
+        const itemPath = `${path}[${index}]`;
+        if (!plain(item))
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Artifact evidence must be a plain object", itemPath);
+        if (typeof item.id !== "string")
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Artifact id must be a string", `${itemPath}.id`);
+        token(item.id, `${itemPath}.id`);
+        if (item.scope !== scope)
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Artifact scope must be ${scope}`, `${itemPath}.scope`);
+        if (seen.has(item.id))
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Duplicate artifact ID ${item.id}`, `${itemPath}.id`);
+        seen.add(item.id);
+        if (item.assurance === "sdk-computed") {
+            exactKeys(item, ["id", "scope", "assurance", "bytes"], itemPath);
+            if (!(item.bytes instanceof Uint8Array))
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "SDK-computed artifact evidence requires actual Uint8Array bytes", `${itemPath}.bytes`);
+            const bytes = new Uint8Array(item.bytes.byteLength);
+            bytes.set(item.bytes);
+            result.push({ id: item.id, scope, assurance: item.assurance, bytes });
+        }
+        else if (item.assurance === "caller-declared") {
+            exactKeys(item, ["id", "scope", "assurance", "algorithm", "value"], itemPath);
+            if (typeof item.algorithm !== "string")
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Artifact algorithm must be a string", `${itemPath}.algorithm`);
+            if (typeof item.value !== "string")
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Artifact value must be a string", `${itemPath}.value`);
+            token(item.algorithm, `${itemPath}.algorithm`);
+            token(item.value, `${itemPath}.value`);
+            result.push({
+                id: item.id,
+                scope,
+                assurance: item.assurance,
+                algorithm: item.algorithm,
+                value: item.value,
+            });
+        }
+        else
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Unknown artifact assurance", `${itemPath}.assurance`);
+    }
+    return result.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+async function digestArtifacts(snapshot, path) {
+    if (snapshot.some((item) => "bytes" in item) &&
+        globalThis.crypto?.subtle === undefined)
+        throw new ComplianceError("CRYPTO_UNAVAILABLE", "Web Crypto SHA-256 is unavailable", path);
+    return Promise.all(snapshot.map(async (item) => {
+        if (!("bytes" in item))
+            return item;
+        const hash = await globalThis.crypto.subtle.digest("SHA-256", item.bytes);
+        return {
+            id: item.id,
+            scope: item.scope,
+            assurance: item.assurance,
+            algorithm: "sha256",
+            value: [...new Uint8Array(hash)]
+                .map((b) => b.toString(16).padStart(2, "0"))
+                .join(""),
+            byteLength: item.bytes.byteLength,
+        };
+    }));
+}
+function snapshotLineage(lineage) {
+    if (!Array.isArray(lineage))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "$.preparationLineage must be an array", "$.preparationLineage");
+    return lineage
+        .map((raw, index) => {
+        const path = `$.preparationLineage[${index}]`;
+        if (!plain(raw))
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Lineage edge must be a plain object", path);
+        exactKeys(raw, ["outputArtifactId", "inputArtifactIds", "transformationArtifactIds"], path);
+        if (typeof raw.outputArtifactId !== "string")
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Lineage output must be a string", `${path}.outputArtifactId`);
+        token(raw.outputArtifactId, `${path}.outputArtifactId`);
+        const readIds = (value, key) => {
+            if (!Array.isArray(value))
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Lineage ${key} must be an array`, `${path}.${key}`);
+            const result = value.map((id, inputIndex) => {
+                if (typeof id !== "string")
+                    throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Lineage artifact id must be a string", `${path}.${key}[${inputIndex}]`);
+                token(id, `${path}.${key}[${inputIndex}]`);
+                return id;
+            });
+            if (new Set(result).size !== result.length)
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Lineage ${key} must be unique`, `${path}.${key}`);
+            return [...result].sort();
+        };
+        const inputs = readIds(raw.inputArtifactIds, "inputArtifactIds"), transformations = readIds(raw.transformationArtifactIds, "transformationArtifactIds");
+        if (inputs.length + transformations.length === 0)
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Lineage edge must have at least one upstream artifact", path);
+        return {
+            outputArtifactId: raw.outputArtifactId,
+            inputArtifactIds: inputs,
+            transformationArtifactIds: transformations,
+        };
+    })
+        .sort((a, b) => a.outputArtifactId < b.outputArtifactId
+        ? -1
+        : a.outputArtifactId > b.outputArtifactId
+            ? 1
+            : 0);
+}
+function validateArtifactGraph(run, inputArtifacts, preparationArtifacts, lineage) {
+    const byId = new Map();
+    for (const [index, item] of [
+        ...inputArtifacts,
+        ...preparationArtifacts,
+    ].entries()) {
+        if (byId.has(item.id))
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Duplicate artifact ID ${item.id}`, `$.${index < inputArtifacts.length ? "inputArtifacts" : "preparationArtifacts"}[${index < inputArtifacts.length ? index : index - inputArtifacts.length}].id`);
+        byId.set(item.id, item);
+    }
+    const referenced = new Set();
+    const requireArtifact = (id, scope, path) => {
+        const artifact = byId.get(id);
+        if (!artifact)
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Artifact reference ${id} is unresolved`, path);
+        if (artifact.scope !== scope)
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Artifact ${id} must have ${scope} scope`, path);
+        referenced.add(id);
+    };
+    let unsourced = false;
+    for (const [index, item] of run.prepared.inputAudit.entries()) {
+        const source = item.record.source;
+        if (source)
+            requireArtifact(source.artifactId, "input", `$.completedRun.prepared.inputAudit[${index}].record.source.artifactId`);
+        else
+            unsourced = true;
+    }
+    const evidence = run.review.evidence;
+    if (evidence) {
+        for (const [index, item] of evidence.groupingAssignments.entries()) {
+            if (item.source)
+                requireArtifact(item.source.artifactId, "input", `$.completedRun.review.evidence.groupingAssignments[${index}].source.artifactId`);
+            else
+                unsourced = true;
+        }
+        for (const [index, item] of evidence.cachedFormulas.entries()) {
+            if (item.source)
+                requireArtifact(item.source.artifactId, "input", `$.completedRun.review.evidence.cachedFormulas[${index}].source.artifactId`);
+            else
+                unsourced = true;
+        }
+    }
+    if (unsourced) {
+        if (run.datasetArtifactId === null)
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Unsourced diagnostic input requires datasetArtifactId", "$.completedRun.datasetArtifactId");
+        const fallback = byId.get(run.datasetArtifactId);
+        if (!fallback ||
+            fallback.scope !== "input" ||
+            fallback.assurance !== "sdk-computed")
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "datasetArtifactId must resolve to SDK-computed input evidence", "$.completedRun.datasetArtifactId");
+        referenced.add(run.datasetArtifactId);
+    }
+    else if (run.datasetArtifactId !== null) {
+        requireArtifact(run.datasetArtifactId, "input", "$.completedRun.datasetArtifactId");
+        if (byId.get(run.datasetArtifactId).assurance !== "sdk-computed")
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "datasetArtifactId must resolve to SDK-computed input evidence", "$.completedRun.datasetArtifactId");
+    }
+    for (const [basisIndex, basis,] of run.prepared.definition.definition.amountBases.entries())
+        for (const [componentIndex, component] of basis.components.entries())
+            if (component.limitation.kind !== "unlimited" &&
+                component.limitation.kind !== "unknown" &&
+                component.limitation.derivation.kind === "external")
+                requireArtifact(component.limitation.derivation.transformationRef, "preparation", `$.definition.amountBases[${basisIndex}].components[${componentIndex}].limitation.derivation.transformationRef`);
+    for (const [ruleIndex, rule,] of run.prepared.definition.definition.reviewRules.entries())
+        if (rule.kind === "layer-order" &&
+            rule.comparability.kind === "caller-asserted")
+            requireArtifact(rule.comparability.rationaleArtifactId, "preparation", `$.definition.reviewRules[${ruleIndex}].comparability.rationaleArtifactId`);
+    if (run.gate.rationaleRef !== null)
+        requireArtifact(run.gate.rationaleRef, "preparation", "$.completedRun.gate.rationaleRef");
+    const edges = new Map();
+    for (const [index, edge] of lineage.entries()) {
+        const path = `$.preparationLineage[${index}]`;
+        if (edges.has(edge.outputArtifactId))
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "An artifact may have only one producing lineage edge", `${path}.outputArtifactId`);
+        const downstream = byId.get(edge.outputArtifactId);
+        if (!downstream)
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Lineage artifact ${edge.outputArtifactId} is unresolved`, `${path}.outputArtifactId`);
+        if (downstream.scope !== "input")
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Lineage output artifact must have input scope", `${path}.outputArtifactId`);
+        for (const [inputIndex, id] of edge.inputArtifactIds.entries()) {
+            if (id === edge.outputArtifactId)
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Lineage may not reference itself", `${path}.inputArtifactIds[${inputIndex}]`);
+            const artifact = byId.get(id);
+            if (!artifact || artifact.scope !== "input")
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Lineage input ${id} must resolve to input evidence`, `${path}.inputArtifactIds[${inputIndex}]`);
+        }
+        for (const [transformIndex, id,] of edge.transformationArtifactIds.entries()) {
+            const artifact = byId.get(id);
+            if (!artifact || artifact.scope !== "preparation")
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Lineage transformation ${id} must resolve to preparation evidence`, `${path}.transformationArtifactIds[${transformIndex}]`);
+        }
+        edges.set(edge.outputArtifactId, [
+            ...edge.inputArtifactIds,
+            ...edge.transformationArtifactIds,
+        ]);
+    }
+    const visiting = new Set(), visited = new Set();
+    for (const root of [...referenced]) {
+        const stack = [{ id: root, exit: false }];
+        while (stack.length > 0) {
+            const { id, exit } = stack.pop();
+            if (exit) {
+                visiting.delete(id);
+                visited.add(id);
+                continue;
+            }
+            if (visiting.has(id))
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Artifact lineage contains a cycle", "$.preparationLineage");
+            if (visited.has(id))
+                continue;
+            visiting.add(id);
+            stack.push({ id, exit: true });
+            for (const upstream of [...(edges.get(id) ?? [])].reverse()) {
+                referenced.add(upstream);
+                stack.push({ id: upstream, exit: false });
+            }
+        }
+    }
+    for (const [index, artifact] of inputArtifacts.entries())
+        if (!referenced.has(artifact.id))
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Artifact ${artifact.id} is orphaned`, `$.inputArtifacts[${index}].id`);
+    for (const [index, artifact] of preparationArtifacts.entries())
+        if (!referenced.has(artifact.id))
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Artifact ${artifact.id} is orphaned`, `$.preparationArtifacts[${index}].id`);
+}
+function rerunAndVerify(run) {
+    assertCompletedValidatedMetricDiagnosticsRun(run);
+    verifyPreparedDiagnosticDataIntegrity(run.prepared);
+    const review = reviewPreparedDiagnosticData({
+        prepared: run.prepared,
+        evidence: run.review.evidence,
+    });
+    if (review.reportFingerprint !== run.review.reportFingerprint ||
+        canonicalJson(review.identityBody) !==
+            canonicalJson(run.review.identityBody))
+        throw new ComplianceError("DIAGNOSTIC_MISMATCH", "Stored diagnostic review does not match a regenerated review", "$.review");
+    const rerun = runMetricDiagnostics({
+        prepared: run.prepared,
+        groupMap: run.groupMap,
+        groupDimensions: run.groupDimensions,
+    });
+    if (canonicalJson(getMetricDiagnosticsResultIdentity(rerun)) !==
+        canonicalJson(getMetricDiagnosticsResultIdentity(run.result)))
+        throw new ComplianceError("DIAGNOSTIC_MISMATCH", "Stored diagnostic result does not match deterministic replay", "$.result");
+    const reviewBlocked = review.report.checks.some((check) => !run.gate.allowedReviewStatuses.includes(check.status)) ||
+        review.evaluations.some((evaluation) => {
+            const status = evaluation.expressionOverflows.length > 0
+                ? "fail"
+                : evaluation.status === "triggered"
+                    ? evaluation.severity
+                    : evaluation.status;
+            return !run.gate.allowedReviewStatuses.includes(status);
+        });
+    const metricBlocked = rerun.findings.some((finding) => finding.category !== "structural" &&
+        !run.gate.allowedMetricFindingSeverities.includes(finding.severity));
+    if (reviewBlocked ||
+        metricBlocked ||
+        run.gate.reviewGate !== "passed" ||
+        run.gate.metricGate !== "passed")
+        throw new ComplianceError("DIAGNOSTIC_MISMATCH", "Diagnostic execution gates do not recompute as passed", "$.gate");
+    return { review, result: getMetricDiagnosticsResultIdentity(run.result) };
+}
+function buildManifest(run, review, inputArtifacts, preparationArtifacts, lineage) {
+    const preparation = getPreparedDiagnosticDataIdentity(run.prepared);
+    return freeze({
+        definitionIntegrity: run.prepared.definition.definitionIntegrity,
+        preparationFingerprint: run.prepared.preparationFingerprint,
+        runPresetId: run.runPresetId,
+        datasetArtifactId: run.datasetArtifactId,
+        inputArtifacts: [...inputArtifacts].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+        preparationArtifacts: [...preparationArtifacts].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+        preparationLineage: lineage,
+        inputAudit: preparation.inputAudit,
+        filter: preparation.filter,
+        groupMap: { ...run.groupMap },
+        groupDimensions: { ...run.groupDimensions },
+        completePeriodCutoffs: preparation.completePeriodCutoffs,
+        expectedCellGridFingerprint: preparation.expectedCellsProvided
+            ? tag("diagnostic-expected-cell-grid", "expectedCells", preparation.expectedCells)
+            : null,
+        executionPolicy: { review, gate: run.gate },
+        engine: {
+            packages: {
+                core: CORE_PACKAGE_VERSION,
+                data: DATA_PACKAGE_VERSION,
+                compliance: COMPLIANCE_PACKAGE_VERSION,
+            },
+            algorithmVersion: "diagnostics-1",
+        },
+    });
+}
+export async function createDiagnosticRunIdentity(input) {
+    if (!plain(input))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Diagnostic evidence must be a plain object", "$");
+    exactKeys(input, [
+        "completedRun",
+        "inputArtifacts",
+        "preparationArtifacts",
+        "preparationLineage",
+    ], "$");
+    const run = input.completedRun;
+    let authenticated;
+    try {
+        authenticated = rerunAndVerify(run);
+    }
+    catch (error) {
+        if (error instanceof ComplianceError)
+            throw error;
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "completedRun must be an authentic completed diagnostic run", "$.completedRun");
+    }
+    const inputSnapshot = snapshotArtifacts(input.inputArtifacts, "input", "$.inputArtifacts");
+    const preparationSnapshot = snapshotArtifacts(input.preparationArtifacts, "preparation", "$.preparationArtifacts");
+    const lineage = snapshotLineage(input.preparationLineage);
+    validateArtifactGraph(run, inputSnapshot, preparationSnapshot, lineage);
+    const [inputArtifacts, preparationArtifacts] = await Promise.all([
+        digestArtifacts(inputSnapshot, "$.inputArtifacts"),
+        digestArtifacts(preparationSnapshot, "$.preparationArtifacts"),
+    ]);
+    const manifest = buildManifest(run, authenticated.review, inputArtifacts, preparationArtifacts, lineage);
+    const runFingerprint = tag("diagnostic-run", "manifest", manifestIdentity(manifest));
+    const resultFingerprint = tag("diagnostic-result", "result", authenticated.result);
+    const runResultFingerprint = bindingTag(runFingerprint, resultFingerprint);
+    const definition = run.prepared.definition;
+    const provenance = freeze({
+        definition: {
+            definition: definition.definition,
+            identities: {
+                algorithm: "fnv1a64-jcs-v1",
+                formulaById: { ...definition.formulaFingerprints },
+                calculationByInstanceId: { ...definition.calculationFingerprints },
+                definition: definition.definitionIntegrity,
+            },
+        },
+        manifest,
+        review: authenticated.review,
+        result: run.result,
+        runFingerprint,
+        resultFingerprint,
+        runResultFingerprint,
+    });
+    verified.set(provenance, run);
+    return provenance;
+}
+export function assertVerifiedDiagnosticRunProvenance(value) {
+    if (value === null || typeof value !== "object" || !verified.has(value))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Value is not authentic verified diagnostic provenance", "$");
+}
+function readArtifactDigests(value, scope, path) {
+    if (!Array.isArray(value))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Artifact digests must be an array", path);
+    return value.map((item, index) => {
+        const itemPath = `${path}[${index}]`;
+        if (!plain(item))
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Artifact digest must be a plain object", itemPath);
+        for (const key of ["id", "algorithm", "value"]) {
+            if (typeof item[key] !== "string")
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `${key} must be a token`, `${itemPath}.${key}`);
+            token(item[key], `${itemPath}.${key}`);
+        }
+        if (item.scope !== scope)
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", `Artifact scope must be ${scope}`, `${itemPath}.scope`);
+        if (item.assurance === "sdk-computed") {
+            exactKeys(item, ["id", "scope", "assurance", "algorithm", "value", "byteLength"], itemPath);
+            if (item.algorithm !== "sha256")
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "SDK digests must use sha256", `${itemPath}.algorithm`);
+            if (!/^[0-9a-f]{64}$/.test(item.value))
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Invalid SHA-256 digest", `${itemPath}.value`);
+            if (!Number.isSafeInteger(item.byteLength) ||
+                item.byteLength < 0)
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Invalid byte length", `${itemPath}.byteLength`);
+        }
+        else if (item.assurance === "caller-declared") {
+            exactKeys(item, ["id", "scope", "assurance", "algorithm", "value"], itemPath);
+        }
+        else {
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Unknown artifact assurance", `${itemPath}.assurance`);
+        }
+        return item;
+    });
+}
+function readRecordedEngine(value) {
+    if (!plain(value))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Invalid diagnostic engine", "$.manifest.engine");
+    exactKeys(value, ["packages", "algorithmVersion"], "$.manifest.engine");
+    if (value.algorithmVersion !== "diagnostics-1")
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Unsupported diagnostic algorithm", "$.manifest.engine.algorithmVersion");
+    if (!plain(value.packages))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Invalid diagnostic package versions", "$.manifest.engine.packages");
+    exactKeys(value.packages, ["core", "data", "compliance"], "$.manifest.engine.packages");
+    for (const name of ["core", "data", "compliance"]) {
+        if (typeof value.packages[name] !== "string")
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Package version must be a token", `$.manifest.engine.packages.${name}`);
+        token(value.packages[name], `$.manifest.engine.packages.${name}`);
+    }
+    return value;
+}
+function auditedNumber(value, path) {
+    if (!plain(value))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Invalid audited number", path);
+    if (value.status === "observed" &&
+        typeof value.value === "number" &&
+        Number.isFinite(value.value)) {
+        exactKeys(value, ["status", "value"], path);
+        return value.value;
+    }
+    if (value.status === "missing" && value.value === null) {
+        exactKeys(value, ["status", "value"], path);
+        return null;
+    }
+    if (value.status === "non-finite" && value.value === null) {
+        exactKeys(value, ["status", "value", "nonFiniteKind"], path);
+        if (value.nonFiniteKind === "nan")
+            return NaN;
+        if (value.nonFiniteKind === "positive-infinity")
+            return Infinity;
+        if (value.nonFiniteKind === "negative-infinity")
+            return -Infinity;
+    }
+    throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Invalid audited number", path);
+}
+/** Normalized optional nulls are omitted only when rebuilding authored input. */
+function omitNulls(value) {
+    return plain(value)
+        ? Object.fromEntries(Object.entries(value).filter(([, item]) => item !== null))
+        : value;
+}
+/** Human descriptions/details are regenerated, but are not identity-bearing. */
+function reviewIdentityView(value) {
+    if (!plain(value) ||
+        !plain(value.report) ||
+        !Array.isArray(value.report.checks))
+        return value;
+    return {
+        ...value,
+        report: {
+            ...value.report,
+            checks: value.report.checks.map((check) => {
+                if (!plain(check))
+                    return check;
+                const { description: _description, details: _details, ...identity } = check;
+                return identity;
+            }),
+        },
+    };
+}
+function provenanceIdentityView(value) {
+    if (!plain(value))
+        return value;
+    const manifest = value.manifest;
+    const executionPolicy = plain(manifest) ? manifest.executionPolicy : null;
+    return {
+        ...value,
+        review: reviewIdentityView(value.review),
+        ...(plain(manifest) && plain(executionPolicy)
+            ? {
+                manifest: {
+                    ...manifest,
+                    executionPolicy: {
+                        ...executionPolicy,
+                        review: reviewIdentityView(executionPolicy.review),
+                    },
+                },
+            }
+            : {}),
+    };
+}
+function replaySerializedRun(compiled, manifest, review) {
+    if (!Array.isArray(manifest.inputAudit))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Input audit must be an array", "$.manifest.inputAudit");
+    const losses = [], exposures = [], expectedCells = [];
+    for (const [index, item] of manifest.inputAudit.entries()) {
+        const path = `$.manifest.inputAudit[${index}]`;
+        if (!plain(item) || !plain(item.record))
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Invalid input audit entry", path);
+        exactKeys(item, ["kind", "record", "disposition"], path);
+        const record = { ...item.record };
+        if (record.source === null)
+            delete record.source;
+        else if (record.source !== undefined)
+            record.source = omitNulls(record.source);
+        if (item.kind === "loss") {
+            if (!plain(record.measures))
+                throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Invalid audited measures", `${path}.record.measures`);
+            record.measures = Object.fromEntries(Object.entries(record.measures).map(([id, value]) => [
+                id,
+                auditedNumber(value, `${path}.record.measures.${id}`),
+            ]));
+            if (record.claimId === null)
+                delete record.claimId;
+            losses.push(record);
+        }
+        else if (item.kind === "exposure") {
+            record.value = auditedNumber(record.value, `${path}.record.value`);
+            if (record.valuation === null)
+                delete record.valuation;
+            exposures.push(record);
+        }
+        else if (item.kind === "expected-cell")
+            expectedCells.push(record);
+        else
+            throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Unknown input audit kind", `${path}.kind`);
+    }
+    if (!plain(manifest.executionPolicy) || !plain(manifest.executionPolicy.gate))
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Missing execution gate", "$.manifest.executionPolicy.gate");
+    const gate = manifest.executionPolicy.gate;
+    exactKeys(gate, [
+        "allowedReviewStatuses",
+        "allowedMetricFindingSeverities",
+        "rationaleRef",
+        "reviewGate",
+        "metricGate",
+    ], "$.manifest.executionPolicy.gate");
+    let outcome;
+    try {
+        outcome = runValidatedMetricDiagnostics(validateDiagnosticRunInput({
+            definition: compiled.definition,
+            losses,
+            exposures,
+            ...(manifest.filter === null
+                ? {}
+                : { filter: omitNulls(manifest.filter) }),
+            completePeriodCutoffs: manifest.completePeriodCutoffs,
+            ...(manifest.expectedCellGridFingerprint === null
+                ? {}
+                : { expectedCells }),
+            reviewEvidence: review.evidence,
+            ...(manifest.runPresetId === null
+                ? {}
+                : { runPresetId: manifest.runPresetId }),
+            ...(manifest.datasetArtifactId === null
+                ? {}
+                : { datasetArtifactId: manifest.datasetArtifactId }),
+            groupMap: manifest.groupMap,
+            groupDimensions: manifest.groupDimensions,
+            policy: {
+                allowedReviewStatuses: gate.allowedReviewStatuses,
+                allowedMetricFindingSeverities: gate.allowedMetricFindingSeverities,
+                ...(gate.rationaleRef === null
+                    ? {}
+                    : { rationaleRef: gate.rationaleRef }),
+            },
+        }));
+    }
+    catch (error) {
+        if (!(error instanceof DiagnosticValidationError))
+            throw error;
+        const issue = error.issues[0];
+        let issuePath = issue?.path ?? "$";
+        const recordPath = /^\$\.(losses|exposures|expectedCells)\[(\d+)\](.*)$/.exec(issuePath);
+        if (recordPath) {
+            const kind = recordPath[1] === "losses"
+                ? "loss"
+                : recordPath[1] === "exposures"
+                    ? "exposure"
+                    : "expected-cell";
+            const auditIndices = manifest.inputAudit.flatMap((item, index) => plain(item) && item.kind === kind ? [index] : []);
+            issuePath = `$.manifest.inputAudit[${auditIndices[Number(recordPath[2])]}].record${recordPath[3]}`;
+        }
+        else if (issuePath.startsWith("$.reviewEvidence"))
+            issuePath = issuePath.replace("$.reviewEvidence", "$.review.evidence");
+        else if (issuePath.startsWith("$.policy"))
+            issuePath = issuePath.replace("$.policy", "$.manifest.executionPolicy.gate");
+        else if (issuePath.startsWith("$.definition"))
+            issuePath = issuePath.replace("$.definition", "$.definition.definition");
+        else
+            issuePath = issuePath.replace(/^\$\./, "$.manifest.");
+        throw new ComplianceError("BAD_DIAGNOSTIC_RUN", issue?.message ?? "Invalid diagnostic replay input", issuePath);
+    }
+    if (outcome.status !== "completed")
+        throw new ComplianceError("DIAGNOSTIC_MISMATCH", "Stored execution does not pass its declared gates", "$.manifest.executionPolicy.gate");
+    return outcome;
+}
+/** Verify serialized evidence by replaying the owning core/data public workflows. */
+export function serializedDiagnosticRunMismatch(value, path = "$.diagnosticRuns[0]") {
+    try {
+        if (!plain(value))
+            return path;
+        const fields = [
+            "definition",
+            "manifest",
+            "review",
+            "result",
+            "runFingerprint",
+            "resultFingerprint",
+            "runResultFingerprint",
+        ];
+        exactKeys(value, fields, "$");
+        for (const key of fields)
+            if (!Object.hasOwn(value, key))
+                return `${path}.${key}`;
+        if (!plain(value.definition))
+            return `${path}.definition`;
+        exactKeys(value.definition, ["definition", "identities"], "$.definition");
+        let compiled;
+        try {
+            compiled = compileDiagnosticDefinition(value.definition.definition);
+        }
+        catch (error) {
+            const issuePath = error instanceof DiagnosticValidationError
+                ? error.issues[0]?.path
+                : undefined;
+            return `${path}.definition.definition${issuePath?.startsWith("$") ? issuePath.slice(1) : ""}`;
+        }
+        const identities = {
+            algorithm: "fnv1a64-jcs-v1",
+            formulaById: compiled.formulaFingerprints,
+            calculationByInstanceId: compiled.calculationFingerprints,
+            definition: compiled.definitionIntegrity,
+        };
+        let mismatch = firstDifference(value.definition.identities, identities, `${path}.definition.identities`);
+        if (mismatch !== null)
+            return mismatch;
+        if (!plain(value.manifest))
+            return `${path}.manifest`;
+        if (!plain(value.review))
+            return `${path}.review`;
+        const manifest = value.manifest;
+        const engine = readRecordedEngine(manifest.engine);
+        const inputArtifacts = readArtifactDigests(manifest.inputArtifacts, "input", "$.manifest.inputArtifacts");
+        const preparationArtifacts = readArtifactDigests(manifest.preparationArtifacts, "preparation", "$.manifest.preparationArtifacts");
+        const lineage = snapshotLineage(manifest.preparationLineage);
+        const run = replaySerializedRun(compiled, manifest, value.review);
+        if (manifest.preparationFingerprint !== run.prepared.preparationFingerprint)
+            return `${path}.manifest.preparationFingerprint`;
+        validateArtifactGraph(run, inputArtifacts, preparationArtifacts, lineage);
+        mismatch = firstDifference(reviewIdentityView(value.review), reviewIdentityView(run.review), `${path}.review`);
+        if (mismatch !== null)
+            return mismatch;
+        const expectedManifest = {
+            ...buildManifest(run, run.review, inputArtifacts, preparationArtifacts, lineage),
+            // Historical package versions describe the original run; reproduction
+            // checks the supported algorithm and bundle-wide version agreement.
+            engine,
+        };
+        mismatch = firstDifference(provenanceIdentityView({ manifest })
+            .manifest, provenanceIdentityView({ manifest: expectedManifest }).manifest, `${path}.manifest`);
+        if (mismatch !== null)
+            return mismatch;
+        const result = getMetricDiagnosticsResultIdentity(run.result);
+        let candidateResult;
+        try {
+            candidateResult = getMetricDiagnosticsResultIdentity(value.result);
+        }
+        catch (error) {
+            const issuePath = error instanceof DiagnosticValidationError
+                ? error.issues[0]?.path
+                : undefined;
+            return `${path}.result${issuePath?.startsWith("$") ? issuePath.slice(1) : ""}`;
+        }
+        mismatch = firstDifference(candidateResult, result, `${path}.result`);
+        if (mismatch !== null)
+            return mismatch;
+        const runFingerprint = tag("diagnostic-run", "manifest", manifestIdentity(expectedManifest));
+        const resultFingerprint = tag("diagnostic-result", "result", result);
+        if (value.runFingerprint !== runFingerprint)
+            return `${path}.runFingerprint`;
+        if (value.resultFingerprint !== resultFingerprint)
+            return `${path}.resultFingerprint`;
+        if (value.runResultFingerprint !==
+            bindingTag(runFingerprint, resultFingerprint))
+            return `${path}.runResultFingerprint`;
+        return null;
+    }
+    catch (error) {
+        if (error instanceof ComplianceError && error.path) {
+            const relative = error.path
+                .replace(/^\$\.completedRun\.prepared/, "$.manifest")
+                .replace(/^\$\.completedRun\.review/, "$.review")
+                .replace(/^\$\.completedRun\.gate/, "$.manifest.executionPolicy.gate")
+                .replace(/^\$\.completedRun\./, "$.manifest.")
+                .replace(/^\$\.(inputArtifacts|preparationArtifacts|preparationLineage)/, "$.manifest.$1");
+            return `${path}${relative.slice(1)}`;
+        }
+        return path;
+    }
+}
+/** @internal Bundle authoring uses owner state rather than trusting the public snapshot. */
+export function verifiedDefinitionForBundle(value) {
+    assertVerifiedDiagnosticRunProvenance(value);
+    return verified.get(value).prepared.definition;
+}
+export async function verifyDiagnosticRunIdentity(candidate, input) {
+    let left;
+    let snapshot;
+    try {
+        left = canonicalJson(candidate);
+        snapshot = JSON.parse(left);
+    }
+    catch {
+        throw new ComplianceError("DIAGNOSTIC_MISMATCH", "Stored diagnostic provenance is not canonical JSON", "$");
+    }
+    const regenerated = await createDiagnosticRunIdentity(input);
+    const comparedSnapshot = provenanceIdentityView(snapshot);
+    const comparedRegenerated = provenanceIdentityView(regenerated);
+    if (canonicalJson(comparedSnapshot) !== canonicalJson(comparedRegenerated))
+        throw new ComplianceError("DIAGNOSTIC_MISMATCH", "Stored diagnostic provenance differs from regenerated provenance", firstDifference(comparedSnapshot, comparedRegenerated, "$") ?? "$");
+    return regenerated;
+}
+function firstDifference(left, right, path) {
+    if (plain(left) && plain(right)) {
+        const keys = [
+            ...new Set([...Object.keys(left), ...Object.keys(right)]),
+        ].sort();
+        for (const key of keys) {
+            const childPath = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+                ? `${path}.${key}`
+                : `${path}[${JSON.stringify(key)}]`;
+            if (!Object.prototype.hasOwnProperty.call(left, key) ||
+                !Object.prototype.hasOwnProperty.call(right, key))
+                return childPath;
+            const found = firstDifference(left[key], right[key], childPath);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (Array.isArray(left) && Array.isArray(right)) {
+        const shared = Math.min(left.length, right.length);
+        for (let index = 0; index < shared; index++) {
+            const found = firstDifference(left[index], right[index], `${path}[${index}]`);
+            if (found)
+                return found;
+        }
+        return left.length === right.length ? null : `${path}[${shared}]`;
+    }
+    try {
+        return canonicalJson(left) === canonicalJson(right) ? null : path;
+    }
+    catch {
+        return path;
+    }
+}
+//# sourceMappingURL=diagnosticRun.js.map