From 5dc54183f2af09f1ab6f0ddaf88faacaa6cf3f07 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:30:41 +0800 Subject: [PATCH] fix(evidence): identify snapshots across portable file readers (#12172) --- docs/getting-started/cli.md | 3 ++ src/application/EvidenceBundleFiles.ts | 32 +++----------- src/application/EvidenceFileEnvelope.ts | 38 +++++++++++++++++ .../analysisView/evidenceFileSource.ts | 10 ++++- src/domain/evidenceErrors.ts | 2 +- .../boundary/cli/bundleComparisonCli.test.ts | 42 ++++++++++++++++++- 6 files changed, 97 insertions(+), 30 deletions(-) create mode 100644 src/application/EvidenceFileEnvelope.ts diff --git a/docs/getting-started/cli.md b/docs/getting-started/cli.md index f9c684b61c..d643eacf4a 100644 --- a/docs/getting-started/cli.md +++ b/docs/getting-started/cli.md @@ -1000,6 +1000,9 @@ The JSON workflow commands supporting this option are: For `inspect-analysis-view`, the request's source reference selects a parent from the bundle for every supported view kind. Bundles exported from MCP work for these commands. Its inline source form cannot also select a bundle. +An `evidence-file` source accepts a standalone Evidence record or a bundle. +When either file input resembles an analysis snapshot, the error identifies +the snapshot and directs you to export session Evidence. A missing ID is refused with `details.reason: "missing"`; supplying a bundle does not make incompatible Evidence valid for a workflow. `compare-managed-members` keeps its two assembly paths and the diff --git a/src/application/EvidenceBundleFiles.ts b/src/application/EvidenceBundleFiles.ts index 468999a176..6105ceafd2 100644 --- a/src/application/EvidenceBundleFiles.ts +++ b/src/application/EvidenceBundleFiles.ts @@ -4,8 +4,6 @@ import { jsonValueValidationIssue } from "../domain/jsonValue.js"; import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCleanup.js"; 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 { @@ -30,6 +28,10 @@ import { bufferedJsonParts, canonicalJsonParts, } from "../domain/jsonSerialization.js"; +import { + evidenceFileEnvelopeKind, + snapshotWrongEvidenceKind, +} from "./EvidenceFileEnvelope.js"; import { readJsonFile } from "./JsonFiles.js"; import { writeTextParts, @@ -114,6 +116,8 @@ const readBundle = async ( const loaded = await readJsonFile(path, signal, resources, operation); if (!loaded.ok) return loaded; if (signal?.aborted) return err(cancelledBy(operation, signal)); + if (evidenceFileEnvelopeKind(loaded.value) === "analysis-snapshot") + return err(snapshotWrongEvidenceKind(path, operation, "bundle")); return authenticateEvidenceBundleValue(loaded.value, path, { operation, immutable, @@ -149,30 +153,6 @@ export const authenticateEvidenceBundleValue = ( userMessage: failure.message, }), ); - if ( - 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: 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, diff --git a/src/application/EvidenceFileEnvelope.ts b/src/application/EvidenceFileEnvelope.ts new file mode 100644 index 0000000000..516f51d00c --- /dev/null +++ b/src/application/EvidenceFileEnvelope.ts @@ -0,0 +1,38 @@ +import { resemblesAnalysisSnapshot } from "../domain/analysisSnapshot.js"; +import { EvidenceFileError } from "../domain/evidenceErrors.js"; +import { absoluteCallerPath } from "../filesystem/callerPath.js"; +import { isRecord } from "../kernel/isRecord.js"; + +/** Observe the already decoded file envelope before authenticating its contents. */ +export const evidenceFileEnvelopeKind = ( + value: unknown, +): "evidence-bundle" | "analysis-snapshot" | "other" => { + if (isRecord(value) && Object.hasOwn(value, "records")) + return "evidence-bundle"; + return resemblesAnalysisSnapshot(value) ? "analysis-snapshot" : "other"; +}; + +/** Use the same observed kind with recovery for the selected Evidence input. */ +export const snapshotWrongEvidenceKind = ( + path: string, + operation: string, + expected: "bundle" | "record-or-bundle", +): EvidenceFileError => { + const importing = operation === "import_evidence_bundle"; + const explanation = + "This JSON appears to be an analysis snapshot. Its snapshot content has not been validated."; + return new EvidenceFileError("read", "wrong-kind", { + path: absoluteCallerPath(path), + detectedKind: "analysis-snapshot", + 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.` + : expected === "bundle" + ? `${explanation} Supply a standalone Evidence bundle from export_evidence_bundle for this input.` + : `${explanation} Supply a standalone Evidence record or bundle for this input. Use export_evidence_bundle to export a bundle from a session.`, + }); +}; diff --git a/src/application/analysisView/evidenceFileSource.ts b/src/application/analysisView/evidenceFileSource.ts index 0930782dbd..157cd2a012 100644 --- a/src/application/analysisView/evidenceFileSource.ts +++ b/src/application/analysisView/evidenceFileSource.ts @@ -19,7 +19,10 @@ import { isUnsupportedEvidenceFormat } from "../../domain/evidenceFormat.js"; import { EvidenceFileError } from "../../domain/evidenceErrors.js"; import { projectInputIssuesBounded } from "../../domain/inputIssueProjection.js"; import { readJsonFile } from "../JsonFiles.js"; -import { isRecord } from "../../kernel/isRecord.js"; +import { + evidenceFileEnvelopeKind, + snapshotWrongEvidenceKind, +} from "../EvidenceFileEnvelope.js"; /** The request cancellation and the scope retaining descriptors whose close failed. */ export interface EvidenceFileReadOptions { @@ -168,7 +171,10 @@ export const readEvidenceFileSource = async ( if (!loaded.ok) return loaded; if (signal?.aborted) return err(cancelledBy(operation, signal)); const value = loaded.value; - if (isRecord(value) && Object.hasOwn(value, "records")) { + const kind = evidenceFileEnvelopeKind(value); + if (kind === "analysis-snapshot") + return err(snapshotWrongEvidenceKind(path, operation, "record-or-bundle")); + if (kind === "evidence-bundle") { const bundle = authenticateEvidenceBundleValue(value, path, { operation, immutable: true, diff --git a/src/domain/evidenceErrors.ts b/src/domain/evidenceErrors.ts index 97afe2c867..51c840a712 100644 --- a/src/domain/evidenceErrors.ts +++ b/src/domain/evidenceErrors.ts @@ -95,7 +95,7 @@ export class EvidenceReferenceError extends EvidenceIntegrityError { } /** Evidence bundle filesystem access failed within the configured policy. */ -/** A recognized document kind supplied where an Evidence bundle is required. */ +/** A recognized file kind supplied where a different Evidence input is required. */ export type EvidenceFileDetectedKind = "analysis-snapshot" | "evidence-record"; export class EvidenceFileError extends AnalysisError { diff --git a/tests/boundary/cli/bundleComparisonCli.test.ts b/tests/boundary/cli/bundleComparisonCli.test.ts index a0a9f1a0c6..7416d01845 100644 --- a/tests/boundary/cli/bundleComparisonCli.test.ts +++ b/tests/boundary/cli/bundleComparisonCli.test.ts @@ -171,7 +171,7 @@ cliTest( ); cliTest( - "identifies an analysis snapshot on either side of a bundle comparison", + "identifies an analysis snapshot across portable Evidence readers", async ({ cli }) => { const root = await createTestTempDirectory("rea-compare-snapshot-kind-"); const bundlePath = join(root, "bundle.json"); @@ -224,6 +224,46 @@ cliTest( ).toMatchObject(wrongKind); } + const source = { kind: "evidence-file", path: snapshotPath }; + const view = { kind: "summary" }; + const direct = await cli.run({ + arguments: [ + "inspect-analysis-view", + JSON.stringify({ source, view }), + "--json", + ], + }); + expect(direct.exitCode).toBe(1); + const explicitSource = { + ...wrongKind, + remediation: { + action: expect.stringContaining("standalone Evidence record or bundle"), + }, + }; + expect(direct.json).toMatchObject(explicitSource); + expect( + parseMcpToolError(await call("inspect_analysis_view", { source, view })) + .error, + ).toMatchObject(explicitSource); + + const portable = await cli.run({ + arguments: [ + "inspect-analysis-view", + JSON.stringify({ + source: { + kind: "retained-evidence", + evidence_id: `ev_${"f".repeat(64)}`, + }, + view, + }), + "--evidence-bundle", + snapshotPath, + "--json", + ], + }); + expect(portable.exitCode).toBe(1); + expect(portable.json).toMatchObject(wrongKind); + const malformed = await compareCli(bundlePath, malformedPath); expect(malformed.exitCode).toBe(1); expect(malformed.json).toMatchObject({