@poe-platform/safe-fs 0.1.725 → 0.1.727

package/README.md

@@ -348,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/package.json

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