@poe-platform/safe-fs 0.1.807 → 0.1.808

package/README.md

@@ -4,6 +4,13 @@ An asynchronous filesystem interface for memory, rooted host directories, S3, an
 
 Under `workerd` and `browser` conditions, the root export includes portable filesystems, `S3FileSystem`, and `MockS3Client`. Supply an S3 transport to use object storage without Node globals.
 
+The `storage` subpath exposes `PagedStorage` and `IntegerTable` for temporary
+working data. Supply `{fs, cwd, env, signal}` and an optional page-cache count
+(default 64 pages of 16 KiB). Scratch data uses retained positioned handles in
+`env.TMPDIR` or `cwd`, with conditional unlink and cleanup through `close()`.
+Providers must support those capabilities; there is no host fallback. Use an
+external backend for large data because memory filesystems retain spilled bytes.
+
 ## Quickstart
 
 Install the standalone package; it does not depend on SafeJS, Safe Bash, or the `poe-code` CLI. These examples use TypeScript in a Node ESM application.
@@ -79,9 +86,11 @@ cause. Preserve cancellation/control exceptions separately. Cross-family
 | Change the namespace | `mkdir`, `rm`, `rename`, `copyFile` |
 | Remove an empty directory | Optional `rmdir`; never a recursive-delete fallback |
 | Links and metadata | Optional `readlink`, `symlink`, `link`, `chmod`, `utimes`, `truncate` |
+| Enumerate directories lazily | Optional `iterateDirectory`; memory, native and paged S3 backends, with mount/overlay/readonly/quota/device/scoped delegation; backend order, no sorted-array fallback |
 | Stream bytes | Optional `readStream`, `writeStream`, using async iterables of byte chunks |
 | Retain an open file | Optional `open` with positioned I/O and synchronization; memory and real backends support `noFollow: true` to atomically refuse a final symlink |
 | Publish immutable objects atomically | Optional `publishFileConditional` with opaque identity/version stats and authoritative compare-and-publish |
+| Publish a checked source set | Optional `publishStagedFileSet` publishes a staged file and retires sibling entries in one backend commit; mount views require all entries on the same supporting backend |
 | Compare backing entries | Optional `compareEntry`, returning `same`, `distinct`, or `unknown` |
 
 All required methods must exist, but a backend may reject an operation with `FsError`, such as `EROFS` for a write or `ENOTSUP` for unsupported semantics. Check optional methods and `capabilities` rather than assuming every backend behaves like a local disk. Errors expose `code` and may include `syscall`, `path`, `dest`, and `cause`.
@@ -295,6 +304,16 @@ Every raw filesystem operation accepts an optional `signal`. Additional fields a
 
 `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).
 
+Overlay copy-up, copy, stream replacement/append and resize transfer retained ranges in 64 KiB chunks through the injected upper's stream writer. Resize streams the retained prefix and bounded zero chunks. Stream writes stage input before publication; cancellation or transfer failure leaves the destination unchanged and cleans staging. Stock Memory overlays transfer staged storage into existing upper inodes, preserving hardlinks without an additional whole-file buffer. `readFile` and `writeFile` remain buffering convenience APIs; use `readStream`/`writeStream` for large payloads. `maxBufferBytes` retains its existing optional total-byte admission semantics, not a working-memory guarantee.
+
+A streaming overlay needs an upper with `atomicRename`, `streamingWrite`, retained reads (`retainedRead` plus `openReadFile`), exclusive create, directory mutation, permissions and timestamps. Both layers must provide retained, bounded range reads with stable file and directory identities. For example, inject these host-authorized adapters with `createOverlayFileSystem({ upper: externalSpool, lower: retainedSource })`, then use `overlay.writeStream(path, source)`. The upper must await each consumed chunk, keep transport queues bounded, and preserve ownership until publication. Supply bounded chunks at the input boundary; the overlay cannot undo a payload-wide allocation already made by its caller. Whole-file-only uppers explicitly reject transfer operations with `ENOTSUP`; they do not silently collect streams.
+
+For Workers, `externalSpool` must store payloads outside isolate RAM and satisfy that contract, including atomic rename and retained identity. Memory and the S3 mock store payloads in RAM and are not external spools. Stock S3/WebDAV do not provide the atomic rename/retained-read contract needed for an overlay upper; setting a capability flag does not add it. A host must inject a qualified external adapter. On Node, rooted Real adapters provide the streaming overlay configuration under their documented external-tree isolation requirement. Mount and read-only wrappers forward the selected backend's capabilities; quota streaming additionally requires a real streaming-append route. S3's buffered append convenience path reports `streamingAppend: false`.
+
+The reusable metadata-only fixture in [`tests/fixtures/bounded-filesystem.ts`](tests/fixtures/bounded-filesystem.ts) generates file ranges and consumes slow writes without storing payload bytes. [`tests/overlay-bounded.test.ts`](tests/overlay-bounded.test.ts) checks fixed transfer sizes, source backpressure, cancellation/error cleanup, byte results, and Memory publication allocation/identity. These deterministic conformance checks do not qualify a deployed Worker backend; follow the [Worker QA plan](../../docs/plans/safe-fs-bounded-overlay-qa.md) for runtime measurements.
+
+`readFileStream(fs, path, options)` reads through the caller's native stream or retained range handle without calling `readFile`. It accepts the stream range/window options above, defaults to a 64 KiB read window, and closes owned readers on completion, failure or cancellation. `skipStream: true` selects retained ranges after an already-attempted stream reports `ENOTSUP`. Chunks are borrowed until the iterator advances. Native adapters must honor the requested window and backpressure. Whole-file-only backends receive `ENOTSUP`; use a streaming or retained-range backend for sequential Worker operations. This helper bounds its I/O window, not the consuming command's parser or output capture.
+
 `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`. Collection limits are disabled by default on Node, browser, and Worker targets. Each call owns its budget; concurrent collections do not consume one another’s allowance. The returned view may retain geometric spare capacity. Configured budgets cover 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>

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

@@ -352,6 +352,11 @@ export interface FileSystem {
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
     compareEntry?(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    /** Optional bounded, lazy directory enumeration in backend-defined order.
+     * No complete listing/sort fallback. Consumers must retire the iterator on
+     * early exit. Namespace changes may reject or follow the backend's live view;
+     * this is not a tree snapshot or a retained path-authority grant. */
+    iterateDirectory?(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
     /** Atomic final-entry removal; every directory is refused, including raced replacements. */

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

@@ -17,3 +17,5 @@ export * from "./fs/s3/http/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
+export { readFileStream } from "./fs/read-file-stream.js";
+export { PagedStorage, IntegerTable, type PagedStorageContext } from "./storage.js";

package/dist/safe-fs/core.js

@@ -15,3 +15,5 @@ export * from "./fs/s3/index.js";
 export * from "./fs/s3/http/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
+export { readFileStream } from "./fs/read-file-stream.js";
+export { PagedStorage, IntegerTable } from "./storage.js";

package/dist/safe-fs/fs/capabilities.js

@@ -141,8 +141,8 @@ export function readOnlyCapabilities(capabilities) {
     });
 }
 export function quotaCapabilities(capabilities) {
-    const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, !capabilities.readOnly);
-    const streamingAppend = requireCapabilities(capabilities.append, !capabilities.readOnly);
+    const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, capabilities.streamingAppend, !capabilities.readOnly);
+    const streamingAppend = requireCapabilities(capabilities.append, capabilities.streamingAppend, !capabilities.readOnly);
     const { streamingWrite: ignoredWrite, streamingAppend: ignoredAppend, ...rest } = capabilities;
     return Object.freeze({ ...rest, synchronousStagingResolution: false, retainedStagingCleanup: false, retainedStagingWrite: false, atomicStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),

package/dist/safe-fs/fs/devices/index.d.ts

@@ -25,6 +25,7 @@ export declare class DeviceFileSystem implements FileSystem {
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;

package/dist/safe-fs/fs/devices/index.js

@@ -490,6 +490,40 @@ export class DeviceFileSystem {
             throw new FsError("ENOTSUP", { path });
         await this.#filesystem.writeStream(path, source, options);
     }
+    async *iterateDirectory(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath)
+            throw new FsError("ENOTDIR", { syscall: "iterateDirectory", path });
+        const virtual = resolved === "/" ? "dev" : resolved === deviceDirectory ? "null" : undefined;
+        if (!this.#filesystem.iterateDirectory)
+            throw new FsError("ENOTSUP", { syscall: "iterateDirectory", path });
+        let seen = false;
+        try {
+            for await (const entry of this.#filesystem.iterateDirectory(virtual ? resolved : path, options)) {
+                options.signal?.throwIfAborted();
+                if (entry.name === "." || entry.name === "..")
+                    continue;
+                if (!entry.name || entry.name.includes("/") || entry.name.includes("\0"))
+                    throw new FsError("EIO", { path, message: "invalid directory entry" });
+                if (entry.name === virtual) {
+                    if (seen)
+                        continue;
+                    seen = true;
+                    yield { name: virtual, type: virtual === "dev" ? "directory" : "character" };
+                }
+                else
+                    yield { name: entry.name, type: entry.type };
+            }
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            if (!virtual || !isFsError(error, "ENOENT") && !isFsError(error, "ENOTDIR"))
+                throw error;
+        }
+        options.signal?.throwIfAborted();
+        if (virtual && !seen)
+            yield { name: virtual, type: virtual === "dev" ? "directory" : "character" };
+    }
     readdir(path, options = {}) {
         const fast = this.#tryResolveSync(path, options);
         if (fast !== undefined && fast !== "/") {
@@ -656,8 +690,12 @@ export class DeviceFileSystem {
         const capabilities = await this.#filesystem.capabilitiesFor?.(destination, { ...options, create: options.destination === null }) ?? this.#filesystem.capabilities;
         if (capabilities.readOnly === true)
             throw new FsError("EROFS", { path: destination });
-        for (const path of [staging.parent.path, staging.directory.path])
-            await this.#mutable(path, options, false);
+        // The parent is an identity guard, not an entry being replaced. Root is a
+        // valid parent; the synthetic device directory still cannot own staging.
+        const parentPath = await this.#resolve(staging.parent.path, options, false);
+        if (parentPath === deviceDirectory || parentPath === nullPath)
+            throw new FsError("EBUSY", { path: staging.parent.path });
+        await this.#mutable(staging.directory.path, options, false);
         const guards = [];
         if (options.ancestors)
             guards.push(await this.prepareDirectoryAncestry(options.ancestors, options));

package/dist/safe-fs/fs/memory/atomic-view.d.ts

@@ -1,6 +1,7 @@
 import type { FileStat, FileSystem } from "../../contracts/filesystem.js";
 /** Internal authority: inspections and stock mutations share one JavaScript turn. */
 export interface MemoryAtomicView {
+    replaceContents(source: string, destination: string): void;
     stat(path: string): FileStat | undefined;
     names(path: string): readonly string[];
 }

package/dist/safe-fs/fs/memory/index.d.ts

@@ -49,6 +49,9 @@ type OwnedStore = {
     root: DirectoryNode;
     ledger: MemoryLedger;
     capabilities: FileSystem["capabilities"];
+    customCapabilities?: FileSystemCapabilities;
+    identityScope?: symbol;
+    atomicView?: MemoryAtomicView;
     intact: () => boolean;
 };
 export interface ConditionalMutationBinding {
@@ -59,7 +62,6 @@ export interface ConditionalMutationBinding {
 }
 export declare function bindConditionalMutation<Result>(identityScope: object | symbol | undefined, binding: ConditionalMutationBinding, action: () => Promise<Result>): Promise<Result>;
 export declare class MemoryFileSystem implements FileSystem {
-    #private;
     capabilitiesFor?: NonNullable<FileSystem["capabilitiesFor"]>;
     private get identityScope();
     get capabilities(): FileSystemCapabilities;
@@ -132,6 +134,7 @@ export declare class MemoryFileSystem implements FileSystem {
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     tryMkdirFastSync(path: string, recursive: boolean, mode: number | undefined): boolean;
     tryRmFastSync(path: string, recursive: boolean, force: boolean): boolean;

package/dist/safe-fs/fs/memory/index.js

@@ -405,6 +405,7 @@ const ext4HtreeEof64 = (1n << 63n) - 1n;
 const extractionStreamGuard = Symbol("extractionStreamGuard");
 const ownedStats = new WeakMap();
 const ownedStores = new WeakMap();
+const receiverCapabilities = new WeakMap();
 // Ensure V8 uses Tagged representation for timestamp fields so all 4 fields share one HeapNumber pointer.
 {
     const dummyAlloc = new MemoryAllocation(new Uint8Array(0), new MemoryLedger(normalizeMemoryFileSystemLimits({})));
@@ -601,17 +602,24 @@ function customMemoryCapabilities(filesystem) {
 }
 export class MemoryFileSystem {
     capabilitiesFor;
-    #customCapabilities;
-    #identityScopeSym;
     get identityScope() {
-        return (this.#identityScopeSym ??= Symbol());
+        return (this._owner.identityScope ??= Symbol());
     }
     get capabilities() {
-        if (!this.#customCapabilities) {
-            this.#customCapabilities = customMemoryCapabilities(this);
-            this._owner.capabilities = this.#customCapabilities;
+        const owner = ownedStores.get(this);
+        if (owner) {
+            if (!owner.customCapabilities) {
+                owner.customCapabilities = customMemoryCapabilities(this);
+                owner.capabilities = owner.customCapabilities;
+            }
+            return owner.customCapabilities;
+        }
+        let caps = receiverCapabilities.get(this);
+        if (!caps) {
+            caps = customMemoryCapabilities(this);
+            receiverCapabilities.set(this, caps);
         }
-        return this.#customCapabilities;
+        return caps;
     }
     nextInode = 1;
     ledger;
@@ -621,7 +629,6 @@ export class MemoryFileSystem {
     root;
     totalBytes = 0;
     symlinkCount = 0;
-    #atomicView;
     _getAtomicView() {
         const owner = ownedStores.get(this);
         if (!owner ||
@@ -648,7 +655,27 @@ export class MemoryFileSystem {
                     return undefined;
             }
         }
-        return this.#atomicView ??= {
+        return owner.atomicView ??= {
+            replaceContents: (source, destination) => {
+                const from = this.entry(source, "overlayAtomicView").node;
+                const to = this.entry(destination, "overlayAtomicView").node;
+                if (from?.type !== "file" || to?.type !== "file" || from === to || from.nlink !== 1)
+                    this.fail("EINVAL", "overlayAtomicView", destination);
+                this.permission(to, 2, "overlayAtomicView", destination);
+                // Exchange owned storage, preserving destination inode/hardlinks and
+                // retained allocation snapshots. Stage cleanup releases the old contents.
+                const allocation = to.allocation, length = to.byteLength;
+                to.allocation = from.allocation;
+                to.byteLength = from.byteLength;
+                from.allocation = allocation;
+                from.byteLength = length;
+                to.view = undefined;
+                from.view = undefined;
+                to.sourceRef = undefined;
+                from.sourceRef = undefined;
+                this.changed(to);
+                this.changed(from);
+            },
             stat: (path) => {
                 this.validatePath(path, "overlayAtomicView");
                 let node = this.root;
@@ -2481,6 +2508,26 @@ export class MemoryFileSystem {
         ownedStats.set(stat, { filesystem: this, path, root: this.root });
         return stat;
     }
+    async *iterateDirectory(path, options = {}) {
+        options.signal?.throwIfAborted();
+        const root = this.root, node = this.resolveNode(path, "iterateDirectory", true);
+        if (node.type !== "directory")
+            this.fail("ENOTDIR", "iterateDirectory", path);
+        this.permission(node, 4, "iterateDirectory", path);
+        const revision = node.revision, ino = node.ino;
+        const check = () => {
+            options.signal?.throwIfAborted();
+            if (this.root !== root || node.ino !== ino || node.revision !== revision || this.resolveNode(path, "iterateDirectory", true) !== node)
+                this.fail("EBUSY", "iterateDirectory", path);
+            this.permission(node, 4, "iterateDirectory", path);
+        };
+        node.atimeMs = Date.now();
+        for (const [name, entry] of node.entries) {
+            check();
+            yield { name, type: entry.type };
+        }
+        check();
+    }
     async readdir(path, options = {}) {
         const limit = directoryEntryLimit(options, path);
         const node = this.resolveNode(path, "readdir", true);

package/dist/safe-fs/fs/mount/index.d.ts

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
 export interface MountFileSystemOptions {
@@ -40,6 +40,7 @@ export declare class MountFileSystem implements FileSystem {
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rmdir(path: string, options?: FsOptions): Promise<void>;
     unlink(path: string, options?: FsOptions): Promise<void>;
@@ -55,6 +56,7 @@ export declare class MountFileSystem implements FileSystem {
     removeTreeConditional(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
     createStagedFile(path: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    publishStagedFileSet(staging: FileStaging, destination: string, supplied: PublishStagedFileSetOptions): Promise<FileStat>;
     removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
     prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     rename(source: string, destination: string, options?: RenameOptions): Promise<void>;

package/dist/safe-fs/fs/mount/index.js

@@ -219,7 +219,7 @@ export class MountFileSystem {
                     && await this.supportsDirectoryValidation(location.path.slice(0, location.path.lastIndexOf("/")) || "/", options, true)
                 : this.capabilities.conditionalChmod;
             const { synchronousDirectoryValidation: ignoredValidation, synchronousStagingResolution: ignoredResolution, ...ordinary } = resize;
-            const withOpen = { ...ordinary, retainedStagingWrite: false, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
+            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
             const capabilities = location.synthetic ? { ...withOpen, open: false, retainedRead: false }
                 : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, withOpen));
             if (location.synthetic)
@@ -483,7 +483,7 @@ export class MountFileSystem {
             release = await this.acquireNamespace(options, [
                 "rename", "symlink", "link", "unlink", "rm", "rmdir",
                 "removeEntryConditional", "removeFileConditional", "removeTreeConditional",
-                "publishStagedFile", "removeStagedFile",
+                "publishStagedFile", "publishStagedFileSet", "removeStagedFile",
             ].includes(syscall));
             const result = await action();
             if (!preserveReceipt)
@@ -802,6 +802,76 @@ export class MountFileSystem {
             return [...entries.values()].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
         });
     }
+    async *iterateDirectory(path, options = {}) {
+        try {
+            const location = await this.operation("iterateDirectory", path, options, async () => {
+                const resolved = await this.resolve(path, options);
+                if (resolved.stat?.type !== "directory")
+                    fail("ENOTDIR");
+                return resolved;
+            });
+            // Only configured mount children are retained, never backend entries.
+            const mounted = new Set();
+            for (const mount of this.mounts) {
+                if (mount.path !== location.path && within(location.path, mount.path)) {
+                    const suffix = mount.path.slice(location.path === "/" ? 1 : location.path.length + 1);
+                    mounted.add(suffix.split("/")[0]);
+                }
+            }
+            const admit = async () => {
+                const current = await this.resolve(path, options);
+                if (current.path !== location.path || current.mount !== location.mount ||
+                    current.local !== location.local || current.synthetic !== location.synthetic ||
+                    current.stat?.type !== "directory")
+                    fail("EBUSY");
+            };
+            if (!location.synthetic) {
+                const iterator = await this.operation("iterateDirectory", path, options, async () => {
+                    await admit();
+                    const backend = location.mount.backend;
+                    if (!backend.iterateDirectory)
+                        fail("ENOTSUP");
+                    return backend.iterateDirectory(location.local, options)[Symbol.asyncIterator]();
+                }, undefined, true); // Transfer ownership before checking cancellation on the first pull.
+                // Admission covers each backend pull, but never a consumer pause. In
+                // particular, caller-backed traversal may publish scratch files between pulls.
+                let complete = false, failed = false;
+                try {
+                    while (true) {
+                        const result = await this.operation("iterateDirectory", path, options, async () => {
+                            await admit();
+                            return iterator.next();
+                        });
+                        if (result.done) {
+                            complete = true;
+                            break;
+                        }
+                        const { name, type } = result.value;
+                        if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\0"))
+                            fail("EIO");
+                        if (!mounted.has(name))
+                            yield { name, type };
+                    }
+                }
+                catch (error) {
+                    failed = true;
+                    throw error;
+                }
+                finally {
+                    if (!complete)
+                        await finishCleanup(() => iterator.return?.(), failed);
+                }
+            }
+            for (const name of mounted) {
+                await this.operation("iterateDirectory", path, options, admit);
+                yield { name, type: "directory" };
+            }
+            options.signal?.throwIfAborted();
+        }
+        catch (error) {
+            throw this.error(error, "iterateDirectory", path, options);
+        }
+    }
     mkdir(path, options = {}) {
         return this.operation("mkdir", path, options, async () => {
             const directories = new Map();
@@ -973,7 +1043,11 @@ export class MountFileSystem {
                     return Object.freeze(staging);
                 const backendCleanup = receipt.cleanup;
                 const cleanup = createStagingCleanup(staging.directory.path, controls => this.operation("removeStagedFile", staging.directory.path, controls, () => backendCleanup.remove(controls), undefined, true), () => backendCleanup.close());
-                return Object.freeze({ ...staging, cleanup });
+                const writer = receipt.writer;
+                return Object.freeze({ ...staging, cleanup, ...(writer ? { writer: Object.freeze({
+                            write: (bytes, controls = {}) => this.operation("stagedWrite", staging.file.path, controls, () => writer.write(bytes, controls), undefined, true),
+                            finish: (controls = {}) => this.operation("stagedFinish", staging.file.path, controls, async () => snapshotStat(await writer.finish(controls)), undefined, true),
+                        }) } : {}) });
             }
             catch (error) {
                 await finishCleanup(() => receipt.cleanup?.close(), true);
@@ -1065,6 +1139,83 @@ export class MountFileSystem {
             });
         }, destination, true);
     }
+    async publishStagedFileSet(staging, destination, supplied) {
+        const entry = (value) => ({ path: value.path, stat: snapshotStat(value.stat) });
+        staging = { parent: entry(staging.parent), directory: entry(staging.directory), file: entry(staging.file) };
+        const options = {
+            ...supplied, parent: snapshotStat(supplied.parent),
+            destination: supplied.destination === null ? null : snapshotStat(supplied.destination),
+            companions: supplied.companions.map(value => ({ ...value, expected: value.expected === null ? null : snapshotStat(value.expected) })),
+            ...(supplied.ancestors === undefined ? {} : { ancestors: snapshotDirectoryAncestry(supplied.ancestors) }),
+        };
+        return this.operation("publishStagedFileSet", staging.file.path, options, async () => {
+            validatePath(destination);
+            if (normalizePath(globalPath(destination)) !== destination || destination === "/")
+                fail("EINVAL");
+            const parent = destination.slice(0, destination.lastIndexOf("/")) || "/";
+            const paths = new Set([destination]);
+            for (const companion of options.companions) {
+                validatePath(companion.path);
+                if (normalizePath(globalPath(companion.path)) !== companion.path || paths.has(companion.path) ||
+                    (companion.path.slice(0, companion.path.lastIndexOf("/")) || "/") !== parent)
+                    fail("EINVAL");
+                paths.add(companion.path);
+            }
+            const ancestors = options.ancestors;
+            if (ancestors && ancestors.at(-1)?.path !== parent)
+                fail("EINVAL");
+            const guard = ancestors ? await this.prepareAncestry(ancestors, options) : undefined;
+            const local = await this.localStaging(staging, options);
+            const target = await this.resolve(destination, options, { followFinal: false, entry: true, allowMissing: true });
+            if (this.protected(target.path))
+                fail("EBUSY");
+            if (local.mount !== target.mount)
+                fail("EXDEV");
+            if (ancestors && target.path !== destination)
+                fail("EAGAIN");
+            this.mutable(target);
+            const backend = local.mount.backend;
+            if (!backend.publishStagedFileSet)
+                fail("ENOTSUP");
+            await requireOwnedMutation(backend, local.staging.directory.path, "atomicFileStaging", options);
+            await requireOwnedMutation(backend, target.local, "atomicFileStaging", options, options.destination === null);
+            const companions = [];
+            for (const companion of options.companions) {
+                const resolved = await this.resolve(companion.path, options, { followFinal: false, entry: true, allowMissing: true });
+                if (this.protected(resolved.path))
+                    fail("EBUSY");
+                if (resolved.mount !== target.mount)
+                    fail("EXDEV");
+                this.mutable(resolved);
+                companions.push({ ...companion, path: resolved.local });
+            }
+            let localAncestors;
+            if (ancestors) {
+                const first = ancestors.findIndex(value => value.path === target.mount.path);
+                if (first < 0)
+                    fail("EINVAL");
+                localAncestors = ancestors.slice(first).map(value => ({
+                    path: target.mount.path === "/" ? value.path : value.path.slice(target.mount.path.length) || "/", stat: value.stat,
+                }));
+            }
+            const callerGuard = options.commitGuard;
+            if (guard || callerGuard !== undefined)
+                await requireOwnedMutation(backend, target.local, "guardedStagingPublication", options, options.destination === null);
+            // One backend performs all version checks and the indivisible commit.
+            // The namespace lock covers admission through its committed receipt.
+            return snapshotStat(await backend.publishStagedFileSet(local.staging, target.local, {
+                ...options, companions,
+                ...(localAncestors === undefined ? {} : { ancestors: localAncestors }),
+                ...(guard || callerGuard !== undefined ? { commitGuard: () => {
+                        if (callerGuard !== undefined)
+                            runStagingGuard(callerGuard);
+                        if (guard)
+                            runStagingGuard(guard);
+                        return true;
+                    } } : {}),
+            }));
+        }, destination, true);
+    }
     removeStagedFile(staging, options = {}) {
         return this.operation("removeStagedFile", staging.directory.path, options, async () => {
             const local = await this.localStaging(staging, options);

package/dist/safe-fs/fs/overlay/index.d.ts

@@ -64,6 +64,7 @@ export declare class OverlayFileSystem implements FileSystem {
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
     compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").EntryComparison>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     realpath(path: string, options?: FsOptions): Promise<string>;
     access(path: string, requestedMode?: number, options?: FsOptions): Promise<void>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
@@ -82,6 +83,7 @@ export declare class OverlayFileSystem implements FileSystem {
     readStream(path: string, options?: ReadStreamOptions): ByteSource;
     private bounded;
     private streamToUpper;
+    private entryBytes;
     writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
 }
 export declare function createOverlayFileSystem(options: OverlayFileSystemOptions): OverlayFileSystem;