@poe-platform/safe-fs 0.1.799 → 0.1.800

package/README.md

@@ -1,6 +1,8 @@
 # safe-fs
 
-An asynchronous filesystem interface for memory, rooted host directories, S3, and WebDAV, with mounts, copy-on-write overlays, and Node-style bridges.
+An asynchronous filesystem interface for memory, rooted host directories, S3, and WebDAV, with mounts, copy-on-write overlays, and Node-style bridges. Portable filesystem types and POSIX helpers compile without Node types.
+
+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.
 
 ## Quickstart
 
@@ -44,7 +46,7 @@ To create new outputs with Safe Bash's `dos2unix`, `unix2dos`, or compression co
 | `@poe-platform/safe-fs` | Full Node API; selects the portable core under the `browser` and `workerd` conditions. |
 | `@poe-platform/safe-fs/core` | Memory, mounts, overlays, read-only, WebDAV, portable bridges, types, and errors. Bundle with the `browser` condition for browsers and Workers. |
 | `@poe-platform/safe-fs/node` | Host filesystem, Node bridge, S3, and configuration helpers; unavailable in browsers. |
-| `@poe-platform/safe-fs/fs/*` | Individual adapters: `memory`, `readonly`, `mount`, `overlay`, `webdav`, `real`, `s3`, and `s3/http`. S3 and its mock accept an injected transport in browsers and Workers; `s3/http` is Node-only. |
+| `@poe-platform/safe-fs/fs/*` | Individual adapters: `memory`, `readonly`, `mount`, `overlay`, `webdav`, `real`, `s3`, and `s3/http`. S3, its mock, and the signed `s3/http` transport work in browsers and Workers. |
 
 ```ts
 import { createMemoryFileSystem, FsError, type FileSystem } from "@poe-platform/safe-fs/core";
@@ -111,6 +113,10 @@ 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.
+Overlays backed by stock Memory filesystems support conditional file mutations,
+directory preparation, and confined staging. Publication may omit `ancestors`
+when the destination shares the staging parent; the overlay checks the ancestry
+retained before staging began.
 See the [staging contract](src/contracts/filesystem.md#atomic-owned-staging).
 
 Capture `retainFileSystemCleanup(scoped, callback, { maxOperations })` before
@@ -273,7 +279,7 @@ 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).
 
-`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. 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.
+`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>
 <summary>S3 filesystem and HTTP transport options</summary>
@@ -336,7 +342,7 @@ Each batch lists from the beginning because previous keys have been deleted; it
 | `enableCopy` | `true`; disabling uses a buffered GET/PUT fallback |
 | `verifiedConditionalOperations` | Optional `put`, `copy`, `delete` booleans, each defaulting to false; enable only after verifying the server's semantics |
 | `clock` | Current date/time function, used for signing |
-| `request` | Optional Node HTTP request factory; defaults to the built-in HTTP(S) client |
+| `request` | Optional Node HTTP request factory; Node defaults to HTTP(S), browsers and Workers use global fetch |
 
 </details>
 
@@ -369,10 +375,10 @@ See the [binding types](src/fs/webdav/webdav.ts) before implementing atomic dire
 ## Safety boundary and limitations
 
 - **Not an OS sandbox.** Rooted storage and bridge confinement check paths and symlinks, but checks and host operations can race concurrent changes. Use a separate OS isolation boundary for hostile workloads. A custom adapter or transport is trusted code with its own host authority.
-- **A read-only view is not an immutable store.** Mount views serialize guest symlink, rename, and removal operations against active path operations. Finish or close read streams before awaiting these namespace changes. Other references can still change the backing filesystem; this coordination applies only to operations through the same mount view. Overlay reads require retained handles and stable object and ancestor identities; unsupported backends or changed read admission fail with `ENOTSUP`. Overlays with two stock MemoryFileSystem layers support race-safe patch publication and confined directory creation/removal. Publication checks both layers, retains logical directory identity across copy-up, and leaves lower bytes intact; wrapped or customized layers remain unsupported. Overlays are not transactions; cancellation and cleanup do not guarantee rollback. Cross-mount rename can fail with `EXDEV`.
+- **A read-only view is not an immutable store.** Mount views serialize guest symlink, rename, and removal operations against active path operations. Finish or close read streams before awaiting these namespace changes. Other references can still change the backing filesystem; this coordination applies only to operations through the same mount view. Overlay reads require retained handles and stable object and ancestor identities; unsupported backends or changed read admission fail with `ENOTSUP`. Overlays with two stock MemoryFileSystem layers support race-safe patch publication, conditional file writes/removal, no-replace rename, and confined directory creation/removal and file writes. Compression file output, `mv -n`, `sed -i`, and ssconvert work with these layers. Upper-file writes retain file identity; lower-file writes copy up without changing lower bytes. Publication checks both layers, retains logical directory identity across copy-up, and leaves lower bytes intact; wrapped or customized layers remain unsupported. Overlays are not transactions; cancellation and cleanup do not guarantee rollback. Cross-mount rename can fail with `EXDEV`.
 - **Remote storage is not a POSIX disk.** S3 and WebDAV do not provide hardlinks or symlinks. S3 rename is non-atomic and may leave partial copies/deletions; `S3RenameError` reports the phase and affected keys. Strong empty-only removal and conditional writes depend on backend support, not a prior listing.
 - **The bridges are partial Node compatibility layers.** No synchronous/callback API, file handles, watchers, bigint stats, flush/retry support, or `cp` dereference/timestamp-preservation options. Missing optional operations fail rather than being approximated with destructive alternatives.
-- **Browser support is filesystem-only.** The `browser` and `workerd` export conditions select the portable surface: memory, mounts, overlays, read-only, WebDAV, and the codec-based bridge. S3 is available through `fs/s3` with an explicit transport, including its portable mock. Real storage, the Node bridge, and the configuration registry are not browser exports. WebDAV still needs server CORS support; no OPFS or directory-handle adapter is included. This does not make the SafeJS runtime browser-compatible.
+- **Browser support is filesystem-only.** The `browser` and `workerd` export conditions select the portable surface: memory, mounts, overlays, read-only, WebDAV, and the codec-based bridge. S3 is available through `fs/s3` with an explicit transport, including its portable mock and `fs/s3/http`. The HTTP transport uses fetch in browsers and Workers and requires server CORS support in browsers. Fetch rejects keys containing dot segments that the URL parser would normalize, and never follows redirects. Node request factories are only supported in Node. Real storage, the Node bridge, and the configuration registry are not browser exports. WebDAV still needs server CORS support; no OPFS or directory-handle adapter is included. This does not make the SafeJS runtime browser-compatible.
 - **Portable temporary names require secure randomness.** Browser overlay staging and portable bridge `mkdtemp` require `crypto.randomUUID` or `crypto.getRandomValues`; without either, they fail with `ENOTSUP` rather than use `Math.random`.
 - **Allocation and identity may be unknown.** Optional `FileStat.allocatedBytes` is provider-reported allocation, not logical length or reclaimable space. Do not infer identity from size, timestamps, or inode numbers across unrelated backends.
 

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

@@ -1,6 +1,5 @@
 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 });
@@ -63,7 +62,6 @@ export function toByteSource(input) {
     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");
@@ -77,46 +75,38 @@ export async function collectBytes(source, options) {
     let buffer = new Uint8Array(0);
     let size = 0;
     function reserve(bytes) {
-        if (bytes > memoryLimit - reserved || bytes > platform.maxCollectionBytes - activeCollectionBytes) {
+        if (bytes > memoryLimit - reserved) {
             throw new FsError("EFBIG", { syscall: "collectBytes", message: "collection exceeds memory budget" });
         }
         reserved += bytes;
-        activeCollectionBytes += bytes;
     }
-    try {
-        options.signal?.throwIfAborted();
-        for await (const chunk of readBytes(source, options.signal)) {
-            activeCollectionBytes -= inputBytes;
-            reserved -= inputBytes;
-            inputBytes = 0;
-            if (chunk.byteLength > (options.maxBytes ?? Infinity) - size) {
-                throw new FsError("EFBIG", { syscall: "collectBytes", message: "output exceeds maxBytes" });
-            }
-            // A small view can retain a large backing buffer. Keep this reservation
-            // while awaiting the next chunk, including while its source is suspended.
-            reserve(chunk.buffer.byteLength);
-            inputBytes = chunk.buffer.byteLength;
-            const nextSize = size + chunk.byteLength;
-            if (nextSize > buffer.byteLength) {
-                const capacity = Math.min(options.maxBytes ?? Infinity, Math.max(nextSize, buffer.byteLength * 2));
-                // Admit both generations before allocation. Do not fall back to repeated
-                // exact-size growth when geometric growth exceeds the budget.
-                reserve(capacity);
-                const replacement = new Uint8Array(capacity);
-                replacement.set(buffer.subarray(0, size));
-                activeCollectionBytes -= buffer.byteLength;
-                reserved -= buffer.byteLength;
-                buffer = replacement;
-            }
-            buffer.set(chunk, size);
-            size = nextSize;
+    options.signal?.throwIfAborted();
+    for await (const chunk of readBytes(source, options.signal)) {
+        reserved -= inputBytes;
+        inputBytes = 0;
+        if (chunk.byteLength > (options.maxBytes ?? Infinity) - size) {
+            throw new FsError("EFBIG", { syscall: "collectBytes", message: "output exceeds maxBytes" });
         }
-        options.signal?.throwIfAborted();
-        return buffer.subarray(0, size);
-    }
-    finally {
-        activeCollectionBytes -= reserved;
+        // A small view can retain a large backing buffer. Keep this reservation
+        // while awaiting the next chunk, including while its source is suspended.
+        reserve(chunk.buffer.byteLength);
+        inputBytes = chunk.buffer.byteLength;
+        const nextSize = size + chunk.byteLength;
+        if (nextSize > buffer.byteLength) {
+            const capacity = Math.min(options.maxBytes ?? Infinity, Math.max(nextSize, buffer.byteLength * 2));
+            // Admit both generations before allocation. Do not fall back to repeated
+            // exact-size growth when geometric growth exceeds the budget.
+            reserve(capacity);
+            const replacement = new Uint8Array(capacity);
+            replacement.set(buffer.subarray(0, size));
+            reserved -= buffer.byteLength;
+            buffer = replacement;
+        }
+        buffer.set(chunk, size);
+        size = nextSize;
     }
+    options.signal?.throwIfAborted();
+    return buffer.subarray(0, size);
 }
 async function abortable(operation, signal) {
     signal?.throwIfAborted();

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

@@ -1,8 +1,2 @@
-import { posix } from "#safe-fs-platform-path";
 export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./virtual-path.js";
-export declare const posixPath: typeof posix;
-export declare const basename: typeof posix.basename;
-export declare const dirname: typeof posix.dirname;
-export declare const extname: typeof posix.extname;
-export declare const joinPath: typeof posix.join;
-export declare const isAbsolutePath: typeof posix.isAbsolute;
+export { posixPath, basename, dirname, extname, joinPath, isAbsolutePath } from "./portable-path.js";

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

@@ -1,8 +1,2 @@
-import { posix } from "#safe-fs-platform-path";
 export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./virtual-path.js";
-export const posixPath = posix;
-export const basename = posix.basename;
-export const dirname = posix.dirname;
-export const extname = posix.extname;
-export const joinPath = posix.join;
-export const isAbsolutePath = posix.isAbsolute;
+export { posixPath, basename, dirname, extname, joinPath, isAbsolutePath } from "./portable-path.js";

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

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

package/dist/safe-fs/core.js

@@ -20,3 +20,4 @@ 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";
+export * from "./fs/s3/index.js";

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

@@ -3440,7 +3440,7 @@ function isStockMemoryMethods(mem, names, checkRootAccessor = true) {
 let lastReadViewData;
 let lastReadViewSourceRef;
 export function getLastReadMemoryFileSourceRef(view) {
-    const ref = view === lastReadViewData ? lastReadViewSourceRef : undefined;
+    const ref = view === lastReadViewData?.deref() ? lastReadViewSourceRef?.deref() : undefined;
     lastReadViewData = undefined;
     lastReadViewSourceRef = undefined;
     return ref;
@@ -3462,8 +3462,8 @@ export function tryReadMemoryFileViewSync(filesystem, path, maxBytes, signal, ca
     else if ((++fastWriteNowTick & 63) === 0)
         node.atimeMs = fastWriteCachedNow = Date.now();
     if (captureSourceRef && node.revision === 0) {
-        lastReadViewData = data;
-        lastReadViewSourceRef = node.sourceRef;
+        lastReadViewData = new WeakRef(data);
+        lastReadViewSourceRef = node.sourceRef === undefined ? undefined : new WeakRef(node.sourceRef);
     }
     return data;
 }

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

@@ -1,6 +1,6 @@
 import type { ByteSource } from "../../contracts/io.js";
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
-import type { CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, StagedFileContent, AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, OpenReadFileOptions, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { ConditionalWriteFileOptions, ConditionalRemoveFileOptions, PrepareDirectoryOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, StagedFileContent, AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, OpenReadFileOptions, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
 export interface OverlayFileSystemOptions {
     readonly upper: FileSystem;
     readonly lower: FileSystem;
@@ -56,6 +56,9 @@ export declare class OverlayFileSystem implements FileSystem {
     private replace;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+    prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
+    writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;

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

@@ -126,13 +126,13 @@ export class OverlayFileSystem {
             ...semantics,
             open: false,
             conditionalChmod: this.publication.supported(),
-            atomicFilePublication: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: this.publication.supported(), atomicStagingAncestry: this.publication.supported(), atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+            atomicFilePublication: false, atomicFileMutation: this.publication.supported(), atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: this.publication.supported(), atomicStagingAncestry: this.publication.supported(), retainedStagingCleanup: this.publication.supported(), atomicDirectoryMetadata: this.publication.supported(), trustedOwnedStaging: false,
             implicitDirectories: false,
             readlink: upper.readlink === true && this.#lower.capabilities.readlink === true ? true
                 : upper.readlink === false && this.#lower.capabilities.readlink === false ? false : undefined,
             ...(upper.readOnly === undefined ? {} : { readOnly: upper.readOnly }),
             ...(effectiveAppend === undefined ? {} : { append: effectiveAppend }),
-            atomicRename: false, atomicRenameNoReplace: false,
+            atomicRename: this.publication.supported(), atomicRenameNoReplace: this.publication.supported(),
             descriptorWriteStream: false,
             retainedResize: false, atomicResize: false,
             hardlinks: false,
@@ -148,7 +148,7 @@ export class OverlayFileSystem {
         Object.defineProperty(this, "capabilities", { writable: false, configurable: false });
     }
     confineExtraction(roots, options = {}) {
-        return this.run(options, async () => this.publication.confine(roots, options, (options, operation) => this.run(options, operation, false), this), false);
+        return this.run(options, async () => this.publication.confine(roots, options, (options, operation) => this.run(options, operation, false), this, this.maxBufferBytes), false);
     }
     createStagedFile(directory, name, content, options) {
         return this.run(options, async () => {
@@ -715,11 +715,38 @@ export class OverlayFileSystem {
             const append = options.flag === "a" || options.flag === "ax";
             if (append && (location.entry?.stat.size ?? 0) + bytes.byteLength > this.maxBufferBytes)
                 fail("EFBIG", path);
-            await this.replace(location, options, async (temporary) => {
-                await this.#upper.writeFile(temporary, bytes, { ...options, flag: append ? "a" : "w" });
-            });
+            if (this.publication.supported() && location.entry?.backend === this.#upper) {
+                const parent = await this.required(dirname(location.path), options);
+                await this.publication.writeFile(location.path, bytes, {
+                    ...options, parent: this.publication.stat(parent.path, parent.stat),
+                    expected: this.publication.stat(location.path, location.entry.stat), append,
+                }, this.maxBufferBytes);
+            }
+            else {
+                await this.replace(location, options, async (temporary) => {
+                    await this.#upper.writeFile(temporary, bytes, { ...options, flag: append ? "a" : "w" });
+                });
+            }
         });
     }
+    prepareDirectory(path, options) {
+        const captured = { ...options };
+        return this.run(captured, () => this.publication.prepareDirectory(path, captured), false);
+    }
+    async writeFileConditional(path, data, options) {
+        options.signal?.throwIfAborted();
+        if (!(data instanceof Uint8Array))
+            throw new TypeError("Overlay files require Uint8Array data");
+        const bytes = new Uint8Array(data);
+        if (bytes.byteLength > this.maxBufferBytes)
+            fail("EFBIG", path);
+        const captured = { ...options };
+        return this.run(captured, () => this.publication.writeFile(path, bytes, captured, this.maxBufferBytes), false);
+    }
+    removeFileConditional(path, options) {
+        const captured = { ...options };
+        return this.run(captured, () => this.publication.removeFile(path, captured), false);
+    }
     async appendFile(path, data, options = {}) {
         return this.writeFile(path, data, { ...options, flag: "a" });
     }
@@ -866,11 +893,13 @@ export class OverlayFileSystem {
     }
     async rename(source, destination, options = {}) {
         return this.run(options, async () => {
-            if (options.noReplace)
+            if (options.noReplace && !this.publication.supported())
                 fail("ENOTSUP", source, "atomic no-replace rename is unsupported");
             this.writable(source);
             const original = await this.required(source, options, false);
             const target = await this.resolve(destination, options, false, true);
+            if (options.noReplace && target.entry)
+                fail("EEXIST", destination);
             if (original.path === target.path)
                 return;
             if (original.path === "/" || target.path === "/")
@@ -885,6 +914,7 @@ export class OverlayFileSystem {
                 if (target.entry.stat.type === "directory" && (await this.listing(target.entry, options)).length)
                     fail("ENOTEMPTY", destination);
             }
+            const guard = this.capabilities.atomicRename ? this.publication.prepareRename(original.path, target.path) : undefined;
             await this.parent(original.path, options);
             await this.parent(target.path, options);
             await this.materialize(original, options);
@@ -902,7 +932,10 @@ export class OverlayFileSystem {
                 movedOrigins.push([destination, { ...origin, moves }]);
             }
             options.signal?.throwIfAborted();
-            await this.#upper.rename(original.path, target.path, options);
+            if (this.capabilities.atomicRename)
+                await this.publication.rename(original.path, target.path, options, guard);
+            else
+                await this.#upper.rename(original.path, target.path, options);
             this.whiteouts.add(original.path);
             if (original.stat.type === "directory")
                 this.opaque.add(target.path);
@@ -998,6 +1031,9 @@ export class OverlayFileSystem {
                 await this.copyUp(entry, options);
                 await operation(entry.path);
             }
+            else if (this.publication.supported() && entry.backend === this.#upper) {
+                await operation(entry.path);
+            }
             else
                 await this.replace({ path: entry.path, entry }, options, operation);
         });
@@ -1123,9 +1159,19 @@ export class OverlayFileSystem {
                     const append = options.flag === "a" || options.flag === "ax";
                     if (append && (location.entry?.stat.size ?? 0) + size > this.maxBufferBytes)
                         fail("EFBIG", path);
-                    await this.replace(location, options, async (temporary) => {
-                        await this.streamToUpper(temporary, this.#upper.readStream(incoming, options), { ...options, flag: append ? "a" : "w" });
-                    }, true);
+                    if (this.publication.supported() && location.entry?.backend === this.#upper) {
+                        const bytes = await this.#upper.readFile(incoming, options);
+                        const parent = await this.required(dirname(location.path), options);
+                        await this.publication.writeFile(location.path, bytes, {
+                            ...options, parent: this.publication.stat(parent.path, parent.stat),
+                            expected: this.publication.stat(location.path, location.entry.stat), append,
+                        }, this.maxBufferBytes);
+                    }
+                    else {
+                        await this.replace(location, options, async (temporary) => {
+                            await this.streamToUpper(temporary, this.#upper.readStream(incoming, options), { ...options, flag: append ? "a" : "w" });
+                        }, true);
+                    }
                 });
             });
             return;

package/dist/safe-fs/fs/overlay/memory-publication.d.ts

@@ -1,4 +1,4 @@
-import type { CreateStagedFileOptions, FileStaging, FileStat, FileSystem, FsOptions, ChmodOptions, PublishStagedFileOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { ConditionalWriteFileOptions, ConditionalRemoveFileOptions, RenameOptions, PrepareDirectoryOptions, CreateStagedFileOptions, FileStaging, FileStat, FileSystem, FsOptions, ChmodOptions, PublishStagedFileOptions, StagedFileContent } from "../../contracts/filesystem.js";
 /** Stock Memory mutations commit before returning their promise. No user code or
  * await is allowed between inspecting the two stores and invoking a mutation. */
 export declare class OverlayMemoryPublication {
@@ -11,6 +11,7 @@ export declare class OverlayMemoryPublication {
     private readonly directories;
     private readonly origins;
     private readonly stages;
+    private readonly stagingAncestors;
     constructor(upper: FileSystem, lower: FileSystem, whiteouts: Set<string>, opaque: Set<string>, hidden: Set<string>);
     supported(): boolean;
     private stores;
@@ -27,9 +28,15 @@ export declare class OverlayMemoryPublication {
     private capture;
     private check;
     prepareChmod(path: string, options: ChmodOptions): (() => true) | undefined;
+    prepareWrite(path: string, options: ConditionalWriteFileOptions): () => true;
+    writeFile(path: string, data: Uint8Array, options: ConditionalWriteFileOptions, maxBytes: number, guard?: () => void): Promise<FileStat>;
+    removeFile(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
+    prepareDirectory(path: string, options: PrepareDirectoryOptions, guard?: () => void): Promise<FileStat>;
+    prepareRename(source: string, destination: string): () => void;
+    rename(source: string, destination: string, options: RenameOptions, guard: () => void): Promise<void>;
     private copyParents;
-    create(directory: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
+    create(directory: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions, guard?: () => void): Promise<FileStaging>;
     publish(staging: FileStaging, path: string, options: PublishStagedFileOptions): Promise<void>;
-    cleanup(staging: FileStaging, options: FsOptions): Promise<void>;
-    confine(roots: readonly string[], options: FsOptions, run: <T>(options: FsOptions, operation: () => Promise<T>) => Promise<T>, fs: FileSystem): FileSystem;
+    cleanup(staging: FileStaging, options: FsOptions, retained?: boolean): Promise<void>;
+    confine(roots: readonly string[], options: FsOptions, run: <T>(options: FsOptions, operation: () => Promise<T>) => Promise<T>, fs: FileSystem, maxBytes: number): FileSystem;
 }