From d8c76b629639bda4405afa9ae2f7676b694f2f10 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 12 Oct 2026 14:08:31 +0800 Subject: [PATCH] fix(io): retain cleanup ownership and honor cancellation Keep failed JSON read handles in the existing server resource scope and fail admission until cleanup succeeds. Thread cancellation through every process CLI input read and replace timer-driven cancellation checks with a shared first-read gate. Classify authenticated standalone Evidence as wrong-kind input while preserving tampered-record integrity failures and actionable messages across ledger, CLI, and MCP consumers. Record unrelated CS_RESTRICT process neighbors as unverified without weakening related-process ownership checks. Update stale ADB fixtures for the actual shell protocol. Validated focused CLI, MCP, filesystem, ownership, and error projection tests; static, docs, and duplication gates pass. The host-level CS_RESTRICT load reproduction was not run. Refs #2050, #2035, #2064. --- src/application/EvidenceBundleFiles.ts | 43 ++- src/application/JsonFiles.ts | 15 +- src/application/JsonInputFile.ts | 13 +- src/application/RegularFileRead.ts | 10 +- .../binary/AnalysisSnapshotCache.ts | 3 +- .../binary/AnalysisSnapshotFiles.ts | 4 + .../binary/BinarySessionRecords.ts | 3 +- .../investigation/EvidenceLedger.test.ts | 27 ++ .../investigation/EvidenceLedger.ts | 16 +- .../investigation/InvestigationRecordPort.ts | 5 +- .../investigation/InvestigationRecords.ts | 3 +- src/application/process/ProcessCli.ts | 42 ++- src/cli/processCommands.ts | 19 +- src/domain/analysisErrorCore.ts | 4 +- src/domain/analysisErrorPresentation.ts | 6 +- src/domain/evidenceBundle.test.ts | 19 ++ src/domain/evidenceBundle.ts | 27 +- src/domain/evidenceErrors.ts | 11 +- src/process/ProcessOwnership.test.ts | 288 +++++++++--------- src/process/ProcessOwnership.ts | 19 +- src/server/registerBundleComparisonTool.ts | 14 +- src/server/registerSessionRecordTools.ts | 3 +- src/server/registerSessionTools.ts | 94 +++--- .../cli/evidenceBundleCommands.test.ts | 21 ++ .../filesystem/analysisSnapshot.test.ts | 56 +++- .../filesystem/evidenceBundleFiles.test.ts | 50 ++- .../jsonFileResourceOwnership.test.ts | 75 +++++ .../filesystem/processCliFileInput.test.ts | 195 +++++++++++- .../mcp/bundleComparisonCancellation.test.ts | 62 +--- .../boundary/mcp/bundleComparisonMcp.test.ts | 4 +- .../mcp/evidenceImportCancellation.test.ts | 119 ++++++++ tests/support/holdFirstFileRead.ts | 55 ++++ 32 files changed, 1007 insertions(+), 318 deletions(-) create mode 100644 tests/boundary/filesystem/jsonFileResourceOwnership.test.ts create mode 100644 tests/support/holdFirstFileRead.ts 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> => - 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> => 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> => { 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 = export const readJsonFile = async ( path: string, signal?: AbortSignal, + resources?: ArtifactResourceScope, ): Promise< Result > => 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[], 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 ( } 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[], signal?: AbortSignal, + resources?: ArtifactResourceScope, ): Promise> => 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> => 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 ( 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 ( 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, + ) => Result, ): Result { 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 { + ): Result { 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; +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; + importEvidenceBundle( + bundle: unknown, + ): Result; } 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 { + ): Result { 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 => { - const loaded = await readJsonFile(path); +const readJson = async ( + path: string, + operation: "capture_process_scenario" | "compare_process_captures", + signal?: AbortSignal, +): Promise => { + 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,81 +67,83 @@ 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 () => { - 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: "platform_binary_environment_withheld", - } - : { 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: "platform_binary_environment_withheld" }, - ], - }); - expect(signalGroup.mock.calls).toEqual([ - [100, "SIGKILL"], - [200, "SIGKILL"], - ]); - expect(signalGroup).not.toHaveBeenCalledWith(900, "SIGKILL"); - }); - it.each([ - "environment_unavailable", + "platform_binary_environment_withheld", "restricted_process_environment_withheld", - ])("fails closed for an unrelated candidate with %s", async (diagnostic) => { + ])( + "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" }, { @@ -207,75 +209,81 @@ describe("opaque process neighbors during cleanup", () => { }); 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, - }, - ]), - ), + it.each([ + "environment_unavailable", + "platform_binary_environment_withheld", + "restricted_process_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: + 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 }) => [ + 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(); - }, - ); + 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", () => { 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>, + 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((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((resolve) => { - resolveFirstRead = resolve; - }); - let releaseRead: (() => void) | undefined; - const readGate = new Promise((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((resolve) => { + resolveFirstRead = resolve; + }); + let releaseRead: (() => void) | undefined; + const readGate = new Promise((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; + }, + }; +};