Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(io): retain cleanup ownership and honor cancellation
morlutod8c76b629639
diff --git a/src/application/EvidenceBundleFiles.ts b/src/application/EvidenceBundleFiles.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 InvestigationRecordPortEvidenceWriter,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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 18e734cf5..75ef2a618 100644--- a/src/server/registerBundleComparisonTool.ts+++ b/src/server/registerBundleComparisonTool.ts@@ -12,12 +12,14 @@ import { BUNDLE_COMPARISON_PROVIDER } from "../application/InvestigationProviderimport { 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 permitversion: "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 permitawait 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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;+ },+ };+};