diff --git a/src/application/EvidenceBundleFiles.ts b/src/application/EvidenceBundleFiles.ts index 1f1a0a0b7..fd3f34673 100644 --- a/src/application/EvidenceBundleFiles.ts +++ b/src/application/EvidenceBundleFiles.ts @@ -1,8 +1,11 @@ +import { resolve } from "node:path"; + import { createImmutableEvidenceBundle, describeEvidenceBundleFailure, describeValidationFailure, parseEvidenceBundle, + singleEvidenceRecordId, type EvidenceBundle, } from "../domain/evidenceBundle.js"; import { @@ -79,6 +82,16 @@ const readBundle = async ( try { bundle = parseBundle(loaded.value); } catch (cause: unknown) { + // An intact record is the wrong selected file, not damaged bundle content. + const evidenceId = singleEvidenceRecordId(loaded.value); + if (evidenceId !== undefined) + return err( + new EvidenceFileError("read", "not-bundle", { + cause, + path: resolve(path), + evidenceId, + }), + ); return err( new EvidenceIntegrityError("Evidence bundle validation failed", { cause, diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.ts index 3e6aa049c..cd9d1fb57 100644 --- a/src/domain/analysisErrorPresentation.ts +++ b/src/domain/analysisErrorPresentation.ts @@ -26,6 +26,7 @@ import { } from "./hopperErrors.js"; import { ProviderSelectionError } from "./providerSelectionError.js"; import { UnknownRegistryError } from "./unknownRegistryError.js"; +import { singleEvidenceRecordMessage } from "./evidenceBundle.js"; import { providerRetryAction } from "./providerOperationHealth.js"; import type { AnalysisError, AnalysisErrorTag } from "./analysisErrorBase.js"; import type { AnalysisErrorProjection } from "./analysisErrorProjection.js"; @@ -148,6 +149,7 @@ export const analysisErrorCategory = ( error instanceof EvidenceFileError && (error.reason === "missing" || error.reason === "not-file" || + error.reason === "not-bundle" || error.reason === "exists") ) return "invalid_input"; @@ -406,6 +408,7 @@ const evidenceFileMessage = ({ operation, reason, published, + evidenceId, }: EvidenceFileError): string => { if (published !== undefined) return "The output file was published, but staging cleanup remains incomplete."; @@ -415,6 +418,7 @@ const evidenceFileMessage = ({ : "Evidence output directory does not exist. Choose an existing directory and try again."; if (reason === "not-file") return "Evidence path does not point to a regular file. Choose a file and try again."; + if (reason === "not-bundle") return singleEvidenceRecordMessage(evidenceId); if (reason === "exists") return "Evidence file already exists. Choose another path or allow overwrite."; if (reason === "invalid-json") diff --git a/src/domain/analysisErrorProjection.ts b/src/domain/analysisErrorProjection.ts index 6c0699eb8..9687c9e77 100644 --- a/src/domain/analysisErrorProjection.ts +++ b/src/domain/analysisErrorProjection.ts @@ -311,6 +311,9 @@ const artifactStateErrorDetails = ( operation: error.operation, reason: error.reason, ...(error.path === undefined ? {} : { path: error.path }), + ...(error.evidenceId === undefined + ? {} + : { evidence_id: error.evidenceId }), ...(error.published === undefined ? {} : { diff --git a/src/domain/evidenceBundle.ts b/src/domain/evidenceBundle.ts index 5e94620c7..31603500f 100644 --- a/src/domain/evidenceBundle.ts +++ b/src/domain/evidenceBundle.ts @@ -212,14 +212,25 @@ export const describeEvidenceBundleFailure = ( input: unknown, cause: unknown, ): string => { - const record = evidenceSchema.safeParse(input); - if (record.success) - return `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.data.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`; + const recordId = singleEvidenceRecordId(input); + if (recordId !== undefined) return singleEvidenceRecordMessage(recordId); return cause instanceof z.ZodError ? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.` : `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`; }; +/** Identify a single Evidence record supplied where a bundle is expected. */ +export const singleEvidenceRecordId = (input: unknown): string | undefined => { + const record = evidenceSchema.safeParse(input); + return record.success ? record.data.evidence_id : undefined; +}; + +/** Explain how to obtain a bundle when one Evidence record was supplied. */ +export const singleEvidenceRecordMessage = ( + evidenceId: string | undefined, +): string => + `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record${evidenceId === undefined ? "" : ` (${evidenceId})`}. Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`; + /** Locate the first schema issue, or keep a thrown constraint message. */ export const describeValidationFailure = (cause: unknown): string => { if (!(cause instanceof z.ZodError)) diff --git a/src/domain/evidenceErrors.ts b/src/domain/evidenceErrors.ts index 364cbe79d..a789bc6b2 100644 --- a/src/domain/evidenceErrors.ts +++ b/src/domain/evidenceErrors.ts @@ -50,17 +50,27 @@ export class EvidenceFileError extends AnalysisError { readonly path: string | undefined; /** Present only when a write committed before cleanup failed. */ readonly published: PublishedEvidenceFile | undefined; + /** The single Evidence record found where a bundle was expected. */ + readonly evidenceId: string | undefined; constructor( readonly operation: "read" | "write", - readonly reason: "not-file" | "exists" | "invalid-json" | "missing" | "io", + readonly reason: + | "not-file" + | "not-bundle" + | "exists" + | "invalid-json" + | "missing" + | "io", options?: AnalysisErrorOptions & { readonly path?: string; readonly published?: PublishedEvidenceFile; + readonly evidenceId?: string; }, ) { super(`Evidence bundle ${operation} failed: ${reason}`, options); this.path = options?.path; this.published = options?.published; + this.evidenceId = options?.evidenceId; } } diff --git a/tests/boundary/filesystem/evidenceBundleFiles.test.ts b/tests/boundary/filesystem/evidenceBundleFiles.test.ts index 856a545aa..c529fd054 100644 --- a/tests/boundary/filesystem/evidenceBundleFiles.test.ts +++ b/tests/boundary/filesystem/evidenceBundleFiles.test.ts @@ -439,13 +439,15 @@ describe("evidence bundle filesystem adapter", () => { const record = bundle().records[0]; const single = join(directory, "record.json"); await writeFile(single, JSON.stringify(record)); + // An intact record is the caller's file selection, not damaged content. expect(await readEvidenceBundle(single)).toMatchObject({ ok: false, error: { - _tag: "EvidenceIntegrityError", - userMessage: expect.stringContaining( - `this JSON is one Evidence record (${String(record?.evidence_id)})`, - ), + _tag: "EvidenceFileError", + operation: "read", + reason: "not-bundle", + path: single, + evidenceId: record?.evidence_id, }, }); diff --git a/tests/boundary/mcp/bundleComparisonMcp.test.ts b/tests/boundary/mcp/bundleComparisonMcp.test.ts index 9fb00e768..b7891844b 100644 --- a/tests/boundary/mcp/bundleComparisonMcp.test.ts +++ b/tests/boundary/mcp/bundleComparisonMcp.test.ts @@ -134,10 +134,17 @@ describe("bundle comparison MCP integration", () => { expect(result.isError).toBe(true); expect(parseMcpToolError(result)).toMatchObject({ error: { - code: "evidence_integrity_mismatch", + code: "invalid_request", + category: "invalid_input", message: expect.stringContaining( `this JSON is one Evidence record (${record.evidence_id})`, ), + details: { + operation: "read", + reason: "not-bundle", + path: recordPath, + evidence_id: record.evidence_id, + }, }, }); } finally {