rea-agents 6.5.0 → 6.7.0

package/dist/application/native/NativeCallRoutes.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { parseRelatedAddresses, referenceKindSchema, } from "../../domain/hopperValues.js";
 import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+const limitationsFrom = (operation, provider, limitations) => limitations.map((limitation) => ({ provider, operation, limitation }));
 const referencesSchema = z.object({
     reference_kinds_available: z.boolean(),
     references: z.array(z.object({
@@ -11,6 +12,27 @@ const referencesSchema = z.object({
     })),
     unresolved_calls: z.array(z.object({ address: z.string(), reason: z.string() })),
 });
+const typedCallRoutes = (references) => {
+    const calls = references.filter(({ kind }) => kind.available && kind.call);
+    const countBySite = new Map();
+    for (const call of calls) {
+        const targets = countBySite.get(call.source_address) ?? new Set();
+        targets.add(call.target_address);
+        countBySite.set(call.source_address, targets);
+    }
+    return calls.map((call) => ({
+        address: call.target_procedure?.address ?? call.target_address,
+        site: call.source_address,
+        relation: call.kind.available && (call.kind.computed || call.kind.indirect)
+            ? "indirect_call"
+            : "direct_call",
+        resolution: (countBySite.get(call.source_address)?.size ?? 0) > 1
+            ? "ambiguous"
+            : call.kind.available && (call.kind.computed || call.kind.indirect)
+                ? "resolved"
+                : "observed",
+    }));
+};
 /** Prefer typed static call references, preserving computed targets and targetless sites. */
 export const readNativeCallRoutes = async (analysis, procedure, signal, selectorOrigin) => {
     const options = {
@@ -19,13 +41,16 @@ export const readNativeCallRoutes = async (analysis, procedure, signal, selector
     };
     const execution = await analysis.execute("procedure_references", { procedure, direction: "outgoing" }, options);
     let unknowns = [];
+    let limitations = [];
     if (execution.ok) {
+        limitations = limitationsFrom("procedure_references", execution.value.provider, execution.value.limitations);
         const parsed = referencesSchema.safeParse(execution.value.result);
         if (!parsed.success)
             return {
                 ok: false,
                 error: new AnalysisOutputError("procedure_references", "Invalid typed call references"),
                 unknowns,
+                limitations,
             };
         // Missing detailed reference flags do not invalidate observed targetless
         // calls. Keep their producing provider even if another provider supplies
@@ -37,40 +62,31 @@ export const readNativeCallRoutes = async (analysis, procedure, signal, selector
         const references = parsed.data.references;
         if (parsed.data.reference_kinds_available === true ||
             (references.length > 0 && references.every(({ kind }) => kind.available))) {
-            const calls = references.filter(({ kind }) => kind.available && kind.call);
-            const countBySite = new Map();
-            for (const call of calls) {
-                const targets = countBySite.get(call.source_address) ?? new Set();
-                targets.add(call.target_address);
-                countBySite.set(call.source_address, targets);
-            }
             return {
                 ok: true,
                 value: {
                     provider: execution.value.provider,
-                    routes: calls.map((call) => ({
-                        address: call.target_procedure?.address ?? call.target_address,
-                        site: call.source_address,
-                        relation: call.kind.available && (call.kind.computed || call.kind.indirect)
-                            ? "indirect_call"
-                            : "direct_call",
-                        resolution: (countBySite.get(call.source_address)?.size ?? 0) > 1
-                            ? "ambiguous"
-                            : call.kind.available &&
-                                (call.kind.computed || call.kind.indirect)
-                                ? "resolved"
-                                : "observed",
-                    })),
+                    routes: typedCallRoutes(references),
                     unknowns,
+                    limitations,
                 },
             };
         }
     }
     else if (execution.error._tag !== "AnalysisCapabilityUnavailableError")
-        return { ok: false, error: execution.error, unknowns };
+        return {
+            ok: false,
+            error: execution.error,
+            unknowns,
+            limitations,
+        };
     const callees = await analysis.execute("procedure_callees", { procedure }, options);
     if (!callees.ok)
-        return { ok: false, error: callees.error, unknowns };
+        return { ok: false, error: callees.error, unknowns, limitations };
+    limitations = [
+        ...limitations,
+        ...limitationsFrom("procedure_callees", callees.value.provider, callees.value.limitations),
+    ];
     const parsed = parseRelatedAddresses(callees.value.result, "callees");
     return parsed.ok
         ? {
@@ -84,7 +100,8 @@ export const readNativeCallRoutes = async (analysis, procedure, signal, selector
                     resolution: "inferred",
                 })),
                 unknowns,
+                limitations,
             },
         }
-        : { ok: false, error: parsed.error, unknowns };
+        : { ok: false, error: parsed.error, unknowns, limitations };
 };

package/dist/application/native/NativeUiActionTrace.js

@@ -5,6 +5,7 @@ import { nativeDispatchMetadataResultSchema } from "../../domain/native/objcSwif
 import { inspectNativeDispatch } from "./NativeDispatchMetadataInspection.js";
 import { jsonValueSchema } from "../../domain/jsonValue.js";
 import { readNativeCallRoutes } from "./NativeCallRoutes.js";
+import { renderSourceLimitations, } from "../SourceLimitations.js";
 import { err, ok } from "../../domain/result.js";
 import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
 import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
@@ -182,6 +183,10 @@ export const traceNativeUiAction = async (analysis, input, signal) => {
             : graph.truncated && trace.reason === null
                 ? "native_trace_output_bound_reached"
                 : trace.reason,
+        limitations: [
+            ...trace.limitations,
+            ...renderSourceLimitations(expanded.limitations),
+        ],
     })));
 };
 const emptyGraph = (targetSha256, provider) => nativeInvestigationGraphSchema.parse({
@@ -277,6 +282,7 @@ const addDirectCallees = async (input) => {
     let examined = 0;
     let omitted = 0;
     let truncated = false;
+    const sourceLimitations = [];
     while (queueIndex < queue.length) {
         const current = queue[queueIndex++];
         if (current === undefined || visited.has(current.address))
@@ -294,6 +300,7 @@ const addDirectCallees = async (input) => {
         }
         const execution = await readNativeCallRoutes(input.analysis, current.address, input.signal, "provider");
         examined += 1;
+        sourceLimitations.push(...(execution.ok ? execution.value.limitations : execution.limitations));
         if (!execution.ok && execution.error._tag === "AnalysisCancelledError")
             return { error: execution.error };
         const unknowns = execution.ok
@@ -414,6 +421,7 @@ const addDirectCallees = async (input) => {
         examined,
         omitted,
         truncated,
+        limitations: sourceLimitations,
     };
 };
 const graphNodeDepths = (start, nodes, edges) => {

package/dist/application/native/NativeValueTrace.js

@@ -5,6 +5,7 @@ import { createEvidence } from "../../domain/evidence.js";
 import { AnalysisCancelledError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
 import { err, ok } from "../../domain/result.js";
 import { jsonParts } from "../../domain/jsonSerialization.js";
+import { renderSourceLimitations, } from "../SourceLimitations.js";
 const NODE_PAYLOAD_BYTES = 8 * 1024 * 1024;
 /** Compose bounded high-p-code def-use graphs across exactly referenced call destinations. */
 export const traceNativeValues = async (analysis, parameters, signal) => {
@@ -13,6 +14,7 @@ export const traceNativeValues = async (analysis, parameters, signal) => {
     const edges = [];
     const procedures = [];
     const unknowns = [];
+    const sourceLimitations = [];
     const callBindings = [];
     const pending = [{ procedure: input.procedure, depth: 0 }];
     const attempted = new Set();
@@ -229,6 +231,11 @@ export const traceNativeValues = async (analysis, parameters, signal) => {
             const targets = nativeCallTargetsSchema.safeParse(resolved.value.result);
             if (!targets.success)
                 return err(new AnalysisOutputError("resolve_native_call_targets", "Invalid static call resolution"));
+            sourceLimitations.push(...targets.data.limitations.map((limitation) => ({
+                provider: resolved.value.provider,
+                operation: "resolve_native_call_targets",
+                limitation,
+            })));
             if (targets.data.targets.length === 0)
                 unknowns.push({
                     procedure: address,
@@ -363,6 +370,7 @@ export const traceNativeValues = async (analysis, parameters, signal) => {
             "Static decompiler def-use graphs cover recovered block members; when membership is unavailable they exclude operations marked dead. Logical CALL argument positions bind to recovered HighParam ordinals and RETURN values bind to recovered CALL outputs; these are decompiler-derived dependencies, not original source or runtime observations. Missing parameters, variadic arguments and alias dependencies remain unknown.",
             "LOAD and STORE are memory operations; object fields, persistent state and RNG semantics are not inferred from names or pseudocode.",
             "Traversal caps depth, decompilations, call-site resolutions, nodes, edges and node payloads (8 MiB). Complete serialized output is bounded to 32 MiB. Pagination reruns analysis and returns edges whose source is on the node page; endpoints outside the page retain stable identities.",
+            ...renderSourceLimitations(sourceLimitations),
         ],
     });
     if (Buffer.byteLength(JSON.stringify(result)) > 32 * 1024 * 1024)

package/dist/application/reverse/ReverseEngineeringService.js

@@ -1,7 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { stat as statPath } from "node:fs/promises";
-import { resolve } from "node:path";
 import { AnalysisAccessDeniedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../../domain/analysisErrorCore.js";
 import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
 import { createEvidence } from "../../domain/evidence.js";
@@ -9,6 +8,7 @@ import { err, ok } from "../../domain/result.js";
 import { objdumpInputSchema, rizinInputSchema, } from "../../domain/reverseEngineering.js";
 import { execFileOutput, execFileOutputFailure, } from "../../process/ExecFileOutput.js";
 import { OwnedCommandFailure, runOwnedCommand, } from "../../process/OwnedCommand.js";
+import { absoluteCallerPath } from "../../filesystem/callerPath.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_COMBINED_OUTPUT_BYTES = 16 * 1024 * 1024;
 // Eight concurrent captures bound retained provider output to 128 MiB.
@@ -147,7 +147,7 @@ export class ReverseEngineeringService {
         const cleanup = await this.retryCleanup(operation);
         if (!cleanup.ok)
             return cleanup;
-        const absolutePath = path === undefined ? undefined : resolve(path);
+        const absolutePath = path === undefined ? undefined : absoluteCallerPath(path);
         let digest;
         try {
             if (absolutePath !== undefined)

package/dist/application/rust/RustBinaryService.js

@@ -5,6 +5,7 @@ import { BINARY_ARCHITECTURES } from "../../domain/binaryTargetTypes.js";
 import { inspectRustBinaryInputSchema, rustBinarySchema, } from "../../domain/rust/rustBinary.js";
 import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
 import { err, ok } from "../../domain/result.js";
+import { completeProviderEvidence } from "../ProviderOperationExecution.js";
 const OPERATION = "inspect_rust_binary";
 const architectureForSubject = (architecture) => {
     switch (architecture) {
@@ -22,10 +23,13 @@ export class RustBinaryService {
     constructor(provider) {
         this.provider = provider;
     }
+    close() {
+        return this.provider.close?.() ?? Promise.resolve();
+    }
     /** Inspect one explicitly selected file without acquiring a binary session. */
     async inspect(rawInput, options) {
         if (options?.signal?.aborted)
-            return err(new AnalysisCancelledError(OPERATION));
+            return err(new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }));
         const input = inspectRustBinaryInputSchema.safeParse(rawInput);
         if (!input.success)
             return err(analysisInputErrorFromIssues(OPERATION, input.error.issues, rawInput, {
@@ -42,12 +46,10 @@ export class RustBinaryService {
         const inspected = await this.provider.inspect(input.data, options);
         if (!inspected.ok)
             return inspected;
-        if (options?.signal?.aborted)
-            return err(new AnalysisCancelledError(OPERATION));
         const report = rustBinarySchema.safeParse(inspected.value);
         if (!report.success || report.data.artifact.path !== input.data.path)
             return err(new AnalysisOutputError(OPERATION, "Rust dependency reader returned malformed metadata or changed the selected artifact identity."));
-        return ok(evidenceFor(this.provider.identity, input.data, report.data));
+        return completeProviderEvidence(evidenceFor(this.provider.identity, input.data, report.data), options?.signal);
     }
 }
 const evidenceFor = (provider, parameters, value) => {

package/dist/application/signals/SignalRecordingService.js

@@ -17,7 +17,7 @@ export class SignalRecordingService {
     async decode(raw, options) {
         const operation = "decode_signal_recording";
         if (options?.signal?.aborted)
-            return err(new AnalysisCancelledError(operation));
+            return err(new AnalysisCancelledError(operation, { cause: options.signal.reason }));
         const input = decodeSignalRecordingInputSchema.safeParse(raw);
         if (!input.success)
             return err(analysisInputErrorFromIssues(operation, input.error.issues, raw, {
@@ -47,7 +47,7 @@ export class SignalRecordingService {
     async inspectDecoders(raw, options) {
         const operation = "inspect_signal_decoders";
         if (options?.signal?.aborted)
-            return err(new AnalysisCancelledError(operation));
+            return err(new AnalysisCancelledError(operation, { cause: options.signal.reason }));
         const input = inspectSignalDecodersInputSchema.safeParse(raw);
         if (!input.success)
             return err(analysisInputErrorFromIssues(operation, input.error.issues, raw, {
@@ -76,6 +76,7 @@ export class SignalRecordingService {
         });
         return options?.signal?.aborted
             ? err(new AnalysisCancelledError(operation, {
+                cause: options.signal.reason,
                 partialObservation: evidence,
             }))
             : ok(evidence);

package/dist/application/wasm/WasmArtifactService.js

@@ -3,7 +3,8 @@ import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from
 import { createEvidence } from "../../domain/evidence.js";
 import { inspectWasmArtifactInputSchema, wasmArtifactSchema, wasmArtifactMatchesSubject, } from "../../domain/wasm/wasmArtifact.js";
 import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
-import { err, ok } from "../../domain/result.js";
+import { err } from "../../domain/result.js";
+import { completeProviderEvidence } from "../ProviderOperationExecution.js";
 const OPERATION = "inspect_wasm_artifact";
 /** Shared artifact validation and typed inline Evidence for CLI/MCP. */
 export class WasmArtifactService {
@@ -48,8 +49,6 @@ export class WasmArtifactService {
         const inspected = await this.provider.inspect(input.data, options);
         if (!inspected.ok)
             return inspected;
-        if (options?.signal?.aborted)
-            return err(new AnalysisCancelledError(OPERATION));
         const execution = inspected.value;
         const report = wasmArtifactSchema.safeParse(execution.result);
         if (!report.success ||
@@ -62,7 +61,7 @@ export class WasmArtifactService {
                     ...new Set([input.data.path, ...input.data.candidate_paths]),
                 ]))
             return err(new AnalysisOutputError(OPERATION, "WABT adapter returned malformed data or changed the selected artifact identity."));
-        return ok(createEvidence(execution.subject, execution.provider, {
+        return completeProviderEvidence(createEvidence(execution.subject, execution.provider, {
             operation: OPERATION,
             parameters: input.data,
             result: report.data,
@@ -72,6 +71,6 @@ export class WasmArtifactService {
             confidence: "observed",
             locations: execution.locations,
             limitations: execution.limitations,
-        }));
+        }), options?.signal);
     }
 }

package/dist/artifacts/AnalysisCleanupLease.js

@@ -0,0 +1,119 @@
+/** Link one resource's confirmed release to its originating analysis error. */
+export class AnalysisCleanupLease {
+    cleanup;
+    #released = false;
+    #releasePromise;
+    #errors = [];
+    #groups = new Set();
+    /** Whether this exact owner has confirmed release. */
+    get released() {
+        return this.#released;
+    }
+    #resourceOwner;
+    #resources;
+    get cleanupResources() {
+        return this.#resourceOwner === undefined
+            ? this.#resources
+            : this.#resourceOwner.cleanupResources;
+    }
+    /** Adopt exact close authority while retaining its live labels across retries. */
+    static forCloseOwner(owner, resource) {
+        return new AnalysisCleanupLease(() => owner.close(), !("cleanupResources" in owner)
+            ? [resource]
+            : {
+                get cleanupResources() {
+                    return owner.cleanupResources;
+                },
+            });
+    }
+    constructor(cleanup, resources) {
+        this.cleanup = cleanup;
+        if (resources !== undefined && "cleanupResources" in resources) {
+            this.#resourceOwner = resources;
+            this.#resources = undefined;
+        }
+        else {
+            this.#resourceOwner = undefined;
+            this.#resources = resources === undefined ? undefined : [...resources];
+        }
+    }
+    release() {
+        if (this.#released)
+            return Promise.resolve();
+        if (this.#releasePromise !== undefined)
+            return this.#releasePromise;
+        const attempt = Promise.resolve()
+            .then(async () => {
+            await this.cleanup();
+            this.#released = true;
+            this.#resolveBoundErrors();
+            for (const group of this.#groups)
+                group.ownerReleased(this);
+            this.#groups.clear();
+        })
+            .finally(() => {
+            if (this.#releasePromise === attempt)
+                this.#releasePromise = undefined;
+        });
+        this.#releasePromise = attempt;
+        return attempt;
+    }
+    /** Binding can follow a concurrent retry that already confirmed release. */
+    bindCleanupError(error) {
+        if (this.#released) {
+            error.resolveCleanup();
+            return;
+        }
+        this.#errors = [
+            ...this.#errors.filter((reference) => reference.deref() !== undefined),
+            new WeakRef(error),
+        ];
+    }
+    /** Bind one aggregate error to every exact lease in a failed retry set. */
+    bindCleanupGroup(group) {
+        if (this.#released) {
+            group.ownerReleased(this);
+            return;
+        }
+        for (const retained of this.#groups)
+            if (!retained.hasLiveError)
+                this.#groups.delete(retained);
+        this.#groups.add(group);
+    }
+    #resolveBoundErrors() {
+        for (const reference of this.#errors)
+            reference.deref()?.resolveCleanup();
+        this.#errors = [];
+    }
+}
+/** Conjunctive cleanup binding for an error covering multiple exact owners. */
+export class AnalysisCleanupLeaseGroup {
+    #error;
+    #pending;
+    constructor(error, owners) {
+        this.#error = new WeakRef(error);
+        this.#pending = new Set(owners);
+        if (this.#pending.size === 0)
+            return;
+        error.bindCleanupResourceOwner(this);
+        for (const owner of this.#pending)
+            owner.bindCleanupGroup(this);
+    }
+    /** Unlabelled owners keep attribution unknown; never match resources by text. */
+    get cleanupResources() {
+        if ([...this.#pending].some((owner) => owner.cleanupResources === undefined))
+            return undefined;
+        return [
+            ...new Set([...this.#pending].flatMap((owner) => owner.cleanupResources ?? [])),
+        ];
+    }
+    get hasLiveError() {
+        return this.#error.deref() !== undefined;
+    }
+    ownerReleased(owner) {
+        if (!this.#pending.delete(owner) || this.#pending.size > 0)
+            return;
+        this.#error.deref()?.resolveCleanup();
+        this.#pending.clear();
+    }
+}

package/dist/artifacts/ArtifactFileOperation.js

@@ -0,0 +1,150 @@
+import { RegularFileOperationCancelled } from "../filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { withOwnedFileHandle, withOwnedRegularFile, RegularFileCancelled, RegularFileCleanupFailure, } from "../filesystem/OwnedRegularFile.js";
+import { ArtifactReaderFailure, artifactPrimaryCleanupLeases, } from "./ArtifactReader.js";
+import { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, } from "./AnalysisCleanupLease.js";
+/** Artifact projection plus the exact descriptor owner and physical operation outcome. */
+export class ArtifactFileCleanupFailure extends ArtifactReaderFailure {
+    cleanupLease;
+    cleanupLeases;
+    fileCleanupFailure;
+    constructor(fileCleanupFailure, cleanupLease) {
+        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
+            : completionCancellation === undefined
+                ? fileCleanupFailure.cleanupCause
+                : new ArtifactReaderFailure("cancelled", "Artifact read cancelled during close", {
+                    cause: completionCancellation.reason,
+                });
+        const projected = ArtifactReaderFailure.withCleanup(primary, ArtifactReaderFailure.cleanupObservation(fileCleanupFailure.cleanupCause, fileCleanupFailure.path));
+        super(projected.reason, projected.message, {
+            cause: fileCleanupFailure,
+            cleanup: projected.cleanup,
+            partialObservation: projected.partialObservation,
+            cancellation: projected.cancellation,
+            ...(projected.boundary === undefined
+                ? {}
+                : { boundary: projected.boundary }),
+        }, projected.details);
+        this.cleanupLease = cleanupLease;
+        this.fileCleanupFailure = fileCleanupFailure;
+        const inherited = fileCleanupFailure.outcome.kind === "failed"
+            ? artifactPrimaryCleanupLeases(fileCleanupFailure.outcome.cause)
+            : [];
+        this.cleanupLeases =
+            inherited === undefined
+                ? undefined
+                : [...new Set([cleanupLease, ...inherited])];
+    }
+}
+/** Normalize the physical primary failure without replacing its exact cleanup owner. */
+export const mapArtifactFileFailure = (cause, classify) => {
+    if (!(cause instanceof ArtifactFileCleanupFailure))
+        return classify(cause);
+    const physical = cause.fileCleanupFailure;
+    if (physical.outcome.kind !== "failed")
+        return cause;
+    const primary = physical.outcome.cause instanceof ArtifactFileCleanupFailure
+        ? mapArtifactFileFailure(physical.outcome.cause, classify)
+        : classify(physical.outcome.cause);
+    if (primary === physical.outcome.cause)
+        return cause;
+    return new ArtifactFileCleanupFailure(new RegularFileCleanupFailure(physical.path, physical.owner, { kind: "failed", cause: primary }, physical.cleanupCause, physical.retention, physical.completionCancellation), cause.cleanupLease);
+};
+/** Read only the physical outcomes carried by known nested file owners. */
+export const artifactFilePrimaryFailure = (cause) => {
+    while (cause instanceof ArtifactFileCleanupFailure &&
+        cause.fileCleanupFailure.outcome.kind === "failed")
+        cause = cause.fileCleanupFailure.outcome.cause;
+    return cause;
+};
+/** Cancellation after confirmed close retains the completed physical operation. */
+export class ArtifactFileCancelled extends ArtifactReaderFailure {
+    fileCancellation;
+    constructor(fileCancellation) {
+        super("cancelled", "Artifact read cancelled", {
+            cause: fileCancellation.reason,
+        });
+        this.fileCancellation = fileCancellation;
+    }
+}
+/** Bind a translated failure to its exact descriptor leases, including failed retries. */
+export const bindArtifactFileCleanup = (cause, error) => {
+    const leases = cause instanceof ArtifactReaderFailure ? cause.cleanupLeases : undefined;
+    if (leases !== undefined)
+        new AnalysisCleanupLeaseGroup(error, leases);
+};
+/** Interpret this owner's typed cancellation, preserving an undefined reason. */
+export const artifactFileCancellationCause = (cause) => {
+    return cause.cancellation === undefined
+        ? cause.cause
+        : cause.cancellation.reason;
+};
+/** Report cancellation at the read stage that actually observed the caller signal. */
+export const assertArtifactReadActive = (signal) => {
+    if (signal?.aborted)
+        throw new ArtifactReaderFailure("cancelled", "Artifact read cancelled", {
+            cause: signal.reason,
+        });
+};
+/** Admit a regular file without blocking on pipes, retaining failed admission closes. */
+export const withArtifactRegularFile = async (path, resources, signal, operation, symlinks = "reject") => {
+    let cleanupLease;
+    assertArtifactReadActive(signal);
+    try {
+        const value = await withOwnedRegularFile(path, {
+            symlinks,
+            ...(signal === undefined ? {} : { signal }),
+            retainFailedClose: (owner) => {
+                cleanupLease = new AnalysisCleanupLease(() => owner.close(), [path]);
+                resources.retain({
+                    kind: "lease",
+                    resource: path,
+                    lease: cleanupLease,
+                });
+            },
+        }, async (file) => {
+            assertArtifactReadActive(signal);
+            return await operation(file);
+        });
+        return value;
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure &&
+            cleanupLease !== undefined)
+            throw new ArtifactFileCleanupFailure(cause, cleanupLease);
+        if (cause instanceof RegularFileCancelled)
+            throw new ArtifactFileCancelled(cause);
+        throw artifactOperationCause(cause);
+    }
+};
+/** Keep admission, operation outcome, final close and failed-owner transfer together. */
+export const withArtifactFileHandle = async (path, file, resources, signal, operation) => {
+    const owner = new OwnedFileHandle(file);
+    const cleanupLease = new AnalysisCleanupLease(() => owner.close(), [path]);
+    try {
+        return await withOwnedFileHandle(path, owner, {
+            ...(signal === undefined ? {} : { signal }),
+            retainFailedClose: () => resources?.retain({
+                kind: "lease",
+                resource: path,
+                lease: cleanupLease,
+            }),
+        }, operation);
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw new ArtifactFileCleanupFailure(cause, cleanupLease);
+        if (cause instanceof RegularFileCancelled)
+            throw new ArtifactFileCancelled(cause);
+        throw artifactOperationCause(cause);
+    }
+};
+const artifactOperationCause = (cause) => cause instanceof RegularFileOperationCancelled
+    ? new ArtifactReaderFailure("cancelled", "Artifact file operation cancelled", { cause: cause.reason })
+    : cause;

package/dist/artifacts/ArtifactHash.js

@@ -7,7 +7,7 @@ export const ARTIFACT_CLASSIFICATION_PREFIX_BYTES = 8_192;
 /** Preserve the inventory cancellation reason at a stream boundary. */
 export const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
-        throw new ArtifactReaderFailure("cancelled", "Artifact inventory cancelled");
+        throw new ArtifactReaderFailure("cancelled", "Artifact inventory cancelled", { cause: signal.reason });
 };
 /** Hash every stream byte and retain its bounded classification prefix. */
 export const hashReadable = async (stream, signal) => {
@@ -36,5 +36,6 @@ export const hashReadable = async (stream, signal) => {
             xmlProbe.write(selected);
         }
     }
+    abortIfNeeded(signal);
     return { sha256: hash.digest("hex"), bytes, prefix: Buffer.concat(prefixes) };
 };