Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(io): retain cleanup ownership and honor cancellation

morlutod8c76b629639
diff --git a/src/application/EvidenceBundleFiles.ts b/src/application/EvidenceBundleFiles.ts
index 1f1a0a0b7..83f2f65d9 100644
--- a/src/application/EvidenceBundleFiles.ts
+++ b/src/application/EvidenceBundleFiles.ts
@@ -1,3 +1,5 @@
+import { resolve } from "node:path";
+
import {
createImmutableEvidenceBundle,
describeEvidenceBundleFailure,
@@ -37,13 +39,15 @@ type EvidenceWriteFailure =
export const readEvidenceBundle = (
path: string,
signal?: AbortSignal,
+ resources?: ArtifactResourceScope,
): Promise<Result<EvidenceBundle, EvidenceReadFailure>> =>
- readBundle(path, parseEvidenceBundle, signal);
+ readBundle(path, parseEvidenceBundle, signal, resources);
/** Read an authenticated immutable snapshot for a subsequent session import. */
export const readImmutableEvidenceBundle = (
path: string,
signal?: AbortSignal,
+ resources?: ArtifactResourceScope,
): Promise<Result<EvidenceBundle, EvidenceReadFailure>> =>
readBundle(
path,
@@ -52,26 +56,30 @@ export const readImmutableEvidenceBundle = (
return createImmutableEvidenceBundle(bundle.records, bundle.unknowns);
},
signal,
+ resources,
);
const readBundle = async (
path: string,
parseBundle: (input: unknown) => EvidenceBundle,
signal?: AbortSignal,
+ resources?: ArtifactResourceScope,
): Promise<Result<EvidenceBundle, EvidenceReadFailure>> => {
if (signal?.aborted)
return err(new AnalysisCancelledError("import_evidence_bundle"));
- const loaded = await readJsonFile(path, signal).catch((cause: unknown) => {
- // A failed close transfers a live handle owner; preserve that failure.
- if (
- signal?.aborted === true &&
- !(cause instanceof RegularFileCleanupFailure)
- )
- return err(
- new AnalysisCancelledError("import_evidence_bundle", { cause }),
- );
- throw cause;
- });
+ const loaded = await readJsonFile(path, signal, resources).catch(
+ (cause: unknown) => {
+ // A failed close transfers a live handle owner; preserve that failure.
+ if (
+ signal?.aborted === true &&
+ !(cause instanceof RegularFileCleanupFailure)
+ )
+ return err(
+ new AnalysisCancelledError("import_evidence_bundle", { cause }),
+ );
+ throw cause;
+ },
+ );
if (!loaded.ok) return loaded;
if (signal?.aborted)
return err(new AnalysisCancelledError("import_evidence_bundle"));
@@ -79,10 +87,19 @@ const readBundle = async (
try {
bundle = parseBundle(loaded.value);
} catch (cause: unknown) {
+ const failure = describeEvidenceBundleFailure(loaded.value, cause);
+ if (failure.kind === "single-record")
+ return err(
+ new EvidenceFileError("read", "wrong-kind", {
+ path: resolve(path),
+ cause,
+ userMessage: failure.message,
+ }),
+ );
return err(
new EvidenceIntegrityError("Evidence bundle validation failed", {
cause,
- userMessage: describeEvidenceBundleFailure(loaded.value, cause),
+ userMessage: failure.message,
}),
);
}
diff --git a/src/application/JsonFiles.ts b/src/application/JsonFiles.ts
index 76a05f9cb..6bd1d66c8 100644
--- a/src/application/JsonFiles.ts
+++ b/src/application/JsonFiles.ts
@@ -24,6 +24,7 @@ import {
type JsonObjectMemberReader,
} from "./JsonInputFile.js";
import { NonRegularFileReadError } from "../filesystem/RegularFile.js";
+import { RegularFileCleanupFailure } from "./RegularFileRead.js";
import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
@@ -42,12 +43,14 @@ type TextWriteResult<Failure = EvidenceFileError | AnalysisCancelledError> =
export const readJsonFile = async (
path: string,
signal?: AbortSignal,
+ resources?: ArtifactResourceScope,
): Promise<
Result<unknown, EvidenceFileError | AnalysisResourceConstraintError>
> =>
readJsonFileInput(
path,
- (selected) => readJsonInputFile(selected, "read_evidence_file", signal),
+ (selected) =>
+ readJsonInputFile(selected, "read_evidence_file", signal, resources),
signal,
);
@@ -56,6 +59,7 @@ export const readJsonObjectMembersFile = (
path: string,
scans: readonly ReadonlyMap<string, JsonObjectMemberReader>[],
signal?: AbortSignal,
+ resources?: ArtifactResourceScope,
): Promise<
Result<
void,
@@ -65,7 +69,13 @@ export const readJsonObjectMembersFile = (
readJsonFileInput(
path,
(selected) =>
- readJsonObjectFile(selected, "read_evidence_file", scans, signal),
+ readJsonObjectFile(
+ selected,
+ "read_evidence_file",
+ scans,
+ signal,
+ resources,
+ ),
signal,
);
@@ -103,6 +113,7 @@ const readJsonFileInput = async <Value>(
}
return ok(decoded.value);
} catch (cause: unknown) {
+ if (cause instanceof RegularFileCleanupFailure) throw cause;
if (cause instanceof AnalysisResourceConstraintError) return err(cause);
if (signal?.aborted === true) throw cause;
return err(
diff --git a/src/application/JsonInputFile.ts b/src/application/JsonInputFile.ts
index bceb482d2..a226cb0cc 100644
--- a/src/application/JsonInputFile.ts
+++ b/src/application/JsonInputFile.ts
@@ -11,6 +11,7 @@ import streamValues from "stream-json/streamers/stream-values.js";
import streamArray from "stream-json/streamers/stream-array.js";
import { RegularFileChangedError } from "../filesystem/RegularFile.js";
+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import { withRegularFile } from "./RegularFileRead.js";
import {
JSON_BYTE_ORDER_MARK_MESSAGE,
@@ -55,6 +56,7 @@ export const readJsonObjectFile = (
operation: string,
scans: readonly ReadonlyMap<string, JsonObjectMemberReader>[],
signal?: AbortSignal,
+ resources?: ArtifactResourceScope,
): Promise<Result<void, JsonInputFileFailure>> =>
withRegularFile(
path,
@@ -188,7 +190,10 @@ export const readJsonObjectFile = (
throw cause;
}
},
- { signal },
+ {
+ signal,
+ ...(resources === undefined ? {} : { resources }),
+ },
);
const memberConsumer = (
@@ -236,6 +241,7 @@ export const readJsonInputFile = (
path: string,
operation: string,
signal?: AbortSignal,
+ resources?: ArtifactResourceScope,
): Promise<Result<unknown, JsonInputFileFailure>> =>
withRegularFile(
path,
@@ -294,7 +300,10 @@ export const readJsonInputFile = (
throw cause;
}
},
- { signal },
+ {
+ signal,
+ ...(resources === undefined ? {} : { resources }),
+ },
);
const jsonReadFailure = (
diff --git a/src/application/RegularFileRead.ts b/src/application/RegularFileRead.ts
index 9183c9f8a..f09f4c192 100644
--- a/src/application/RegularFileRead.ts
+++ b/src/application/RegularFileRead.ts
@@ -95,7 +95,8 @@ const withRegularFileOwned = async <Value>(
cause.cleanupCause,
);
if (options.resources === undefined) throw failure;
- await retryRegularFileCleanup(failure, options.resources);
+ const retry = await retryRegularFileCleanup(failure, options.resources);
+ if (retry.cleanup !== undefined) throw failure;
throw cause.cause;
}
const owner = new OwnedFileHandle(handle);
@@ -128,9 +129,10 @@ const withRegularFileOwned = async <Value>(
cleanupCause,
);
if (options.resources === undefined) throw failure;
- const cleanup = await retryRegularFileCleanup(failure, options.resources);
- if (cleanup.outcome.kind === "failed") throw cleanup.outcome.cause;
- return cleanup.outcome.value;
+ const retry = await retryRegularFileCleanup(failure, options.resources);
+ if (retry.cleanup !== undefined) throw failure;
+ if (retry.outcome.kind === "failed") throw retry.outcome.cause;
+ return retry.outcome.value;
}
if (outcome.kind === "failed") throw outcome.cause;
return outcome.value;
diff --git a/src/application/binary/AnalysisSnapshotCache.ts b/src/application/binary/AnalysisSnapshotCache.ts
index 6440ccf6a..bdaa9f68d 100644
--- a/src/application/binary/AnalysisSnapshotCache.ts
+++ b/src/application/binary/AnalysisSnapshotCache.ts
@@ -8,6 +8,7 @@ import {
} from "../../domain/evidenceErrors.js";
import { NoBinaryOpenError } from "../../domain/configurationErrors.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
+import type { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import { rebindEvidenceSubjectTargetPath } from "../../domain/evidence.js";
import { err, ok, type Result } from "../../domain/result.js";
import {
@@ -190,7 +191,7 @@ export class AnalysisSnapshotCache {
| undefined,
mergeEvidence: (
bundle: EvidenceBundle,
- ) => Result<number, EvidenceIntegrityError>,
+ ) => Result<number, EvidenceIntegrityError | AnalysisInputError>,
): Result<number, AnalysisError> {
let validated: AnalysisSnapshot;
try {
diff --git a/src/application/binary/AnalysisSnapshotFiles.ts b/src/application/binary/AnalysisSnapshotFiles.ts
index 174b58bfc..e4b69953a 100644
--- a/src/application/binary/AnalysisSnapshotFiles.ts
+++ b/src/application/binary/AnalysisSnapshotFiles.ts
@@ -15,6 +15,7 @@ import { err, ok, type Result } from "../../domain/result.js";
import type { AnalysisResourceConstraintError } from "../../domain/analysisErrorCore.js";
import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
import { readJsonObjectMembersFile, writeTextFile } from "../JsonFiles.js";
+import { RegularFileCleanupFailure } from "../RegularFileRead.js";
import type { JsonObjectMemberReader } from "../JsonInputFile.js";
import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
@@ -24,6 +25,7 @@ type SnapshotFailure = EvidenceFileError | EvidenceIntegrityError;
export const readAnalysisSnapshot = async (
path: string,
signal?: AbortSignal,
+ resources?: ArtifactResourceScope,
): Promise<
Result<
AnalysisSnapshot,
@@ -61,6 +63,7 @@ export const readAnalysisSnapshot = async (
metadata,
],
signal,
+ resources,
);
if (!loaded.ok) return loaded;
signal?.throwIfAborted();
@@ -74,6 +77,7 @@ export const readAnalysisSnapshot = async (
signal?.throwIfAborted();
return ok(snapshot);
} catch (cause: unknown) {
+ if (cause instanceof RegularFileCleanupFailure) throw cause;
if (signal?.aborted === true)
return err(new AnalysisCancelledError("read_evidence_file", { cause }));
return err(
diff --git a/src/application/binary/BinarySessionRecords.ts b/src/application/binary/BinarySessionRecords.ts
index cfa0fa3b2..5a6bb4dd0 100644
--- a/src/application/binary/BinarySessionRecords.ts
+++ b/src/application/binary/BinarySessionRecords.ts
@@ -11,6 +11,7 @@ import {
AnalysisSnapshotMismatchError,
} from "../../domain/evidenceErrors.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
+import type { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
import type {
RecordUnknownInput,
@@ -129,7 +130,7 @@ export abstract class BinarySessionRecords {
importEvidenceBundle(
bundle: unknown,
- ): Result<number, EvidenceIntegrityError> {
+ ): Result<number, EvidenceIntegrityError | AnalysisInputError> {
const imported = this.#records.mergeEvidenceBundle(bundle);
if (!imported.ok) return imported;
if (imported.value.metadataChanged) this.invalidateSnapshot();
diff --git a/src/application/investigation/EvidenceLedger.test.ts b/src/application/investigation/EvidenceLedger.test.ts
index d4750f9c8..995580194 100644
--- a/src/application/investigation/EvidenceLedger.test.ts
+++ b/src/application/investigation/EvidenceLedger.test.ts
@@ -4,6 +4,7 @@ import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";
import { createEvidence } from "../../domain/evidence.js";
import { createEvidenceBundle } from "../../domain/evidenceBundle.js";
import { recordUnknownInputSchema } from "../../domain/residualUnknown.js";
+import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import { EvidenceLedger } from "./EvidenceLedger.js";
const TARGET: BinaryTarget = {
@@ -234,6 +235,32 @@ describe("evidence ledger metadata imports", () => {
});
describe("evidence bundle imports", () => {
+ it("classifies an authenticated Evidence record as the wrong import kind", () => {
+ const record = createEvidence(TARGET, PROVIDER, {
+ operation: "health",
+ parameters: {},
+ result: true,
+ });
+ const result = new EvidenceLedger().import(record);
+ expect(result).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "AnalysisInputError",
+ userMessage: expect.stringContaining(
+ `this JSON is one Evidence record (${record.evidence_id})`,
+ ),
+ },
+ });
+ if (result.ok) throw new Error("Expected a wrong-kind import failure");
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "invalid_request",
+ category: "invalid_input",
+ message: expect.stringContaining(
+ `this JSON is one Evidence record (${record.evidence_id})`,
+ ),
+ });
+ });
+
it("rejects conflicting duplicate IDs without mutating the ledger", () => {
const ledger = new EvidenceLedger();
const first = createEvidence(TARGET, PROVIDER, {
diff --git a/src/application/investigation/EvidenceLedger.ts b/src/application/investigation/EvidenceLedger.ts
index fb27d40c8..7a5cd9f63 100644
--- a/src/application/investigation/EvidenceLedger.ts
+++ b/src/application/investigation/EvidenceLedger.ts
@@ -8,6 +8,7 @@ import {
validateResidualUnknownAddition,
type EvidenceBundle,
} from "../../domain/evidenceBundle.js";
+import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
import { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
import {
@@ -37,7 +38,10 @@ export interface EvidenceImportDelta {
readonly metadataChanged: boolean;
}
-type ImportResult = Result<EvidenceImportDelta, EvidenceLedgerFailure>;
+type ImportResult = Result<
+ EvidenceImportDelta,
+ EvidenceLedgerFailure | AnalysisInputError
+>;
/** Session-owned set of immutable evidence records. */
export class EvidenceLedger {
@@ -76,10 +80,18 @@ export class EvidenceLedger {
try {
bundle = parseEvidenceBundle(input);
} catch (cause: unknown) {
+ const failure = describeEvidenceBundleFailure(input, cause);
+ if (failure.kind === "single-record")
+ return err(
+ new AnalysisInputError("import_evidence_bundle", {
+ cause,
+ userMessage: failure.message,
+ }),
+ );
return err(
new EvidenceIntegrityError("Evidence bundle validation failed", {
cause,
- userMessage: describeEvidenceBundleFailure(input, cause),
+ userMessage: failure.message,
}),
);
}
diff --git a/src/application/investigation/InvestigationRecordPort.ts b/src/application/investigation/InvestigationRecordPort.ts
index aacf8fa26..efaf9700b 100644
--- a/src/application/investigation/InvestigationRecordPort.ts
+++ b/src/application/investigation/InvestigationRecordPort.ts
@@ -2,6 +2,7 @@ import type { Evidence } from "../../domain/evidence.js";
import type { EvidenceBundle } from "../../domain/evidenceBundle.js";
import type { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
+import type { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
import type {
RecordUnknownInput,
@@ -67,5 +68,7 @@ export interface InvestigationRecordPort
EvidenceWriter,
EvidenceUnknownWriter,
UnknownRegistryPort {
- importEvidenceBundle(bundle: unknown): Result<number, EvidenceIntegrityError>;
+ importEvidenceBundle(
+ bundle: unknown,
+ ): Result<number, EvidenceIntegrityError | AnalysisInputError>;
}
diff --git a/src/application/investigation/InvestigationRecords.ts b/src/application/investigation/InvestigationRecords.ts
index 9f10f14bd..29b93e246 100644
--- a/src/application/investigation/InvestigationRecords.ts
+++ b/src/application/investigation/InvestigationRecords.ts
@@ -3,6 +3,7 @@ import type { Evidence } from "../../domain/evidence.js";
import type { EvidenceBundle } from "../../domain/evidenceBundle.js";
import type { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
+import type { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
import type {
RecordUnknownInput,
@@ -65,7 +66,7 @@ export class InvestigationRecords
/** Atomically merge a bundle and report changes for the owner's post-commit observers. */
mergeEvidenceBundle(
bundle: unknown,
- ): Result<EvidenceImportDelta, EvidenceIntegrityError> {
+ ): Result<EvidenceImportDelta, EvidenceIntegrityError | AnalysisInputError> {
return this.#evidence.import(bundle);
}
diff --git a/src/application/process/ProcessCli.ts b/src/application/process/ProcessCli.ts
index c353af622..94cc05c70 100644
--- a/src/application/process/ProcessCli.ts
+++ b/src/application/process/ProcessCli.ts
@@ -1,7 +1,10 @@
import { z } from "zod";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
-import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
+import {
+ AnalysisCancelledError,
+ AnalysisInputError,
+} from "../../domain/analysisErrorCore.js";
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import { createEvidence, parseEvidence } from "../../domain/evidence.js";
import { describeValidationFailure } from "../../domain/evidenceBundle.js";
@@ -23,6 +26,7 @@ import {
} from "../../domain/process/processEvidenceProvider.js";
import { createProcessCaptureEvidence } from "./ProcessEvidence.js";
import { readJsonFile } from "../JsonFiles.js";
+import { RegularFileCleanupFailure } from "../RegularFileRead.js";
/** Safe process-command failure returned to the CLI adapter. */
export interface ProcessCliErrorOutput {
@@ -51,7 +55,7 @@ export const captureProcessScenarioFile = async (
signal?: AbortSignal,
) => {
try {
- const input = await readJson(path);
+ const input = await readJson(path, "capture_process_scenario", signal);
const parsed = processScenarioSchema.safeParse(input);
if (!parsed.success)
throw analysisInputErrorFromIssues(
@@ -86,6 +90,7 @@ export const captureProcessScenarioFile = async (
if (!captured.ok) return cliAnalysisError(captured.error);
return createProcessCaptureEvidence(parsed.data, captured.value);
} catch (cause: unknown) {
+ if (cause instanceof RegularFileCleanupFailure) throw cause;
return projectProcessCliError(cause);
}
};
@@ -95,14 +100,23 @@ export const compareProcessEvidenceFiles = async (
leftPath: string,
rightPath: string,
traceSpecPath?: string,
+ signal?: AbortSignal,
) => {
try {
- const left = parseCaptureEvidence(await readJson(leftPath), "left");
- const right = parseCaptureEvidence(await readJson(rightPath), "right");
+ const left = parseCaptureEvidence(
+ await readJson(leftPath, "compare_process_captures", signal),
+ "left",
+ );
+ const right = parseCaptureEvidence(
+ await readJson(rightPath, "compare_process_captures", signal),
+ "right",
+ );
const traceSpecification =
traceSpecPath === undefined
? undefined
- : parseTraceSpecification(await readJson(traceSpecPath));
+ : parseTraceSpecification(
+ await readJson(traceSpecPath, "compare_process_captures", signal),
+ );
const comparison =
traceSpecification === undefined
? compareProcessCaptures(left.capture, right.capture)
@@ -129,6 +143,7 @@ export const compareProcessEvidenceFiles = async (
evidenceLinks: [left.id, right.id],
});
} catch (cause: unknown) {
+ if (cause instanceof RegularFileCleanupFailure) throw cause;
return projectProcessCliError(cause);
}
};
@@ -194,8 +209,21 @@ const invalidCaptureEvidence = (cause: unknown): ProcessCliFailure =>
`Capture evidence is malformed (${describeValidationFailure(cause)}). Create new capture evidence, then try again.`,
);
-const readJson = async (path: string): Promise<unknown> => {
- const loaded = await readJsonFile(path);
+const readJson = async (
+ path: string,
+ operation: "capture_process_scenario" | "compare_process_captures",
+ signal?: AbortSignal,
+): Promise<unknown> => {
+ if (signal?.aborted) throw new AnalysisCancelledError(operation);
+ const loaded = await readJsonFile(path, signal).catch((cause: unknown) => {
+ if (
+ signal?.aborted === true &&
+ !(cause instanceof RegularFileCleanupFailure)
+ )
+ throw new AnalysisCancelledError(operation, { cause });
+ throw cause;
+ });
+ if (signal?.aborted) throw new AnalysisCancelledError(operation);
if (loaded.ok) return loaded.value;
if (loaded.error._tag !== "EvidenceFileError") throw loaded.error;
const detail = describeValidationFailure(loaded.error.cause);
diff --git a/src/cli/processCommands.ts b/src/cli/processCommands.ts
index d58a4f059..09538a6c4 100644
--- a/src/cli/processCommands.ts
+++ b/src/cli/processCommands.ts
@@ -40,12 +40,19 @@ export const registerProcessCommands = (
.describe("Optional partial-order or finite-trace specification path"),
}),
run: ({ args }) =>
- logCliCommand(
- logger,
- "compare-process-captures",
- () =>
- compareProcessEvidenceFiles(args.left, args.right, args.traceSpec),
- isProcessCliFailure,
+ withCommandCancellation((signal) =>
+ logCliCommand(
+ logger,
+ "compare-process-captures",
+ () =>
+ compareProcessEvidenceFiles(
+ args.left,
+ args.right,
+ args.traceSpec,
+ signal,
+ ),
+ isProcessCliFailure,
+ ),
),
});
};
diff --git a/src/domain/analysisErrorCore.ts b/src/domain/analysisErrorCore.ts
index c13ba891d..8e1138f19 100644
--- a/src/domain/analysisErrorCore.ts
+++ b/src/domain/analysisErrorCore.ts
@@ -45,13 +45,15 @@ export class AnalysisProtocolError extends AnalysisError {
/** Caller input failed provider-neutral application parsing. */
export class AnalysisInputError extends AnalysisError {
readonly _tag = "AnalysisInputError";
+ override readonly userMessage: string | undefined;
constructor(
readonly operation: string,
- options?: AnalysisErrorOptions,
+ options?: AnalysisErrorOptions & { readonly userMessage?: string },
readonly issues: readonly AnalysisInputIssue[] = [],
) {
super(`Invalid analysis input for ${operation}`, options);
+ this.userMessage = options?.userMessage;
}
}
diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.ts
index 3e6aa049c..fd5db4823 100644
--- a/src/domain/analysisErrorPresentation.ts
+++ b/src/domain/analysisErrorPresentation.ts
@@ -148,6 +148,7 @@ export const analysisErrorCategory = (
error instanceof EvidenceFileError &&
(error.reason === "missing" ||
error.reason === "not-file" ||
+ error.reason === "wrong-kind" ||
error.reason === "exists")
)
return "invalid_input";
@@ -210,7 +211,10 @@ export const analysisErrorUserMessage = (error: AnalysisError): string => {
if (error instanceof AnalysisArtifactChangedError)
return "The selected artifact changed during acquisition; no stable snapshot was decoded.";
if (error instanceof AnalysisInputError)
- return "Analysis input is invalid. Check the arguments and try again.";
+ return (
+ error.userMessage ??
+ "Analysis input is invalid. Check the arguments and try again."
+ );
const hopperMessage = hopperErrorUserMessage(error);
if (hopperMessage !== undefined) return hopperMessage;
if (error.userMessage !== undefined) return error.userMessage;
diff --git a/src/domain/evidenceBundle.test.ts b/src/domain/evidenceBundle.test.ts
index c0a322fe6..d2f90cbf6 100644
--- a/src/domain/evidenceBundle.test.ts
+++ b/src/domain/evidenceBundle.test.ts
@@ -5,6 +5,7 @@ import { ANALYSIS_SNAPSHOT_TARGET } from "./analysisSnapshot.fixture.js";
import {
createEvidenceBundle,
createImmutableEvidenceBundle,
+ describeEvidenceBundleFailure,
evidenceBundleForTarget,
parseEvidenceBundle,
} from "./evidenceBundle.js";
@@ -18,6 +19,24 @@ const provider = { id: "fixture", name: "Fixture", version: "1" };
const targetDigest = "a".repeat(64);
const foreignDigest = "b".repeat(64);
+describe("evidence bundle failure classification", () => {
+ it("treats only authenticated standalone Evidence as the wrong input kind", () => {
+ const record = createEvidence(undefined, provider, {
+ operation: "observe",
+ parameters: {},
+ result: { observed: true },
+ });
+ const single = describeEvidenceBundleFailure(record, new Error("bundle"));
+ expect(single).toMatchObject({ kind: "single-record" });
+
+ const tampered = describeEvidenceBundleFailure(
+ { ...record, normalized_result: { observed: false } },
+ new Error("bundle"),
+ );
+ expect(tampered).toMatchObject({ kind: "invalid-bundle" });
+ });
+});
+
const makeUnknown = (
question: string,
scopeDigest: string,
diff --git a/src/domain/evidenceBundle.ts b/src/domain/evidenceBundle.ts
index 5e94620c7..c1fa3ce1c 100644
--- a/src/domain/evidenceBundle.ts
+++ b/src/domain/evidenceBundle.ts
@@ -208,16 +208,29 @@ const referencedEvidenceIds = (unknown: ResidualUnknown): readonly string[] => [
* Name the bundle constraint that failed and how to recover. A single
* Evidence record, such as one command result, is not a bundle.
*/
+export type EvidenceBundleFailureDescription =
+ | { readonly kind: "single-record"; readonly message: string }
+ | { readonly kind: "invalid-bundle"; readonly message: string };
+
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.`;
- 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.`;
+): EvidenceBundleFailureDescription => {
+ try {
+ const record = parseEvidence(input);
+ return {
+ kind: "single-record",
+ message: `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`,
+ };
+ } catch {
+ return {
+ kind: "invalid-bundle",
+ message:
+ 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.`,
+ };
+ }
};
/** Locate the first schema issue, or keep a thrown constraint message. */
diff --git a/src/domain/evidenceErrors.ts b/src/domain/evidenceErrors.ts
index 364cbe79d..1aae747fd 100644
--- a/src/domain/evidenceErrors.ts
+++ b/src/domain/evidenceErrors.ts
@@ -45,6 +45,7 @@ export class EvidenceReferenceError extends EvidenceIntegrityError {
/** Evidence bundle filesystem access failed within the configured policy. */
export class EvidenceFileError extends AnalysisError {
readonly _tag = "EvidenceFileError";
+ override readonly userMessage: string | undefined;
/** Caller-selected path that failed, resolved against the working directory. */
readonly path: string | undefined;
@@ -53,14 +54,22 @@ export class EvidenceFileError extends AnalysisError {
constructor(
readonly operation: "read" | "write",
- readonly reason: "not-file" | "exists" | "invalid-json" | "missing" | "io",
+ readonly reason:
+ | "not-file"
+ | "exists"
+ | "wrong-kind"
+ | "invalid-json"
+ | "missing"
+ | "io",
options?: AnalysisErrorOptions & {
readonly path?: string;
readonly published?: PublishedEvidenceFile;
+ readonly userMessage?: string;
},
) {
super(`Evidence bundle ${operation} failed: ${reason}`, options);
this.path = options?.path;
this.published = options?.published;
+ this.userMessage = options?.userMessage;
}
}
diff --git a/src/process/ProcessOwnership.test.ts b/src/process/ProcessOwnership.test.ts
index 0aa644add..de233698c 100644
--- a/src/process/ProcessOwnership.test.ts
+++ b/src/process/ProcessOwnership.test.ts
@@ -67,20 +67,90 @@ describe("owned process-group cleanup discovery", () => {
});
describe("opaque process neighbors during cleanup", () => {
- it("cleans verified run-owned groups and records a withheld unrelated neighbor", async () => {
+ it.each([
+ "platform_binary_environment_withheld",
+ "restricted_process_environment_withheld",
+ ])(
+ "cleans verified run-owned groups and records an unrelated %s neighbor",
+ async (diagnostic) => {
+ const processes = [
+ { pid: 100, parentPid: 1, processGroupId: 100, command: "capture" },
+ {
+ pid: 200,
+ parentPid: 1,
+ processGroupId: 200,
+ command: "detached-child",
+ },
+ {
+ pid: 900,
+ parentPid: 1,
+ processGroupId: 900,
+ command: "/usr/bin/opaque-neighbor",
+ },
+ ].map((process) => ({ ...process, state: "S" }));
+ const signalGroup = vi.fn();
+ const identities = new Map(
+ processes.map(({ pid }) => [
+ pid,
+ { state: "readable" as const, identity: `start-${String(pid)}` },
+ ]),
+ );
+ const adapter: ProcessOwnershipHost = {
+ platform: "darwin",
+ listProcesses: () => Promise.resolve(processes),
+ environment: (pid) =>
+ Promise.resolve({
+ REA_PROCESS_RUN_ID: pid === 900 ? "unowned" : "run-token",
+ }),
+ processIdentities: () => Promise.resolve(identities),
+ runTokens: (members) =>
+ Promise.resolve(
+ new Map(
+ members.map(({ pid }) => [
+ pid,
+ pid === 900
+ ? {
+ state: "unavailable" as const,
+ reason: diagnostic,
+ }
+ : { state: "readable" as const, runId: "run-token" },
+ ]),
+ ),
+ ),
+ signalGroup,
+ };
+
+ const result = await cleanupOwnedProcessGroup(
+ {
+ ...ownership,
+ sweepTokenOwnedProcesses: true,
+ captureBaseline: [],
+ },
+ adapter,
+ );
+
+ expect(result).toMatchObject({
+ cleaned: true,
+ signaled: true,
+ unverified: [{ pid: 900, diagnostic }],
+ });
+ expect(signalGroup.mock.calls).toEqual([
+ [100, "SIGKILL"],
+ [200, "SIGKILL"],
+ ]);
+ expect(signalGroup).not.toHaveBeenCalledWith(900, "SIGKILL");
+ },
+ );
+
+ it("fails closed for an unrelated candidate with an ordinary unavailable environment", async () => {
+ const diagnostic = "environment_unavailable";
const processes = [
{ pid: 100, parentPid: 1, processGroupId: 100, command: "capture" },
- {
- pid: 200,
- parentPid: 1,
- processGroupId: 200,
- command: "detached-child",
- },
{
pid: 900,
parentPid: 1,
processGroupId: 900,
- command: "/usr/bin/opaque-neighbor",
+ command: "opaque-neighbor",
},
].map((process) => ({ ...process, state: "S" }));
const signalGroup = vi.fn();
@@ -106,7 +176,7 @@ describe("opaque process neighbors during cleanup", () => {
pid === 900
? {
state: "unavailable" as const,
- reason: "platform_binary_environment_withheld",
+ reason: diagnostic,
}
: { state: "readable" as const, runId: "run-token" },
]),
@@ -125,32 +195,47 @@ describe("opaque process neighbors during cleanup", () => {
);
expect(result).toMatchObject({
- cleaned: true,
- signaled: true,
- unverified: [
- { pid: 900, diagnostic: "platform_binary_environment_withheld" },
- ],
+ cleaned: false,
+ reason: expect.stringContaining(`${diagnostic}=1`),
});
- expect(signalGroup.mock.calls).toEqual([
- [100, "SIGKILL"],
- [200, "SIGKILL"],
- ]);
+ if (result.cleaned)
+ throw new Error("Expected unknown ownership to fail closed");
+ expect(result.reason).toContain(`live candidates 900=${diagnostic}`);
+ expect(result.reason).not.toContain("unowned");
+ expect(result.reason).not.toContain("run-token");
+ expect(signalGroup.mock.calls).toEqual([[100, "SIGKILL"]]);
expect(signalGroup).not.toHaveBeenCalledWith(900, "SIGKILL");
});
+});
+describe("related sweep candidates during cleanup", () => {
it.each([
"environment_unavailable",
+ "platform_binary_environment_withheld",
"restricted_process_environment_withheld",
- ])("fails closed for an unrelated candidate with %s", async (diagnostic) => {
+ ])("fails closed for a related candidate with %s", async (diagnostic) => {
const processes = [
- { pid: 100, parentPid: 1, processGroupId: 100, command: "capture" },
{
- pid: 900,
+ pid: 100,
parentPid: 1,
- processGroupId: 900,
- command: "opaque-neighbor",
+ processGroupId: 100,
+ state: "S",
+ command: "capture",
},
- ].map((process) => ({ ...process, state: "S" }));
+ {
+ pid: 101,
+ parentPid: 100,
+ processGroupId: 100,
+ state: "S",
+ uid:
+ diagnostic === "restricted_process_environment_withheld"
+ ? (process.getuid?.() ?? 0)
+ : process.getuid?.() === 0
+ ? 1
+ : 0,
+ command: "ready-hang",
+ },
+ ];
const signalGroup = vi.fn();
const identities = new Map(
processes.map(({ pid }) => [
@@ -159,24 +244,23 @@ describe("opaque process neighbors during cleanup", () => {
]),
);
const adapter: ProcessOwnershipHost = {
- platform: "darwin",
listProcesses: () => Promise.resolve(processes),
environment: (pid) =>
- Promise.resolve({
- REA_PROCESS_RUN_ID: pid === 900 ? "unowned" : "run-token",
- }),
+ pid === 100
+ ? Promise.resolve({ REA_PROCESS_RUN_ID: "run-token" })
+ : Promise.reject(new Error("EACCES: permission denied")),
processIdentities: () => Promise.resolve(identities),
runTokens: (members) =>
Promise.resolve(
new Map(
members.map(({ pid }) => [
pid,
- pid === 900
- ? {
+ pid === 100
+ ? { state: "readable" as const, runId: "run-token" }
+ : {
state: "unavailable" as const,
reason: diagnostic,
- }
- : { state: "readable" as const, runId: "run-token" },
+ },
]),
),
),
@@ -194,90 +278,14 @@ describe("opaque process neighbors during cleanup", () => {
expect(result).toMatchObject({
cleaned: false,
- reason: expect.stringContaining(`${diagnostic}=1`),
+ reason: expect.stringContaining(
+ "process ownership token could not be read",
+ ),
});
- if (result.cleaned)
- throw new Error("Expected unknown ownership to fail closed");
- expect(result.reason).toContain(`live candidates 900=${diagnostic}`);
- expect(result.reason).not.toContain("unowned");
- expect(result.reason).not.toContain("run-token");
- expect(signalGroup.mock.calls).toEqual([[100, "SIGKILL"]]);
- expect(signalGroup).not.toHaveBeenCalledWith(900, "SIGKILL");
+ expect(signalGroup).not.toHaveBeenCalled();
});
});
-describe("related sweep candidates during cleanup", () => {
- it.each(["environment_unavailable", "platform_binary_environment_withheld"])(
- "fails closed for a related candidate with %s",
- async (diagnostic) => {
- const processes = [
- {
- pid: 100,
- parentPid: 1,
- processGroupId: 100,
- state: "S",
- command: "capture",
- },
- {
- pid: 101,
- parentPid: 100,
- processGroupId: 100,
- state: "S",
- uid: process.getuid?.() === 0 ? 1 : 0,
- command: "ready-hang",
- },
- ];
- const signalGroup = vi.fn();
- const identities = new Map(
- processes.map(({ pid }) => [
- pid,
- { state: "readable" as const, identity: `start-${String(pid)}` },
- ]),
- );
- const adapter: ProcessOwnershipHost = {
- listProcesses: () => Promise.resolve(processes),
- environment: (pid) =>
- pid === 100
- ? Promise.resolve({ REA_PROCESS_RUN_ID: "run-token" })
- : Promise.reject(new Error("EACCES: permission denied")),
- processIdentities: () => Promise.resolve(identities),
- runTokens: (members) =>
- Promise.resolve(
- new Map(
- members.map(({ pid }) => [
- pid,
- pid === 100
- ? { state: "readable" as const, runId: "run-token" }
- : {
- state: "unavailable" as const,
- reason: diagnostic,
- },
- ]),
- ),
- ),
- signalGroup,
- };
-
- const result = await cleanupOwnedProcessGroup(
- {
- ...ownership,
- sweepTokenOwnedProcesses: true,
- captureBaseline: [],
- },
- adapter,
- );
-
- expect(result).toMatchObject({
- cleaned: false,
- reason: expect.stringContaining(
- "process ownership token could not be read",
- ),
- });
- expect(signalGroup).not.toHaveBeenCalled();
- },
- );
-});
-
describe("sampled detached process groups during cleanup", () => {
it("signals only token-authenticated sampled groups and reports an unowned sample", async () => {
const processes = [
diff --git a/src/process/ProcessOwnership.ts b/src/process/ProcessOwnership.ts
index 5b181fe76..399b9cd06 100644
--- a/src/process/ProcessOwnership.ts
+++ b/src/process/ProcessOwnership.ts
@@ -805,17 +805,21 @@ const TOKEN_READ_RETRY_DELAY_MS = 40;
/** Darwin reports this when the kernel withholds a platform binary's environment. */
const PLATFORM_BINARY_ENVIRONMENT_WITHHELD =
"platform_binary_environment_withheld";
+/** Darwin reports this when the kernel withholds a restricted process environment. */
+const RESTRICTED_PROCESS_ENVIRONMENT_WITHHELD =
+ "restricted_process_environment_withheld";
const currentProcessUid = (): number | undefined =>
typeof process.getuid === "function" ? process.getuid() : undefined;
/**
* Whether the operating system provably withheld this candidate's run token:
- * current macOS omits the environment of Apple platform binaries from
- * KERN_PROCARGS2 and fails with EINVAL for processes owned by another
- * account, and neither class can be token-verified by any caller. Such a
- * candidate is recorded as unverified instead of failing an otherwise clean
- * capture; every other unreadable candidate stays fail-closed.
+ * current macOS omits the environment of Apple platform binaries and
+ * CS_RESTRICT processes from KERN_PROCARGS2, and fails with EINVAL for
+ * processes owned by another account. These classes cannot be token-verified
+ * by this caller. An unrelated candidate is recorded as unverified instead
+ * of failing an otherwise clean capture; every related or otherwise
+ * unreadable candidate stays fail-closed.
*/
const environmentWithheldFromInspection = (
entry: ProcessTableEntry,
@@ -824,7 +828,10 @@ const environmentWithheldFromInspection = (
const uid = currentProcessUid();
if (uid !== undefined && entry.uid !== undefined && entry.uid !== uid)
return true;
- return diagnostic === PLATFORM_BINARY_ENVIRONMENT_WITHHELD;
+ return (
+ diagnostic === PLATFORM_BINARY_ENVIRONMENT_WITHHELD ||
+ diagnostic === RESTRICTED_PROCESS_ENVIRONMENT_WITHHELD
+ );
};
const scanTokenOwnedProcesses = async (
diff --git a/src/server/registerBundleComparisonTool.ts b/src/server/registerBundleComparisonTool.ts
index 18e734cf5..75ef2a618 100644
--- a/src/server/registerBundleComparisonTool.ts
+++ b/src/server/registerBundleComparisonTool.ts
@@ -12,12 +12,14 @@ import { BUNDLE_COMPARISON_PROVIDER } from "../application/InvestigationProvider
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import { withAdmittedAnalysis } from "./analysisAdmission.js";
import { runAdmittedToolOperation } from "./admittedToolOperation.js";
+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
/** Register canonical Evidence bundle comparison. */
export const registerBundleComparisonTool = (
server: EvidenceMcpServer,
session: BinarySessionPort,
contract: ReturnType<typeof toolContract<"compare_bundles">>,
+ resources: ArtifactResourceScope,
): void => {
const admission = withAdmittedAnalysis({ kind: "session", session });
server.registerTool(
@@ -31,8 +33,16 @@ export const registerBundleComparisonTool = (
context.mcpReq.signal,
async () => {
const [left, right] = await Promise.all([
- readEvidenceBundle(input.left_bundle_path, context.mcpReq.signal),
- readEvidenceBundle(input.right_bundle_path, context.mcpReq.signal),
+ readEvidenceBundle(
+ input.left_bundle_path,
+ context.mcpReq.signal,
+ resources,
+ ),
+ readEvidenceBundle(
+ input.right_bundle_path,
+ context.mcpReq.signal,
+ resources,
+ ),
]);
if (!left.ok) return server.delivery.toCallToolResult(left, contract);
if (!right.ok)
diff --git a/src/server/registerSessionRecordTools.ts b/src/server/registerSessionRecordTools.ts
index 5854aac9d..41efe981e 100644
--- a/src/server/registerSessionRecordTools.ts
+++ b/src/server/registerSessionRecordTools.ts
@@ -89,6 +89,7 @@ const registerSnapshotEvidenceTool = ({
const registerImportEvidenceTool = ({
server,
session,
+ resources,
importContract,
}: EvidenceToolRegistration): void => {
server.registerTool(
@@ -97,7 +98,7 @@ const registerImportEvidenceTool = ({
async (input, context) => {
const path = input.path;
const signal = context.mcpReq.signal;
- const loaded = await readImmutableEvidenceBundle(path, signal);
+ const loaded = await readImmutableEvidenceBundle(path, signal, resources);
if (!loaded.ok)
return server.delivery.toCallToolResult(loaded, importContract);
const retainedUnknownRevisions = new Set(
diff --git a/src/server/registerSessionTools.ts b/src/server/registerSessionTools.ts
index 4db8031ce..16b9e6408 100644
--- a/src/server/registerSessionTools.ts
+++ b/src/server/registerSessionTools.ts
@@ -160,6 +160,7 @@ export interface LifecycleToolRegistration {
const registerLifecycleTools = (
registration: LifecycleToolRegistration,
+ artifactResources: ArtifactResourceScope,
): void => {
const {
server,
@@ -169,7 +170,7 @@ const registerLifecycleTools = (
availabilityPolicy,
androidAnalysisAvailability,
} = registration;
- registerOpenLifecycleTool(registration);
+ registerOpenLifecycleTool(registration, artifactResources);
registerCloseLifecycleTool(registration);
registerSessionStatusTool({
server,
@@ -181,12 +182,10 @@ const registerLifecycleTools = (
});
};
-const registerOpenLifecycleTool = ({
- server,
- session,
- logger,
- openContract,
-}: LifecycleToolRegistration): void => {
+const registerOpenLifecycleTool = (
+ { server, session, logger, openContract }: LifecycleToolRegistration,
+ artifactResources: ArtifactResourceScope,
+): void => {
server.registerTool(
openContract.name,
toolRegistrationOptions(openContract),
@@ -196,6 +195,7 @@ const registerOpenLifecycleTool = ({
const loaded = await readAnalysisSnapshot(
input.snapshot_path,
context.mcpReq.signal,
+ artifactResources,
);
if (!loaded.ok)
return server.delivery.toCallToolResult(loaded, openContract);
@@ -302,42 +302,45 @@ export const registerSessionTools = (
const compareBundlesContract = toolContract("compare_bundles");
const snapshotContract = toolContract("get_evidence_bundle");
const processResources = new ProcessCaptureResourceScope();
- registerLifecycleTools({
- server,
- session,
- logger,
- openContract,
- closeContract,
- statusContract,
- startedAt: options.startedAt ?? new Date().toISOString(),
- availabilityPolicy: sessionAvailabilityPolicy(
- options.availabilityPolicy,
- {},
- ),
- androidAnalysisAvailability:
- options.androidAnalysisAvailability ?? missingAndroidAvailability,
- closeProcessResources: async () => {
- try {
- await processResources.retryCleanup();
- return ok(null);
- } catch (cause: unknown) {
- return err(
- new ProcessCaptureError(
- "process capture cleanup remains incomplete",
- {
- cause,
- reason: "cleanup_incomplete",
- cleanupResources: ["process_capture_resources"],
- executionFailure:
- cause instanceof Error
- ? cause.message || cause.name
- : String(cause),
- },
- ),
- );
- }
+ registerLifecycleTools(
+ {
+ server,
+ session,
+ logger,
+ openContract,
+ closeContract,
+ statusContract,
+ startedAt: options.startedAt ?? new Date().toISOString(),
+ availabilityPolicy: sessionAvailabilityPolicy(
+ options.availabilityPolicy,
+ {},
+ ),
+ androidAnalysisAvailability:
+ options.androidAnalysisAvailability ?? missingAndroidAvailability,
+ closeProcessResources: async () => {
+ try {
+ await processResources.retryCleanup();
+ return ok(null);
+ } catch (cause: unknown) {
+ return err(
+ new ProcessCaptureError(
+ "process capture cleanup remains incomplete",
+ {
+ cause,
+ reason: "cleanup_incomplete",
+ cleanupResources: ["process_capture_resources"],
+ executionFailure:
+ cause instanceof Error
+ ? cause.message || cause.name
+ : String(cause),
+ },
+ ),
+ );
+ }
+ },
},
- });
+ options.artifactResources,
+ );
registerEvidenceTools({
server,
session,
@@ -381,7 +384,12 @@ export const registerSessionTools = (
registerProcessComparisonTool(server, session, compareContract);
registerArtifactComparisonTool(server, session, compareArtifactsContract);
registerFunctionComparisonTool(server, session, compareFunctionsContract);
- registerBundleComparisonTool(server, session, compareBundlesContract);
+ registerBundleComparisonTool(
+ server,
+ session,
+ compareBundlesContract,
+ options.artifactResources,
+ );
registerInvestigationTools(server, session);
registerUnknownTools({ server, session });
registerContextTools(server, session);
diff --git a/tests/boundary/cli/evidenceBundleCommands.test.ts b/tests/boundary/cli/evidenceBundleCommands.test.ts
index 418c20eb4..abb56f7e8 100644
--- a/tests/boundary/cli/evidenceBundleCommands.test.ts
+++ b/tests/boundary/cli/evidenceBundleCommands.test.ts
@@ -66,6 +66,27 @@ cliTest(
},
);
+cliTest(
+ "reports a standalone Evidence record as the wrong input file kind",
+ async ({ cli }) => {
+ const root = await createTestTempDirectory("rea-evidence-record-input-");
+ const path = join(root, "record.json");
+ const record = revisionBundle().records[0];
+ if (record === undefined) throw new Error("Missing fixture Evidence");
+ await writeFile(path, JSON.stringify(record));
+ const result = await cli.run({
+ arguments: ["evidence-import", path, "--json"],
+ });
+ expect(result.exitCode).toBe(1);
+ expect(result.json).toMatchObject({
+ code: "invalid_request",
+ category: "invalid_input",
+ details: { path },
+ message: expect.stringContaining("this JSON is one Evidence record"),
+ });
+ },
+);
+
cliTest(
"rejects altered Evidence and incomplete unknown history before reporting counts",
async ({ cli }) => {
diff --git a/tests/boundary/filesystem/analysisSnapshot.test.ts b/tests/boundary/filesystem/analysisSnapshot.test.ts
index a235fb4e6..e4b331538 100644
--- a/tests/boundary/filesystem/analysisSnapshot.test.ts
+++ b/tests/boundary/filesystem/analysisSnapshot.test.ts
@@ -1,10 +1,11 @@
import { readFile, stat, writeFile } from "node:fs/promises";
import { join } from "node:path";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, onTestFinished, vi } from "vitest";
import { withArtifactResourceScope } from "../../fixtures/artifactInventory.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { holdFirstFileRead } from "../../support/holdFirstFileRead.js";
import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";
import {
@@ -29,6 +30,8 @@ import { createEvidence } from "../../../src/domain/evidence.js";
import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js";
import { readJsonObjectFile } from "../../../src/application/JsonInputFile.js";
import { RegularFileChangedError } from "../../../src/filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js";
+import { RegularFileCleanupFailure } from "../../../src/application/RegularFileRead.js";
const snapshotFixture = (): AnalysisSnapshot => {
const target = snapshotTarget(TARGET);
@@ -227,20 +230,67 @@ describe("analysis snapshot member decoding", () => {
`${" ".repeat(9 * 1024 * 1024)}${JSON.stringify(snapshot)}`,
);
const controller = new AbortController();
+ const reads = await holdFirstFileRead(path);
+ onTestFinished(() => {
+ controller.abort();
+ reads.release();
+ });
const pending = readAnalysisSnapshot(path, controller.signal);
- const timer = setTimeout(() => controller.abort(), 1);
+ await reads.firstRead;
+ controller.abort();
+ reads.release();
try {
expect(await pending).toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError" },
});
+ expect(reads.readCount).toBe(1);
} finally {
- clearTimeout(timer);
+ vi.restoreAllMocks();
}
const loaded = await readAnalysisSnapshot(path);
if (!loaded.ok) throw loaded.error;
expect(loaded.value).toEqual(snapshot);
});
+});
+
+describe("analysis snapshot file ownership", () => {
+ it.each([false, true])(
+ "retains the file owner when snapshot close fails (cancelled: %s)",
+ async (cancelDuringClose) => {
+ const directory = await createTestTempDirectory("rea-snapshot-cleanup-");
+ const path = join(directory, "snapshot.json");
+ await writeFile(path, JSON.stringify(snapshotFixture()));
+ const controller = new AbortController();
+ const cleanupCause = new Error("injected snapshot file close failure");
+ const close = vi
+ .spyOn(OwnedFileHandle.prototype, "close")
+ .mockImplementationOnce(async () => {
+ if (cancelDuringClose) controller.abort();
+ throw cleanupCause;
+ });
+ let failure: unknown;
+ try {
+ try {
+ await readAnalysisSnapshot(
+ path,
+ cancelDuringClose ? controller.signal : undefined,
+ );
+ } catch (cause: unknown) {
+ failure = cause;
+ }
+ expect(failure).toBeInstanceOf(RegularFileCleanupFailure);
+ if (!(failure instanceof RegularFileCleanupFailure))
+ throw new Error("Expected the retained snapshot file handle owner");
+ expect(failure.cleanupCause).toBe(cleanupCause);
+ expect(failure.owner.handle.fd).toBeGreaterThanOrEqual(0);
+ } finally {
+ close.mockRestore();
+ if (failure instanceof RegularFileCleanupFailure)
+ await failure.owner.close();
+ }
+ },
+ );
it("rejects changed bytes between scans on the same descriptor", async () => {
const directory = await createTestTempDirectory("rea-snapshot-changed-");
diff --git a/tests/boundary/filesystem/evidenceBundleFiles.test.ts b/tests/boundary/filesystem/evidenceBundleFiles.test.ts
index 856a545aa..44d577d26 100644
--- a/tests/boundary/filesystem/evidenceBundleFiles.test.ts
+++ b/tests/boundary/filesystem/evidenceBundleFiles.test.ts
@@ -434,21 +434,8 @@ describe("evidence bundle filesystem adapter", () => {
},
);
- it("names the failed bundle constraint for a single record or schema mismatch", async () => {
+ it("names schema mismatches that prevent bundle parsing", async () => {
const directory = await createTestTempDirectory("rea-evidence-");
- const record = bundle().records[0];
- const single = join(directory, "record.json");
- await writeFile(single, JSON.stringify(record));
- expect(await readEvidenceBundle(single)).toMatchObject({
- ok: false,
- error: {
- _tag: "EvidenceIntegrityError",
- userMessage: expect.stringContaining(
- `this JSON is one Evidence record (${String(record?.evidence_id)})`,
- ),
- },
- });
-
const partial = join(directory, "partial.json");
await writeFile(partial, JSON.stringify({ evidence_id: "typo" }));
const rejected = await readEvidenceBundle(partial);
@@ -477,3 +464,38 @@ describe("evidence bundle filesystem adapter", () => {
});
});
});
+
+describe("standalone Evidence bundle inputs", () => {
+ it("classifies a record only after authenticating it", async () => {
+ const directory = await createTestTempDirectory("rea-evidence-");
+ const record = bundle().records[0];
+ const single = join(directory, "record.json");
+ await writeFile(single, JSON.stringify(record));
+ expect(await readEvidenceBundle(single)).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "EvidenceFileError",
+ reason: "wrong-kind",
+ path: single,
+ userMessage: expect.stringContaining(
+ `this JSON is one Evidence record (${String(record?.evidence_id)})`,
+ ),
+ },
+ });
+
+ const tamperedRecord = join(directory, "tampered-record.json");
+ await writeFile(
+ tamperedRecord,
+ JSON.stringify({ ...record, normalized_result: "changed" }),
+ );
+ expect(await readEvidenceBundle(tamperedRecord)).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "EvidenceIntegrityError",
+ userMessage: expect.stringContaining(
+ "does not match the bundle schema",
+ ),
+ },
+ });
+ });
+});
diff --git a/tests/boundary/filesystem/jsonFileResourceOwnership.test.ts b/tests/boundary/filesystem/jsonFileResourceOwnership.test.ts
new file mode 100644
index 000000000..9e04ec1e0
--- /dev/null
+++ b/tests/boundary/filesystem/jsonFileResourceOwnership.test.ts
@@ -0,0 +1,75 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { expect, it, vi } from "vitest";
+
+import { ArtifactResourceScope } from "../../../src/artifacts/ArtifactResourceScope.js";
+import { readJsonFile } from "../../../src/application/JsonFiles.js";
+import { RegularFileCleanupFailure } from "../../../src/application/RegularFileRead.js";
+import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+
+it("retains and retries a JSON file owner after a persistent close failure", async () => {
+ const root = await createTestTempDirectory("rea-json-file-owner-");
+ const path = join(root, "input.json");
+ await writeFile(path, '{"value":"retained"}');
+ const resources = new ArtifactResourceScope();
+ const closeFailure = new Error("injected persistent close failure");
+ let attempts = 0;
+ const close = vi
+ .spyOn(OwnedFileHandle.prototype, "close")
+ .mockImplementation(async () => {
+ attempts += 1;
+ throw closeFailure;
+ });
+ let failure: unknown;
+ try {
+ try {
+ await readJsonFile(path, undefined, resources);
+ } catch (cause: unknown) {
+ failure = cause;
+ }
+ expect(failure).toBeInstanceOf(RegularFileCleanupFailure);
+ if (!(failure instanceof RegularFileCleanupFailure))
+ throw new Error("Expected the failed file owner to remain visible");
+ expect(failure.cleanupCause).toBe(closeFailure);
+ expect(failure.outcome).toMatchObject({
+ kind: "completed",
+ value: { ok: true, value: { value: "retained" } },
+ });
+ expect(failure.owner.handle.fd).toBeGreaterThanOrEqual(0);
+ expect(attempts).toBe(2);
+ } finally {
+ close.mockRestore();
+ await resources.close();
+ }
+ if (!(failure instanceof RegularFileCleanupFailure))
+ throw new Error("Expected the retained file owner");
+ expect(failure.owner.handle.fd).toBe(-1);
+});
+
+it("returns parsed JSON when a failed file close is recovered by the resource scope", async () => {
+ const root = await createTestTempDirectory("rea-json-file-close-retry-");
+ const path = join(root, "input.json");
+ await writeFile(path, '{"value":"retained"}');
+ const resources = new ArtifactResourceScope();
+ const closeFailure = new Error("injected transient close failure");
+ const originalClose = OwnedFileHandle.prototype.close;
+ let attempts = 0;
+ const close = vi
+ .spyOn(OwnedFileHandle.prototype, "close")
+ .mockImplementation(async function (this: OwnedFileHandle) {
+ attempts += 1;
+ if (attempts === 1) throw closeFailure;
+ await originalClose.call(this);
+ });
+ try {
+ const parsed = await readJsonFile(path, undefined, resources);
+ if (!parsed.ok) throw parsed.error;
+ expect(parsed.value).toEqual({ value: "retained" });
+ expect(attempts).toBe(2);
+ } finally {
+ close.mockRestore();
+ await resources.close();
+ }
+});
diff --git a/tests/boundary/filesystem/processCliFileInput.test.ts b/tests/boundary/filesystem/processCliFileInput.test.ts
index c4b340ffc..10548091a 100644
--- a/tests/boundary/filesystem/processCliFileInput.test.ts
+++ b/tests/boundary/filesystem/processCliFileInput.test.ts
@@ -1,15 +1,22 @@
import { writeFile } from "node:fs/promises";
import { join } from "node:path";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, onTestFinished, vi } from "vitest";
import {
captureProcessScenarioFile,
+ compareProcessEvidenceFiles,
projectProcessCliError,
} from "../../../src/application/process/ProcessCli.js";
import { JSON_BYTE_ORDER_MARK_MESSAGE } from "../../../src/application/Utf8JsonInput.js";
+import { createEvidence } from "../../../src/domain/evidence.js";
+import { PROCESS_PROVIDER } from "../../../src/domain/process/processEvidenceProvider.js";
+import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../../src/domain/process/processCaptureExample.js";
+import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js";
+import { RegularFileCleanupFailure } from "../../../src/application/RegularFileRead.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { holdFirstFileRead } from "../../support/holdFirstFileRead.js";
-describe("process CLI input diagnostics", () => {
+describe("process CLI error projection", () => {
it("preserves local diagnostics for unexpected process failures", () => {
const projected = projectProcessCliError(
new Error("SECRET internal failure /private/path"),
@@ -22,7 +29,116 @@ describe("process CLI input diagnostics", () => {
});
expect(JSON.stringify(projected)).not.toContain("stack");
});
+});
+
+describe("process CLI file cancellation", () => {
+ it("projects pre-aborted file reads as cancellation", async () => {
+ const root = await createTestTempDirectory("rea-process-cli-cancel-");
+ const controller = new AbortController();
+ controller.abort();
+ expect(
+ await captureProcessScenarioFile(
+ join(root, "missing-scenario.json"),
+ process.env,
+ controller.signal,
+ ),
+ ).toMatchObject({
+ error: "Process command failed",
+ code: "cancelled",
+ category: "cancelled",
+ details: { operation: "capture_process_scenario" },
+ });
+ expect(
+ await compareProcessEvidenceFiles(
+ join(root, "missing-left.json"),
+ join(root, "missing-right.json"),
+ join(root, "missing-trace.json"),
+ controller.signal,
+ ),
+ ).toMatchObject({
+ code: "cancelled",
+ category: "cancelled",
+ details: { operation: "compare_process_captures" },
+ });
+ });
+
+ it.each([
+ { workflow: "capture", input: "scenario" },
+ { workflow: "compare", input: "left" },
+ { workflow: "compare", input: "right" },
+ { workflow: "compare", input: "trace specification" },
+ ] as const)(
+ "stops streamed $workflow $input reads after cancellation",
+ async ({ workflow, input }) => {
+ const root = await createTestTempDirectory("rea-process-cli-stream-");
+ const paths = {
+ scenario: join(root, "scenario.json"),
+ left: join(root, "left.json"),
+ right: join(root, "right.json"),
+ trace: join(root, "trace.json"),
+ };
+ const evidence = JSON.stringify(processCaptureEvidence());
+ const scenario = JSON.stringify({
+ executable: process.execPath,
+ arguments: [],
+ });
+ const traceSpecification = JSON.stringify(validTraceSpecification());
+ const contentsByInput = {
+ scenario: input === "scenario" ? stream(scenario) : scenario,
+ left: input === "left" ? stream(evidence) : evidence,
+ right: input === "right" ? stream(evidence) : evidence,
+ trace:
+ input === "trace specification"
+ ? stream(traceSpecification)
+ : traceSpecification,
+ };
+ await Promise.all([
+ writeFile(paths.scenario, contentsByInput.scenario),
+ writeFile(paths.left, contentsByInput.left),
+ writeFile(paths.right, contentsByInput.right),
+ writeFile(paths.trace, contentsByInput.trace),
+ ]);
+ const targetPath =
+ paths[input === "trace specification" ? "trace" : input];
+ const contents =
+ contentsByInput[input === "trace specification" ? "trace" : input];
+ const reader = await holdFirstFileRead(targetPath);
+ onTestFinished(reader.release);
+ const controller = new AbortController();
+ try {
+ const pending =
+ workflow === "capture"
+ ? captureProcessScenarioFile(
+ paths.scenario,
+ process.env,
+ controller.signal,
+ )
+ : compareProcessEvidenceFiles(
+ paths.left,
+ paths.right,
+ paths.trace,
+ controller.signal,
+ );
+ await reader.firstRead;
+ controller.abort();
+ reader.release();
+ expect(await pending).toMatchObject({
+ error: "Process command failed",
+ code: "cancelled",
+ category: "cancelled",
+ });
+ expect(reader.readCount).toBe(1);
+ expect(reader.totalReadBytes).toBeLessThan(contents.length);
+ } finally {
+ controller.abort();
+ reader.release();
+ vi.restoreAllMocks();
+ }
+ },
+ );
+});
+describe("process CLI input diagnostics", () => {
it("projects missing, malformed JSON, and invalid scenario files", async () => {
const root = await createTestTempDirectory("rea-process-cli-diagnostics-");
const malformed = join(root, "malformed.json");
@@ -78,6 +194,44 @@ describe("process CLI input diagnostics", () => {
});
});
+ it.each([false, true])(
+ "preserves the open-file owner when close fails (cancelled: %s)",
+ async (cancelDuringClose) => {
+ const root = await createTestTempDirectory("rea-process-cli-cleanup-");
+ const path = join(root, "scenario.json");
+ await writeFile(path, JSON.stringify({ executable: process.execPath }));
+ const controller = new AbortController();
+ const cleanupCause = new Error("injected file close failure");
+ const close = vi
+ .spyOn(OwnedFileHandle.prototype, "close")
+ .mockImplementationOnce(async () => {
+ if (cancelDuringClose) controller.abort();
+ throw cleanupCause;
+ });
+ let failure: unknown;
+ try {
+ try {
+ await captureProcessScenarioFile(
+ path,
+ process.env,
+ cancelDuringClose ? controller.signal : undefined,
+ );
+ } catch (cause: unknown) {
+ failure = cause;
+ }
+ expect(failure).toBeInstanceOf(RegularFileCleanupFailure);
+ if (!(failure instanceof RegularFileCleanupFailure))
+ throw new Error("Expected the retained file handle owner");
+ expect(failure.cleanupCause).toBe(cleanupCause);
+ expect(failure.owner.handle.fd).toBeGreaterThanOrEqual(0);
+ } finally {
+ close.mockRestore();
+ if (failure instanceof RegularFileCleanupFailure)
+ await failure.owner.close();
+ }
+ },
+ );
+
it("names a leading byte-order mark instead of quoting it as a token", async () => {
const path = join(
await createTestTempDirectory("rea-process-cli-diagnostics-"),
@@ -91,3 +245,40 @@ describe("process CLI input diagnostics", () => {
});
});
});
+
+const processCaptureEvidence = () =>
+ createEvidence(undefined, PROCESS_PROVIDER, {
+ predicateType: "rea.process-capture",
+ operation: "capture_process_scenario",
+ parameters: {},
+ result: EMPTY_PROCESS_CAPTURE_EXAMPLE,
+ confidence: "observed",
+ authority: "controlled-replay",
+ environment: {
+ id: "fixture",
+ platform: "fixture",
+ architecture: "fixture",
+ isolation: "process",
+ },
+ });
+
+const stream = (json: string) => " ".repeat(8 * 1024 * 1024) + json;
+
+const validTraceSpecification = () => ({
+ events: [
+ {
+ id: "started",
+ source: "lifecycle",
+ exact: { state: "started" },
+ },
+ {
+ id: "finished",
+ source: "lifecycle",
+ exact: { state: "finished" },
+ },
+ ],
+ language: {
+ kind: "partial_order",
+ happens_before: [{ before: "started", after: "finished" }],
+ },
+});
diff --git a/tests/boundary/mcp/bundleComparisonCancellation.test.ts b/tests/boundary/mcp/bundleComparisonCancellation.test.ts
index b665c54e1..fc0c7c725 100644
--- a/tests/boundary/mcp/bundleComparisonCancellation.test.ts
+++ b/tests/boundary/mcp/bundleComparisonCancellation.test.ts
@@ -1,5 +1,5 @@
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
-import { open, writeFile, type FileHandle } from "node:fs/promises";
+import { writeFile } from "node:fs/promises";
import { join } from "node:path";
import { expect, it, onTestFinished, vi } from "vitest";
@@ -13,6 +13,7 @@ import { createServer } from "../../../src/server/createServer.js";
import { ToolResultDelivery } from "../../../src/server/toolResult.js";
import { createTestBinarySession } from "../../fixtures/binarySession.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { holdFirstFileRead } from "../../support/holdFirstFileRead.js";
it("leaves the session unchanged after bundle comparison cancellation and permits a retry", async () => {
const root = await createTestTempDirectory("rea-mcp-compare-cancel-");
@@ -58,8 +59,10 @@ it("leaves the session unchanged after bundle comparison cancellation and permit
version: "1",
});
const controller = new AbortController();
+ let releaseRead: (() => void) | undefined;
onTestFinished(async () => {
controller.abort();
+ releaseRead?.();
vi.restoreAllMocks();
await client.close();
await server.close();
@@ -70,8 +73,8 @@ it("leaves the session unchanged after bundle comparison cancellation and permit
await server.connect(serverTransport);
await client.connect(clientTransport);
- const reader = await holdFirstRead(leftPath);
- onTestFinished(reader.release);
+ const reader = await holdFirstFileRead(leftPath);
+ releaseRead = reader.release;
let resolveDispatched: (() => void) | undefined;
const dispatched = new Promise<void>((resolve) => {
@@ -162,56 +165,3 @@ it("leaves the session unchanged after bundle comparison cancellation and permit
]),
);
});
-
-const holdFirstRead = async (path: string) => {
- // Hold the first streamed read after it reaches the operating system.
- const probe = await open(path, "r");
- const identity = await probe.stat();
- const fileHandlePrototype = Object.getPrototypeOf(probe) as {
- read(
- buffer: Buffer,
- offset: number,
- length: number,
- position: number | null,
- ): Promise<{ readonly bytesRead: number; readonly buffer: Buffer }>;
- };
- await probe.close();
- let totalReadBytes = 0;
- let readCount = 0;
- let resolveFirstRead: (() => void) | undefined;
- const firstRead = new Promise<void>((resolve) => {
- resolveFirstRead = resolve;
- });
- let releaseRead: (() => void) | undefined;
- const readGate = new Promise<void>((resolve) => {
- releaseRead = resolve;
- });
- const read = fileHandlePrototype.read;
- vi.spyOn(fileHandlePrototype, "read").mockImplementation(async function (
- this: FileHandle,
- ...args: [Buffer, number, number, number | null]
- ) {
- const current = await this.stat();
- const isTarget =
- current.dev === identity.dev && current.ino === identity.ino;
- const result = await read.call(this, ...args);
- if (!isTarget) return result;
- totalReadBytes += result.bytesRead;
- readCount += 1;
- if (readCount === 1) {
- resolveFirstRead?.();
- await readGate;
- }
- return result;
- });
- return {
- firstRead,
- release: () => releaseRead?.(),
- get readCount() {
- return readCount;
- },
- get totalReadBytes() {
- return totalReadBytes;
- },
- };
-};
diff --git a/tests/boundary/mcp/bundleComparisonMcp.test.ts b/tests/boundary/mcp/bundleComparisonMcp.test.ts
index 9fb00e768..ab8838287 100644
--- a/tests/boundary/mcp/bundleComparisonMcp.test.ts
+++ b/tests/boundary/mcp/bundleComparisonMcp.test.ts
@@ -134,7 +134,9 @@ 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",
+ details: { path: recordPath },
message: expect.stringContaining(
`this JSON is one Evidence record (${record.evidence_id})`,
),
diff --git a/tests/boundary/mcp/evidenceImportCancellation.test.ts b/tests/boundary/mcp/evidenceImportCancellation.test.ts
index cb65dc71a..0413e6ec4 100644
--- a/tests/boundary/mcp/evidenceImportCancellation.test.ts
+++ b/tests/boundary/mcp/evidenceImportCancellation.test.ts
@@ -7,6 +7,7 @@ import { createEvidence } from "../../../src/domain/evidence.js";
import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js";
import { createServer } from "../../../src/server/createServer.js";
import { ToolResultDelivery } from "../../../src/server/toolResult.js";
+import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js";
import { createTestBinarySession } from "../../fixtures/binarySession.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
@@ -137,3 +138,121 @@ it("keeps the complete session unchanged after SDK import cancellation and permi
);
await client.ping();
});
+
+it("retains a failed import close in the server scope through SDK error projection", async () => {
+ const root = await createTestTempDirectory("rea-mcp-import-close-");
+ const path = join(root, "bundle.json");
+ const session = createTestBinarySession(() => {
+ throw new Error("Evidence import must not start a binary provider");
+ });
+ const provider = { id: "fixture", name: "Fixture", version: "1" };
+ const existing = createEvidence(undefined, provider, {
+ operation: "existing_observation",
+ parameters: {},
+ result: { retained: true },
+ });
+ const imported = createEvidence(undefined, provider, {
+ operation: "imported_observation",
+ parameters: {},
+ result: { retained: "close failure" },
+ });
+ const recorded = session.recordEvidence(existing);
+ if (!recorded.ok) throw recorded.error;
+ await writeFile(path, JSON.stringify(createEvidenceBundle([imported])));
+
+ let allowClose = false;
+ let retainedOwner: OwnedFileHandle | undefined;
+ const originalClose = OwnedFileHandle.prototype.close;
+ const close = vi
+ .spyOn(OwnedFileHandle.prototype, "close")
+ .mockImplementation(async function (this: OwnedFileHandle) {
+ retainedOwner ??= this;
+ if (!allowClose) throw new Error("persistent file close failure");
+ return originalClose.call(this);
+ });
+
+ const server = createServer({ kind: "session", session });
+ const client = new Client({
+ name: "evidence-import-close-failure",
+ version: "1",
+ });
+ onTestFinished(async () => {
+ allowClose = true;
+ close.mockRestore();
+ await client.close();
+ await server.close();
+ await session.close();
+ });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+ const before = session.exportEvidenceBundle();
+
+ const result = await client.callTool({
+ name: "import_evidence_bundle",
+ arguments: { path },
+ });
+ expect(result.isError).toBe(true);
+ expect(session.exportEvidenceBundle()).toEqual(before);
+ expect(retainedOwner).toBeDefined();
+ expect(retainedOwner?.handle.fd).toBeGreaterThanOrEqual(0);
+
+ await client.close();
+ await expect(server.close()).rejects.toThrow("REA session cleanup failed");
+ expect(retainedOwner?.handle.fd).toBeGreaterThanOrEqual(0);
+ allowClose = true;
+ close.mockRestore();
+ await server.close();
+ expect(retainedOwner?.handle.fd).toBe(-1);
+ await session.close();
+});
+
+it("retries a transient import close failure before admitting the bundle", async () => {
+ const root = await createTestTempDirectory("rea-mcp-import-close-retry-");
+ const path = join(root, "bundle.json");
+ const session = createTestBinarySession(() => {
+ throw new Error("Evidence import must not start a binary provider");
+ });
+ const imported = createEvidence(
+ undefined,
+ { id: "fixture", name: "Fixture", version: "1" },
+ {
+ operation: "imported_observation",
+ parameters: {},
+ result: { retained: "retry succeeded" },
+ },
+ );
+ await writeFile(path, JSON.stringify(createEvidenceBundle([imported])));
+
+ const originalClose = OwnedFileHandle.prototype.close;
+ const close = vi
+ .spyOn(OwnedFileHandle.prototype, "close")
+ .mockImplementationOnce(async () => {
+ throw new Error("one transient file close failure");
+ });
+ const server = createServer({ kind: "session", session });
+ const client = new Client({
+ name: "evidence-import-close-retry",
+ version: "1",
+ });
+ onTestFinished(async () => {
+ close.mockRestore();
+ await client.close();
+ await server.close();
+ await session.close();
+ });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+
+ const result = await client.callTool({
+ name: "import_evidence_bundle",
+ arguments: { path },
+ });
+ close.mockRestore();
+ expect(result.isError).not.toBe(true);
+ expect(session.exportEvidenceBundle().records).toContainEqual(imported);
+ await client.ping();
+});
diff --git a/tests/support/holdFirstFileRead.ts b/tests/support/holdFirstFileRead.ts
new file mode 100644
index 000000000..3d5082891
--- /dev/null
+++ b/tests/support/holdFirstFileRead.ts
@@ -0,0 +1,55 @@
+import { open, type FileHandle } from "node:fs/promises";
+import { vi } from "vitest";
+
+/** Pause after one selected file chunk reaches the operating system. */
+export const holdFirstFileRead = async (path: string) => {
+ const probe = await open(path, "r");
+ const identity = await probe.stat();
+ const fileHandlePrototype = Object.getPrototypeOf(probe) as {
+ read(
+ buffer: Buffer,
+ offset: number,
+ length: number,
+ position: number | null,
+ ): Promise<{ readonly bytesRead: number; readonly buffer: Buffer }>;
+ };
+ await probe.close();
+ let totalReadBytes = 0;
+ let readCount = 0;
+ let resolveFirstRead: (() => void) | undefined;
+ const firstRead = new Promise<void>((resolve) => {
+ resolveFirstRead = resolve;
+ });
+ let releaseRead: (() => void) | undefined;
+ const readGate = new Promise<void>((resolve) => {
+ releaseRead = resolve;
+ });
+ const read = fileHandlePrototype.read;
+ vi.spyOn(fileHandlePrototype, "read").mockImplementation(async function (
+ this: FileHandle,
+ ...args: [Buffer, number, number, number | null]
+ ) {
+ const current = await this.stat();
+ const isTarget =
+ current.dev === identity.dev && current.ino === identity.ino;
+ const result = await read.call(this, ...args);
+ if (!isTarget) return result;
+ totalReadBytes += result.bytesRead;
+ readCount += 1;
+ if (readCount === 1) {
+ resolveFirstRead?.();
+ await readGate;
+ }
+ return result;
+ });
+ return {
+ firstRead,
+ release: () => releaseRead?.(),
+ get readCount() {
+ return readCount;
+ },
+ get totalReadBytes() {
+ return totalReadBytes;
+ },
+ };
+};