@poe-platform/safe-fs 0.1.724 → 0.1.726

package/README.md

@@ -339,6 +339,8 @@ Each batch lists from the beginning because previous keys have been deleted; it
 
 Known identity Content-Length responses use one result buffer; other responses grow storage up to the configured ceiling and return a view without a final copy. Growth can temporarily retain the old and new buffers (up to three times the response size), plus transport chunks. These per-response defaults leave headroom in Workers; hosts must still budget for metadata parsing, text decoding, transport buffers, and concurrent reads, especially when raising the limits. Use streaming reads for large files.
 
+WebDAV metadata parsing limits the document to 100,000 elements, 100,000 content nodes, 100,000 attributes, and 256 levels of nesting, independently of `maxEntries`. Text is bounded by `maxXmlBytes`. Exceeding a structural budget reports `EFBIG`; parsing yields cooperatively so caller cancellation and `timeoutMs` remain active.
+
 See the [binding types](src/fs/webdav/webdav.ts) before implementing atomic directory removal. A recursive WebDAV DELETE does not satisfy that contract.
 
 </details>
@@ -346,7 +348,7 @@ 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 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 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`.
 - **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` export condition selects the portable surface: memory, mounts, overlays, read-only, WebDAV, and the codec-based bridge. Real storage, S3, 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.

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

@@ -38,6 +38,9 @@ export interface DirectoryEntry {
 export interface FileSystemCapabilities {
     readonly open?: boolean;
     readonly versionedDescriptors?: boolean;
+    /** Prefer pathname streaming for shell > / >> when supported, retaining open for explicit handles.
+     * The host owns stream atomicity; this does not provide retained descriptor identity for redirected output. */
+    readonly preferStreamingRedirection?: boolean;
     readonly readOnly?: boolean;
     readonly read?: boolean;
     readonly stat?: boolean;

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

@@ -0,0 +1,8 @@
+import type { FileStat, FileSystem } from "../../contracts/filesystem.js";
+/** Internal authority: inspections and stock mutations share one JavaScript turn. */
+export interface MemoryAtomicView {
+    stat(path: string): FileStat | undefined;
+    names(path: string): readonly string[];
+}
+export declare function registerMemoryAtomicView(fs: FileSystem, view: MemoryAtomicView, intact: () => boolean): void;
+export declare function memoryAtomicView(fs: FileSystem): MemoryAtomicView | undefined;

package/dist/safe-fs/fs/memory/atomic-view.js

@@ -0,0 +1,8 @@
+const views = new WeakMap();
+export function registerMemoryAtomicView(fs, view, intact) {
+    views.set(fs, { view, intact });
+}
+export function memoryAtomicView(fs) {
+    const registered = views.get(fs);
+    return registered?.intact() ? registered.view : undefined;
+}

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

@@ -5,6 +5,7 @@ import { getOwnedWebDavEntry } from "../webdav/resource-id.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { openFileDescriptor } from "../descriptor.js";
 import { resolveMissingTarget } from "./missing-target.js";
+import { registerMemoryAtomicView } from "./atomic-view.js";
 import { MemoryAllocation, MemoryLedger } from "./ledger.js";
 import { normalizeMemoryFileSystemLimits } from "./limits.js";
 export { defaultMemoryFileSystemLimits } from "./limits.js";
@@ -93,6 +94,40 @@ export class MemoryFileSystem {
             capabilities: this.capabilities,
             intact: () => this.root === root,
         });
+        registerMemoryAtomicView(this, {
+            stat: (path) => {
+                this.validatePath(path, "overlayAtomicView");
+                let node = this.root;
+                for (const component of path.split("/").filter(Boolean)) {
+                    if (component === "." || component === "..")
+                        this.fail("EINVAL", "overlayAtomicView", path);
+                    if (!node)
+                        return undefined;
+                    if (node.type !== "directory")
+                        this.fail("ENOTDIR", "overlayAtomicView", path);
+                    this.permission(node, 1, "overlayAtomicView", path);
+                    node = node.entries.get(component);
+                }
+                return node ? this.snapshot(node) : undefined;
+            },
+            names: (path) => {
+                const node = this.entry(path, "overlayAtomicView").node;
+                if (node.type !== "directory")
+                    this.fail("ENOTDIR", "overlayAtomicView", path);
+                return [...node.entries.keys()];
+            },
+        }, () => {
+            if (Object.getPrototypeOf(this) !== MemoryFileSystem.prototype
+                || Object.getOwnPropertyDescriptor(this, "root")?.value !== root
+                || Object.getOwnPropertyDescriptor(this, "ledger")?.value !== ownedStores.get(this)?.ledger
+                || Object.getOwnPropertyDescriptor(this, "capabilities")?.value !== ownedStores.get(this)?.capabilities)
+                return false;
+            return Object.entries(memoryImplementation).every(([name, expected]) => {
+                const actual = Object.getOwnPropertyDescriptor(this, name)
+                    ?? Object.getOwnPropertyDescriptor(MemoryFileSystem.prototype, name);
+                return actual?.value === expected.value && actual?.get === expected.get && actual?.set === expected.set;
+            });
+        });
         if (this.compareEntry === memoryImplementation.compareEntry?.value) {
             registeredAuthorities.add(this);
             registerEntryAuthority(this, compareOwnedMemory);

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 { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, OpenReadFileOptions, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, StagedFileContent, AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, OpenReadFileOptions, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
 export interface OverlayFileSystemOptions {
     readonly upper: FileSystem;
     readonly lower: FileSystem;
@@ -16,8 +16,13 @@ export declare class OverlayFileSystem implements FileSystem {
     private readonly activeStages;
     private readonly linkMetadata;
     private readonly linkOrigins;
+    private readonly publication;
     private queue;
     constructor(options: OverlayFileSystemOptions);
+    confineExtraction(roots: readonly string[], options?: FsOptions): Promise<FileSystem>;
+    createStagedFile(directory: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
+    publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
     open(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
     private run;
     capabilitiesFor(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;

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

@@ -1,3 +1,4 @@
+import { OverlayMemoryPublication } from "./memory-publication.js";
 import { platform } from "#safe-fs-platform";
 import { openRetainedReadFile, requireCapabilities, retainedReadCapabilities } from "../capabilities.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
@@ -71,12 +72,14 @@ export class OverlayFileSystem {
     activeStages = new Set();
     linkMetadata = new Map();
     linkOrigins = new Map();
+    publication;
     queue = Promise.resolve();
     constructor(options) {
         if (options.upper === options.lower)
             throw new TypeError("Overlay upper and lower must be distinct backends");
         this.#upper = options.upper;
         this.#lower = options.lower;
+        this.publication = new OverlayMemoryPublication(this.#upper, this.#lower, this.whiteouts, this.opaque, this.activeStages);
         registerEntryView(this, (path, options) => this.run(options, async () => {
             const entry = await this.required(path, options);
             return { filesystem: entry.backend, path: entry.path, readOnly: this.capabilities.readOnly === true };
@@ -120,7 +123,7 @@ export class OverlayFileSystem {
         this.capabilities = Object.freeze({
             ...semantics,
             open: false,
-            atomicFilePublication: false, atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+            atomicFilePublication: false, atomicFileMutation: false, atomicFileStaging: this.publication.supported(), atomicStagingAncestry: this.publication.supported(), atomicDirectoryMetadata: false, trustedOwnedStaging: false,
             implicitDirectories: false,
             readlink: upper.readlink === true && this.#lower.capabilities.readlink === true ? true
                 : upper.readlink === false && this.#lower.capabilities.readlink === false ? false : undefined,
@@ -141,6 +144,22 @@ 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);
+    }
+    createStagedFile(directory, name, content, options) {
+        return this.run(options, async () => {
+            if (content.type === "file" && content.data.byteLength > this.maxBufferBytes)
+                fail("EFBIG", directory);
+            return this.publication.create(directory, name, content, options);
+        }, false);
+    }
+    publishStagedFile(staging, destination, options) {
+        return this.run(options, () => this.publication.publish(staging, destination, options), false);
+    }
+    removeStagedFile(staging, options = {}) {
+        return this.run(options, () => this.publication.cleanup(staging, options), false);
+    }
     async open(path, options) {
         options.signal?.throwIfAborted();
         throw new FsError("ENOTSUP", { syscall: "open", path });
@@ -169,6 +188,11 @@ export class OverlayFileSystem {
     }
     capabilitiesFor(path, options = {}) {
         return this.run(options, async () => {
+            validatePath(path);
+            // Owned cleanup queries capabilities before using its retained receipt;
+            // private staging is deliberately unavailable to pathname resolution.
+            if ([...this.activeStages].some(root => isPathWithin(root, path)))
+                return this.capabilities;
             const location = await this.resolve(path, options, options.create !== undefined || options.creation !== "exclusive", true);
             const backend = location.entry?.backend ?? this.#upper;
             const capabilities = await backend.capabilitiesFor?.(location.path, options) ?? backend.capabilities;
@@ -219,6 +243,19 @@ export class OverlayFileSystem {
             if (current.backend !== entry.backend || compareIdentity(entry.stat, current.stat) !== "same")
                 fail("ENOTSUP", entry.path, "overlay read layer changed during admission");
             options.signal?.throwIfAborted();
+            if (entry.stat.type === "directory" && this.publication.supported()) {
+                const logical = this.publication.stat(entry.path, snapshotStat(entry.stat));
+                return new Proxy(handle, {
+                    get(target, property) {
+                        if (property === "stat")
+                            return async (options = {}) => ({
+                                ...await target.stat(options), identityScope: logical.identityScope, dev: logical.dev, ino: logical.ino,
+                            });
+                        const value = Reflect.get(target, property, target);
+                        return typeof value === "function" ? value.bind(target) : value;
+                    },
+                });
+            }
             return handle;
         }
         catch (error) {
@@ -601,6 +638,8 @@ export class OverlayFileSystem {
             await this.clone(entry, temporary, options);
             options.signal?.throwIfAborted();
             await this.#upper.rename(temporary, entry.path, options);
+            if (entry.stat.type === "directory")
+                this.publication.copiedDirectory(entry.path, entry.stat);
             this.rememberLink(entry, entry.path);
             if (origin)
                 this.linkOrigins.set(entry.path, origin);
@@ -681,10 +720,16 @@ export class OverlayFileSystem {
         return this.writeFile(path, data, { ...options, flag: "a" });
     }
     async stat(path, options = {}) {
-        return this.run(options, async () => snapshotStat((await this.required(path, options)).stat), false);
+        return this.run(options, async () => {
+            const entry = await this.required(path, options);
+            return this.publication.stat(entry.path, snapshotStat(entry.stat));
+        }, false);
     }
     async lstat(path, options = {}) {
-        return this.run(options, async () => snapshotStat((await this.required(path, options, false)).stat), false);
+        return this.run(options, async () => {
+            const entry = await this.required(path, options, false);
+            return this.publication.stat(entry.path, snapshotStat(entry.stat));
+        }, false);
     }
     compareEntry(path, peer, peerPath, options = {}) {
         return compareEntries(this, path, peer, peerPath, options);

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

@@ -0,0 +1,34 @@
+import type { CreateStagedFileOptions, FileStaging, FileStat, FileSystem, FsOptions, 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 {
+    private readonly upper;
+    private readonly lower;
+    private readonly whiteouts;
+    private readonly opaque;
+    private readonly hidden;
+    private readonly receipts;
+    private readonly directories;
+    private readonly origins;
+    private readonly stages;
+    constructor(upper: FileSystem, lower: FileSystem, whiteouts: Set<string>, opaque: Set<string>, hidden: Set<string>);
+    supported(): boolean;
+    private stores;
+    private path;
+    private physical;
+    private observation;
+    private visible;
+    copiedDirectory(path: string, lower: FileStat): void;
+    stat(path: string, physical: FileStat): FileStat;
+    private same;
+    private expect;
+    private ancestors;
+    private inspect;
+    private capture;
+    private check;
+    private copyParents;
+    create(directory: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): 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;
+}

package/dist/safe-fs/fs/overlay/memory-publication.js

@@ -0,0 +1,295 @@
+import { FsError, isFsError } from "../../contracts/errors.js";
+import { dirname, isPathWithin, validatePath } from "../../contracts/virtual-path.js";
+import { memoryAtomicView } from "../memory/atomic-view.js";
+import { compareIdentity } from "../mount/identity.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 class OverlayMemoryPublication {
+    upper;
+    lower;
+    whiteouts;
+    opaque;
+    hidden;
+    receipts = new WeakMap();
+    directories = new Map();
+    origins = new Map();
+    stages = new WeakMap();
+    constructor(upper, lower, whiteouts, opaque, hidden) {
+        this.upper = upper;
+        this.lower = lower;
+        this.whiteouts = whiteouts;
+        this.opaque = opaque;
+        this.hidden = hidden;
+    }
+    supported() { return !!memoryAtomicView(this.upper) && !!memoryAtomicView(this.lower); }
+    stores() {
+        const upper = memoryAtomicView(this.upper), lower = memoryAtomicView(this.lower);
+        if (!upper || !lower)
+            throw new FsError("ENOTSUP", { syscall: "overlayPublication" });
+        return { upper, lower };
+    }
+    path(path) {
+        validatePath(path);
+        if (!path.startsWith("/") || (path !== "/" && path.endsWith("/"))
+            || path.split("/").some(component => component === "." || component === "..")) {
+            throw new FsError("EINVAL", { path });
+        }
+    }
+    physical(view, path) {
+        try {
+            return view.stat(path);
+        }
+        catch (error) {
+            if (isFsError(error, "ENOENT") || isFsError(error, "ENOTDIR"))
+                return undefined;
+            throw error;
+        }
+    }
+    observation(path) {
+        const stores = this.stores();
+        const upper = this.physical(stores.upper, path);
+        const lowerHidden = [...this.whiteouts].some(root => isPathWithin(root, path))
+            || [...this.opaque].some(root => root !== path && isPathWithin(root, path));
+        const lower = lowerHidden ? undefined : this.physical(stores.lower, path);
+        return { path, ...(upper ? { upper } : {}), ...(lower ? { lower } : {}) };
+    }
+    visible(observation) {
+        return observation.upper ?? observation.lower;
+    }
+    copiedDirectory(path, lower) {
+        if (!this.supported())
+            return;
+        const upper = this.physical(this.stores().upper, path);
+        if (upper?.type === "directory") {
+            this.origins.set(path, { upper, lower });
+            const directory = this.directories.get(path);
+            if (directory && !directory.upper && this.same(directory.lower, lower))
+                directory.upper = upper;
+        }
+    }
+    stat(path, physical) {
+        if (!this.supported())
+            return physical;
+        const observation = this.observation(path);
+        if (!this.same(physical, this.visible(observation), physical.type === "file"))
+            throw new FsError("EAGAIN", { path });
+        let logical = physical;
+        if (physical.type === "directory") {
+            let directory = this.directories.get(path);
+            if (!directory || !this.same(directory.upper, observation.upper) || !this.same(directory.lower, observation.lower)) {
+                directory = { ...observation, identityScope: Symbol("overlay directory"), ino: physical.ino, dev: physical.dev };
+                this.directories.set(path, directory);
+            }
+            logical = { ...physical, identityScope: directory.identityScope, dev: directory.dev, ino: directory.ino };
+        }
+        this.receipts.set(logical, observation);
+        return logical;
+    }
+    same(actual, expected, unchanged = false) {
+        if (!actual || !expected)
+            return actual === expected;
+        return compareIdentity(actual, expected) === "same" && actual.type === expected.type
+            && (!unchanged || ["revision", "size", "mode", "nlink", "mtimeMs", "ctimeMs"].every(key => actual[key] === expected[key]));
+    }
+    expect(path, expected, unchanged = false) {
+        const receipt = this.receipts.get(expected);
+        if (!receipt || receipt.path !== path)
+            throw new FsError("ENOTSUP", { path, message: "unowned overlay publication receipt" });
+        const actual = this.observation(path);
+        const origin = this.origins.get(path);
+        const copied = !receipt.upper && receipt.lower?.type === "directory" && origin
+            && this.same(origin.upper, actual.upper) && this.same(origin.lower, receipt.lower);
+        if ((!copied && !this.same(actual.upper, receipt.upper, unchanged))
+            || !this.same(actual.lower, receipt.lower, unchanged))
+            throw new FsError("EAGAIN", { path });
+    }
+    ancestors(path) {
+        const paths = ["/"];
+        for (const component of dirname(path).split("/").filter(Boolean)) {
+            paths.push(`${paths.at(-1) === "/" ? "" : paths.at(-1)}/${component}`);
+        }
+        return paths;
+    }
+    inspect(path) {
+        this.path(path);
+        for (const parent of this.ancestors(path)) {
+            const stat = this.visible(this.observation(parent));
+            if (!stat)
+                throw new FsError("ENOENT", { path: parent });
+            if (stat.type !== "directory")
+                throw new FsError("ENOTDIR", { path: parent });
+            if (((stat.mode >> 6) & 1) !== 1)
+                throw new FsError("EACCES", { path: parent });
+        }
+        return this.visible(this.observation(path));
+    }
+    capture(path) {
+        return this.ancestors(path).map(parent => {
+            const physical = this.inspect(parent);
+            if (physical?.type !== "directory")
+                throw new FsError("ENOTDIR", { path: parent });
+            return { path: parent, stat: this.stat(parent, physical) };
+        });
+    }
+    check(entries) {
+        for (const entry of entries) {
+            this.expect(entry.path, entry.stat);
+            if (this.inspect(entry.path)?.type !== "directory")
+                throw new FsError("ENOTDIR", { path: entry.path });
+        }
+    }
+    async copyParents(entries, options) {
+        for (const entry of entries) {
+            options.signal?.throwIfAborted();
+            this.check(entries);
+            const observation = this.observation(entry.path);
+            if (observation.upper)
+                continue;
+            const lower = observation.lower;
+            // Stock mkdir performs its complete mutation synchronously.
+            const pending = this.upper.mkdir(entry.path, { ...options, mode: lower.mode & 0o7777 });
+            this.copiedDirectory(entry.path, lower);
+            await pending;
+        }
+    }
+    async create(directory, name, content, options) {
+        options.signal?.throwIfAborted();
+        this.path(directory);
+        this.expect(dirname(directory), options.parent);
+        if (this.inspect(directory))
+            throw new FsError("EEXIST", { path: directory });
+        const ancestors = this.capture(directory);
+        await this.copyParents(ancestors, options);
+        options.signal?.throwIfAborted();
+        this.check(ancestors);
+        this.expect(dirname(directory), options.parent);
+        if (this.inspect(directory))
+            throw new FsError("EEXIST", { path: directory });
+        const parent = this.observation(dirname(directory)).upper;
+        const staging = await this.upper.createStagedFile(directory, name, content, { ...options, parent });
+        this.stages.set(staging, staging);
+        this.hidden.add(directory);
+        return staging;
+    }
+    async publish(staging, path, options) {
+        options.signal?.throwIfAborted();
+        this.path(path);
+        const owned = this.stages.get(staging);
+        if (!owned)
+            throw new FsError("ENOTSUP", { path });
+        const paths = this.ancestors(path);
+        const ancestors = options.ancestors;
+        if (!ancestors || ancestors.length !== paths.length || ancestors.some((entry, index) => entry.path !== paths[index])) {
+            throw new FsError("EINVAL", { path, message: "complete overlay ancestry is required" });
+        }
+        this.check(ancestors);
+        this.expect(dirname(path), options.parent);
+        const current = this.inspect(path);
+        if (options.destination === null) {
+            if (current)
+                throw new FsError("EAGAIN", { path });
+        }
+        else {
+            this.expect(path, options.destination, true);
+            if (current?.type !== "file" || current.nlink !== 1)
+                throw new FsError("EAGAIN", { path });
+        }
+        const translated = ancestors.map(entry => ({ path: entry.path, stat: this.observation(entry.path).upper }));
+        const target = this.observation(path).upper;
+        // No await between the logical checks above and the physical commit below.
+        await this.upper.publishStagedFile(owned, path, {
+            ...options, ancestors: translated, parent: translated.at(-1).stat, destination: target ?? null,
+        });
+    }
+    async cleanup(staging, options) {
+        this.stores();
+        const owned = this.stages.get(staging);
+        if (!owned)
+            throw new FsError("ENOTSUP", { path: staging.directory.path });
+        await this.upper.removeStagedFile(owned, options);
+        this.hidden.delete(owned.directory.path);
+        this.stages.delete(staging);
+    }
+    confine(roots, options, run, fs) {
+        options.signal?.throwIfAborted();
+        const retained = new Map();
+        for (const root of roots) {
+            this.path(root);
+            const entries = [...this.capture(root), { path: root, stat: this.stat(root, this.inspect(root)) }];
+            for (const entry of entries) {
+                if (entry.stat.type !== "directory")
+                    throw new FsError("ENOTDIR", { path: entry.path });
+                retained.set(entry.path, entry.stat);
+            }
+        }
+        return new Proxy(fs, {
+            get: (target, property) => {
+                if (property === "confineExtraction" || property === "objects")
+                    return undefined;
+                if (["mkdir", "rm", "rmdir"].includes(String(property)))
+                    return (path, mutation = {}) => run(mutation, async () => {
+                        mutation.signal?.throwIfAborted();
+                        this.path(path);
+                        if (!roots.some(root => isPathWithin(root, path)))
+                            throw new FsError("EPERM", { path });
+                        this.check([...retained].filter(([root]) => isPathWithin(root, path)).map(([path, stat]) => ({ path, stat })));
+                        const current = this.inspect(path);
+                        if (property === "mkdir") {
+                            if (current) {
+                                if (mutation.recursive && current.type === "directory")
+                                    return;
+                                throw new FsError("EEXIST", { path });
+                            }
+                            const entries = this.capture(path);
+                            await this.copyParents(entries, mutation);
+                            this.check([...retained].filter(([root]) => isPathWithin(root, path)).map(([path, stat]) => ({ path, stat })));
+                            this.check(entries);
+                            if (this.inspect(path))
+                                throw new FsError("EAGAIN", { path });
+                            await this.upper.mkdir(path, mutation);
+                            this.opaque.add(path);
+                            return;
+                        }
+                        if (!current) {
+                            if (property === "rm" && mutation.force)
+                                return;
+                            throw new FsError("ENOENT", { path });
+                        }
+                        if (path === "/")
+                            throw new FsError("EBUSY", { path });
+                        if (current.type === "directory") {
+                            const stores = this.stores();
+                            const observation = this.observation(path);
+                            const names = new Set([
+                                ...(observation.upper ? stores.upper.names(path) : []),
+                                ...(observation.lower && !this.opaque.has(path) ? stores.lower.names(path) : []),
+                            ]);
+                            if ([...names].some(name => this.inspect(`${path}/${name}`)))
+                                throw new FsError("ENOTEMPTY", { path });
+                        }
+                        else if (property === "rmdir")
+                            throw new FsError("ENOTDIR", { path });
+                        const parent = this.inspect(dirname(path));
+                        if (((parent.mode >> 6) & 3) !== 3)
+                            throw new FsError("EACCES", { path });
+                        const upper = this.observation(path).upper;
+                        const removal = upper ? property === "rmdir"
+                            ? this.upper.rmdir(path, mutation) : this.upper.rm(path, mutation) : undefined;
+                        // Bind the whiteout in the same turn as the stock upper removal.
+                        // Rejected Memory mutations leave the entry present.
+                        if (!upper || !this.physical(this.stores().upper, path)) {
+                            this.whiteouts.add(path);
+                            this.origins.delete(path);
+                        }
+                        await removal;
+                    });
+                const value = Reflect.get(target, property, target);
+                if (typeof value !== "function")
+                    return value;
+                if (["lstat", "stat", "readFile", "readStream", "openReadFile", "readdir", "realpath", "access", "capabilitiesFor", "readlink"].includes(String(property)))
+                    return value.bind(target);
+                return () => { throw new FsError("ENOTSUP", { syscall: String(property) }); };
+            },
+        });
+    }
+}

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

@@ -1,7 +1,7 @@
 import { FsError, isErrnoCode, isFsError } from "../../contracts/errors.js";
 import { composeAbortSignals } from "../../contracts/abort.js";
 import { readBytes } from "../../contracts/io.js";
-import { davChild, davChildren, parseXml, scalar, XmlResponseLimitError } from "./xml.js";
+import { davChild, davChildren, parseXmlSteps, scalar, XmlResponseLimitError, XmlResourceLimitError } from "./xml.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { assertCallbackAuthorityAllowed, compareEntries, registerEntryAuthority } from "../mount/comparison.js";
 import { compareWebDavResources, ownedResponseIdentifier, recordOwnedResourceStat, registerResourceQuery, resourceIdentifier } from "./resource-id.js";
@@ -561,7 +561,34 @@ export class WebDavFileSystem {
         const data = await this.bytes(response, this.maxXmlBytes, signal);
         const encoding = (data[0] === 0xff && data[1] === 0xfe) || (data[0] === 0x3c && data[1] === 0)
             ? "utf-16le" : (data[0] === 0xfe && data[1] === 0xff) || (data[0] === 0 && data[1] === 0x3c) ? "utf-16be" : "utf-8";
-        return parseXml(new TextDecoder(encoding, { fatal: true }).decode(data), maxResponses === undefined ? undefined : { maxResponses });
+        const parser = parseXmlSteps(new TextDecoder(encoding, { fatal: true }).decode(data), {
+            ...(maxResponses === undefined ? {} : { maxResponses }),
+            maxNodes: 100_000, maxContentNodes: 100_000, maxDepth: 256,
+            maxAttributes: 100_000, maxTextLength: this.maxXmlBytes,
+        });
+        let work = 0;
+        try {
+            while (true) {
+                signal.throwIfAborted();
+                const step = parser.next();
+                if (step.done)
+                    return step.value;
+                work += step.value;
+                if (work >= 4096) {
+                    work = 0;
+                    // Yield to the host task queue so request deadlines and caller aborts can fire.
+                    await new Promise(resolve => setTimeout(resolve, 0));
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof XmlResourceLimitError)
+                fail("EFBIG", "webdav", "", error.message);
+            throw error;
+        }
+        finally {
+            parser.return(undefined);
+        }
     }
     async multistatus(response, signal, method = "PROPFIND", path = "") {
         const link = response.headers.get("link");

package/dist/safe-fs/fs/webdav/xml.d.ts

@@ -6,7 +6,10 @@ export interface XmlLimits extends Omit<DocumentLimits, "onElement"> {
 }
 export declare class XmlResponseLimitError extends SyntaxError {
 }
+export declare class XmlResourceLimitError extends SyntaxError {
+}
 export declare function parseXml(input: string, limits?: XmlLimits): XmlElement;
+export declare function parseXmlSteps(input: string, limits?: XmlLimits): Generator<number, XmlElement, void>;
 export declare function davChildren(element: XmlElement, localName: string): XmlElement[];
 export declare function davChild(element: XmlElement, localName: string): XmlElement | undefined;
 export declare function scalar(element: XmlElement): string;

package/dist/safe-fs/fs/webdav/xml.js

@@ -1,15 +1,31 @@
-import { parseXml as parseDocument, XmlLimitError } from "../../xml.js";
+import { parseXmlSteps as parseDocumentSteps, XmlLimitError } from "../../xml.js";
 export class XmlResponseLimitError extends SyntaxError {
 }
+export class XmlResourceLimitError extends SyntaxError {
+}
 function invalid(message) { throw new SyntaxError(`Invalid WebDAV XML: ${message}`); }
 export function parseXml(input, limits = {}) {
+    const parser = parseXmlSteps(input, limits);
+    try {
+        let step = parser.next();
+        while (!step.done)
+            step = parser.next();
+        return step.value;
+    }
+    catch (error) {
+        if (error instanceof XmlResourceLimitError)
+            throw new SyntaxError(error.message);
+        throw error;
+    }
+}
+export function* parseXmlSteps(input, limits = {}) {
     const { maxResponses, ...documentLimits } = limits;
     if (maxResponses !== undefined && (!Number.isSafeInteger(maxResponses) || maxResponses < 1)) {
         throw new RangeError("XML limits must be positive integers");
     }
     let responses = 0;
     try {
-        return parseDocument(input, { ...documentLimits, retainContent: false,
+        return yield* parseDocumentSteps(input, { ...documentLimits, retainContent: false,
             onElement(element, parent, depth) {
                 if (maxResponses !== undefined && depth === 2 && parent?.namespace === "DAV:" && parent.localName === "multistatus"
                     && element.namespace === "DAV:" && element.localName === "response" && ++responses > maxResponses) {
@@ -20,7 +36,7 @@ export function parseXml(input, limits = {}) {
     }
     catch (error) {
         if (error instanceof XmlLimitError)
-            invalid(error.message);
+            throw new XmlResourceLimitError(`Invalid WebDAV XML: ${error.message}`);
         if (error instanceof SyntaxError && error.message.startsWith("Invalid XML:")) {
             error.message = error.message.replace("Invalid XML:", "Invalid WebDAV XML:");
         }

package/dist/safe-fs/xml.js

@@ -288,9 +288,10 @@ export function* parseXmlSteps(input, limits = {}) {
         const parent = stack.at(-1);
         if (parent) {
             parent.element.text += text;
-            if (retainContent && (text.length || kind === "cdata")) {
+            if (text.length || kind === "cdata") {
                 admitContent();
-                parent.content.push({ kind, text });
+                if (retainContent)
+                    parent.content.push({ kind, text });
             }
         }
         else {
@@ -302,9 +303,10 @@ export function* parseXmlSteps(input, limits = {}) {
             }
             if (text.length % 512)
                 yield text.length % 512;
-            if (retainContent && text.length) {
+            if (text.length) {
                 admitContent();
-                (root ? epilog : prolog).push({ kind, text });
+                if (retainContent)
+                    (root ? epilog : prolog).push({ kind, text });
             }
         }
     };
@@ -326,8 +328,8 @@ export function* parseXmlSteps(input, limits = {}) {
             const parent = stack.at(-1);
             const text = source.slice(offset + 4, end);
             admitText(text);
+            admitContent();
             if (retainContent) {
-                admitContent();
                 (parent?.content ?? (root ? epilog : prolog)).push({ kind: "comment", text });
             }
             offset = end + 3;
@@ -371,8 +373,8 @@ export function* parseXmlSteps(input, limits = {}) {
                     yield start % 512;
                 const text = content.slice(start);
                 admitText(text);
+                admitContent();
                 if (retainContent) {
-                    admitContent();
                     (parent?.content ?? (root ? epilog : prolog)).push({ kind: "processing-instruction", target, text });
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.724",
+  "version": "0.1.726",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",