@poe-platform/safe-fs 0.1.807 → 0.1.809

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({})));
@@ -583,8 +584,8 @@ const SHARED_STOCK_MEMORY_CAPABILITIES = Object.freeze({
     permissions: true,
     timestamps: true,
     atomicRename: true,
-    atomicFileStaging: true, retainedStagingCleanup: true, retainedStagingWrite: true, atomicStagingAncestry: true, atomicFileMutation: true, atomicEntryRemoval: true, atomicEntryRemovalReceipt: true, atomicTreeRemoval: true,
-    synchronousDirectoryValidation: true, synchronousStagingResolution: true, guardedStagingPublication: true,
+    atomicStagedFileMutation: true, atomicFileStaging: true, retainedStagingCleanup: true, retainedStagingWrite: true, atomicStagingAncestry: true, atomicFileMutation: true, atomicEntryRemoval: true, atomicEntryRemovalReceipt: true, atomicTreeRemoval: true,
+    synchronousDirectoryValidation: true, synchronousStagingResolution: true, synchronousFollowedStagingResolution: true, guardedStagingPublication: true,
     atomicDirectoryMetadata: true,
     streamingRead: true,
     retainedRead: true,
@@ -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;
         }
-        return this.#customCapabilities;
+        let caps = receiverCapabilities.get(this);
+        if (!caps) {
+            caps = customMemoryCapabilities(this);
+            receiverCapabilities.set(this, caps);
+        }
+        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;
@@ -2159,13 +2186,14 @@ export class MemoryFileSystem {
         return () => this.verifyDirectoryAncestry(entries, controls);
     }
     async prepareStagingResolution(path, options = {}) {
+        const followFinal = options.followFinalSymlink === true;
         const controls = options.signal === undefined ? {} : { signal: options.signal };
         controls.signal?.throwIfAborted();
         this.validatePath(path, "prepareStagingResolution");
         if (!path.startsWith("/") || normalizePath(path) !== path)
             this.fail("EINVAL", "prepareStagingResolution", path);
         const traversed = [];
-        const location = this.resolve(path, "prepareStagingResolution", { followFinal: false, allowMissing: true, resolutionSteps: traversed });
+        const location = this.resolve(path, "prepareStagingResolution", { followFinal, allowMissing: true, resolutionSteps: traversed });
         if (location.node && location.node.type !== "file")
             this.fail("ENOTSUP", "prepareStagingResolution", path);
         const parentPath = location.path.slice(0, location.path.lastIndexOf("/")) || "/";
@@ -2180,7 +2208,7 @@ export class MemoryFileSystem {
             const currentSteps = [];
             let current;
             try {
-                current = this.resolve(path, "verifyStagingResolution", { followFinal: false, allowMissing: true, resolutionSteps: currentSteps });
+                current = this.resolve(path, "verifyStagingResolution", { followFinal, allowMissing: true, resolutionSteps: currentSteps });
             }
             catch (error) {
                 if (error instanceof FsError && ["ENOENT", "ENOTDIR", "ELOOP"].includes(error.code))
@@ -2218,6 +2246,7 @@ export class MemoryFileSystem {
     }
     async publishStagedFile(receipt, destination, options) {
         const signal = options.signal;
+        const preserveIdentity = options.preserveIdentity === true;
         const guard = options.commitGuard;
         const ancestors = options.ancestors === undefined ? undefined : snapshotDirectoryAncestry(options.ancestors);
         const snapshot = (entry) => ({ path: entry.path, stat: { ...entry.stat } });
@@ -2245,9 +2274,48 @@ export class MemoryFileSystem {
             this.fail("EINVAL", "publishStagedFile", destination);
         if (target.node && target.node.type !== "file")
             this.fail("EAGAIN", "publishStagedFile", destination);
+        if (preserveIdentity) {
+            if (this.capabilities.atomicStagedFileMutation !== true)
+                this.fail("ENOTSUP", "publishStagedFile", destination);
+            if (file.node?.type !== "file" || target.node?.type !== "file" || expected === null)
+                this.fail("EINVAL", "publishStagedFile", destination);
+            this.permission(file.parent, 3, "publishStagedFile", staging.file.path);
+            this.permission(target.parent, 3, "publishStagedFile", destination);
+            this.permission(target.node, 2, "publishStagedFile", destination);
+            // Provider-owned storage is copied directly, without assembling an archive
+            // in caller memory. Preserve retained staging readers and independent writes.
+            this.admitSize(target.node, file.node.byteLength, "publishStagedFile", destination);
+            const allocation = this.allocate(file.node.byteLength, "publishStagedFile", destination);
+            try {
+                for (let offset = 0; offset < file.node.byteLength; offset += 65536) {
+                    allocation.data.set(file.node.data.subarray(offset, offset + 65536), offset);
+                }
+            }
+            catch (error) {
+                allocation.release();
+                throw error;
+            }
+            // No awaits or overridable operations occur between admission and commit.
+            const now = Date.now();
+            this.replaceData(target.node, allocation);
+            this.changed(target.node, now);
+            target.node.atimeMs = file.node.atimeMs;
+            target.node.mtimeMs = file.node.mtimeMs;
+            file.parent.entries.delete(file.name);
+            this.ledger.release(file.name.length * 2, 1);
+            file.node.nlink--;
+            file.node.ctimeMs = now;
+            file.node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, file.node.revision + 1);
+            this.releaseNode(file.node);
+            this.changed(file.parent, now);
+            memoryCaches.get(this.ledger).clearWrites();
+            return;
+        }
         return MemoryFileSystem.prototype.rename.call(this, staging.file.path, destination, { ...controls, noReplace: expected === null });
     }
     async publishStagedFileSet(receipt, destination, options) {
+        if (options.preserveIdentity)
+            this.fail("ENOTSUP", "publishStagedFileSet", destination);
         const signal = options.signal;
         const guard = options.commitGuard;
         const ancestors = options.ancestors === undefined ? undefined : snapshotDirectoryAncestry(options.ancestors);
@@ -2481,6 +2549,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, PrepareStagingResolutionOptions, 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 {
@@ -18,7 +18,7 @@ export declare class MountFileSystem implements FileSystem {
     private supportsStagingAncestry;
     private supportsDirectoryValidation;
     prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
-    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    prepareStagingResolution(path: string, options?: PrepareStagingResolutionOptions): Promise<FileStagingResolution>;
     private prepareAncestry;
     private protected;
     openReadFile(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
@@ -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

@@ -109,6 +109,7 @@ export class MountFileSystem {
                 retainedStagingCleanup: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
                 synchronousDirectoryValidation: ["prepareDirectoryAncestry"], guardedStagingPublication: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
                 trustedOwnedStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory"],
+                atomicStagedFileMutation: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
                 atomicFilePublication: ["publishFileConditional"], atomicEntryRemoval: ["removeEntryConditional"], atomicEntryRemovalReceipt: ["removeEntryConditional"], atomicTreeRemoval: ["removeTreeConditional"], atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
                 symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"], timestamps: ["utimes"], readlink: ["readlink"],
                 descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
@@ -128,7 +129,7 @@ export class MountFileSystem {
             return values.every(value => value === true) ? true : values.every(value => value === false) ? false : undefined;
         };
         const semantics = Object.fromEntries([
-            "guardedStagingPublication", "retainedStagingCleanup", "atomicEntryRemovalReceipt",
+            "guardedStagingPublication", "retainedStagingCleanup", "atomicEntryRemovalReceipt", "atomicStagedFileMutation",
             "trustedOwnedStaging", "atomicFilePublication", "atomicEntryRemoval", "atomicTreeRemoval", "atomicFileMutation", "atomicFileStaging", "atomicDirectoryMetadata", "read", "stat", "readdir", "realpath", "access", "open", "versionedDescriptors",
             "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
             "remove", "removeDirectory", "recursiveRemove", "rename", "atomicRenameNoReplace", "copy", "exclusiveCopy", "readlink", "truncate",
@@ -190,7 +191,8 @@ export class MountFileSystem {
                 fail("EINVAL");
             const location = await this.resolve(path, options, {
                 allowMissing: options.create ?? true,
-                followFinal: options.stagingResolution !== true && (options.create !== undefined || options.creation !== "exclusive"),
+                retainedResolution: options.stagingResolution === true && options.followFinalSymlink === true,
+                followFinal: options.stagingResolution === true ? options.followFinalSymlink === true : options.create !== undefined || options.creation !== "exclusive",
                 ...(options.create === undefined ? {} : { resizeCreate: options.create }),
             });
             const observed = ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(location.local, options)
@@ -211,15 +213,15 @@ export class MountFileSystem {
                     const input = location.mount.path === "/" ? path : path.slice(location.mount.path.length) || "/";
                     const declared = input === location.local ? resize : ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(input, options) ?? location.mount.backend.capabilities);
                     options.signal?.throwIfAborted();
-                    resolution = declared.synchronousStagingResolution === true && await this.supportsStagingAncestry(location, resize, options);
+                    resolution = declared.synchronousStagingResolution === true && (options.followFinalSymlink !== true || declared.synchronousFollowedStagingResolution === true) && await this.supportsStagingAncestry(location, resize, options);
                 }
             }
             const conditionalChmod = options.conditionalChmod === true
                 ? resize.conditionalChmod === true && typeof location.mount.backend.chmod === "function"
                     && 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 { synchronousDirectoryValidation: ignoredValidation, synchronousStagingResolution: ignoredResolution, synchronousFollowedStagingResolution: ignoredFollowedResolution, ...ordinary } = resize;
+            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution, ...(options.followFinalSymlink === true ? { synchronousFollowedStagingResolution: 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)
@@ -263,19 +265,19 @@ export class MountFileSystem {
         return this.operation("prepareDirectoryAncestry", ancestors.at(-1)?.path ?? "/", options, () => this.prepareAncestry(ancestors, options));
     }
     prepareStagingResolution(path, options = {}) {
-        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        const controls = { ...(options.signal === undefined ? {} : { signal: options.signal }), ...(options.followFinalSymlink === true ? { followFinalSymlink: true } : {}) };
         return this.operation("prepareStagingResolution", path, controls, async () => {
             if (normalizePath(globalPath(path)) !== path)
                 fail("EINVAL");
             const observed = [];
-            const location = await this.resolve(path, controls, { followFinal: false, allowMissing: true, resolutionSteps: observed });
+            const location = await this.resolve(path, controls, { followFinal: controls.followFinalSymlink === true, retainedResolution: controls.followFinalSymlink === true, allowMissing: true, resolutionSteps: observed });
             if (location.synthetic || !within(location.mount.path, path))
                 fail("ENOTSUP");
             const backend = location.mount.backend;
             const input = location.mount.path === "/" ? path : path.slice(location.mount.path.length) || "/";
             const declared = ownedMutationCapabilities(backend, await backend.capabilitiesFor?.(input, { ...controls, stagingResolution: true }) ?? backend.capabilities);
             controls.signal?.throwIfAborted();
-            if (declared.synchronousStagingResolution !== true || !backend.prepareStagingResolution)
+            if (declared.synchronousStagingResolution !== true || controls.followFinalSymlink === true && declared.synchronousFollowedStagingResolution !== true || !backend.prepareStagingResolution)
                 fail("ENOTSUP");
             const prefix = directoryAncestryPaths(location.mount.path).map(ancestor => {
                 const entry = observed.find(step => step.path === ancestor);
@@ -483,7 +485,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)
@@ -545,6 +547,10 @@ export class MountFileSystem {
         let followedFinalLink = false;
         const verified = async (location) => {
             let inspection = !location.stat && settings.resizeCreate === true ? creationVerification : verification;
+            // A guarded resolution binds the original link chain and missing target
+            // through the authoritative backend receipt; realpath cannot name absence.
+            if (settings.retainedResolution && !location.stat && followedFinalLink)
+                inspection = undefined;
             // A missing entry has no realpath. Verify its existing parent while
             // leaving dangling final symlinks on the ordinary following path.
             if (inspection && !location.stat && settings.allowMissing && !followedFinalLink && inspection.finalName === undefined) {
@@ -802,6 +808,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 +1049,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);
@@ -1022,6 +1102,8 @@ export class MountFileSystem {
             await requireOwnedMutation(local.mount.backend, target.local, "atomicFileStaging", options, options.destination === null);
             if (!local.mount.backend.publishStagedFile)
                 fail("ENOTSUP");
+            if (options.preserveIdentity)
+                await requireOwnedMutation(local.mount.backend, target.local, "atomicStagedFileMutation", options);
             if (ancestors || callerGuard !== undefined)
                 await requireOwnedMutation(local.mount.backend, target.local, "guardedStagingPublication", options, options.destination === null);
             if (!ancestors) {
@@ -1065,6 +1147,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

@@ -43,6 +43,7 @@ export declare class OverlayFileSystem implements FileSystem {
     private bytes;
     private cleanGarbage;
     cleanup(options?: FsOptions): Promise<void>;
+    private stagingOptions;
     private staged;
     private preserve;
     private clone;
@@ -64,6 +65,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 +84,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;