@poe-platform/safe-fs 0.1.727 → 0.1.729

package/README.md

@@ -98,6 +98,13 @@ creation and updates without inode numbers, staging directories or permission
 APIs. Read the [conditional publication contract](src/contracts/conditional-publication.md)
 before implementing the host operation; ordinary writes do not provide it.
 
+For temporary staging that must be cleaned up after its parent moves, adapters
+advertising `retainedStagingCleanup` accept `createStagedFile(..., { parent,
+retainCleanup: true })`. Use the returned `staging.cleanup.remove()` and always
+call `staging.cleanup.close()` in `finally`. Memory and its supported wrappers
+retain only the owned staging entries; replacement entries remain protected.
+See the [staging contract](src/contracts/filesystem.md#atomic-owned-staging).
+
 | Backend or wrapper | Use it for |
 | --- | --- |
 | `createMemoryFileSystem()` | Isolated, nonpersistent storage with links, permissions, timestamps, and streams; each path resolution admits at most 65,536 cumulative UTF-16 code units across the input and followed symlink targets, rejecting excess with `ENAMETOOLONG` before component allocation |
@@ -231,7 +238,7 @@ There are no package environment variables, implicit credentials, or automatic `
 | Memory / read-only | Memory accepts independent optional `maxFileBytes`, `maxRetainedBytes`, `maxMetadataUnits` and `maxBytes` quotas, all unlimited by default. Read-only takes the backing filesystem, without an options object. |
 | Real | Required `root`: existing absolute host directory; the constructor/factory also accepts the root string directly. |
 | Mount | Required `root`: fallback filesystem. `mounts` defaults to `{}` and maps absolute virtual paths to filesystems. |
-| Overlay | Required `upper` and `lower`; `maxBufferBytes` is unlimited unless configured. |
+| Overlay | Required `upper` and `lower`; `maxBufferBytes` is unlimited unless configured; it and per-read `maxBytes` accept explicit `Infinity`. |
 | Quota | `withFileSystemQuota` requires a nonnegative safe-integer `maxBytes`. It serializes mutations and counts files, symlinks, copies, hard links, truncation, and streaming writes. |
 | Node bridge | `cwd` defaults to `/`, must be an absolute virtual path; optional lifetime `signal` and trusted `readFileMaxBytes` cap forwarded to backend reads before copy/decode. |
 | Portable bridge | Same `cwd`, `signal` and `readFileMaxBytes`, plus required `codec` with `isEncoding`, `encode`, and `decode` functions. |
@@ -251,9 +258,9 @@ Every raw filesystem operation accepts an optional `signal`. Additional fields a
 | `copyFile` | `exclusive` (default false) |
 | `readStream` | `start` (default 0), `endExclusive` (default end of file), `chunkSize` (built-in default 64 KiB) |
 
-`access` takes a separate mode bitmask from `ACCESS_MODES`. `chmod` takes a mode, `utimes` takes millisecond timestamps, and `truncate` takes a byte length (default 0). Backend limits still apply. Node-shaped bridge methods translate their own options rather than accepting these raw option objects; see the [bridge signatures](src/bridge/filesystem.ts).
+`access` takes a separate mode bitmask from `ACCESS_MODES`. `chmod` takes a mode, `utimes` takes millisecond timestamps, and `truncate` takes a byte length (default 0). For conditional chmod, check `capabilitiesFor(path, { conditionalChmod: true })` (or `capabilities`) and require `conditionalChmod: true`; supply `parent`, `expected`, and complete root-to-parent `ancestors` together. An optional mutation-free `commitGuard` must return literal `true` synchronously. Memory validates at its metadata commit; mount and supported Memory overlays preserve wrapper ancestry. Real uses its existing externally isolated host-tree boundary and does not prevent races with other processes. Backend limits still apply. Node-shaped bridge methods translate their own options rather than accepting these raw option objects; see the [bridge signatures](src/bridge/filesystem.ts).
 
-`collectBytes(source, { maxBytes, maxMemoryBytes, signal })` snapshots streamed chunks into one growing buffer. `maxMemoryBytes` limits owned capacity, the current input's full backing buffer, and overlapping allocations during growth; exhaustion throws `EFBIG`. Browser and Worker bundles additionally share a fixed 32 MiB budget across active collectors, even when byte limits are omitted. The returned view may retain geometric spare capacity. This budget covers collection, not caller-retained results, transport buffering, archive decoding, strings, or the rest of the runtime; use streaming APIs and limit concurrent workloads for larger inputs.
+`collectBytes(source, { maxBytes, maxMemoryBytes, signal })` snapshots streamed chunks into one growing buffer. `maxBytes` and `maxMemoryBytes` accept explicit `Infinity`. `maxMemoryBytes` limits owned capacity, the current input's full backing buffer, and overlapping allocations during growth; exhaustion throws `EFBIG`. Browser and Worker bundles additionally share a fixed 32 MiB budget across active collectors, even when byte limits are omitted. The returned view may retain geometric spare capacity. This budget covers collection, not caller-retained results, transport buffering, archive decoding, strings, or the rest of the runtime; use streaming APIs and limit concurrent workloads for larger inputs.
 
 <details>
 <summary>S3 filesystem and HTTP transport options</summary>
@@ -273,12 +280,12 @@ For in-memory S3 simulations, `new MockS3Client({ buckets, pageSize?, now?, auth
 | `maxReadBytes` | Unlimited unless configured |
 | `maxStreamBytes` | Unlimited unless configured |
 | `maxListEntries` | Unlimited unless configured |
-| `removalLimits.maxRequests` | 32 transport calls per `rm`, including lookup, listing, and deletes |
-| `removalLimits.maxListEntries` | 32 returned listing entries in aggregate per `rm`, including lookup |
-| `removalLimits.maxDeleteObjects` | 16 objects per `rm` |
+| `removalLimits.maxRequests` | Unlimited unless configured; transport calls per `rm`, including lookup, listing, and deletes |
+| `removalLimits.maxListEntries` | Unlimited unless configured; returned listing entries in aggregate per `rm`, including lookup |
+| `removalLimits.maxDeleteObjects` | Unlimited unless configured; objects per `rm` |
 | `compareEntry` | Optional trusted backing-identity callback |
 
-Removal limits apply even when shell filesystem-call limits admit a recursive `rm` as one operation. Each limit accepts a positive safe integer. Traversal stops at the listing/request cap and rejects with `EFBIG`; all delete requests must fit the remaining request budget before the first mutation. Nonrecursive removal checks for children using pages of at most two entries. Configure larger `removalLimits` only where the deployment can afford the corresponding work. These limits count adapter transport calls; retries inside a supplied transport need their own limit. Remote failures or concurrent writers can still cause partial deletion after preflight.
+Removal limits apply even when shell filesystem-call limits admit a recursive `rm` as one operation. Removal limits default to unlimited and accept a positive safe integer or `Infinity`. Read, stream, listing, and request limits also accept explicit `Infinity`. Traversal stops at the listing/request cap and rejects with `EFBIG`; all delete requests must fit the remaining request budget before the first mutation. Nonrecursive removal checks for children using pages of at most two entries. Configure finite `removalLimits` to bound the work in deployments that need them. These limits count adapter transport calls; retries inside a supplied transport need their own limit. Remote failures or concurrent writers can still cause partial deletion after preflight.
 
 For larger trees, a trusted integration can process one bounded batch per request/job using its explicitly supplied transport. This example uses at most 17 transport calls and retains at most 16 summaries; repeat in a later job until `done`. The prefix must come from trusted deployment configuration, include the filesystem's configured prefix, and end in `/`. This deliberately bypasses filesystem collision checks and deletes directory markers as well as files; serialize it with writers when complete removal is required.
 
@@ -339,7 +346,7 @@ Each batch lists from the beginning because previous keys have been deleted; it
 
 Known identity Content-Length responses use one result buffer; other responses grow storage up to the configured ceiling and return a view without a final copy. Growth can temporarily retain the old and new buffers (up to three times the response size), plus transport chunks. These per-response defaults leave headroom in Workers; hosts must still budget for metadata parsing, text decoding, transport buffers, and concurrent reads, especially when raising the limits. Use streaming reads for large files.
 
-WebDAV metadata parsing limits the document to 100,000 elements, 100,000 content nodes, 100,000 attributes, and 256 levels of nesting, independently of `maxEntries`. Text is bounded by `maxXmlBytes`. Exceeding a structural budget reports `EFBIG`; parsing yields cooperatively so caller cancellation and `timeoutMs` remain active.
+WebDAV `maxEntries`, `maxResponseBytes`, `maxXmlBytes`, and per-read `maxBytes` accept explicit `Infinity`. WebDAV metadata parsing limits the document to 100,000 elements, 100,000 content nodes, 100,000 attributes, and 256 levels of nesting, independently of `maxEntries`. Text is bounded by `maxXmlBytes`. Exceeding a structural budget reports `EFBIG`; parsing yields cooperatively so caller cancellation and `timeoutMs` remain active.
 
 See the [binding types](src/fs/webdav/webdav.ts) before implementing atomic directory removal. A recursive WebDAV DELETE does not satisfy that contract.
 

package/dist/safe-fs/contracts/errors.js

@@ -44,7 +44,14 @@ export class FsError extends Error {
         const operation = options.syscall ? `, ${options.syscall}` : "";
         const path = options.path === undefined ? "" : ` '${options.path}'`;
         const destination = options.dest === undefined ? "" : ` -> '${options.dest}'`;
-        super(`${code}: ${options.message ?? descriptions[code]}${operation}${path}${destination}`, options);
+        const prevStackLimit = Error.stackTraceLimit;
+        Error.stackTraceLimit = 0;
+        try {
+            super(`${code}: ${options.message ?? descriptions[code]}${operation}${path}${destination}`, options);
+        }
+        finally {
+            Error.stackTraceLimit = prevStackLimit;
+        }
         this.name = "FsError";
         this.code = code;
         this.errno = errno;

package/dist/safe-fs/contracts/filesystem.d.ts

@@ -68,16 +68,29 @@ export interface FileSystemCapabilities {
     readonly symlinks?: boolean;
     readonly hardlinks?: boolean;
     readonly permissions?: boolean;
+    /** Enforces chmod target/ancestry receipts and a synchronous guard at the metadata commit.
+     * Host adapters retain their documented external-filesystem isolation requirements. */
+    readonly conditionalChmod?: boolean;
     readonly timestamps?: boolean;
     readonly atomicRename?: boolean;
     /** Owned staging serialized within a trusted host; requires external tree isolation. */
     readonly trustedOwnedStaging?: boolean;
     readonly atomicFileStaging?: boolean;
+    /** Creates a cleanup handle bound to owned staging entries, independent of ancestor paths. */
+    readonly retainedStagingCleanup?: boolean;
     /** Atomically verifies every supplied root-to-parent directory identity at publication. */
     readonly atomicStagingAncestry?: boolean;
+    /** Prepares directory guards that validate without yielding or mutating state. */
+    readonly synchronousDirectoryValidation?: boolean;
+    /** Captures a followed destination path with a synchronous commit validator. */
+    readonly synchronousStagingResolution?: boolean;
+    /** Invokes commitGuard in the same synchronous section as staged replacement. */
+    readonly guardedStagingPublication?: boolean;
     readonly atomicFilePublication?: boolean;
     readonly atomicFileMutation?: boolean;
     readonly atomicEntryRemoval?: boolean;
+    /** Returns an atomic post-unlink inode snapshot when explicitly requested. */
+    readonly atomicEntryRemovalReceipt?: boolean;
     readonly atomicTreeRemoval?: boolean;
     readonly atomicDirectoryMetadata?: boolean;
     readonly atomicRenameNoReplace?: boolean;
@@ -93,10 +106,24 @@ export interface FileSystemCapabilities {
 export interface FsOptions {
     readonly signal?: AbortSignal;
 }
+export interface ChmodOptions extends FsOptions {
+    /** Conditional fields require conditionalChmod and a complete parent/target/ancestry receipt. */
+    readonly parent?: FileStat;
+    readonly expected?: FileStat;
+    readonly ancestors?: readonly FileStagingEntry[];
+    /** Trusted, mutation-free validation; must return literal true synchronously. */
+    readonly commitGuard?: () => true;
+}
 export interface OpenReadFileOptions extends FsOptions {
     readonly allowDirectory?: boolean;
 }
 export interface CapabilityQueryOptions extends OpenReadFileOptions {
+    /** Include complete wrapper ancestry when checking conditional chmod support. */
+    readonly conditionalChmod?: boolean;
+    /** Inspect complete ancestry for staged publication, including other mounts.
+     * Omission retains the ordinary per-target query and its acquisition intent. */
+    readonly stagingAncestry?: boolean;
+    readonly stagingResolution?: boolean;
     readonly create?: boolean;
     readonly creation?: OpenFileOptions["creation"];
 }
@@ -182,20 +209,46 @@ export interface ConditionalWriteFileOptions extends FsOptions {
     readonly expected: FileStat | null;
     readonly append?: boolean;
     readonly mode?: number;
+    readonly atimeMs?: number;
+    readonly mtimeMs?: number;
 }
 export interface ConditionalRemoveEntryOptions extends FsOptions {
     readonly parent: FileStat;
     readonly expected: FileStat;
 }
+export interface ConditionalRemoveEntryReceiptOptions extends ConditionalRemoveEntryOptions {
+    readonly returnRemainingStat?: boolean | undefined;
+}
 export type ConditionalRemoveFileOptions = ConditionalRemoveEntryOptions;
 export interface FileStagingEntry {
     readonly path: string;
     readonly stat: FileStat;
 }
+export interface FileResolutionStep extends FileStagingEntry {
+    readonly linkTarget?: string;
+}
+export interface FileStagingResolution {
+    readonly path: string;
+    readonly parent: FileStat;
+    readonly destination: FileStat | null;
+    readonly ancestors: readonly FileStagingEntry[];
+    readonly traversed: readonly FileResolutionStep[];
+    readonly validate: () => true;
+}
+/** Ownership acquired with staging creation. remove is one-shot with shared
+ * completion; close drains admitted removal and releases without new mutation.
+ * Both release retained resources even after a failed removal. Call close when
+ * abandoning the staging receipt. An explicit cleanup signal is independent of
+ * the creation signal; scoped cleanup consumes the cleanup operation budget. */
+export interface FileStagingCleanup {
+    remove(options?: FsOptions): Promise<void>;
+    close(): Promise<void>;
+}
 export interface FileStaging {
     readonly parent: FileStagingEntry;
     readonly directory: FileStagingEntry;
     readonly file: FileStagingEntry;
+    readonly cleanup?: FileStagingCleanup;
 }
 export type StagedFileContent = {
     readonly type: "file";
@@ -205,6 +258,8 @@ export type StagedFileContent = {
     readonly target: string;
 };
 export interface CreateStagedFileOptions extends FsOptions {
+    /** Requires retainedStagingCleanup; unsupported backends reject before creation. */
+    readonly retainCleanup?: boolean;
     readonly parent: FileStat;
     readonly mode?: number;
     readonly atimeMs?: number;
@@ -212,6 +267,9 @@ export interface CreateStagedFileOptions extends FsOptions {
 }
 export interface PublishStagedFileOptions extends FsOptions {
     readonly ancestors?: readonly FileStagingEntry[];
+    /** Trusted, mutation-free validation. Must return literal true synchronously;
+     * a promise is not acceptance. Requires guardedStagingPublication. */
+    readonly commitGuard?: () => true;
     readonly parent: FileStat;
     readonly destination: FileStat | null;
 }
@@ -241,7 +299,10 @@ export interface FileSystem {
      * Failures before commit preserve the destination. No stat/write fallback. */
     publishFileConditional?(path: string, source: ByteSource, options: ConditionalFilePublicationOptions): Promise<FileStat>;
     writeFileConditional?(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
-    removeEntryConditional?(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
+    removeEntryConditional?(path: string, options: ConditionalRemoveEntryOptions & {
+        readonly returnRemainingStat?: false | undefined;
+    }): Promise<void>;
+    removeEntryConditional?(path: string, options: ConditionalRemoveEntryReceiptOptions): Promise<void | FileStat>;
     removeTreeConditional?(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
     removeFileConditional?(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     readonly capabilities: FileSystemCapabilities;
@@ -249,6 +310,11 @@ export interface FileSystem {
     prepareDirectory?(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     createStagedFile?(directoryPath: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     publishStagedFile?(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    /** Admit a complete canonical root-to-directory prefix and prepare a guard.
+     * The returned guard checks current identities/search access synchronously;
+     * preparation is not validation, and the guard's result is not an async lease. */
+    prepareDirectoryAncestry?(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
+    prepareStagingResolution?(path: string, options?: FsOptions): Promise<FileStagingResolution>;
     removeStagedFile?(staging: FileStaging, options?: FsOptions): Promise<void>;
     openReadFile?(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
     openResizeFile?(path: string, options?: OpenResizeFileOptions): Promise<FileResizeHandle>;
@@ -275,7 +341,7 @@ export interface FileSystem {
     readlink?(path: string, options?: FsOptions): Promise<string>;
     symlink?(target: string, path: string, options?: FsOptions): Promise<void>;
     link?(existingPath: string, newPath: string, options?: FsOptions): Promise<void>;
-    chmod?(path: string, mode: number, options?: FsOptions): Promise<void>;
+    chmod?(path: string, mode: number, options?: ChmodOptions): Promise<void>;
     utimes?(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
     truncate?(path: string, length?: number, options?: FsOptions): Promise<void>;
     readStream?(path: string, options?: ReadStreamOptions): ByteSource;

package/dist/safe-fs/contracts/io.js

@@ -1,23 +1,75 @@
 import { FsError } from "./errors.js";
 import { finishCleanup } from "./cleanup.js";
 import { platform } from "#safe-fs-platform";
+let sharedTextEncoder;
+const EMPTY_BYTES = new Uint8Array(0);
+const DONE_RESULT = Object.freeze({ done: true, value: undefined });
+const RESOLVED_DONE = Promise.resolve(DONE_RESULT);
+const readBytesSignal = Symbol.for("safe-fs.readBytesSignal");
+const EMPTY_BYTE_ITERATOR = Object.freeze({
+    [Symbol.asyncIterator]() { return this; },
+    tryNextSync() { return DONE_RESULT; },
+    next() { return RESOLVED_DONE; },
+    return() { return RESOLVED_DONE; },
+});
+const EMPTY_BYTE_SOURCE = Object.freeze({
+    [Symbol.asyncIterator]() { return EMPTY_BYTE_ITERATOR; },
+});
+const noop = () => { };
+class SingleChunkByteIterator {
+    constructor(bytes) {
+        this.bytes = bytes;
+        this.consumed = false;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    tryNextSync() {
+        if (this.consumed)
+            return DONE_RESULT;
+        this.consumed = true;
+        return { done: false, value: this.bytes };
+    }
+    next() {
+        if (this.consumed)
+            return RESOLVED_DONE;
+        this.consumed = true;
+        return Promise.resolve({ done: false, value: this.bytes });
+    }
+    return() {
+        this.consumed = true;
+        return RESOLVED_DONE;
+    }
+}
+class SingleChunkByteSource {
+    constructor(bytes) {
+        this.bytes = bytes;
+    }
+    [Symbol.asyncIterator]() {
+        return new SingleChunkByteIterator(this.bytes);
+    }
+}
 export function toByteSource(input) {
     if (typeof input !== "string" && !(input instanceof Uint8Array)) {
         throw new TypeError("Byte source input must be a string or Uint8Array");
     }
-    const bytes = typeof input === "string" ? new TextEncoder().encode(input) : new Uint8Array(input);
-    return (async function* () {
-        if (bytes.byteLength > 0)
-            yield bytes;
-    })();
+    if (typeof input === "string") {
+        if (input.length === 0)
+            return EMPTY_BYTE_SOURCE;
+    }
+    else if (input.byteLength === 0) {
+        return EMPTY_BYTE_SOURCE;
+    }
+    const bytes = typeof input === "string" ? (sharedTextEncoder ??= new TextEncoder()).encode(input) : new Uint8Array(input);
+    return new SingleChunkByteSource(bytes);
 }
 let activeCollectionBytes = 0;
 export async function collectBytes(source, options) {
     if (options.maxBytes !== undefined && options.maxBytes !== Infinity && (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0)) {
         throw new RangeError("maxBytes must be a nonnegative safe integer");
     }
-    if (options.maxMemoryBytes !== undefined && (!Number.isSafeInteger(options.maxMemoryBytes) || options.maxMemoryBytes < 0)) {
-        throw new RangeError("maxMemoryBytes must be a nonnegative safe integer");
+    if (options.maxMemoryBytes !== undefined && options.maxMemoryBytes !== Infinity && (!Number.isSafeInteger(options.maxMemoryBytes) || options.maxMemoryBytes < 0)) {
+        throw new RangeError("maxMemoryBytes must be a nonnegative safe integer or Infinity");
     }
     const memoryLimit = options.maxMemoryBytes ?? Infinity;
     let reserved = 0;
@@ -91,34 +143,164 @@ async function abortable(operation, signal) {
         }
     });
 }
-export async function* readBytes(source, signal) {
-    signal?.throwIfAborted();
-    const iterator = source[Symbol.asyncIterator]();
-    let finished = false;
-    let failed = false;
-    try {
-        while (true) {
-            const result = await abortable(() => iterator.next(), signal);
+class ReadBytesGenerator {
+    constructor(source, signal) {
+        this.source = source;
+        this.abortSignal = signal;
+        this.iterator = undefined;
+        this.nativeAbort = false;
+        this.finished = false;
+        this.closing = undefined;
+        this.turn = undefined;
+        this.readingSync = false;
+        this.syncFailure = undefined;
+    }
+    get [readBytesSignal]() {
+        return this.abortSignal;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    _schedule(action) {
+        const previous = this.turn;
+        let release;
+        const reserved = new Promise(resolve => { release = resolve; });
+        // Reserve before calling a producer, which may synchronously reenter us.
+        this.turn = reserved;
+        const result = previous
+            ? previous.then(action)
+            : this.readingSync
+                ? Promise.resolve().then(action)
+                : action();
+        const finish = () => {
+            if (this.turn === reserved)
+                this.turn = undefined;
+            release();
+        };
+        void result.then(finish, finish);
+        return result;
+    }
+    _ensureIterator() {
+        let it = this.iterator;
+        if (!it) {
+            const signal = this.abortSignal;
+            signal?.throwIfAborted();
+            it = this.source[Symbol.asyncIterator]();
+            this.iterator = it;
+            this.nativeAbort = signal !== undefined && it.abortSignal === signal;
+        }
+        return it;
+    }
+    async _cleanupIterator(failed) {
+        const signal = this.abortSignal;
+        if (!this.finished && this.iterator?.return) {
+            this.finished = true;
+            const it = this.iterator;
+            const cleanup = Promise.resolve().then(() => it.return());
+            if (signal?.aborted)
+                void cleanup.catch(noop);
+            else
+                this.closing = abortable(() => cleanup, signal).then(noop);
+        }
+        else {
+            this.finished = true;
+        }
+        if (this.closing) {
+            const pending = this.closing;
+            try {
+                await finishCleanup(() => pending, failed);
+            }
+            finally {
+                if (this.closing === pending)
+                    this.closing = undefined;
+            }
+        }
+    }
+    tryNextSync() {
+        if (this.turn || this.readingSync || this.syncFailure)
+            return undefined;
+        if (this.finished)
+            return DONE_RESULT;
+        this.readingSync = true;
+        try {
+            const it = this._ensureIterator();
+            if (typeof it.tryNextSync !== "function")
+                return undefined;
+            const signal = this.abortSignal;
+            signal?.throwIfAborted();
+            const syncResult = it.tryNextSync();
+            signal?.throwIfAborted();
+            if (syncResult === undefined)
+                return undefined;
+            if (syncResult.done) {
+                this.finished = true;
+                return DONE_RESULT;
+            }
+            if (!(syncResult.value instanceof Uint8Array))
+                throw new TypeError("Byte sources must yield Uint8Array chunks");
+            return syncResult;
+        }
+        catch (error) {
+            this.syncFailure = { reason: error };
+            return undefined;
+        }
+        finally {
+            this.readingSync = false;
+        }
+    }
+    async _runNext() {
+        if (this.finished)
+            return DONE_RESULT;
+        try {
+            if (this.syncFailure) {
+                const { reason } = this.syncFailure;
+                this.syncFailure = undefined;
+                throw reason;
+            }
+            const it = this._ensureIterator();
+            const signal = this.abortSignal;
+            signal?.throwIfAborted();
+            const syncResult = typeof it.tryNextSync === "function" ? it.tryNextSync() : undefined;
+            const result = syncResult ?? (this.nativeAbort ? await it.next() : await abortable(() => it.next(), signal));
+            signal?.throwIfAborted();
             if (result.done) {
-                finished = true;
-                return;
+                this.finished = true;
+                return DONE_RESULT;
             }
             if (!(result.value instanceof Uint8Array))
                 throw new TypeError("Byte sources must yield Uint8Array chunks");
-            yield result.value;
+            return result;
+        }
+        catch (error) {
+            await this._cleanupIterator(true);
+            throw error;
         }
     }
-    catch (error) {
-        failed = true;
-        throw error;
+    next() {
+        if (this.finished && !this.turn && !this.readingSync && !this.syncFailure && !this.closing)
+            return RESOLVED_DONE;
+        return this._schedule(() => this._runNext());
     }
-    finally {
-        if (!finished && iterator.return) {
-            const cleanup = Promise.resolve().then(() => iterator.return());
-            if (signal?.aborted)
-                void cleanup.catch(() => { });
-            else
-                await finishCleanup(() => abortable(() => cleanup, signal), failed);
+    return(value) {
+        if ((this.finished || !this.iterator?.return) && !this.turn && !this.readingSync && !this.closing && value === undefined) {
+            this.finished = true;
+            return RESOLVED_DONE;
         }
+        return this._schedule(async () => {
+            await this._cleanupIterator(false);
+            return { done: true, value: await value };
+        });
+    }
+    throw(error) {
+        return this._schedule(async () => {
+            await this._cleanupIterator(true);
+            throw error;
+        });
+    }
+}
+export function readBytes(source, signal) {
+    if (signal !== undefined && source[readBytesSignal] === signal) {
+        return source;
     }
+    return new ReadBytesGenerator(source, signal);
 }

package/dist/safe-fs/contracts/virtual-path.d.ts

@@ -1,4 +1,6 @@
-export declare function validatePath(path: string): void;
+export declare const MAX_PATH_BYTES = 65536;
+export declare const MAX_PATH_COMPONENTS = 2048;
+export declare function validatePath(path: string, maxComponents?: number): void;
 export declare function resolvePath(cwd: string, ...paths: string[]): string;
 export declare function normalizePath(path: string, cwd?: string): string;
 export declare function dirname(path: string): string;

package/dist/safe-fs/contracts/virtual-path.js

@@ -1,8 +1,27 @@
 import { FsError } from "./errors.js";
-export function validatePath(path) {
+export const MAX_PATH_BYTES = 65_536;
+export const MAX_PATH_COMPONENTS = 2048;
+export function validatePath(path, maxComponents = MAX_PATH_COMPONENTS) {
     if (typeof path !== "string" || path.includes("\0")) {
         throw new FsError("EINVAL", { syscall: "resolve", message: "paths must be strings without NUL bytes" });
     }
+    if (path.length > MAX_PATH_BYTES) {
+        throw new FsError("ENAMETOOLONG", { syscall: "resolve", path });
+    }
+    const limit = Math.min(maxComponents, MAX_PATH_COMPONENTS);
+    let components = 0;
+    let inComponent = false;
+    for (let i = 0; i < path.length; i++) {
+        if (path.charCodeAt(i) === 47) {
+            inComponent = false;
+        }
+        else if (!inComponent) {
+            inComponent = true;
+            if (++components > limit) {
+                throw new FsError("ENAMETOOLONG", { syscall: "resolve", path });
+            }
+        }
+    }
 }
 export function resolvePath(cwd, ...paths) {
     validatePath(cwd);

package/dist/safe-fs/core.d.ts

@@ -23,3 +23,4 @@ export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
 export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
+export { bindConditionalMutation, type ConditionalMutationBinding } from "./fs/memory/index.js";

package/dist/safe-fs/core.js

@@ -19,3 +19,4 @@ export { compareEntries, registerEntryView } from "./fs/mount/comparison.js";
 export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
+export { bindConditionalMutation } from "./fs/memory/index.js";

package/dist/safe-fs/fs/capabilities.d.ts

@@ -7,4 +7,4 @@ export declare function openRetainedResizeFile(filesystem: FileSystem, path: str
 export declare function readOnlyCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function quotaCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function ownedMutationCapabilities(filesystem: FileSystem, capabilities?: FileSystemCapabilities): FileSystemCapabilities;
-export declare function requireOwnedMutation(filesystem: FileSystem, path: string, capability: "atomicFilePublication" | "atomicEntryRemoval" | "atomicTreeRemoval" | "atomicFileMutation" | "atomicFileStaging" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;
+export declare function requireOwnedMutation(filesystem: FileSystem, path: string, capability: "retainedStagingCleanup" | "atomicFilePublication" | "atomicEntryRemoval" | "atomicEntryRemovalReceipt" | "atomicTreeRemoval" | "atomicFileMutation" | "atomicFileStaging" | "guardedStagingPublication" | "atomicStagingAncestry" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;