fix(evidence): recognize misplaced snapshots across bundle readers (#12151)

* fix(evidence): recognize misplaced snapshots across bundle readers

Refs #12126

* docs(evidence): explain recovery for misplaced snapshots
This commit is contained in:
morluto authored and GitHub committed 2026-11-18 22:01:18 -05:00
1 parent 72be66d050
commit 461cedd73c
3 files changed
+82 -7

No files matched your search

+5
View File
@@ -945,6 +945,11 @@ not read artifact contents: the inventories of two builds are unresolved
records, or one opaque change when you pair them. Use `compare-artifacts`,
described at the end of this section, to compare their contents.
If a selected file looks like an analysis snapshot, comparison reports the
wrong artifact kind. To compare its Evidence, restore the snapshot with its
matching target, provider and analysis profile, then export a standalone
Evidence bundle from that session.
`--record_pairs` accepts an inline JSON array or the path to a local JSON
file containing that array, matching MCP `compare_bundles.record_pairs`. For a
file, use `rea compare left.json right.json --record_pairs pairs.json --json`.
+15 -7
View File
@@ -5,6 +5,7 @@ import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCle
import { requireAuthenticationHeadroom } from "./JsonAuthenticationHeadroom.js";
import { absoluteCallerPath } from "../filesystem/callerPath.js";
import { resemblesAnalysisSnapshot } from "../domain/analysisSnapshot.js";
import { isRecord } from "../kernel/isRecord.js";
import { describeValidationFailure } from "../domain/validationFailure.js";
import {
@@ -149,22 +150,29 @@ export const authenticateEvidenceBundleValue = (
}),
);
if (
operation === "import_evidence_bundle" &&
typeof value === "object" &&
value !== null &&
isRecord(value) &&
!Object.hasOwn(value, "records") &&
resemblesAnalysisSnapshot(value)
)
) {
const importing = operation === "import_evidence_bundle";
const explanation =
"This JSON appears to be an analysis snapshot rather than an Evidence bundle. Its snapshot content has not been validated.";
return err(
new EvidenceFileError("read", "wrong-kind", {
path: absoluteCallerPath(path),
cause: failure.cause,
detectedKind: "analysis-snapshot",
related: { operations: ["open_binary", "export_evidence_bundle"] },
userMessage:
"This JSON appears to be an analysis snapshot rather than an Evidence bundle. Its snapshot content has not been validated. To restore it, use a matching target, provider and analysis profile: call open_binary with snapshot_path set to this file to load the snapshot, and close_binary with snapshot_path to save updated state. Alternatively, supply a bundle from export_evidence_bundle.",
related: {
operations: importing
? ["open_binary", "export_evidence_bundle"]
: ["export_evidence_bundle"],
},
userMessage: importing
? `${explanation} To restore it, use a matching target, provider and analysis profile: call open_binary with snapshot_path set to this file to load the snapshot, and close_binary with snapshot_path to save updated state. Alternatively, supply a bundle from export_evidence_bundle.`
: `${explanation} Supply a standalone Evidence bundle from export_evidence_bundle for this input.`,
}),
);
}
return err(
new EvidenceIntegrityError("Evidence bundle validation failed", {
cause: failure.cause,
@@ -170,6 +170,68 @@ cliTest(
},
);
cliTest(
"identifies an analysis snapshot on either side of a bundle comparison",
async ({ cli }) => {
const root = await createTestTempDirectory("rea-compare-snapshot-kind-");
const bundlePath = join(root, "bundle.json");
const snapshotPath = join(root, "snapshot.json");
const malformedPath = join(root, "malformed.json");
const snapshot = {
target: {},
binding: {},
evidence_bundle: {},
entries: [],
workflow_entries: [],
};
await Promise.all([
writeFile(bundlePath, serializeEvidenceBundle(createEvidenceBundle([]))),
writeFile(snapshotPath, JSON.stringify(snapshot)),
writeFile(malformedPath, JSON.stringify({ ...snapshot, records: [] })),
]);
const call = await cli.sharedMcpCall?.();
if (call === undefined) throw new Error("Expected shared MCP session");
const wrongKind = {
code: "invalid_request",
remediation: {
action: expect.stringContaining("standalone Evidence bundle"),
},
details: {
operation: "read",
reason: "wrong-kind",
detected_kind: "analysis-snapshot",
path: snapshotPath,
related_operations: ["export_evidence_bundle"],
},
};
const compareCli = (left: string, right: string) =>
cli.run({ arguments: ["compare", left, right, "--json"] });
const compareMcp = (left: string, right: string) =>
call("compare_bundles", {
left_bundle_path: left,
right_bundle_path: right,
});
for (const [left, right] of [
[snapshotPath, bundlePath],
[bundlePath, snapshotPath],
] as const) {
const compared = await compareCli(left, right);
expect(compared.exitCode).toBe(1);
expect(compared.json).toMatchObject(wrongKind);
expect(
parseMcpToolError(await compareMcp(left, right)).error,
).toMatchObject(wrongKind);
}
const malformed = await compareCli(bundlePath, malformedPath);
expect(malformed.exitCode).toBe(1);
expect(malformed.json).toMatchObject({
code: "evidence_integrity_mismatch",
});
},
);
cliTest(
"rejects relative bundle paths over stdio MCP while CLI resolves them from its cwd",
async ({ cli }) => {