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(filesystem): preserve digest failures through cleanup cancellation
morlutoe65c3955f92d
diff --git a/src/adb/AdbProvider.ts b/src/adb/AdbProvider.tsindex a19470c43..9fdca5941 100644--- a/src/adb/AdbProvider.ts+++ b/src/adb/AdbProvider.ts@@ -56,11 +56,16 @@ import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.import { err, ok, type Result } from "../domain/result.js";import type { JsonValue } from "../domain/jsonValue.js";import { jsonObjectSchema } from "../domain/jsonValue.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";import {+ hashStableFile,+ stableFileHashCause,+} from "../filesystem/StableFileHash.js";+import {+ regularFileCancellation,RegularFileCancelled,RegularFileCleanupFailure,} from "../filesystem/OwnedRegularFile.js";+import { RegularFileOperationCancelled } from "../filesystem/RegularFile.js";import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";import { createEvidence } from "../domain/evidence.js";import {@@ -182,9 +187,8 @@ const hashAdbFile = async (});} catch (cause: unknown) {if (- cause !== signal?.reason &&- (cause instanceof RegularFileCleanupFailure ||- cause instanceof RegularFileCancelled)+ cause instanceof RegularFileCleanupFailure ||+ cause instanceof RegularFileCancelled)throw new AdbDigestFailure(cause as@@ -194,8 +198,8 @@ const hashAdbFile = async (closeLease?.bindCleanupError(error);},);- if (signal?.aborted === true)- throw new AnalysisCancelledError(operation, { cause });+ if (cause instanceof RegularFileOperationCancelled)+ throw new AnalysisCancelledError(operation, { cause: cause.reason });throw cause;}};@@ -203,7 +207,6 @@ const hashAdbFile = async (const adbDigestError = (cause: unknown,operation: string,- signal: AbortSignal | undefined,partialObservation:| AdbAcquiredFilePartialObservation| AdbPackagePullPartialObservation,@@ -238,12 +241,10 @@ const adbDigestError = ();const primaryCause =digestOutcome.kind === "failed" ? digestOutcome.cause : undefined;- if (- signal?.aborted === true ||- primaryCause instanceof AnalysisCancelledError- ) {+ const cancellation = regularFileCancellation(digestFailure);+ if (cancellation !== undefined) {const error = new AnalysisCancelledError(operation, {- cause: digestFailure,+ cause: cancellation.reason,cleanup: { reason, resources: [resource] },partialObservation,});@@ -258,7 +259,8 @@ const adbDigestError = (operation,`The pulled file could not be fully digested or its handle could not be closed: ${digestFailure.path}`,{- cause: primaryCause ?? digestFailure,+ cause:+ digestOutcome.kind === "failed" ? primaryCause : digestFailure,partialObservation,},);@@ -2085,7 +2087,14 @@ export class AdbProvider {device_path: string | null;stage: "resolve_paths" | "pull" | "digest";message: string;+ cause: unknown;}[] = [];+ const observedFailures = () =>+ failures.map(({ device_path, stage, message }) => ({+ device_path,+ stage,+ message,+ }));const cancelledPackagePull = (error: AnalysisCancelledError,localPath: string,@@ -2102,7 +2111,7 @@ export class AdbProvider {output_directory: directory.value,artifacts,failures: [- ...failures,+ ...observedFailures(),{device_path: devicePath,stage,@@ -2139,6 +2148,7 @@ export class AdbProvider {device_path: entry.device_path,stage: "pull",message: pulled.error.message,+ cause: pulled.error,});continue;}@@ -2189,7 +2199,7 @@ export class AdbProvider {},],failures: [- ...failures,+ ...observedFailures(),{device_path: entry.device_path,stage: "digest",@@ -2207,7 +2217,6 @@ export class AdbProvider {const cleanupError = adbDigestError(cause,operation,- signal,partialObservation,);if (cleanupError !== undefined) return err(cleanupError);@@ -2218,16 +2227,24 @@ export class AdbProvider {entry.device_path,"digest",);+ const physicalCause = stableFileHashCause(cause);failures.push({device_path: entry.device_path,stage: "digest",- message: `The pulled file could not be read back after pulling: ${localPath}`,+ message: `The pulled file could not be read back after pulling: ${localPath}: ${physicalCause instanceof Error ? physicalCause.message : String(physicalCause)}`,+ cause,});}}if (artifacts.length === 0 && failures.length > 0) {const primary = new AnalysisProtocolError(`Every APK pull failed for ${packageName} on ${serial}: ${failures[0]!.message}`,+ {+ cause: new AggregateError(+ failures.map(({ cause }) => cause),+ "APK pulls failed",+ ),+ },);return failOwnedPackage(primary);}@@ -2239,7 +2256,7 @@ export class AdbProvider {package_name: packageName,output_directory: directory.value,artifacts,- failures,+ failures: observedFailures(),coverage: failures.length === 0 ? "complete" : "partial",},provider,@@ -2330,12 +2347,7 @@ export class AdbProvider {digest_status: "unknown",},};- const cleanupError = adbDigestError(- cause,- operation,- signal,- partialObservation,- );+ const cleanupError = adbDigestError(cause, operation, partialObservation);if (cleanupError !== undefined) return err(cleanupError);if (cause instanceof AnalysisCancelledError) {cause.retainPartialObservation(partialObservation);@@ -3145,7 +3157,7 @@ export class AdbProvider {const cleanupError =retainedObservation === undefined? undefined- : adbDigestError(cause, operation, signal, retainedObservation);+ : adbDigestError(cause, operation, retainedObservation);if (cleanupError !== undefined) return err(cleanupError);if (cause instanceof AnalysisCancelledError) {if (retainedObservation !== undefined)diff --git a/src/android/AndroidTargetSnapshot.ts b/src/android/AndroidTargetSnapshot.tsindex f49f65f9c..1801768c6 100644--- a/src/android/AndroidTargetSnapshot.ts+++ b/src/android/AndroidTargetSnapshot.ts@@ -10,6 +10,7 @@ import {} from "../domain/analysisErrorCore.js";import {openRegularFile,+ assertRegularFileActive,sameRegularFileState,} from "../filesystem/RegularFile.js";import type { AndroidOperation } from "../domain/android/androidAnalysis.js";@@ -25,7 +26,7 @@ export const snapshotAndroidTarget = async (const snapshot = join(root, "target.apk");try {await copyAndroidSnapshot(path, snapshot, sha256, signal);- signal?.throwIfAborted();+ assertRegularFileActive(signal);await chmod(snapshot, 0o400);return snapshot;} catch (cause: unknown) {@@ -51,7 +52,7 @@ export const snapshotAndroidEngine = async (const path = join(root, "engine.jar");try {const observed = await copyAndroidSnapshot(source, path, sha256, signal);- signal?.throwIfAborted();+ assertRegularFileActive(signal);await chmod(path, 0o400);return { path, sha256: observed };} catch (cause: unknown) {@@ -71,7 +72,7 @@ const copyAndroidSnapshot = async (expectedSha256: string,signal?: AbortSignal,): Promise<string> => {- signal?.throwIfAborted();+ assertRegularFileActive(signal);const source = await openRegularFile(sourcePath, {symlinks: "follow",signal,@@ -84,7 +85,7 @@ const copyAndroidSnapshot = async (const hash = createHash("sha256");try {const initial = await source.stat();- signal?.throwIfAborted();+ assertRegularFileActive(signal);const digest = new Transform({transform(chunk: Buffer,@@ -106,7 +107,7 @@ const copyAndroidSnapshot = async (});try {destination = await open(snapshotPath, "wx", 0o600);- signal?.throwIfAborted();+ assertRegularFileActive(signal);inputStream = source.createReadStream({start: 0,end: initial.size,@@ -114,7 +115,7 @@ const copyAndroidSnapshot = async (});outputStream = destination.createWriteStream({ autoClose: false });await pipeline(inputStream, digest, outputStream, { signal });- signal?.throwIfAborted();+ assertRegularFileActive(signal);await verifySourceState(source, sourcePath, initial, copiedBytes);const observedSha256 = hash.digest("hex");if (observedSha256 !== expectedSha256)diff --git a/src/android/JadxProvider.ts b/src/android/JadxProvider.tsindex 8fb456c64..074a218bf 100644--- a/src/android/JadxProvider.ts+++ b/src/android/JadxProvider.ts@@ -27,10 +27,17 @@ import {snapshotAndroidEngine,snapshotAndroidTarget,} from "./AndroidTargetSnapshot.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";+import {+ hashStableFile,+ stableFileHashCause,+ StableFileHashFailure,+} from "../filesystem/StableFileHash.js";import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";import { RegularFileChangedError } from "../filesystem/RegularFile.js";-import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";+import {+ RegularFileCleanupFailure,+ regularFileCancellation,+} from "../filesystem/OwnedRegularFile.js";import {inspectJadxAvailability,resolveJadxConfigurationInputs,@@ -70,35 +77,33 @@ const executionError = (context: {session: JadxSession | undefined;}): AnalysisError => {const { cause, request, timeout, timeoutMs, signal, session } = context;+ const cancellation = regularFileCancellation(cause);+ const cancellationError =+ cancellation === undefined+ ? undefined+ : timeout.aborted && cancellation.reason === timeout.reason+ ? new AnalysisTimeoutError(request.operation, timeoutMs, {+ cause: cancellation.reason,+ })+ : new AnalysisCancelledError(request.operation, {+ cause: cancellation.reason,+ });if (cause instanceof RegularFileCleanupFailure) {const primaryCause =cause.outcome.kind === "failed"- ? cause.outcome.cause- : signal?.aborted- ? signal.reason- : timeout.aborted- ? timeout.reason- : undefined;- const primaryOptions =- primaryCause === undefined ? {} : { cause: primaryCause };+ ? stableFileHashCause(cause.outcome.cause)+ : cause;const primary =- signal?.aborted === true- ? new AnalysisCancelledError(request.operation, primaryOptions)- : timeout.aborted- ? new AnalysisTimeoutError(- request.operation,- timeoutMs,- primaryOptions,- )- : primaryCause instanceof AnalysisError- ? primaryCause- : new ProviderAdapterError("jadx", request.operation, {- cause: primaryCause ?? cause,- userMessage:- primaryCause instanceof Error- ? primaryCause.message- : cause.message,- });+ cancellationError ??+ (primaryCause instanceof AnalysisError+ ? primaryCause+ : new ProviderAdapterError("jadx", request.operation, {+ cause: primaryCause,+ userMessage:+ primaryCause instanceof Error+ ? primaryCause.message+ : String(primaryCause),+ }));const cleanup = new ProviderCleanupError("jadx",[cause.path],@@ -112,11 +117,17 @@ const executionError = (context: {);return analysisErrorWithCleanupFailure(primary, cleanup, request.operation);}+ if (cancellationError !== undefined) return cancellationError;+ if (cause instanceof StableFileHashFailure)+ return new ProviderAdapterError("jadx", request.operation, {+ cause: cause.cause,+ userMessage: cause.message,+ });+ if (cause instanceof AnalysisError) return cause;if (signal?.aborted === true)return new AnalysisCancelledError(request.operation, { cause });if (timeout.aborted)return new AnalysisTimeoutError(request.operation, timeoutMs);- if (cause instanceof AnalysisError) return cause;const protocolFailure = session?.transport.failureReason();if (protocolFailure !== undefined && protocolFailure !== null)return new AnalysisOutputError(request.operation, protocolFailure, {@@ -193,9 +204,9 @@ const hashAndroidSource = async (try {return (await hashStableFile(path, { signal, retainFailedClose })).sha256;} catch (cause: unknown) {- if (signal.aborted) throw cause;- if (cause instanceof RegularFileChangedError)- throw androidSourceChanged(operation, path, cause);+ const physical = stableFileHashCause(cause);+ if (physical instanceof RegularFileChangedError)+ throw androidSourceChanged(operation, path, physical);throw cause;}};diff --git a/src/apktool/ApktoolProvider.ts b/src/apktool/ApktoolProvider.tsindex 2fa61fe5f..1c33d515a 100644--- a/src/apktool/ApktoolProvider.ts+++ b/src/apktool/ApktoolProvider.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";import { createHash, randomUUID } from "node:crypto";import { createWriteStream } from "node:fs";import {@@ -846,6 +847,15 @@ export class ApktoolProvider {);} catch (cause) {await removeWorkspace();+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ return err(+ failureWithCleanup(+ new AnalysisCancelledError(operation, {+ cause: cancellation.reason,+ }),+ ),+ );return err(failureWithCleanup(signal?.aborted === truediff --git a/src/application/BinaryTargetResolver.ts b/src/application/BinaryTargetResolver.tsindex 1e206801b..d0d869ba0 100644--- a/src/application/BinaryTargetResolver.ts+++ b/src/application/BinaryTargetResolver.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";import { constants, type Stats } from "node:fs";import { createHash } from "node:crypto";import {@@ -224,6 +225,13 @@ export const parseBinaryTarget = async (}} catch (cause: unknown) {if (cause instanceof AnalysisCancelledError) return err(cause);+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ return err(+ new AnalysisCancelledError("resolve_binary_target", {+ cause: cancellation.reason,+ }),+ );if (signal?.aborted === true && cause === signal.reason)return err(new AnalysisCancelledError("resolve_binary_target", { cause }),diff --git a/src/application/LinuxHopperPublisher.ts b/src/application/LinuxHopperPublisher.tsindex 7fa308588..8acbefec9 100644--- a/src/application/LinuxHopperPublisher.ts+++ b/src/application/LinuxHopperPublisher.ts@@ -10,9 +10,16 @@ import {import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";import { err, ok, type Result } from "../domain/result.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";+import {+ hashStableFile,+ StableFileHashFailure,+} from "../filesystem/StableFileHash.js";import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";-import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";+import {+ RegularFileCleanupFailure,+ RegularFileCancelled,+ regularFileCancellation,+} from "../filesystem/OwnedRegularFile.js";import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";import { verifyDetachedPgpSignature } from "../process/DetachedPgpSignature.js";import { execFileOutput } from "../process/ExecFileOutput.js";@@ -705,8 +712,17 @@ export class LinuxHopperPublisher {},);}- if (hashFailure.outcome.kind === "failed")- throw hashFailure.outcome.cause;+ if (hashFailure.outcome.kind === "failed") {+ if (regularFileCancellation(hashFailure) !== undefined)+ throw hashFailure.outcome.cause;+ throw new StableFileHashFailure(path, hashFailure.outcome.cause);+ }+ const cancellation = regularFileCancellation(hashFailure);+ if (cancellation !== undefined)+ throw new RegularFileCancelled(path, hashFailure.owner, {+ outcome: hashFailure.outcome,+ reason: cancellation.reason,+ });return hashFailure.outcome.value;}}@@ -1084,21 +1100,26 @@ const releaseFailure = (signal: AbortSignal | undefined,fallback: HopperReleaseError["reason"],): HopperReleaseError => {- if (cause instanceof HopperReleaseError && cause.reason === "cleanup_failed")- return cause;+ if (cause instanceof HopperReleaseError) return cause;if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)return new HopperReleaseError("cleanup_failed","Hopper publisher cleanup remains incomplete.",{ cause },);- if (signal?.aborted === true)+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ return new HopperReleaseError(+ "cancelled",+ "Hopper publisher verification was cancelled.",+ { cause: cancellation.reason },+ );+ if (!(cause instanceof StableFileHashFailure) && signal?.aborted === true)return new HopperReleaseError("cancelled","Hopper publisher verification was cancelled.",{ cause },);- if (cause instanceof HopperReleaseError) return cause;return new HopperReleaseError(fallback,"Hopper publisher verification could not complete.",diff --git a/src/application/ReferenceSourceImportPolicy.ts b/src/application/ReferenceSourceImportPolicy.tsindex 547e57cd3..30e683e0c 100644--- a/src/application/ReferenceSourceImportPolicy.ts+++ b/src/application/ReferenceSourceImportPolicy.ts@@ -112,8 +112,8 @@ const buildIgnored = async (const retry = await retryRegularFileCleanup(cause, resources);if (retry.cleanup !== undefined) {const primary =- cause.outcome.kind === "failed"- ? cause.outcome.cause+ retry.outcome.kind === "failed"+ ? retry.outcome.cause: cause.cleanupCause;return err({...failure(diff --git a/src/application/RegularFileRead.ts b/src/application/RegularFileRead.tsindex 4d26e2ca5..ca420a2b7 100644--- a/src/application/RegularFileRead.ts+++ b/src/application/RegularFileRead.ts@@ -4,6 +4,8 @@ import { lstat, stat, type FileHandle } from "node:fs/promises";import {sameRegularFileState,RegularFileChangedError,+ RegularFileOperationCancelled,+ assertRegularFileActive,} from "../filesystem/RegularFile.js";import {RegularFileCleanupFailure,@@ -45,14 +47,19 @@ export const retryRegularFileCleanup = async <Value>(readonly outcome: RegularFileReadOutcome<Value>;readonly cleanup?: AnalysisCleanupObservation;}> => {+ const outcome: RegularFileReadOutcome<Value> =+ failure.outcome.kind === "failed" &&+ failure.outcome.cause instanceof RegularFileOperationCancelled+ ? { kind: "failed", cause: failure.outcome.cause.reason }+ : failure.outcome;const released = await resources.release({kind: "file-handle",handle: failure.owner,resource: failure.path,});- if (released.kind === "released") return { outcome: failure.outcome };+ if (released.kind === "released") return { outcome };return {- outcome: failure.outcome,+ outcome,cleanup: {reason: `${failureMessage(failure.cleanupCause)}; retry: ${failureMessage(released.cause)}`,resources: [failure.path],@@ -82,9 +89,9 @@ export const withRegularFile = async <Value>(async (handle) => {admitted = handle;const stats = await handle.stat();- signal?.throwIfAborted();+ assertRegularFileActive(signal);const value = await read(handle, stats);- signal?.throwIfAborted();+ assertRegularFileActive(signal);const [opened, currentPath] = await Promise.all([handle.stat(),options.symlinks === "reject" ? lstat(path) : stat(path),@@ -94,11 +101,12 @@ export const withRegularFile = async <Value>(!sameRegularFileState(stats, currentPath))throw new RegularFileChangedError(path);+ assertRegularFileActive(signal);return value;},);} catch (cause: unknown) {- if (signal?.aborted === true && cause === signal.reason) throw cause;+ if (cause instanceof RegularFileOperationCancelled) throw cause.reason;if (cause instanceof RegularFileCancelled &&cause.owner.handle === admitteddiff --git a/src/application/SetupClientConfiguration.ts b/src/application/SetupClientConfiguration.tsindex 43b90e344..44a73c804 100644--- a/src/application/SetupClientConfiguration.ts+++ b/src/application/SetupClientConfiguration.ts@@ -74,6 +74,8 @@ export class ClientConfigurationCleanupRollbackFailure extends RegularFileCleanu[failure.cleanupCause, new Error(configurationFailure.failure.detail)],`Configuration readback cleanup and rollback failed: ${configurationFailure.failure.path}`,),+ failure.retention,+ failure.completionCancellation,);}}diff --git a/src/application/WebScriptExportService.ts b/src/application/WebScriptExportService.tsindex 1fbb419d7..a792706c2 100644--- a/src/application/WebScriptExportService.ts+++ b/src/application/WebScriptExportService.ts@@ -243,11 +243,11 @@ const readCapture = async (incomplete: retry.cleanup !== undefined,cause: cause.cleanupCause,};- if (cause.outcome.kind === "completed")- return ok({ bytes: cause.outcome.value as Buffer, cleanup });+ if (retry.outcome.kind === "completed")+ return ok({ bytes: retry.outcome.value as Buffer, cleanup });const primary = captureReadFailure(path,- cause.outcome.cause,+ retry.outcome.cause,signal,retry.cleanup === undefined ? { cause: cause.cleanupCause } : undefined,);diff --git a/src/artifacts/ArtifactFileOperation.ts b/src/artifacts/ArtifactFileOperation.tsindex dbed70192..a7d49754e 100644--- a/src/artifacts/ArtifactFileOperation.ts+++ b/src/artifacts/ArtifactFileOperation.ts@@ -1,4 +1,5 @@import type { FileHandle } from "node:fs/promises";+import { RegularFileOperationCancelled } from "../filesystem/RegularFile.js";import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";import {withOwnedFileHandle,@@ -22,11 +23,25 @@ export class ArtifactFileCleanupFailure<Value = unknown,> extends ArtifactReaderFailure {readonly cleanupLeases: readonly AnalysisCleanupLease[] | undefined;+ readonly fileCleanupFailure: RegularFileCleanupFailure<Value>;constructor(- readonly fileCleanupFailure: RegularFileCleanupFailure<Value>,+ fileCleanupFailure: RegularFileCleanupFailure<Value>,readonly cleanupLease: AnalysisCleanupLease,- readonly completionCancellation?: { readonly reason: unknown },) {+ const outcome = fileCleanupFailure.outcome;+ if (+ outcome.kind === "failed" &&+ outcome.cause instanceof RegularFileOperationCancelled+ )+ fileCleanupFailure = new RegularFileCleanupFailure(+ fileCleanupFailure.path,+ fileCleanupFailure.owner,+ { kind: "failed", cause: artifactOperationCause(outcome.cause) },+ fileCleanupFailure.cleanupCause,+ fileCleanupFailure.retention,+ fileCleanupFailure.completionCancellation,+ );+ const completionCancellation = fileCleanupFailure.completionCancellation;const primary =fileCleanupFailure.outcome.kind === "failed"? fileCleanupFailure.outcome.cause@@ -60,6 +75,7 @@ export class ArtifactFileCleanupFailure<},projected.details,);+ this.fileCleanupFailure = fileCleanupFailure;const inherited =primary instanceof ArtifactFileCleanupFailure ||primary instanceof ArtifactResourceRetryFailure@@ -95,9 +111,9 @@ export const mapArtifactFileFailure = ({ kind: "failed", cause: primary },physical.cleanupCause,physical.retention,+ physical.completionCancellation,),cause.cleanupLease,- cause.completionCancellation,);};@@ -175,6 +191,7 @@ export const withArtifactRegularFile = async <Value>(path,{symlinks,+ ...(signal === undefined ? {} : { signal }),retainFailedClose: (owner) => {cleanupLease = new AnalysisCleanupLease(() => owner.close(), [path]);resources.retain({@@ -189,23 +206,16 @@ export const withArtifactRegularFile = async <Value>(return await operation(file);},);- if (signal?.aborted)- throw new ArtifactFileCancelled({- reason: signal.reason,- outcome: { kind: "completed", value },- });return value;} catch (cause: unknown) {if (cause instanceof RegularFileCleanupFailure &&cleanupLease !== undefined)- throw new ArtifactFileCleanupFailure(- cause,- cleanupLease,- signal?.aborted ? { reason: signal.reason } : undefined,- );- throw cause;+ throw new ArtifactFileCleanupFailure(cause, cleanupLease);+ if (cause instanceof RegularFileCancelled)+ throw new ArtifactFileCancelled(cause);+ throw artifactOperationCause(cause);}};@@ -236,13 +246,18 @@ export const withArtifactFileHandle = async <Value>();} catch (cause: unknown) {if (cause instanceof RegularFileCleanupFailure)- throw new ArtifactFileCleanupFailure(- cause,- cleanupLease,- signal?.aborted ? { reason: signal.reason } : undefined,- );+ throw new ArtifactFileCleanupFailure(cause, cleanupLease);if (cause instanceof RegularFileCancelled)throw new ArtifactFileCancelled(cause);- throw cause;+ throw artifactOperationCause(cause);}};++const artifactOperationCause = (cause: unknown): unknown =>+ cause instanceof RegularFileOperationCancelled+ ? new ArtifactReaderFailure(+ "cancelled",+ "Artifact file operation cancelled",+ { cause: cause.reason },+ )+ : cause;diff --git a/src/artifacts/NativeDmgArtifactReader.ts b/src/artifacts/NativeDmgArtifactReader.tsindex d8636f4ae..3dd27a5fd 100644--- a/src/artifacts/NativeDmgArtifactReader.ts+++ b/src/artifacts/NativeDmgArtifactReader.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";import { mkdtemp, realpath, rm, type FileHandle } from "node:fs/promises";import { tmpdir } from "node:os";import { basename, join } from "node:path";@@ -597,10 +598,11 @@ export class NativeDmgArtifactReader implements ArtifactReader {} catch (cause: unknown) {if (cause instanceof RegularFileAdmissionFailure) {this.#verificationProbeHandle = cause.owner;+ const cancellation = regularFileCancellation(cause.cause);const failure =- signal?.aborted === true- ? this.#cancelledVerification(signal.reason)- : primaryFailure;+ cancellation === undefined+ ? primaryFailure+ : this.#cancelledVerification(cancellation.reason);throw ArtifactReaderFailure.withCleanup(failure,ArtifactReaderFailure.cleanupObservation(@@ -609,8 +611,9 @@ export class NativeDmgArtifactReader implements ArtifactReader {),);}- if (signal?.aborted === true)- throw this.#cancelledVerification(signal.reason);+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ throw this.#cancelledVerification(cancellation.reason);if (cause instanceof NonRegularFileReadError) return false;return classifyCommandFailure(cause, undefined).reason === "io";}diff --git a/src/artifacts/RegularFileAdmission.test.ts b/src/artifacts/RegularFileAdmission.test.tsindex 97f61fc34..fe1d0fb37 100644--- a/src/artifacts/RegularFileAdmission.test.ts+++ b/src/artifacts/RegularFileAdmission.test.ts@@ -7,6 +7,7 @@ import {NonRegularFileReadError,openRegularFile,RegularFileAdmissionFailure,+ RegularFileOperationCancelled,sameRegularFileState,} from "../filesystem/RegularFile.js";@@ -65,7 +66,10 @@ it.each(["cancellation after open", "non-regular metadata", "stat failure"])(expect(cause.cause).toBeInstanceOf(NonRegularFileReadError);else if (failureCase === "stat failure")expect(cause.cause).toBe(statFailure);- else expect(cause.cause).toBe(cancellation);+ else {+ expect(cause.cause).toBeInstanceOf(RegularFileOperationCancelled);+ expect(cause.cause).toMatchObject({ reason: cancellation });+ }},);@@ -107,7 +111,7 @@ it.each([},);-it("keeps cancellation that arrives during the non-regular metadata probe", async () => {+it("preserves the non-regular admission failure when cancellation arrives during its metadata probe", async () => {const controller = new AbortController();const cancellation = new Error("cancelled during probe");mockOpen.mockImplementation(async () => {@@ -120,5 +124,5 @@ it("keeps cancellation that arrives during the non-regular metadata probe", asynsymlinks: "follow",signal: controller.signal,}),- ).rejects.toBe(cancellation);+ ).rejects.toBeInstanceOf(NonRegularFileReadError);});diff --git a/src/artifacts/inventory/hashStableRootArtifact.ts b/src/artifacts/inventory/hashStableRootArtifact.tsindex 0956771b0..cf57b804a 100644--- a/src/artifacts/inventory/hashStableRootArtifact.ts+++ b/src/artifacts/inventory/hashStableRootArtifact.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../../filesystem/OwnedRegularFile.js";import { lstat } from "node:fs/promises";import type { Stats } from "node:fs";import type { FileHandle } from "node:fs/promises";@@ -31,14 +32,21 @@ export const openRootArtifact = async (} catch (cause: unknown) {const primary =cause instanceof RegularFileAdmissionFailure ? cause.cause : cause;+ const cancellation = regularFileCancellation(primary);const failure =- primary instanceof NonRegularFileReadError+ cancellation !== undefined? new ArtifactReaderFailure(- "format",- `Artifact root is not a regular file: ${path}`,- { cause: primary },+ "cancelled",+ "Artifact admission cancelled",+ { cause: cancellation.reason },)- : primary;+ : primary instanceof NonRegularFileReadError+ ? new ArtifactReaderFailure(+ "format",+ `Artifact root is not a regular file: ${path}`,+ { cause: primary },+ )+ : primary;if (cause instanceof RegularFileAdmissionFailure) {const resource = `root artifact descriptor for ${path}`;const cleanup = await resourceScope.release({diff --git a/src/cutter/CutterBridgeClient.ts b/src/cutter/CutterBridgeClient.tsindex 2074ba659..dc821745d 100644--- a/src/cutter/CutterBridgeClient.ts+++ b/src/cutter/CutterBridgeClient.ts@@ -1049,9 +1049,9 @@ const descriptorFailure = (? descriptorFailure(outcome.cause, operation): outcome?.kind === "completed" &&cause instanceof ArtifactFileCleanupFailure &&- cause.completionCancellation !== undefined+ cause.fileCleanupFailure.completionCancellation !== undefined? new AnalysisCancelledError(operation, {- cause: cause.completionCancellation.reason,+ cause: cause.fileCleanupFailure.completionCancellation.reason,}): undefined;if (primary === undefined && outcome?.kind !== "failed") return cleanup;diff --git a/src/electron/ElectronFuseProvider.ts b/src/electron/ElectronFuseProvider.tsindex d05baff43..af3a29bb6 100644--- a/src/electron/ElectronFuseProvider.ts+++ b/src/electron/ElectronFuseProvider.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";import type { ExecutionOptions } from "../application/AnalysisProvider.js";import type { ElectronFusePort } from "../application/electron/ElectronFusePort.js";import { AnalysisError } from "../domain/analysisErrorBase.js";@@ -93,7 +94,13 @@ const failureFor = (signal?: AbortSignal,): AnalysisError => {if (cause instanceof AnalysisError) return cause;- if (signal?.aborted) return new AnalysisCancelledError(OPERATION);+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ return new AnalysisCancelledError(OPERATION, {+ cause: cancellation.reason,+ });+ if (signal?.aborted)+ return new AnalysisCancelledError(OPERATION, { cause: signal.reason });if (cause instanceof ElectronFusePathFailure)return new AnalysisInputError(OPERATION, { cause }, [{ path: ["path"], reason: cause.reason, message: cause.message },diff --git a/src/filesystem/OwnedRegularFile.ts b/src/filesystem/OwnedRegularFile.tsindex f79978e02..aad2d1c1f 100644--- a/src/filesystem/OwnedRegularFile.ts+++ b/src/filesystem/OwnedRegularFile.ts@@ -1,7 +1,12 @@import type { FileHandle } from "node:fs/promises";import { OwnedFileHandle } from "./OwnedFileHandle.js";-import { openRegularFile, RegularFileAdmissionFailure } from "./RegularFile.js";+import {+ openRegularFile,+ RegularFileAdmissionFailure,+ assertRegularFileActive,+ RegularFileOperationCancelled,+} from "./RegularFile.js";export type RegularFileOperationOutcome<Value> =| { readonly kind: "completed"; readonly value: Value }@@ -48,6 +53,7 @@ export class RegularFileCleanupFailure<Value = unknown> extends Error {| { readonly kind: "callback_threw"; readonly cause: unknown } = {kind: "not_requested",},+ readonly completionCancellation?: { readonly reason: unknown },) {super(`Regular file cleanup failed for ${path}`, {cause: new AggregateError(@@ -68,6 +74,26 @@ export interface OwnedFileOperationOptions {readonly retainFailedClose?: (owner: OwnedFileHandle) => void;}+/** Read only cancellation facts recorded by the operation or its final close. */+export const regularFileCancellation = (+ cause: unknown,+): { readonly reason: unknown } | undefined => {+ const primary =+ cause instanceof RegularFileCleanupFailure &&+ cause.outcome.kind === "failed"+ ? cause.outcome.cause+ : cause;+ if (+ primary instanceof RegularFileOperationCancelled ||+ primary instanceof RegularFileCancelled+ )+ return { reason: primary.reason };+ return cause instanceof RegularFileCleanupFailure &&+ cause.outcome.kind === "completed"+ ? cause.completionCancellation+ : undefined;+};+export interface OwnedRegularFileOptions extends OwnedFileOperationOptions {readonly symlinks?: "follow" | "reject";}@@ -110,6 +136,7 @@ export const withOwnedFileHandle = async <Value>(const handle = owner.handle;let outcome: RegularFileOperationOutcome<Value>;try {+ assertRegularFileActive(options.signal);outcome = { kind: "completed", value: await operation(handle) };} catch (cause: unknown) {outcome = { kind: "failed", cause };@@ -117,6 +144,10 @@ export const withOwnedFileHandle = async <Value>(try {await owner.close();} catch (cleanupCause: unknown) {+ const completionCancellation =+ outcome.kind === "completed" && options.signal?.aborted === true+ ? { reason: options.signal.reason }+ : undefined;// Retain the physical read outcome even if the caller cancelled during// close: consumers may need completed observations such as a file digest.throw new RegularFileCleanupFailure(@@ -125,6 +156,7 @@ export const withOwnedFileHandle = async <Value>(outcome,cleanupCause,retainOwner(options.retainFailedClose, owner),+ completionCancellation,);}if (outcome.kind === "failed") throw outcome.cause;diff --git a/src/filesystem/RegularFile.ts b/src/filesystem/RegularFile.tsindex 47fdfa1d8..8b83f936a 100644--- a/src/filesystem/RegularFile.ts+++ b/src/filesystem/RegularFile.ts@@ -5,6 +5,20 @@ import { lstat, open, stat, type FileHandle } from "node:fs/promises";import { OwnedFileHandle } from "./OwnedFileHandle.js";+/** Cancellation observed at a file operation's explicit checkpoint. */+export class RegularFileOperationCancelled extends Error {+ readonly _tag = "RegularFileOperationCancelled";+ constructor(readonly reason: unknown) {+ super("Regular file operation cancelled", { cause: reason });+ this.name = this._tag;+ }+}++export const assertRegularFileActive = (signal?: AbortSignal): void => {+ if (signal?.aborted === true)+ throw new RegularFileOperationCancelled(signal.reason);+};+/** Identifies a selected path that cannot be read as one regular file. */export class NonRegularFileReadError extends Error {readonly code: "EISDIR" | "ENOTFILE";@@ -60,7 +74,7 @@ export const openRegularFile = async (readonly signal?: AbortSignal | undefined;},): Promise<FileHandle> => {- options.signal?.throwIfAborted();+ assertRegularFileActive(options.signal);const handle = await open(path,constants.O_RDONLY |@@ -74,26 +88,24 @@ export const openRegularFile = async (cause,);if (nonRegular === undefined) throw cause;- // Cancellation during the metadata probe outranks the reclassification.- options.signal?.throwIfAborted();throw nonRegular;});const owner = new OwnedFileHandle(handle);try {- options.signal?.throwIfAborted();+ assertRegularFileActive(options.signal);const metadata = await handle.stat();- options.signal?.throwIfAborted();if (!metadata.isFile())throw new NonRegularFileReadError(path, metadata.isDirectory());+ assertRegularFileActive(options.signal);// O_NOFOLLOW is unavailable on Windows. Recheck the name only on hosts// where open could have followed a symlink, while the descriptor is owned.if (options.symlinks === "reject" && (constants.O_NOFOLLOW ?? 0) === 0) {const named = await lstat(path);- options.signal?.throwIfAborted();if (named.isSymbolicLink())throw new NonRegularFileReadError(path, false);if (!sameRegularFileState(metadata, named))throw new RegularFileChangedError(path);+ assertRegularFileActive(options.signal);}return handle;} catch (cause: unknown) {diff --git a/src/filesystem/StableFileHash.ts b/src/filesystem/StableFileHash.tsindex 657020efa..890de4d9c 100644--- a/src/filesystem/StableFileHash.ts+++ b/src/filesystem/StableFileHash.ts@@ -1,9 +1,15 @@import { createHash } from "node:crypto";import { stat } from "node:fs/promises";-import { withOwnedRegularFile } from "./OwnedRegularFile.js";+import {+ withOwnedRegularFile,+ RegularFileCancelled,+ RegularFileCleanupFailure,+} from "./OwnedRegularFile.js";import {RegularFileChangedError,+ RegularFileOperationCancelled,+ assertRegularFileActive,sameRegularFileState,} from "./RegularFile.js";import type { OwnedFileHandle } from "./OwnedFileHandle.js";@@ -13,42 +19,76 @@ export interface StableFileHashOptions {readonly retainFailedClose: (owner: OwnedFileHandle) => void;}+/** Physical hash admission/read failure with no outstanding descriptor cleanup. */+export class StableFileHashFailure extends Error {+ readonly _tag = "StableFileHashFailure";+ constructor(+ readonly path: string,+ override readonly cause: unknown,+ ) {+ super(+ `Could not hash ${path}: ${cause instanceof Error ? cause.message : String(cause)}`,+ { cause },+ );+ this.name = this._tag;+ }+}++/** Read the producing boundary's physical failure without guessing from signal state. */+export const stableFileHashCause = (cause: unknown): unknown =>+ cause instanceof StableFileHashFailure ? cause.cause : cause;+/** Hash one regular file from its admitted descriptor and verify its path state. */export const hashStableFile = async (path: string,options: StableFileHashOptions,-): Promise<{ readonly sha256: string; readonly bytes: number }> =>- withOwnedRegularFile(path, options, async (handle) => {- const initial = await handle.stat();- if (!Number.isSafeInteger(initial.size) || initial.size < 0)- throw new RangeError(- `Regular file size cannot be represented safely: ${path}`,- );- const hash = createHash("sha256");- const chunk = Buffer.allocUnsafe(64 * 1024);- let position = 0;- while (position <= initial.size) {- options.signal?.throwIfAborted();- const length = Math.min(chunk.length, initial.size - position + 1);- if (length <= 0) break;- const read = await handle.read(chunk, 0, length, position);- options.signal?.throwIfAborted();- if (read.bytesRead === 0) break;- hash.update(chunk.subarray(0, read.bytesRead));- position += read.bytesRead;- if (position > initial.size) throw new RegularFileChangedError(path);- }- options.signal?.throwIfAborted();- const [opened, currentPath] = await Promise.all([- handle.stat(),- stat(path),- ]);- options.signal?.throwIfAborted();+): Promise<{ readonly sha256: string; readonly bytes: number }> => {+ try {+ return await withOwnedRegularFile(path, options, async (handle) => {+ const initial = await handle.stat();+ if (!Number.isSafeInteger(initial.size) || initial.size < 0)+ throw new RangeError(+ `Regular file size cannot be represented safely: ${path}`,+ );+ const hash = createHash("sha256");+ const chunk = Buffer.allocUnsafe(64 * 1024);+ let position = 0;+ while (position <= initial.size) {+ assertRegularFileActive(options.signal);+ const length = Math.min(chunk.length, initial.size - position + 1);+ if (length <= 0) break;+ const read = await handle.read(chunk, 0, length, position);+ if (+ position + read.bytesRead > initial.size ||+ (read.bytesRead === 0 && position < initial.size)+ )+ throw new RegularFileChangedError(path);+ assertRegularFileActive(options.signal);+ if (read.bytesRead === 0) break;+ hash.update(chunk.subarray(0, read.bytesRead));+ position += read.bytesRead;+ }+ assertRegularFileActive(options.signal);+ const [opened, currentPath] = await Promise.all([+ handle.stat(),+ stat(path),+ ]);+ if (+ position !== initial.size ||+ !sameRegularFileState(initial, opened) ||+ !sameRegularFileState(initial, currentPath)+ )+ throw new RegularFileChangedError(path);+ assertRegularFileActive(options.signal);+ return { sha256: hash.digest("hex"), bytes: position };+ });+ } catch (cause: unknown) {if (- position !== initial.size ||- !sameRegularFileState(initial, opened) ||- !sameRegularFileState(initial, currentPath)+ cause instanceof RegularFileCleanupFailure ||+ cause instanceof RegularFileCancelled ||+ cause instanceof RegularFileOperationCancelled)- throw new RegularFileChangedError(path);- return { sha256: hash.digest("hex"), bytes: position };- });+ throw cause;+ throw new StableFileHashFailure(path, cause);+ }+};diff --git a/src/firmware/FirmwareFailures.ts b/src/firmware/FirmwareFailures.tsindex 0cf56ddbc..4c8f0e795 100644--- a/src/firmware/FirmwareFailures.ts+++ b/src/firmware/FirmwareFailures.ts@@ -60,10 +60,10 @@ export const firmwareFailure = (deadline,treeCleanupLease,)- : cause.completionCancellation !== undefined+ : cause.fileCleanupFailure.completionCancellation !== undefined? firmwareCancellation(operation,- cause.completionCancellation.reason,+ cause.fileCleanupFailure.completionCancellation.reason,deadline,): undefined;diff --git a/src/flutter/FlutterBuildProvider.ts b/src/flutter/FlutterBuildProvider.tsindex 85924b5e7..11df7c013 100644--- a/src/flutter/FlutterBuildProvider.ts+++ b/src/flutter/FlutterBuildProvider.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";import { createHash } from "node:crypto";import { chmod, mkdtemp, open as openFile, rm, stat } from "node:fs/promises";import { createReadStream } from "node:fs";@@ -165,6 +166,11 @@ const mapInputFailure = (cause: unknown,): AnalysisError => {if (cause instanceof AnalysisError) return cause;+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ return new AnalysisCancelledError(operation, {+ cause: cancellation.reason,+ });if (isCancellation(cause))return new AnalysisCancelledError(operation, { cause });if (@@ -212,6 +218,11 @@ const mapOwnedIoFailure = (cause: unknown,): AnalysisError => {if (cause instanceof AnalysisError) return cause;+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ return new AnalysisCancelledError(operation, {+ cause: cancellation.reason,+ });if (isCancellation(cause))return new AnalysisCancelledError(operation, { cause });if (diff --git a/src/ghidra/GhidraClient.ts b/src/ghidra/GhidraClient.tsindex 460918599..2b4b62d70 100644--- a/src/ghidra/GhidraClient.ts+++ b/src/ghidra/GhidraClient.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";import { createHash, randomBytes, randomUUID } from "node:crypto";import type { Stats } from "node:fs";import type { FileHandle } from "node:fs/promises";@@ -64,6 +65,7 @@ import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";import {openRegularFile,+ assertRegularFileActive,RegularFileChangedError,RegularFileAdmissionFailure,sameRegularFileState,@@ -453,13 +455,13 @@ export class GhidraClient {let result: Result<T, unknown>;try {const initial = await handle.stat();- signal?.throwIfAborted();+ assertRegularFileActive(signal);if (!Number.isSafeInteger(initial.size) || initial.size < 0)throw new RangeError("Snapshot size must be a safe integer");const value = await read(handle, initial, path);- signal?.throwIfAborted();+ assertRegularFileActive(signal);const after = await handle.stat();- signal?.throwIfAborted();+ assertRegularFileActive(signal);if (!sameRegularFileState(initial, after))throw new RegularFileChangedError(path);result = ok(value);@@ -480,11 +482,20 @@ export class GhidraClient {} catch (cause: unknown) {if (cause instanceof RegularFileAdmissionFailure)this.#snapshotOwners.add(cause.owner);+ const primary =+ cause instanceof RegularFileAdmissionFailure ? cause.cause : cause;+ const cancellation = regularFileCancellation(primary);return err(this.#failure(- signal?.aborted === true ? "cancelled" : "protocol",+ cancellation !== undefined || signal?.aborted === true+ ? "cancelled"+ : "protocol","Ghidra target snapshot could not be read for load-image verification",- cause,+ cancellation === undefined ||+ cause instanceof RegularFileAdmissionFailure+ ? cause+ : cancellation.reason,+ cancellation === undefined ? {} : { cancellation },),);}diff --git a/src/javascript/recovery/RecoveryFiles.ts b/src/javascript/recovery/RecoveryFiles.tsindex 6cea1b81b..545744f08 100644--- a/src/javascript/recovery/RecoveryFiles.ts+++ b/src/javascript/recovery/RecoveryFiles.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../../filesystem/OwnedRegularFile.js";import { createHash } from "node:crypto";import { lstat, mkdir, opendir, writeFile } from "node:fs/promises";import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";@@ -37,7 +38,11 @@ const scanRecoveryFile = async (// A descriptor whose close failed stays owned by its error, even when// cancellation was also requested.if (cause instanceof RegularFileAdmissionFailure) throw cause;- checkRecoveryCancellation(signal);+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ throw new AnalysisCancelledError(OPERATION, {+ cause: cancellation.reason,+ });if (cause instanceof NonRegularFileReadError)throw new AnalysisOutputError(OPERATION,diff --git a/src/kuna/KunaCommand.ts b/src/kuna/KunaCommand.tsindex b4f98dda6..cdc996322 100644--- a/src/kuna/KunaCommand.ts+++ b/src/kuna/KunaCommand.ts@@ -19,7 +19,10 @@ import {} from "../process/OwnedCommand.js";import { hashStableFile } from "../filesystem/StableFileHash.js";import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";-import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";+import {+ RegularFileCleanupFailure,+ regularFileCancellation,+} from "../filesystem/OwnedRegularFile.js";import type {OwnedProviderProcessSpawnOptions,ProviderProcessSnapshot,@@ -92,7 +95,6 @@ const message = (cause: unknown): string =>export const kunaFileCleanupError = (failure: RegularFileCleanupFailure,operation: string,- signal?: AbortSignal,): AnalysisError => {const cleanup = new ProviderCleanupError(KUNA_PROVIDER_ID,@@ -100,33 +102,24 @@ export const kunaFileCleanupError = ({ reason: message(failure.cleanupCause) },{ cause: failure, operation },);- if (failure.outcome.kind === "completed") return cleanup;- const primaryCause = failure.outcome.cause;- const primary =- primaryCause instanceof AnalysisError- ? primaryCause- : signal?.aborted === true- ? new AnalysisCancelledError(operation, { cause: primaryCause })- : new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {- cause: primaryCause,- userMessage: `Kuna ${operation} failed: ${message(primaryCause)}`,- });- if (primary instanceof AnalysisCancelledError)+ const cancellation = regularFileCancellation(failure);+ if (cancellation !== undefined)return new AnalysisCancelledError(operation, {- cause: new AggregateError(- [primary, cleanup],- "Kuna operation was cancelled and descriptor cleanup failed",- { cause: primary },- ),+ cause: cancellation.reason,cleanup: {- reason: cleanup.message,+ reason: message(failure.cleanupCause),resources: [failure.path],},- ...(primary.capturedOutput === undefined- ? {}- : { capturedOutput: primary.capturedOutput }),- partialObservation: primary.partialObservation,});+ if (failure.outcome.kind === "completed") return cleanup;+ const primaryCause = failure.outcome.cause;+ const primary =+ primaryCause instanceof AnalysisError+ ? primaryCause+ : new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {+ cause: primaryCause,+ userMessage: `Kuna ${operation} failed: ${message(primaryCause)}`,+ });return analysisErrorWithCleanupFailure(primary, cleanup, operation);};@@ -194,18 +187,22 @@ export const runKunaCommand = async (if (cause instanceof RegularFileCleanupFailure) {return {kind: "failed",- error: kunaFileCleanupError(cause, request.operation, request.signal),+ error: kunaFileCleanupError(cause, request.operation),fileCleanupFailure: cause,};}+ const cancellation = regularFileCancellation(cause);return {kind: "failed",- error: request.signal.aborted- ? new AnalysisCancelledError(request.operation, { cause })- : new ProviderAdapterError(KUNA_PROVIDER_ID, request.operation, {- cause,- userMessage: `Cannot verify ${installation.executable}: ${message(cause)}`,- }),+ error:+ cancellation !== undefined+ ? new AnalysisCancelledError(request.operation, {+ cause: cancellation.reason,+ })+ : new ProviderAdapterError(KUNA_PROVIDER_ID, request.operation, {+ cause,+ userMessage: `Cannot verify ${installation.executable}: ${message(cause)}`,+ }),};}try {diff --git a/src/kuna/KunaInstallation.ts b/src/kuna/KunaInstallation.tsindex 66dc551de..af5580c1d 100644--- a/src/kuna/KunaInstallation.ts+++ b/src/kuna/KunaInstallation.ts@@ -1,3 +1,4 @@+import { assertRegularFileActive } from "../filesystem/RegularFile.js";import { constants } from "node:fs";import { access, realpath, stat } from "node:fs/promises";import { join } from "node:path";@@ -6,10 +7,14 @@ import type { JsonValue } from "../domain/jsonValue.js";import type { AnalysisError } from "../domain/analysisErrorBase.js";import { err, ok, type Result } from "../domain/result.js";import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";+import {+ hashStableFile,+ stableFileHashCause,+} from "../filesystem/StableFileHash.js";import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";import {RegularFileCleanupFailure,+ regularFileCancellation,withOwnedRegularFile,} from "../filesystem/OwnedRegularFile.js";import {@@ -149,7 +154,7 @@ export const inspectKunaInstallation = async ({ command },);} catch (cause: unknown) {- options.signal?.throwIfAborted();+ assertRegularFileActive(options.signal);return failure("executable_missing",`Cannot execute REA_KUNA_COMMAND ${command}: ${message(cause)}. ${KUNA_COMMAND_REMEDIATION}`,@@ -169,7 +174,7 @@ export const inspectKunaInstallation = async (...(options.signal === undefined ? {} : { signal: options.signal }),}));} catch (cause: unknown) {- options.signal?.throwIfAborted();+ assertRegularFileActive(options.signal);const output = execFileOutputFailure(cause);return failure("version_unresolved",@@ -207,16 +212,19 @@ export const inspectKunaInstallation = async (executable,options.fileCloseResources,);- options.signal?.throwIfAborted();+ assertRegularFileActive(options.signal);return { fingerprint, script };},));} catch (cause: unknown) {- if (cause instanceof RegularFileCleanupFailure) throw cause;- options.signal?.throwIfAborted();+ if (+ cause instanceof RegularFileCleanupFailure ||+ regularFileCancellation(cause) !== undefined+ )+ throw cause;return failure("executable_missing",- `Cannot fingerprint ${executable}: ${message(cause)}`,+ `Cannot fingerprint ${executable}: ${message(stableFileHashCause(cause))}`,{ command, executable },);}diff --git a/src/kuna/KunaProjectCache.ts b/src/kuna/KunaProjectCache.tsindex 9dc5a1789..f6319d5e4 100644--- a/src/kuna/KunaProjectCache.ts+++ b/src/kuna/KunaProjectCache.ts@@ -23,8 +23,14 @@ import {} from "../domain/analysisErrorCore.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { err, ok, type Result } from "../domain/result.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";-import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";+import {+ hashStableFile,+ stableFileHashCause,+} from "../filesystem/StableFileHash.js";+import {+ RegularFileCleanupFailure,+ regularFileCancellation,+} from "../filesystem/OwnedRegularFile.js";import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";import type { KunaInstallation } from "./KunaInstallation.js";import {@@ -350,8 +356,8 @@ export class KunaProjectCache {kunaExportFailure(cause, signal),cause,);- signal?.throwIfAborted();- if (!isDamaged(cause)) throw cause;+ if (regularFileCancellation(cause) !== undefined) throw cause;+ if (!isDamaged(stableFileHashCause(cause))) throw cause;await this.#discard(key);return undefined;}diff --git a/src/kuna/KunaProjectExport.ts b/src/kuna/KunaProjectExport.tsindex 5ca1cb135..273013822 100644--- a/src/kuna/KunaProjectExport.ts+++ b/src/kuna/KunaProjectExport.ts@@ -10,7 +10,10 @@ import {import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { err, ok, type Result } from "../domain/result.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";+import {+ hashStableFile,+ StableFileHashFailure,+} from "../filesystem/StableFileHash.js";import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";import { prepareProcessOwnershipInspection } from "../process/ProcessOwnershipObservation.js";import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js";@@ -32,7 +35,10 @@ import {type KunaProjectFunction,} from "./KunaProjectFiles.js";import { KUNA_PROVIDER_ID } from "./KunaRelease.js";-import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";+import {+ RegularFileCleanupFailure,+ regularFileCancellation,+} from "../filesystem/OwnedRegularFile.js";/** Operation name every export and cache failure reports. */export const KUNA_EXPORT_OPERATION = "kuna:decompile-project";@@ -125,10 +131,15 @@ export const kunaExportFailure = (signal: AbortSignal | undefined,): AnalysisError => {if (cause instanceof RegularFileCleanupFailure)- return kunaFileCleanupError(cause, KUNA_EXPORT_OPERATION, signal);- if (signal?.aborted === true)- return new AnalysisCancelledError(KUNA_EXPORT_OPERATION, { cause });+ return kunaFileCleanupError(cause, KUNA_EXPORT_OPERATION);+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ return new AnalysisCancelledError(KUNA_EXPORT_OPERATION, {+ cause: cancellation.reason,+ });if (cause instanceof AnalysisError) return cause;+ if (!(cause instanceof StableFileHashFailure) && signal?.aborted === true)+ return new AnalysisCancelledError(KUNA_EXPORT_OPERATION, { cause });return new ProviderAdapterError(KUNA_PROVIDER_ID, KUNA_EXPORT_OPERATION, {cause,userMessage: `Kuna project cache failed: ${message(cause)}`,diff --git a/src/kuna/KunaProvider.ts b/src/kuna/KunaProvider.tsindex 48f4d35c6..a66c5b7a4 100644--- a/src/kuna/KunaProvider.ts+++ b/src/kuna/KunaProvider.ts@@ -15,7 +15,10 @@ import {} from "../domain/analysisProfile.js";import type { BinaryTarget } from "../domain/binaryTargetTypes.js";import { err, ok } from "../domain/result.js";-import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";+import {+ RegularFileCleanupFailure,+ regularFileCancellation,+} from "../filesystem/OwnedRegularFile.js";import { snapshotEnvironment } from "../process/snapshotEnvironment.js";import {kunaFileCleanupError,@@ -168,7 +171,11 @@ export class KunaProvider implements AnalysisProviderCandidate {options?: AnalysisProfileResolutionOptions,) {if (options?.signal?.aborted === true)- return err(new AnalysisCancelledError("kuna:profile"));+ return err(+ new AnalysisCancelledError("kuna:profile", {+ cause: options.signal.reason,+ }),+ );let installation: Awaited<ReturnType<typeof inspectKunaInstallation>>;const fileCloseResources = options?.fileCloseResources;if (fileCloseResources === undefined)@@ -186,12 +193,18 @@ export class KunaProvider implements AnalysisProviderCandidate {fileCloseResources: fileCloseScope.owner,});} catch (cause: unknown) {+ const cancellation = regularFileCancellation(cause);+ if (+ !(cause instanceof RegularFileCleanupFailure) &&+ cancellation !== undefined+ )+ return err(+ new AnalysisCancelledError("kuna:profile", {+ cause: cancellation.reason,+ }),+ );if (!(cause instanceof RegularFileCleanupFailure)) throw cause;- const error = kunaFileCleanupError(- cause,- "kuna:profile",- options?.signal,- );+ const error = kunaFileCleanupError(cause, "kuna:profile");fileCloseScope.bindFailure(cause, error);return err(error);}diff --git a/src/kuna/KunaSessionClient.ts b/src/kuna/KunaSessionClient.tsindex ae8478459..0c281cbf3 100644--- a/src/kuna/KunaSessionClient.ts+++ b/src/kuna/KunaSessionClient.ts@@ -73,7 +73,10 @@ import {type KunaProjectFileSpan,} from "./KunaProjectReader.js";import { kunaUnavailable } from "./KunaUnavailable.js";-import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";+import {+ RegularFileCleanupFailure,+ regularFileCancellation,+} from "../filesystem/OwnedRegularFile.js";import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";@@ -1331,12 +1334,18 @@ export class KunaSessionClient implements AnalysisClient {);return ok(inspected.value);} catch (cause: unknown) {+ const cancellation = regularFileCancellation(cause);+ if (+ !(cause instanceof RegularFileCleanupFailure) &&+ cancellation !== undefined+ )+ return err(+ new AnalysisCancelledError("health", {+ cause: cancellation.reason,+ }),+ );if (!(cause instanceof RegularFileCleanupFailure)) throw cause;- const error = kunaFileCleanupError(- cause,- "health",- this.#session.signal,- );+ const error = kunaFileCleanupError(cause, "health");fileCloseScope.bindFailure(cause, error);return err(error);}diff --git a/src/native/NativeMacOSProvider.ts b/src/native/NativeMacOSProvider.tsindex 49b1b894a..8e7c938cf 100644--- a/src/native/NativeMacOSProvider.ts+++ b/src/native/NativeMacOSProvider.ts@@ -44,6 +44,7 @@ import { BinaryTargetError } from "../domain/configurationErrors.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { AnalysisError } from "../domain/analysisErrorBase.js";+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";import type { NativeUiObservationResult } from "../domain/native/nativeUiObservation.js";import {@@ -211,6 +212,13 @@ class NativeMacOSClient implements AnalysisClient {);} catch (cause) {if (cause instanceof AnalysisError) return err(cause);+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ return err(+ new AnalysisCancelledError(operation, {+ cause: cancellation.reason,+ }),+ );return err(options?.signal?.aborted? new AnalysisCancelledError(operation)diff --git a/src/pcap/PcapSnapshot.ts b/src/pcap/PcapSnapshot.tsindex 2e9082ccd..416198ccf 100644--- a/src/pcap/PcapSnapshot.ts+++ b/src/pcap/PcapSnapshot.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";import { createHash } from "node:crypto";import { chmod, open, stat, mkdir } from "node:fs/promises";import { join } from "node:path";@@ -72,6 +73,11 @@ export class PcapSnapshot {try {return await read();} catch (cause) {+ const cancellation = regularFileCancellation(cause);+ if (cancellation !== undefined)+ throw new AnalysisCancelledError(OPERATION, {+ cause: cancellation.reason,+ });if (signal?.aborted)throw new AnalysisCancelledError(OPERATION, { cause });if (cause instanceof AnalysisError) throw cause;@@ -186,9 +192,17 @@ export class PcapSnapshot {signal?.throwIfAborted();return { bytes: copied, sha256: hash.digest("hex") };} catch (cause) {- if (signal?.aborted)- throw new AnalysisCancelledError(OPERATION, { cause });+ if (cause instanceof RegularFileAdmissionFailure) this.own(cause.owner);+ const primary =+ cause instanceof RegularFileAdmissionFailure ? cause.cause : cause;+ const cancellation = regularFileCancellation(primary);+ if (cancellation !== undefined)+ throw new AnalysisCancelledError(OPERATION, {+ cause: cancellation.reason,+ });if (cause instanceof AnalysisError) throw cause;+ if (signal?.aborted)+ throw new AnalysisCancelledError(OPERATION, { cause: signal.reason });throw new AnalysisResourceConstraintError(OPERATION,"file-size",@@ -242,10 +256,17 @@ export class PcapSnapshot {);await this.release(file);} catch (cause) {- if (signal?.aborted)- throw new AnalysisCancelledError(OPERATION, { cause });if (cause instanceof RegularFileAdmissionFailure) this.own(cause.owner);+ const primary =+ cause instanceof RegularFileAdmissionFailure ? cause.cause : cause;+ const cancellation = regularFileCancellation(primary);+ if (cancellation !== undefined)+ throw new AnalysisCancelledError(OPERATION, {+ cause: cancellation.reason,+ });if (cause instanceof AnalysisError) throw cause;+ if (signal?.aborted)+ throw new AnalysisCancelledError(OPERATION, { cause: signal.reason });throw new AnalysisArtifactChangedError(OPERATION,selectedPath,diff --git a/src/reference/ReferenceSourceReaderFile.ts b/src/reference/ReferenceSourceReaderFile.tsindex e8cabdaeb..edef7a128 100644--- a/src/reference/ReferenceSourceReaderFile.ts+++ b/src/reference/ReferenceSourceReaderFile.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";import type { BigIntStats } from "node:fs";import type { FileHandle } from "node:fs/promises";import { dirname } from "node:path";@@ -278,7 +279,7 @@ const readStableFileEntry = async (retain(cause.owner);cause = cause.cause;}- if (isAborted(signal))+ if (regularFileCancellation(cause) !== undefined || isAborted(signal))return entryFailure(path,"file",diff --git a/tests/boundary/filesystem/regularFileCancellation.test.ts b/tests/boundary/filesystem/regularFileCancellation.test.tsindex 9a36a581e..456714c03 100644--- a/tests/boundary/filesystem/regularFileCancellation.test.ts+++ b/tests/boundary/filesystem/regularFileCancellation.test.ts@@ -3,7 +3,10 @@ import { open, readFile, writeFile } from "node:fs/promises";import { join } from "node:path";import { expect, it, vi } from "vitest";-import { withRegularFile } from "../../../src/application/RegularFileRead.js";+import {+ withRegularFile,+ retryRegularFileCleanup,+} from "../../../src/application/RegularFileRead.js";import { ArtifactResourceScope } from "../../../src/artifacts/ArtifactResourceScope.js";import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js";import {@@ -231,3 +234,53 @@ it.each(["completed", "failed"] as const)(expect(retained[0]?.handle.fd).toBe(-1);},);++it.each(+ [null, "caller stopped", new Error("caller stopped")].flatMap((reason) =>+ [false, true].map((retryFails) => ({ reason, retryFails })),+ ),+)(+ "projects the exact checkpoint reason after application cleanup retry fails=$retryFails ($reason)",+ async ({ reason, retryFails }) => {+ const root = await createTestTempDirectory("rea-file-retry-reason-");+ const path = join(root, "input.bin");+ await writeFile(path, "file bytes");+ const controller = new AbortController();+ const resources = new ArtifactResourceScope();+ const nativeClose = OwnedFileHandle.prototype.close;+ let allowClose = false;+ const close = vi+ .spyOn(OwnedFileHandle.prototype, "close")+ .mockImplementation(async function (this: OwnedFileHandle) {+ if (!allowClose) throw new Error("close unavailable");+ await nativeClose.call(this);+ });+ let failure: unknown;+ try {+ failure = await withRegularFile(+ path,+ async () => {+ controller.abort(reason);+ return "completed callback";+ },+ { signal: controller.signal },+ ).catch((cause: unknown) => cause);+ if (!(failure instanceof RegularFileCleanupFailure))+ throw new Error("Missing checkpoint cleanup owner");+ allowClose = !retryFails;+ const retried = await retryRegularFileCleanup(failure, resources);+ expect(retried.outcome.kind).toBe("failed");+ if (retried.outcome.kind !== "failed")+ throw new Error("Lost cancellation outcome");+ expect(retried.outcome.cause).toBe(reason);+ expect(retried.cleanup !== undefined).toBe(retryFails);+ expect(resources.hasPending).toBe(retryFails);+ } finally {+ allowClose = true;+ await resources.close();+ if (failure instanceof RegularFileCleanupFailure)+ await failure.owner.close();+ close.mockRestore();+ }+ },+);diff --git a/tests/boundary/filesystem/stableFileHashOwnership.test.ts b/tests/boundary/filesystem/stableFileHashOwnership.test.tsindex e19faaae9..f6dbad92c 100644--- a/tests/boundary/filesystem/stableFileHashOwnership.test.ts+++ b/tests/boundary/filesystem/stableFileHashOwnership.test.ts@@ -342,3 +342,263 @@ it("retries pending cleanup before acquiring a publisher temporary root", asyncawait publisher.close();}});++it.each([+ { stage: "close", reason: null },+ { stage: "close", reason: "caller stopped" },+ { stage: "close", reason: new Error("caller stopped") },+ { stage: "retention", reason: "after the failed close" },+] as const)(+ "records completion cancellation at $stage before owner handoff",+ async ({ stage, reason }) => {+ const root = await createTestTempDirectory("rea-hash-close-provenance-");+ const path = join(root, "input.bin");+ await writeFile(path, "owned bytes");+ const controller = new AbortController();+ const nativeClose = OwnedFileHandle.prototype.close;+ const close = vi+ .spyOn(OwnedFileHandle.prototype, "close")+ .mockImplementationOnce(async () => {+ if (stage === "close") controller.abort(reason);+ throw new Error("injected failed close");+ });+ let retained: OwnedFileHandle | undefined;+ try {+ const failure: unknown = await hashStableFile(path, {+ signal: controller.signal,+ retainFailedClose: (owner) => {+ retained = owner;+ if (stage === "retention") controller.abort(reason);+ },+ }).catch((cause: unknown) => cause);+ expect(failure).toBeInstanceOf(RegularFileCleanupFailure);+ expect(failure).toMatchObject({+ outcome: { kind: "completed", value: { bytes: 11 } },+ });+ if (stage === "close") {+ expect(failure).toMatchObject({ completionCancellation: { reason } });+ expect(+ Reflect.get(failure as object, "completionCancellation").reason,+ ).toBe(reason);+ } else+ expect(failure).not.toHaveProperty(+ "completionCancellation",+ expect.anything(),+ );+ } finally {+ close.mockRestore();+ if (retained !== undefined) await nativeClose.call(retained);+ }+ },+);++it("tags a physical hash failure without inferring cancellation from a later signal", async () => {+ const root = await createTestTempDirectory("rea-hash-physical-provenance-");+ const path = join(root, "input.bin");+ await writeFile(path, "owned bytes");+ const controller = new AbortController();+ const primary = Object.assign(new Error("injected digest read failure"), {+ code: "EIO",+ });+ const nativeOpen = regularFile.openRegularFile;+ const open = vi+ .spyOn(regularFile, "openRegularFile")+ .mockImplementation(async (selected, options) => {+ const handle = await nativeOpen(selected, options);+ vi.spyOn(handle, "read").mockRejectedValueOnce(primary);+ return handle;+ });+ const nativeClose = OwnedFileHandle.prototype.close;+ const close = vi+ .spyOn(OwnedFileHandle.prototype, "close")+ .mockImplementationOnce(async function (this: OwnedFileHandle) {+ await nativeClose.call(this);+ controller.abort(primary);+ });+ try {+ const failure: unknown = await hashStableFile(path, {+ signal: controller.signal,+ retainFailedClose: () => {+ throw new Error("Close succeeded");+ },+ }).catch((cause: unknown) => cause);+ expect(failure).toMatchObject({+ _tag: "StableFileHashFailure",+ cause: primary,+ });+ if (!(failure instanceof Error))+ throw new Error("Expected producer-owned physical failure");+ expect(failure.cause).toBe(primary);+ } finally {+ open.mockRestore();+ close.mockRestore();+ }+});++it.each([false, true])(+ "preserves premature EOF with same-read cancellation and failed close=%s",+ async (failClose) => {+ const root = await createTestTempDirectory("rea-hash-eof-cancel-");+ const path = join(root, "input.bin");+ await writeFile(path, "admitted extent");+ const controller = new AbortController();+ const nativeOpen = regularFile.openRegularFile;+ let retained: OwnedFileHandle | undefined;+ const open = vi+ .spyOn(regularFile, "openRegularFile")+ .mockImplementation(async (selected, options) => {+ const handle = await nativeOpen(selected, options);+ vi.spyOn(handle, "read").mockImplementationOnce(async () => {+ controller.abort("cancelled at EOF");+ return { bytesRead: 0, buffer: Buffer.alloc(0) };+ });+ return handle;+ });+ const nativeClose = OwnedFileHandle.prototype.close;+ const close = vi.spyOn(OwnedFileHandle.prototype, "close");+ if (failClose) close.mockRejectedValueOnce(new Error("close unavailable"));+ try {+ const failure: unknown = await hashStableFile(path, {+ signal: controller.signal,+ retainFailedClose: (owner) => {+ retained = owner;+ },+ }).catch((cause: unknown) => cause);+ const physical =+ failure instanceof RegularFileCleanupFailure+ ? failure.outcome.kind === "failed"+ ? failure.outcome.cause+ : undefined+ : failure instanceof Error+ ? failure.cause+ : undefined;+ expect(physical).toBeInstanceOf(regularFile.RegularFileChangedError);+ if (failClose) {+ expect(failure).toBeInstanceOf(RegularFileCleanupFailure);+ expect(retained?.handle.fd).toBeGreaterThanOrEqual(0);+ } else expect(failure).toMatchObject({ _tag: "StableFileHashFailure" });+ } finally {+ open.mockRestore();+ close.mockRestore();+ if (retained !== undefined) await nativeClose.call(retained);+ }+ },+);++it.each(+ [null, "caller stopped", new Error("caller stopped")].flatMap((reason) =>+ [false, true].map((failClose) => ({ reason, failClose })),+ ),+)(+ "retains the exact read checkpoint reason with failed close=$failClose ($reason)",+ async ({ reason, failClose }) => {+ const root = await createTestTempDirectory("rea-hash-read-checkpoint-");+ const path = join(root, "input.bin");+ await writeFile(path, "admitted bytes");+ const controller = new AbortController();+ const nativeOpen = regularFile.openRegularFile;+ let retained: OwnedFileHandle | undefined;+ let handleSeen: Awaited<ReturnType<typeof nativeOpen>> | undefined;+ const open = vi+ .spyOn(regularFile, "openRegularFile")+ .mockImplementation(async (selected, options) => {+ const handle = await nativeOpen(selected, options);+ handleSeen = handle;+ const read = handle.read.bind(handle);+ vi.spyOn(handle, "read").mockImplementationOnce(async (...args) => {+ const result = await read(...args);+ controller.abort(reason);+ return result;+ });+ return handle;+ });+ const nativeClose = OwnedFileHandle.prototype.close;+ const close = vi.spyOn(OwnedFileHandle.prototype, "close");+ if (failClose) close.mockRejectedValueOnce(new Error("close unavailable"));+ try {+ const failure: unknown = await hashStableFile(path, {+ signal: controller.signal,+ retainFailedClose: (owner) => {+ retained = owner;+ },+ }).catch((cause: unknown) => cause);+ const primary =+ failure instanceof RegularFileCleanupFailure &&+ failure.outcome.kind === "failed"+ ? failure.outcome.cause+ : failure;+ expect(primary).toBeInstanceOf(regularFile.RegularFileOperationCancelled);+ expect(+ (primary as regularFile.RegularFileOperationCancelled).reason,+ ).toBe(reason);+ expect(handleSeen?.fd).toBe(failClose ? retained?.handle.fd : -1);+ } finally {+ open.mockRestore();+ close.mockRestore();+ if (retained !== undefined) await nativeClose.call(retained);+ }+ },+);++it.each(["physical", "completed"] as const)(+ "preserves the publisher's %s hash outcome after cancellation and a successful close retry",+ async (outcome) => {+ const root = await createTestTempDirectory(+ "rea-publisher-hash-retry-cancel-",+ );+ const path = join(root, "launcher");+ await writeFile(path, "launcher bytes");+ const controller = new AbortController();+ const primary = new Error("injected publisher read failure");+ const reason = null;+ const nativeOpen = regularFile.openRegularFile;+ const open = vi+ .spyOn(regularFile, "openRegularFile")+ .mockImplementation(async (selected, options) => {+ const handle = await nativeOpen(selected, options);+ if (outcome === "physical")+ vi.spyOn(handle, "read").mockRejectedValueOnce(primary);+ return handle;+ });+ const nativeClose = OwnedFileHandle.prototype.close;+ let ownerSeen: OwnedFileHandle | undefined;+ let attempts = 0;+ const close = vi+ .spyOn(OwnedFileHandle.prototype, "close")+ .mockImplementation(async function (this: OwnedFileHandle) {+ ownerSeen = this;+ attempts++;+ if (attempts === 1) {+ controller.abort(reason);+ throw new Error("first close unavailable");+ }+ await nativeClose.call(this);+ });+ const publisher = new LinuxHopperPublisher(+ { XDG_CACHE_HOME: join(root, "cache") },+ async () => undefined,+ );+ try {+ const result = await publisher.inspectLauncher(path, controller.signal);+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Injected hash outcome passed");+ expect(result.error.reason).toBe(+ outcome === "physical" ? "verification_unavailable" : "cancelled",+ );+ if (outcome === "physical")+ expect(result.error.cause).toMatchObject({+ _tag: "StableFileHashFailure",+ cause: primary,+ });+ else expect(result.error.cause).toBe(reason);+ expect(attempts).toBe(2);+ expect(ownerSeen?.handle.fd).toBe(-1);+ } finally {+ open.mockRestore();+ close.mockRestore();+ await publisher.close();+ if (ownerSeen !== undefined && ownerSeen.handle.fd >= 0)+ await nativeClose.call(ownerSeen);+ }+ },+);diff --git a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.tsindex c033e276f..5ff68f8ff 100644--- a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts+++ b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts@@ -145,7 +145,7 @@ it);it.skipIf(process.platform === "win32")(- "keeps cancellation primary when an executable hash read and close both fail",+ "keeps the physical hash read failure primary when cancellation and close failure follow",async () => {const fixture = await session("rea-kuna-cancelled-read-close-");const installed = await inspectKunaInstallationOwned({@@ -174,9 +174,15 @@ it.skipIf(process.platform === "win32")(if (result.ok) throw new Error("injected cancelled read passed");originatingError = result.error;expect(result.error).toMatchObject({- _tag: "AnalysisCancelledError",+ _tag: "ProviderAdapterError",cleanupIncomplete: true,cleanupResources: [installed.value.executable],+ diagnostics: {+ primary_error: {+ code: "execution_failure",+ message: expect.stringContaining("injected read fault"),+ },+ },});} finally {injected.failReadStage = undefined;diff --git a/tests/boundary/providers/kuna/kunaInstallationLifetime.test.ts b/tests/boundary/providers/kuna/kunaInstallationLifetime.test.tsindex 764a12a32..2b123ddea 100644--- a/tests/boundary/providers/kuna/kunaInstallationLifetime.test.ts+++ b/tests/boundary/providers/kuna/kunaInstallationLifetime.test.ts@@ -1,3 +1,4 @@+import { regularFileCancellation } from "../../../../src/filesystem/OwnedRegularFile.js";import { afterEach, beforeEach, expect, it, vi } from "vitest";const gates = vi.hoisted(() => {@@ -128,7 +129,12 @@ it}gates.shebangRead.release();- await expect(inspection).rejects.toBe(controller.signal.reason);+ const failure: unknown = await inspection.catch(+ (cause: unknown) => cause,+ );+ const cancellation = regularFileCancellation(failure);+ expect(cancellation).toBeDefined();+ expect(cancellation?.reason).toBe(controller.signal.reason);await expect(cleanup).resolves.toBeUndefined();expect(gates.opens).toBe(phase === "hash-close" ? 1 : 2);expect(scope.hasPending).toBe(false);