rea-agents 6.2.0 → 6.4.0

package/dist/dotnet/ManagedPeReader.js

@@ -29,25 +29,51 @@ const architectureFor = (machine) => {
             throw managedFailure("invalid-directory", "pe.machine", `Unsupported PE machine 0x${machine.toString(16).padStart(4, "0")}`);
     }
 };
-const mapRva = (mapping) => {
+/** Resolve one section identity for both exact reads and available-byte queries. */
+const resolveRva = (mapping) => {
     const { bytes, sections, rva, size, scope } = mapping;
-    if (rva === 0 && size === 0)
-        return 0;
-    for (const section of sections) {
-        const mappedSize = Math.max(section.virtualSize, section.rawSize);
-        if (rva < section.virtualAddress)
-            continue;
+    if (!Number.isSafeInteger(rva) ||
+        !Number.isSafeInteger(size) ||
+        rva < 0 ||
+        size < 0 ||
+        rva > 0xffff_ffff ||
+        (size > 0 && size > 0x1_0000_0000 - rva))
+        throw managedFailure("invalid-directory", scope, `${scope} has an invalid RVA range`);
+    // VirtualSize owns RVA containment; raw size also includes alignment padding.
+    const selected = sections.find((section) => {
         const within = rva - section.virtualAddress;
-        if (within > mappedSize || size > mappedSize - within)
+        return (section.virtualSize > 0 &&
+            within >= 0 &&
+            within < section.virtualSize &&
+            size <= section.virtualSize - within);
+    });
+    if (selected === undefined)
+        throw managedFailure("invalid-directory", scope, `${scope} RVA is not covered by one PE section`);
+    for (const section of sections) {
+        if (section === selected || section.virtualSize === 0)
             continue;
-        if (within > section.rawSize || size > section.rawSize - within)
-            throw managedFailure("invalid-directory", scope, `${scope} occupies virtual bytes without file-backed data`);
-        const offset = add(section.rawOffset, within, scope);
-        requireRange(bytes, offset, size, scope);
-        return offset;
+        const end = section.virtualAddress + section.virtualSize;
+        const intersects = size === 0
+            ? rva >= section.virtualAddress && rva < end
+            : rva < end && rva + size > section.virtualAddress;
+        if (intersects)
+            throw managedFailure("invalid-directory", scope, `${scope} RVA range has ambiguous overlapping PE section mappings`);
     }
-    throw managedFailure("invalid-directory", scope, `${scope} RVA is not covered by a PE section`);
+    const within = rva - selected.virtualAddress;
+    if (within > selected.rawSize || size > selected.rawSize - within)
+        throw managedFailure("invalid-directory", scope, `${scope} occupies virtual bytes without file-backed data`);
+    const offset = add(selected.rawOffset, within, scope);
+    requireRange(bytes, offset, size, scope);
+    let available = Math.min(selected.virtualSize - within, selected.rawSize - within, bytes.length - offset, 0x1_0000_0000 - rva);
+    // A future overlap ends the uniquely mapped extent even if the current byte is unique.
+    for (const section of sections)
+        if (section !== selected &&
+            section.virtualAddress > rva &&
+            section.virtualSize > 0)
+            available = Math.min(available, section.virtualAddress - rva);
+    return { offset, available };
 };
+const mapRva = (mapping) => mapping.rva === 0 && mapping.size === 0 ? 0 : resolveRva(mapping).offset;
 const readDirectory = (bytes, offset) => {
     requireRange(bytes, offset, 8, "pe.data-directory");
     return {
@@ -186,16 +212,6 @@ export const readManagedPeLayout = (bytes) => {
         cliDirectoryPresent,
         cliIssue,
         rvaToOffset: (rva, size, scope) => mapRva({ bytes, sections, rva, size, scope }),
-        rvaAvailableBytes: (rva, scope) => {
-            mapRva({ bytes, sections, rva, size: 1, scope });
-            for (const section of sections) {
-                if (rva < section.virtualAddress)
-                    continue;
-                const within = rva - section.virtualAddress;
-                if (within < section.rawSize)
-                    return Math.min(section.rawSize - within, bytes.length - section.rawOffset - within);
-            }
-            throw managedFailure("invalid-directory", scope, `${scope} RVA is not covered by file-backed PE section data`);
-        },
+        rvaAvailableBytes: (rva, scope) => resolveRva({ bytes, sections, rva, size: 1, scope }).available,
     };
 };

package/dist/dotnet/ManagedReaderFailure.js

@@ -14,7 +14,8 @@ export const readManagedValue = (operation, issues) => {
         return operation();
     }
     catch (cause) {
-        if (!(cause instanceof ManagedReaderFailure))
+        if (!(cause instanceof ManagedReaderFailure) ||
+            cause.issue.code === "resource-limit")
             throw cause;
         issues.push(cause.issue);
         return undefined;

package/dist/dotnet/ManagedStaticProvider.js

@@ -1,21 +1,27 @@
 import { createHash } from "node:crypto";
-import { createReadStream } from "node:fs";
-import { readFile } from "node:fs/promises";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { MANAGED_STATIC_PROVIDER_IDENTITY as IDENTITY, managedStaticCapabilities, } from "./ManagedStaticProviderMetadata.js";
+import { managedStaticCapabilities } from "./ManagedStaticProviderMetadata.js";
+import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
 import { MANAGED_TOOL_CONTRACTS, managedTargetInputSchema, } from "../contracts/managed/managedToolContracts.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
 import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
 import { inspectManagedArtifactBytes } from "./ManagedArtifactInspector.js";
 import { inspectManagedMembersBytes } from "./ManagedMemberInspector.js";
 import { inspectManagedNativeBoundariesBytes } from "./ManagedNativeBoundaryInspector.js";
+import { openRegularFile } from "../filesystem/RegularFile.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+// This provider eagerly retains the full PE snapshot. Keep its input resource
+// policy separate from decoded metadata/output capacity; it is not a PE format limit.
+const MAX_MANAGED_SNAPSHOT_BYTES = 128 * 1024 * 1024;
+const snapshotCapacityError = (operation) => new AnalysisResourceConstraintError(operation, "memory", "Managed static inspection requires an eagerly retained PE snapshot within its input byte budget.", { max_snapshot_bytes: MAX_MANAGED_SNAPSHOT_BYTES });
 /** Execution-free managed PE/CLI auxiliary provider. */
 export class ManagedStaticProvider {
     #capabilities = managedStaticCapabilities();
     identity() {
-        return IDENTITY;
+        return MANAGED_STATIC_PROVIDER;
     }
     capabilities() {
         return this.#capabilities;
@@ -32,18 +38,18 @@ class ManagedStaticClient {
     }
     async execute(operation, parameters, options) {
         if (operation === "health")
-            return ok(createAnalysisExecution(null, IDENTITY));
+            return ok(createAnalysisExecution(null, MANAGED_STATIC_PROVIDER));
         if (!isManagedOperation(operation))
-            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Operation is not implemented by the managed static provider."));
+            return err(new AnalysisCapabilityUnavailableError(MANAGED_STATIC_PROVIDER.id, operation, "Operation is not implemented by the managed static provider."));
         if (this.target.format !== "pe")
-            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Managed static triage requires a PE target; observed ${this.target.format}.`));
+            return err(new AnalysisCapabilityUnavailableError(MANAGED_STATIC_PROVIDER.id, operation, `Managed static triage requires a PE target; observed ${this.target.format}.`));
         try {
             if (options?.signal?.aborted === true)
                 return err(new AnalysisCancelledError(operation));
             const snapshot = this.#snapshotBytes;
             const observed = snapshot === undefined
-                ? await readManagedSnapshot(this.target.path, options?.signal)
-                : await hashManagedSource(this.target.path, options?.signal);
+                ? await readManagedSnapshot(this.target.path, operation, options?.signal)
+                : await hashManagedSource(this.target.path, operation, options?.signal);
             if (observed.sha256 !== this.target.sha256)
                 return err(new EvidenceIntegrityError(`Managed artifact digest changed after open: expected ${this.target.sha256}, observed ${observed.sha256} at ${this.target.path}`));
             const bytes = snapshot ?? observed.bytes;
@@ -51,7 +57,7 @@ class ManagedStaticClient {
                 throw new TypeError("Managed snapshot bytes are unavailable");
             this.#snapshotBytes = bytes;
             const result = inspectManagedOperation(operation, parameters, bytes, this.target);
-            return ok(createAnalysisExecution(result, IDENTITY, {
+            return ok(createAnalysisExecution(result, MANAGED_STATIC_PROVIDER, {
                 rawResult: null,
                 limitations: result.limitations,
                 subject: this.target,
@@ -61,7 +67,11 @@ class ManagedStaticClient {
         catch (cause) {
             if (options?.signal?.aborted === true)
                 return err(new AnalysisCancelledError(operation));
-            return err(new ProviderAdapterError(IDENTITY.id, operation, { cause }));
+            if (cause instanceof AnalysisError)
+                return err(cause);
+            return err(new ProviderAdapterError(MANAGED_STATIC_PROVIDER.id, operation, {
+                cause,
+            }));
         }
     }
     close() {
@@ -69,27 +79,51 @@ class ManagedStaticClient {
         return Promise.resolve(ok(null));
     }
 }
-const readManagedSnapshot = async (path, signal) => {
-    const bytes = await readFile(path, signal === undefined ? undefined : { signal });
-    return {
-        byteLength: bytes.length,
-        sha256: createHash("sha256").update(bytes).digest("hex"),
-        bytes,
-    };
+const readManagedSnapshot = async (path, operation, signal) => {
+    const handle = await openRegularFile(path, { symlinks: "follow", signal });
+    try {
+        const metadata = await handle.stat();
+        if (metadata.size > MAX_MANAGED_SNAPSHOT_BYTES)
+            throw snapshotCapacityError(operation);
+        const bytes = await readBoundedFileBytes(handle, MAX_MANAGED_SNAPSHOT_BYTES, signal);
+        if (bytes === undefined)
+            throw snapshotCapacityError(operation);
+        signal?.throwIfAborted();
+        return {
+            byteLength: bytes.length,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            bytes,
+        };
+    }
+    finally {
+        await handle.close();
+    }
 };
-const hashManagedSource = async (path, signal) => {
-    const digest = createHash("sha256");
-    let byteLength = 0;
-    const stream = createReadStream(path, signal === undefined ? undefined : { signal });
-    for await (const chunk of stream) {
-        if (!Buffer.isBuffer(chunk))
-            throw new TypeError("Managed source stream returned non-buffer data");
-        if (chunk.length > Number.MAX_SAFE_INTEGER - byteLength)
-            throw new RangeError("Managed source byte length overflowed");
-        byteLength += chunk.length;
-        digest.update(chunk);
+const hashManagedSource = async (path, operation, signal) => {
+    const handle = await openRegularFile(path, { symlinks: "follow", signal });
+    try {
+        if ((await handle.stat()).size > MAX_MANAGED_SNAPSHOT_BYTES)
+            throw snapshotCapacityError(operation);
+        const digest = createHash("sha256");
+        let byteLength = 0;
+        const stream = handle.createReadStream({
+            autoClose: false,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        for await (const chunk of stream) {
+            signal?.throwIfAborted();
+            if (!Buffer.isBuffer(chunk))
+                throw new TypeError("Managed source stream returned non-buffer data");
+            if (chunk.length > MAX_MANAGED_SNAPSHOT_BYTES - byteLength)
+                throw snapshotCapacityError(operation);
+            byteLength += chunk.length;
+            digest.update(chunk);
+        }
+        return { byteLength, sha256: digest.digest("hex") };
+    }
+    finally {
+        await handle.close();
     }
-    return { byteLength, sha256: digest.digest("hex") };
 };
 const isManagedOperation = (operation) => MANAGED_TOOL_CONTRACTS.some(({ name }) => name === operation);
 const inspectManagedOperation = (operation, parameters, bytes, target) => {

package/dist/dotnet/ManagedStaticProviderMetadata.js

@@ -1,11 +1,8 @@
 import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
 import { MANAGED_TOOL_CONTRACTS, } from "../contracts/managed/managedToolContracts.js";
-/** Identity of execution-free managed metadata observations. */
-export const MANAGED_STATIC_PROVIDER_IDENTITY = Object.freeze(MANAGED_STATIC_PROVIDER);
-const IDENTITY = MANAGED_STATIC_PROVIDER_IDENTITY;
 /** Declare managed metadata coverage without opening or loading an assembly. */
 export const managedStaticCapabilities = () => Object.freeze(MANAGED_TOOL_CONTRACTS.map((contract) => Object.freeze({
-    provider: IDENTITY,
+    provider: MANAGED_STATIC_PROVIDER,
     operation: contract.name,
     available: true,
     reason: null,

package/dist/evaluation/AgentEvaluationReport.js

@@ -1,15 +1,19 @@
 /** Require configured facts to pass while preserving workflow and execution gates. */
 export const agentEvaluationPassed = (result) => result.exitCode === 0 &&
-    result.naturalUse &&
+    (result.expectedFirstTool === null
+        ? !result.naturalUse
+        : result.naturalUse) &&
     result.correctFirstTool &&
     result.repeatedCallCount === 0 &&
     result.inputValidationFailureCount === 0 &&
     result.requiredToolSubsequenceMet &&
     result.inputTokens > 0 &&
-    (result.factualCorrectness === "passed" ||
-        (result.factualCorrectness === "not_assessed" &&
-            result.answerHeuristicsMet &&
-            result.epistemicCuePresent));
+    (result.expectedFirstTool === null
+        ? result.targetClarificationPassed === true
+        : result.factualCorrectness === "passed" ||
+            (result.factualCorrectness === "not_assessed" &&
+                result.answerHeuristicsMet &&
+                result.epistemicCuePresent));
 /** Keep assessed fixture outcomes and scenarios without truth oracles distinct. */
 export const summarizeFactualCorrectness = (results) => {
     const passed = results.filter(({ factualCorrectness }) => factualCorrectness === "passed").length;

package/dist/evaluation/CodexAgentEval.js

@@ -1,5 +1,6 @@
 import { evaluateKnownAnswers, } from "./KnownAnswerEvaluation.js";
 import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
+import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const record = (value) => isRecord(value) ? value : undefined;
 const textValue = (value) => typeof value === "string" && value.length > 0 ? value : undefined;
@@ -20,19 +21,38 @@ const evidenceIdsFrom = (value) => {
         return [];
     return [...new Set(encoded.match(/ev_[a-f0-9]{64}/gu) ?? [])];
 };
-const toolResultFailed = (item) => {
-    if (item.status === "failed" ||
-        (item.error !== undefined && item.error !== null))
-        return true;
+const toolResultError = (item) => {
     const result = record(item.result ?? item.output);
     const structured = record(result?.structured_content ?? result?.structuredContent);
-    return result?.isError === true || structured?.error !== undefined;
+    const direct = record(structured?.error ?? result?.error ?? item.error);
+    if (direct !== undefined || structured !== undefined)
+        return direct;
+    // Codex preserves some REA failures only as one complete JSON text block.
+    // A client-truncated preview or SDK prose is not a structured error record.
+    const content = result?.content;
+    if (!Array.isArray(content) || content.length !== 1)
+        return undefined;
+    const block = record(content[0]);
+    if (block?.type !== "text" || typeof block.text !== "string")
+        return undefined;
+    try {
+        return record(record(JSON.parse(block.text))?.error);
+    }
+    catch (cause) {
+        if (cause instanceof SyntaxError || cause instanceof RangeError)
+            return undefined;
+        throw cause;
+    }
 };
-const toolResultErrorCode = (item) => {
+const toolResultFailed = (item, error) => {
+    if (item.status === "failed" ||
+        (item.error !== undefined && item.error !== null))
+        return true;
     const result = record(item.result ?? item.output);
     const structured = record(result?.structured_content ?? result?.structuredContent);
-    const error = record(structured?.error ?? result?.error ?? item.error);
-    return textValue(error?.code) ?? null;
+    return (result?.isError === true ||
+        structured?.error !== undefined ||
+        error !== undefined);
 };
 const callFromItem = (value) => {
     const item = record(value);
@@ -41,14 +61,15 @@ const callFromItem = (value) => {
     const tool = textValue(item.tool) ?? textValue(item.name);
     if (tool === undefined)
         return undefined;
+    const error = toolResultError(item);
     return {
         id: textValue(item.id) ?? null,
         server: textValue(item.server) ?? textValue(item.server_name) ?? null,
         tool,
         arguments: item.arguments ?? item.input ?? {},
         evidenceIds: evidenceIdsFrom(item.result ?? item.output),
-        error: toolResultFailed(item),
-        errorCode: toolResultErrorCode(item),
+        error: toolResultFailed(item, error),
+        errorCode: textValue(error?.code) ?? null,
     };
 };
 const agentTextFromItem = (value) => {
@@ -106,12 +127,21 @@ export const evaluateCodexEvents = (events, expectedFirstTool, options = {}) =>
         consumeEvent(state, event);
     const reaCalls = state.calls.filter(({ server }) => server === null || server.toLowerCase() === "rea");
     const signatures = new Map();
+    let targetRevision = 0;
     for (const call of reaCalls) {
-        const signature = `${call.tool}:${JSON.stringify(canonicalValue(call.arguments))}`;
+        // A status read before and after a successful target lifecycle change is
+        // useful verification, not a duplicate analysis or unchanged failed retry.
+        const context = call.tool === "binary_session" ? `${String(targetRevision)}:` : "";
+        const signature = `${context}${call.tool}:${JSON.stringify(canonicalValue(call.arguments))}`;
         signatures.set(signature, (signatures.get(signature) ?? 0) + 1);
+        if (!call.error &&
+            (call.tool === "open_binary" || call.tool === "close_binary"))
+            targetRevision += 1;
     }
     const repeatedCallCount = [...signatures.values()].reduce((total, count) => total + Math.max(0, count - 1), 0);
-    const inputValidationFailureCount = reaCalls.filter(({ errorCode }) => errorCode === "invalid_request").length;
+    const inputValidationFailureCount = reaCalls.filter((call) => call.errorCode === "invalid_request" ||
+        (call.error &&
+            TOOL_CONTRACTS.find(({ name }) => name === call.tool)?.inputSchema.safeParse(call.arguments).success === false)).length;
     const requiredToolSubsequenceMet = containsOrderedSubsequence(reaCalls.filter(({ error }) => !error).map(({ tool }) => tool), options.requiredToolSubsequence ?? []);
     const finalMessage = state.finalMessages.at(-1) ?? "";
     const evidenceIds = [
@@ -124,7 +154,7 @@ export const evaluateCodexEvents = (events, expectedFirstTool, options = {}) =>
     const factualAssessment = evaluateKnownAnswers(events, finalMessage, options.fixtureClaims);
     return {
         naturalUse: reaCalls.length > 0,
-        correctFirstTool: reaCalls[0]?.tool === expectedFirstTool,
+        correctFirstTool: (reaCalls[0]?.tool ?? null) === expectedFirstTool,
         firstTool: reaCalls[0]?.tool ?? null,
         reaCalls,
         repeatedCallCount,

package/dist/evm/EvmoleFailures.js

@@ -24,8 +24,6 @@ export const evmInterfaceFailure = (cause, phase, path, workerLimits, limiter =
                     message: cause.message,
                     exit_code: cause.snapshot?.exitCode ?? null,
                     signal: cause.snapshot?.signal ?? null,
-                    stdout: cause.snapshot?.stdout.text ?? null,
-                    stderr: cause.snapshot?.stderr.text ?? null,
                 },
             }, { operation: "inspect_evm_interface", cause });
         if (cause.reason === "cancelled")

package/dist/evm/EvmoleInterfaceProvider.js

@@ -44,14 +44,29 @@ export class EvmoleInterfaceProvider {
     environment;
     launcher;
     createRuntime;
+    #tail = Promise.resolve();
+    #closing = false;
+    #closePromise;
+    #pendingCleanup;
     constructor(environment = process.env, launcher, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-evm-interface-" })) {
         this.environment = environment;
         this.launcher = launcher;
         this.createRuntime = createRuntime;
     }
     /** Bind recovered interface candidates to both original carrier and decoded byte identity. */
-    async inspect(input, options) {
+    inspect(input, options) {
+        if (this.#closing)
+            return Promise.resolve(err(this.#closedError()));
+        const operation = this.#tail.then(() => this.#closing ? err(this.#closedError()) : this.#inspect(input, options));
+        this.#tail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async #inspect(input, options) {
+        const pending = await this.#retire();
+        if (pending !== undefined)
+            return err(pending);
         let root;
+        let processOwner;
         let retainedOutput;
         let phase = "configuration";
         let workerLimits;
@@ -221,6 +236,8 @@ export class EvmoleInterfaceProvider {
             }));
         }
         catch (cause) {
+            if (cause instanceof OwnedCommandFailure)
+                processOwner = cause.cleanupOwner;
             let fileFailure;
             if (cause instanceof OwnedCommandFailure &&
                 cause.snapshot?.exitCode === EVM_FILE_SIZE_FAILURE_EXIT &&
@@ -249,12 +266,20 @@ export class EvmoleInterfaceProvider {
                     : { capturedOutput: retainedOutput })
                 : evmInterfaceFailure(cause, phase, input.path, workerLimits, limiter, fileFailure));
         }
+        if (processOwner !== undefined) {
+            this.#pendingCleanup = { root, process: processOwner };
+            // The command failure already owns this cleanup diagnostic and its resources.
+            return result;
+        }
         if (root !== undefined) {
             try {
                 await root.close();
             }
             catch (cause) {
-                return err(new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [root.path], {
+                const retainedRoot = root;
+                this.#pendingCleanup = { root: retainedRoot, process: undefined };
+                root = undefined;
+                return err(new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [retainedRoot.path], {
                     reason: cause instanceof Error ? cause.message : String(cause),
                     previous_error: result.ok
                         ? null
@@ -271,4 +296,44 @@ export class EvmoleInterfaceProvider {
                 : { capturedOutput: retainedOutput }))
             : result;
     }
+    async close() {
+        this.#closing = true;
+        this.#closePromise ??= this.#tail
+            .then(async () => {
+            const failure = await this.#retire();
+            if (failure !== undefined)
+                throw failure;
+        })
+            .catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
+    }
+    #closedError() {
+        return new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [], { reason: "Provider is closing" }, { operation: OPERATION });
+    }
+    async #retire() {
+        const pending = this.#pendingCleanup;
+        if (pending === undefined)
+            return undefined;
+        if (pending.process !== undefined) {
+            const stopped = await pending.process.stop();
+            if (stopped.status === "incomplete")
+                return new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [pending.process.launch.ownership?.runId ?? "owned-worker"], { reason: stopped.reason }, { operation: OPERATION });
+            pending.process = undefined;
+        }
+        if (pending.root !== undefined) {
+            const root = pending.root;
+            try {
+                await root.close();
+                pending.root = undefined;
+            }
+            catch (cause) {
+                return new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [root.path], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation: OPERATION, cause });
+            }
+        }
+        this.#pendingCleanup = undefined;
+        return undefined;
+    }
 }

package/dist/filesystem/OwnedDirectoryHandle.js

@@ -0,0 +1,29 @@
+/** Dir.close invalidates Node's private handle before its native close settles. */
+export class OwnedDirectoryHandle {
+    handle;
+    #state = { kind: "open" };
+    constructor(handle) {
+        this.handle = handle;
+    }
+    close() {
+        if (this.#state.kind === "closed")
+            return Promise.resolve();
+        if (this.#state.kind === "closing")
+            return this.#state.attempt;
+        if (this.#state.kind === "failed")
+            return Promise.reject(this.#state.cause);
+        const attempt = Promise.resolve().then(async () => {
+            try {
+                await this.handle.close();
+                this.#state = { kind: "closed" };
+            }
+            catch (cause) {
+                // Dir has no public validity signal with which to authorize a retry.
+                this.#state = { kind: "failed", cause };
+                throw cause;
+            }
+        });
+        this.#state = { kind: "closing", attempt };
+        return attempt;
+    }
+}

package/dist/filesystem/OwnedFileHandle.js

@@ -0,0 +1,36 @@
+/** One file handle whose close result must remain truthful across retries. */
+export class OwnedFileHandle {
+    handle;
+    #state = { kind: "open" };
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /** Close the owned handle, retaining an unconfirmed close as a sticky failure. */
+    close() {
+        if (this.#state.kind === "closed")
+            return Promise.resolve();
+        if (this.#state.kind === "closing")
+            return this.#state.attempt;
+        if (this.#state.kind === "failed")
+            return Promise.reject(this.#state.cause);
+        if (this.handle.fd < 0) {
+            const cause = new Error("File handle was invalidated before this owner confirmed its close");
+            this.#state = { kind: "failed", cause };
+            return Promise.reject(cause);
+        }
+        const attempt = Promise.resolve().then(() => this.#attemptClose());
+        this.#state = { kind: "closing", attempt };
+        return attempt;
+    }
+    async #attemptClose() {
+        try {
+            await this.handle.close();
+            this.#state = { kind: "closed" };
+        }
+        catch (cause) {
+            this.#state =
+                this.handle.fd < 0 ? { kind: "failed", cause } : { kind: "open" };
+            throw cause;
+        }
+    }
+}

package/dist/filesystem/RegularFile.js

@@ -0,0 +1,73 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { OwnedFileHandle } from "./OwnedFileHandle.js";
+/** Identifies a selected path that cannot be read as one regular file. */
+export class NonRegularFileReadError extends Error {
+    path;
+    code;
+    constructor(path, directory) {
+        super(`Selected input must be a regular file: ${path}`);
+        this.path = path;
+        this.name = "NonRegularFileReadError";
+        this.code = directory ? "EISDIR" : "ENOTFILE";
+    }
+}
+/** Admission failed and the opened descriptor could not be confirmed closed. */
+export class RegularFileAdmissionFailure extends Error {
+    path;
+    cleanupCause;
+    owner;
+    cause;
+    constructor(path, admissionCause, cleanupCause, owner) {
+        super(`Selected input failed admission and its descriptor close failed: ${path}`);
+        this.path = path;
+        this.cleanupCause = cleanupCause;
+        this.owner = owner;
+        this.name = "RegularFileAdmissionFailure";
+        this.cause = admissionCause;
+    }
+}
+/** A regular input no longer matches the extent or identity admitted for reading. */
+export class RegularFileChangedError extends Error {
+    path;
+    code = "ESTALE";
+    constructor(path) {
+        super(`Selected input changed while being read: ${path}`);
+        this.path = path;
+        this.name = "RegularFileChangedError";
+    }
+}
+/** Open and verify the selected file descriptor without blocking on pipes. */
+export const openRegularFile = async (path, options) => {
+    options.signal?.throwIfAborted();
+    const handle = await open(path, constants.O_RDONLY |
+        (constants.O_NONBLOCK ?? 0) |
+        (constants.O_NOCTTY ?? 0) |
+        (options.symlinks === "reject" ? (constants.O_NOFOLLOW ?? 0) : 0));
+    const owner = new OwnedFileHandle(handle);
+    try {
+        options.signal?.throwIfAborted();
+        const metadata = await handle.stat();
+        options.signal?.throwIfAborted();
+        if (!metadata.isFile())
+            throw new NonRegularFileReadError(path, metadata.isDirectory());
+        return handle;
+    }
+    catch (cause) {
+        try {
+            await owner.close();
+        }
+        catch (cleanupCause) {
+            throw new RegularFileAdmissionFailure(path, cause, cleanupCause, owner);
+        }
+        throw cause;
+    }
+};
+/** Compare one regular file's identity and mutable metadata across a read. */
+export const sameRegularFileState = (expected, observed) => observed.isFile() &&
+    expected.dev === observed.dev &&
+    expected.ino === observed.ino &&
+    expected.size === observed.size &&
+    expected.mode === observed.mode &&
+    expected.mtimeMs === observed.mtimeMs &&
+    expected.ctimeMs === observed.ctimeMs;