@poe-platform/safe-fs 0.1.726 → 0.1.728

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

@@ -45,6 +45,37 @@ function integer(value, syscall, path) {
     if (!Number.isSafeInteger(value) || value < 0)
         throw new FsError("EINVAL", { syscall, path });
 }
+const OPEN_FILE_OPTION_KEYS = new Set(["access", "creation", "truncate", "append", "mode", "exactMode", "noFollow", "synchronization", "signal"]);
+const managedCapabilitiesCache = new WeakMap();
+function getManagedCapabilities(capabilities, access, append) {
+    let byKey = managedCapabilitiesCache.get(capabilities);
+    const key = `${access}:${append ? 1 : 0}`;
+    if (byKey) {
+        const cached = byKey.get(key);
+        if (cached)
+            return cached;
+    }
+    else {
+        byKey = new Map();
+        managedCapabilitiesCache.set(capabilities, byKey);
+    }
+    const positionedAppendWrite = capabilities.positionedAppendWrite === true && capabilities.positionedWrite && access !== "read";
+    const frozen = Object.freeze({
+        ...(capabilities.noFollow === undefined ? {} : { noFollow: capabilities.noFollow }),
+        ...(capabilities.publication === undefined ? {} : { publication: capabilities.publication }),
+        ...(capabilities.position === undefined ? {} : { position: capabilities.position }),
+        ...(capabilities.readObservation === undefined ? {} : { readObservation: capabilities.readObservation }),
+        ...(capabilities.openTruncate === undefined ? {} : { openTruncate: capabilities.openTruncate }),
+        positionedRead: capabilities.positionedRead && access !== "write",
+        positionedWrite: capabilities.positionedWrite && access !== "read" && (!append || positionedAppendWrite),
+        ...(capabilities.positionedAppendWrite === undefined ? {} : { positionedAppendWrite }),
+        ...(capabilities.delegateZeroLengthWrite === undefined ? {} : { delegateZeroLengthWrite: capabilities.delegateZeroLengthWrite && access !== "read" }),
+        truncate: capabilities.truncate && access !== "read",
+        synchronization: capabilities.synchronization,
+    });
+    byKey.set(key, frozen);
+    return frozen;
+}
 class ManagedFileDescriptor {
     capabilities;
     #path;
@@ -62,26 +93,13 @@ class ManagedFileDescriptor {
         const getPosition = capabilities.position === true ? backend.getPosition : undefined;
         if (capabilities.position === true && typeof getPosition !== "function")
             throw new FsError("ENOTSUP", { syscall: "getPosition", path });
-        this.#getPosition = getPosition?.bind(backend);
+        this.#getPosition = getPosition;
         const probeRead = capabilities.readObservation === true ? backend.probeRead : undefined;
         if (capabilities.readObservation === true && typeof probeRead !== "function")
             throw new FsError("ENOTSUP", { syscall: "probeRead", path });
-        this.#probeRead = probeRead?.bind(backend);
+        this.#probeRead = probeRead;
         this.#backend = backend;
-        const positionedAppendWrite = capabilities.positionedAppendWrite === true && capabilities.positionedWrite && options.access !== "read";
-        this.capabilities = Object.freeze({
-            ...(capabilities.noFollow === undefined ? {} : { noFollow: capabilities.noFollow }),
-            ...(capabilities.publication === undefined ? {} : { publication: capabilities.publication }),
-            ...(capabilities.position === undefined ? {} : { position: capabilities.position }),
-            ...(capabilities.readObservation === undefined ? {} : { readObservation: capabilities.readObservation }),
-            ...(capabilities.openTruncate === undefined ? {} : { openTruncate: capabilities.openTruncate }),
-            positionedRead: capabilities.positionedRead && options.access !== "write",
-            positionedWrite: capabilities.positionedWrite && options.access !== "read" && (!options.append || positionedAppendWrite),
-            ...(capabilities.positionedAppendWrite === undefined ? {} : { positionedAppendWrite }),
-            ...(capabilities.delegateZeroLengthWrite === undefined ? {} : { delegateZeroLengthWrite: capabilities.delegateZeroLengthWrite && options.access !== "read" }),
-            truncate: capabilities.truncate && options.access !== "read",
-            synchronization: capabilities.synchronization,
-        });
+        this.capabilities = getManagedCapabilities(capabilities, options.access, options.append);
     }
     #run(syscall, options, action) {
         const signal = options.signal;
@@ -128,7 +146,7 @@ class ManagedFileDescriptor {
         return this.#run("getPosition", options, async (backend, forwarded) => {
             if (!this.capabilities.position || !this.#getPosition)
                 throw new FsError("ENOTSUP", { syscall: "getPosition", path: this.#path });
-            const position = await this.#getPosition(backend.resource, forwarded);
+            const position = await this.#getPosition.call(backend, backend.resource, forwarded);
             if (!Number.isSafeInteger(position) || position < 0)
                 throw new FsError("EIO", { syscall: "getPosition", path: this.#path });
             return position;
@@ -138,7 +156,7 @@ class ManagedFileDescriptor {
         return this.#run("probeRead", options, async (backend, forwarded) => {
             if (!this.capabilities.readObservation || !this.#probeRead)
                 throw new FsError("ENOTSUP", { syscall: "probeRead", path: this.#path });
-            const readiness = await this.#probeRead(backend.resource, forwarded);
+            const readiness = await this.#probeRead.call(backend, backend.resource, forwarded);
             if (readiness !== "ready" && readiness !== "blocked" && readiness !== "unknown")
                 throw new FsError("EIO", { syscall: "probeRead", path: this.#path });
             return readiness;
@@ -209,11 +227,17 @@ export async function openFileDescriptor(path, options, capabilities, acquire) {
         throw new FsError("EINVAL", { syscall: "open", path });
     const signal = options.signal;
     signal?.throwIfAborted();
-    const keys = ["access", "creation", "truncate", "append", "mode", "exactMode", "noFollow", "synchronization", "signal"];
     const { access, creation = "never", truncate = false, append = false, mode = 0o666, synchronization } = options;
-    if (Object.keys(options).some(key => !keys.includes(key))
-        || !["read", "write", "readwrite"].includes(access)
-        || !["never", "ifMissing", "exclusive"].includes(creation)
+    let invalidKey = false;
+    for (const key in options) {
+        if (Object.prototype.hasOwnProperty.call(options, key) && !OPEN_FILE_OPTION_KEYS.has(key)) {
+            invalidKey = true;
+            break;
+        }
+    }
+    if (invalidKey
+        || (access !== "read" && access !== "write" && access !== "readwrite")
+        || (creation !== "never" && creation !== "ifMissing" && creation !== "exclusive")
         || options.noFollow !== undefined && typeof options.noFollow !== "boolean"
         || options.exactMode !== undefined && typeof options.exactMode !== "boolean"
         || typeof truncate !== "boolean" || typeof append !== "boolean"
@@ -226,7 +250,7 @@ export async function openFileDescriptor(path, options, capabilities, acquire) {
         ...(options.noFollow === undefined ? {} : { noFollow: options.noFollow }),
         ...(options.exactMode === undefined ? {} : { exactMode: options.exactMode }),
         ...(signal === undefined ? {} : { signal }), ...(synchronization === undefined ? {} : { synchronization }) });
-    const admittedCapabilities = Object.freeze({ ...capabilities });
+    const admittedCapabilities = Object.isFrozen(capabilities) ? capabilities : Object.freeze({ ...capabilities });
     admitCapabilities(path, admitted, admittedCapabilities);
     let backend;
     try {
@@ -238,9 +262,11 @@ export async function openFileDescriptor(path, options, capabilities, acquire) {
     }
     try {
         signal?.throwIfAborted();
-        const selected = Object.freeze({ ...(backend.capabilities ?? admittedCapabilities) });
+        const rawBackendCapabilities = backend.capabilities;
+        const selected = rawBackendCapabilities ? Object.freeze({ ...rawBackendCapabilities }) : admittedCapabilities;
         signal?.throwIfAborted();
-        admitCapabilities(path, admitted, selected);
+        if (rawBackendCapabilities)
+            admitCapabilities(path, admitted, selected);
         const descriptor = new ManagedFileDescriptor(path, admitted, selected, backend);
         signal?.throwIfAborted();
         return descriptor;

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

@@ -1,5 +1,5 @@
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
-import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 export declare class DeviceFileSystem implements FileSystem {
     #private;
@@ -27,11 +27,16 @@ export declare class DeviceFileSystem implements FileSystem {
     rmdir(path: string, options?: FsOptions): Promise<void>;
     publishFileConditional(path: string, source: ByteSource, options: ConditionalFilePublicationOptions): Promise<FileStat>;
     writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
-    removeEntryConditional(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
+    removeEntryConditional(path: string, options: ConditionalRemoveEntryOptions & {
+        readonly returnRemainingStat?: false | undefined;
+    }): Promise<void>;
+    removeEntryConditional(path: string, options: ConditionalRemoveEntryReceiptOptions): Promise<void | FileStat>;
     removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     removeTreeConditional(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
     createStagedFile(path: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
+    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
     removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
     prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     rename(source: string, destination: string, options?: RenameOptions): Promise<void>;

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

@@ -1,29 +1,37 @@
+import { snapshotStagingCreation } from "../staging-cleanup.js";
 import { FsError, isFsError } from "../../contracts/errors.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { compareEntries, registerEntryAuthority, registerEntryView } from "../mount/comparison.js";
 import { deviceDirectory, lexicalDevicePath, nullPath, resolveDevicePath } from "./path.js";
+import { tryResolveMemoryDevicePath } from "../memory/index.js";
 import { createDeviceYield, deviceReadStream, drainDeviceFile, drainDeviceInput } from "./stream.js";
 import { openRetainedReadFile, openRetainedResizeFile, retainedResizeCapabilities, ownedMutationCapabilities, requireOwnedMutation } from "../capabilities.js";
 import { pathNamespace } from "../path-namespace.js";
+import { runStagingGuard, snapshotDirectoryAncestry, snapshotStagingResolution } from "../staging-ancestry.js";
 import { openFileDescriptor } from "../descriptor.js";
+import { normalizePath } from "../../contracts/virtual-path.js";
 const views = new WeakMap();
 const deviceCapabilities = Object.freeze({
+    synchronousStagingResolution: false,
     readOnly: false, read: true, stat: true, realpath: true, access: true, readdir: false,
     write: true, append: true, exclusiveCreate: true, streamingRead: true, retainedRead: true,
     streamingWrite: true, streamingAppend: true, independentWriteStreams: true, copy: true, exclusiveCopy: true,
     remove: false, removeDirectory: false, recursiveRemove: false, rename: false,
     mkdir: false, recursiveMkdir: false, symlinks: false, hardlinks: false, readlink: false,
     permissions: false, timestamps: false, truncate: false, randomAccessWrite: false,
-    open: true, atomicFilePublication: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+    open: true, retainedStagingCleanup: false, atomicFilePublication: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
     atomicRename: false, atomicRenameNoReplace: false, descriptorWriteStream: true, retainedResize: true, atomicResize: false,
 });
 function globalCapabilities(filesystem) {
     const capabilities = { readOnly: false };
     const optional = {
         open: ["open"],
+        retainedStagingCleanup: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
+        synchronousDirectoryValidation: ["prepareDirectoryAncestry"], guardedStagingPublication: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
+        synchronousStagingResolution: ["prepareStagingResolution"],
         trustedOwnedStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory"],
-        atomicFilePublication: ["publishFileConditional"], atomicEntryRemoval: ["removeEntryConditional"], atomicTreeRemoval: ["removeTreeConditional"], atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
+        atomicFilePublication: ["publishFileConditional"], atomicEntryRemoval: ["removeEntryConditional"], atomicEntryRemovalReceipt: ["removeEntryConditional"], atomicTreeRemoval: ["removeTreeConditional"], atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
         streamingRead: ["readStream"], streamingWrite: ["writeStream"], retainedRead: ["openReadFile"],
         streamingAppend: ["writeStream"], descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
         symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"],
@@ -36,6 +44,8 @@ function globalCapabilities(filesystem) {
                 if (key === "copy" || key === "exclusiveCopy")
                     return undefined;
                 let declared = filesystem.capabilities[key];
+                if (key === "atomicEntryRemovalReceipt")
+                    declared = ownedMutationCapabilities(filesystem).atomicEntryRemovalReceipt;
                 if (declared === true && optional[key]?.some(method => typeof filesystem[method] !== "function"))
                     declared = false;
                 if (key === "retainedResize" && filesystem.capabilities.readOnly === true)
@@ -94,8 +104,16 @@ export class DeviceFileSystem {
         registerEntryAuthority(this, async () => "unknown");
         return view;
     }
-    #resolve(path, options, followFinal = true, resizeCreate) {
-        return resolveDevicePath(this.#filesystem, path, options, followFinal, resizeCreate);
+    #resolve(path, options, followFinal = true, resizeCreate, traversal) {
+        return resolveDevicePath(this.#filesystem, path, options, followFinal, resizeCreate, traversal);
+    }
+    #tryResolveSync(path, options) {
+        if (options.signal?.aborted)
+            return undefined;
+        if (Reflect.get(this.#filesystem, pathNamespace) === undefined) {
+            return tryResolveMemoryDevicePath(this.#filesystem, path);
+        }
+        return undefined;
     }
     async #mutable(path, options, followFinal = true) {
         if (reserved(await this.#resolve(path, options, followFinal)))
@@ -129,10 +147,14 @@ export class DeviceFileSystem {
         return reserved(resolved) ? resolved : this.#filesystem.canonicalizeMissingTarget?.(path, options);
     }
     async capabilitiesFor(path, options = {}) {
+        options.signal?.throwIfAborted();
+        if (options.stagingResolution === true && (normalizePath(path) !== path || !path.startsWith("/")))
+            throw new FsError("EINVAL", { path });
         let resolved;
         let selected;
+        const traversal = options.stagingResolution === true ? { virtual: false } : undefined;
         try {
-            resolved = await this.#resolve(path, options, options.create !== undefined || options.creation !== "exclusive", options.create);
+            resolved = await this.#resolve(path, options, options.stagingResolution !== true && (options.create !== undefined || options.creation !== "exclusive"), options.create, traversal);
         }
         catch (error) {
             options.signal?.throwIfAborted();
@@ -160,6 +182,10 @@ export class DeviceFileSystem {
             return { ...deviceCapabilities, open: false, readdir: true, write: false, append: false,
                 exclusiveCreate: false, streamingWrite: false, streamingAppend: false, independentWriteStreams: false, descriptorWriteStream: false,
                 retainedRead: false, retainedResize: false, streamingRead: false, copy: false, exclusiveCopy: false };
+        // This intent cannot bind virtual traversal. Do not infer other path
+        // capabilities by resolving the shadowed entry in the backing filesystem.
+        if (traversal?.virtual)
+            return Object.freeze({ synchronousStagingResolution: false });
         if (selected === undefined) {
             const query = this.#filesystem.capabilitiesFor;
             options.signal?.throwIfAborted();
@@ -169,26 +195,58 @@ export class DeviceFileSystem {
         const observed = ownedMutationCapabilities(this.#filesystem, selected ?? this.#filesystem.capabilities);
         options.signal?.throwIfAborted();
         const capabilities = observed.retainedResize === true ? retainedResizeCapabilities(this.#filesystem, observed) : observed;
-        const unavailable = {};
-        if (typeof this.#filesystem.open !== "function")
-            unavailable.open = false;
-        if (typeof this.#filesystem.readStream !== "function")
-            unavailable.streamingRead = false;
+        let unavailable;
+        if (options.stagingResolution === true && observed.synchronousStagingResolution === true) {
+            try {
+                const resolution = snapshotStagingResolution(await this.#filesystem.prepareStagingResolution(path, options));
+                options.signal?.throwIfAborted();
+                if (resolution.path !== resolved)
+                    throw new FsError("EAGAIN", { path });
+                if ([resolution.path, ...resolution.traversed.map(entry => entry.path)].some(entry => entry === deviceDirectory || entry.startsWith(`${deviceDirectory}/`))) {
+                    (unavailable ??= {}).synchronousStagingResolution = false;
+                }
+                runStagingGuard(resolution.validate);
+            }
+            catch (error) {
+                options.signal?.throwIfAborted();
+                if (!isFsError(error, "ENOTSUP"))
+                    throw error;
+                (unavailable ??= {}).synchronousStagingResolution = false;
+            }
+        }
+        if (resolved.startsWith(`${deviceDirectory}/`)) {
+            const u = unavailable ??= {};
+            u.atomicStagingAncestry = false;
+            u.synchronousDirectoryValidation = false;
+            u.synchronousStagingResolution = false;
+        }
+        if (typeof this.#filesystem.open !== "function" && capabilities.open !== false)
+            (unavailable ??= {}).open = false;
+        if (typeof this.#filesystem.readStream !== "function" && capabilities.streamingRead !== false)
+            (unavailable ??= {}).streamingRead = false;
         if (typeof this.#filesystem.writeStream !== "function") {
-            unavailable.streamingWrite = false;
-            unavailable.streamingAppend = false;
-            unavailable.descriptorWriteStream = false;
-        }
-        if (typeof this.#filesystem.openReadFile !== "function")
-            unavailable.retainedRead = false;
-        if (observed.atomicResize === true && (typeof this.#filesystem.resizeFile !== "function" || observed.readOnly === true))
-            unavailable.atomicResize = false;
-        const result = Object.keys(unavailable).some(key => capabilities[key] !== false)
-            ? { ...capabilities, ...unavailable } : capabilities;
+            if (capabilities.streamingWrite !== false)
+                (unavailable ??= {}).streamingWrite = false;
+            if (capabilities.streamingAppend !== false)
+                (unavailable ??= {}).streamingAppend = false;
+            if (capabilities.descriptorWriteStream !== false)
+                (unavailable ??= {}).descriptorWriteStream = false;
+        }
+        if (typeof this.#filesystem.openReadFile !== "function" && capabilities.retainedRead !== false)
+            (unavailable ??= {}).retainedRead = false;
+        if (observed.atomicResize === true && (typeof this.#filesystem.resizeFile !== "function" || observed.readOnly === true) && capabilities.atomicResize !== false)
+            (unavailable ??= {}).atomicResize = false;
+        const result = unavailable ? { ...capabilities, ...unavailable } : capabilities;
         options.signal?.throwIfAborted();
         return result;
     }
-    async stat(path, options = {}) {
+    stat(path, options = {}) {
+        if (this.#tryResolveSync(path, options) !== undefined) {
+            return this.#filesystem.stat(path, options);
+        }
+        return this.#statSlow(path, options);
+    }
+    async #statSlow(path, options) {
         const resolved = await this.#resolve(path, options);
         options.signal?.throwIfAborted();
         if (resolved === nullPath)
@@ -201,7 +259,13 @@ export class DeviceFileSystem {
         options.signal?.throwIfAborted();
         return result;
     }
-    async lstat(path, options = {}) {
+    lstat(path, options = {}) {
+        if (this.#tryResolveSync(path, options) !== undefined) {
+            return this.#filesystem.lstat(path, options);
+        }
+        return this.#lstatSlow(path, options);
+    }
+    async #lstatSlow(path, options) {
         const resolved = await this.#resolve(path, options, false);
         options.signal?.throwIfAborted();
         if (resolved === nullPath)
@@ -217,11 +281,23 @@ export class DeviceFileSystem {
     compareEntry(path, peer, peerPath, options = {}) {
         return compareEntries(this, path, peer, peerPath, options);
     }
-    async realpath(path, options = {}) {
+    realpath(path, options = {}) {
+        if (this.#tryResolveSync(path, options) !== undefined) {
+            return this.#filesystem.realpath(path, options);
+        }
+        return this.#realpathSlow(path, options);
+    }
+    async #realpathSlow(path, options) {
         const resolved = await this.#resolve(path, options);
         return reserved(resolved) ? resolved : this.#filesystem.realpath(path, options);
     }
-    async readFile(path, options = {}) {
+    readFile(path, options = {}) {
+        if (this.#tryResolveSync(path, options) !== undefined) {
+            return this.#filesystem.readFile(path, options);
+        }
+        return this.#readFileSlow(path, options);
+    }
+    async #readFileSlow(path, options) {
         const resolved = await this.#resolve(path, options);
         if (resolved === nullPath) {
             nonnegative(options.maxBytes, path);
@@ -389,7 +465,14 @@ export class DeviceFileSystem {
             throw new FsError("ENOTSUP", { path });
         await this.#filesystem.writeStream(path, source, options);
     }
-    async readdir(path, options = {}) {
+    readdir(path, options = {}) {
+        const fast = this.#tryResolveSync(path, options);
+        if (fast !== undefined && fast !== "/") {
+            return this.#filesystem.readdir(path, options);
+        }
+        return this.#readdirSlow(path, options);
+    }
+    async #readdirSlow(path, options) {
         const resolved = await this.#resolve(path, options);
         if (resolved === nullPath)
             throw new FsError("ENOTDIR", { path });
@@ -421,7 +504,13 @@ export class DeviceFileSystem {
         admitDirectoryEntries(merged.size, limit, path);
         return [...merged.values()];
     }
-    async mkdir(path, options = {}) {
+    mkdir(path, options = {}) {
+        if (this.#tryResolveSync(path, options) !== undefined) {
+            return this.#filesystem.mkdir(path, options);
+        }
+        return this.#mkdirSlow(path, options);
+    }
+    async #mkdirSlow(path, options) {
         const resolved = await this.#resolve(path, options);
         if (reserved(resolved)) {
             if (resolved !== nullPath && options.recursive)
@@ -430,7 +519,13 @@ export class DeviceFileSystem {
         }
         await this.#filesystem.mkdir(path, options);
     }
-    async rm(path, options = {}) {
+    rm(path, options = {}) {
+        if (this.#tryResolveSync(path, options) !== undefined) {
+            return this.#filesystem.rm(path, options);
+        }
+        return this.#rmSlow(path, options);
+    }
+    async #rmSlow(path, options) {
         await this.#mutable(path, options, false);
         await this.#filesystem.rm(path, options);
     }
@@ -466,11 +561,16 @@ export class DeviceFileSystem {
         return this.#filesystem.writeFileConditional(path, data, options);
     }
     async removeEntryConditional(path, options) {
+        options = { ...options };
+        const requested = options.returnRemainingStat === true;
         await this.#mutable(path, options, false);
         await requireOwnedMutation(this.#filesystem, path, "atomicEntryRemoval", options);
+        if (requested)
+            await requireOwnedMutation(this.#filesystem, path, "atomicEntryRemovalReceipt", options);
         if (!this.#filesystem.removeEntryConditional)
             throw new FsError("ENOTSUP", { path });
-        await this.#filesystem.removeEntryConditional(path, options);
+        const receipt = await this.#filesystem.removeEntryConditional(path, options);
+        return requested && receipt !== undefined ? Object.freeze({ ...receipt }) : undefined;
     }
     async removeFileConditional(path, options) {
         await this.#mutable(path, options, false);
@@ -487,20 +587,95 @@ export class DeviceFileSystem {
         await this.#filesystem.removeTreeConditional(path, options);
     }
     async createStagedFile(path, name, content, options) {
+        options = snapshotStagingCreation(options, path);
         await this.#mutable(path, options, false);
         await requireOwnedMutation(this.#filesystem, path, "atomicFileStaging", options, true);
+        if (options.retainCleanup === true)
+            await requireOwnedMutation(this.#filesystem, path, "retainedStagingCleanup", options, true);
         if (!this.#filesystem.createStagedFile)
             throw new FsError("ENOTSUP", { path });
         return this.#filesystem.createStagedFile(path, name, content, options);
     }
     async publishStagedFile(staging, destination, options) {
+        options.signal?.throwIfAborted();
+        if (options.ancestors !== undefined) {
+            const entries = snapshotDirectoryAncestry(options.ancestors);
+            if (entries.some(entry => entry.path === deviceDirectory || entry.path.startsWith(`${deviceDirectory}/`)))
+                throw new FsError("ENOTSUP", { path: destination });
+            await requireOwnedMutation(this.#filesystem, destination, "atomicStagingAncestry", options, options.destination === null);
+        }
         for (const path of [staging.directory.path, staging.file.path, destination])
             await this.#mutable(path, options, false);
         await requireOwnedMutation(this.#filesystem, staging.directory.path, "atomicFileStaging", options);
+        await requireOwnedMutation(this.#filesystem, destination, "atomicFileStaging", options, options.destination === null);
         if (!this.#filesystem.publishStagedFile)
             throw new FsError("ENOTSUP", { path: destination });
+        if (options.commitGuard !== undefined)
+            await requireOwnedMutation(this.#filesystem, destination, "guardedStagingPublication", options, options.destination === null);
         await this.#filesystem.publishStagedFile(staging, destination, options);
     }
+    async prepareDirectoryAncestry(ancestors, options = {}) {
+        options.signal?.throwIfAborted();
+        try {
+            const entries = snapshotDirectoryAncestry(ancestors);
+            const controls = options.signal === undefined ? {} : { signal: options.signal };
+            controls.signal?.throwIfAborted();
+            if (entries.some(entry => entry.path === deviceDirectory || entry.path.startsWith(`${deviceDirectory}/`))
+                || !this.#filesystem.prepareDirectoryAncestry) {
+                throw new FsError("ENOTSUP", { syscall: "prepareDirectoryAncestry" });
+            }
+            for (const entry of entries) {
+                const declared = await this.#filesystem.capabilitiesFor?.(entry.path, { ...controls, stagingAncestry: true }) ?? this.#filesystem.capabilities;
+                controls.signal?.throwIfAborted();
+                if (declared.synchronousDirectoryValidation !== true)
+                    throw new FsError("ENOTSUP", { syscall: "prepareDirectoryAncestry", path: entry.path });
+            }
+            const guard = await this.#filesystem.prepareDirectoryAncestry(entries, controls);
+            controls.signal?.throwIfAborted();
+            if (typeof guard !== "function")
+                throw new FsError("ENOTSUP", { syscall: "prepareDirectoryAncestry" });
+            return () => {
+                controls.signal?.throwIfAborted();
+                runStagingGuard(guard);
+                return true;
+            };
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            throw error;
+        }
+    }
+    async prepareStagingResolution(path, options = {}) {
+        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        controls.signal?.throwIfAborted();
+        if (normalizePath(path) !== path || !path.startsWith("/"))
+            throw new FsError("EINVAL", { path });
+        try {
+            const traversal = { virtual: false };
+            const resolved = await this.#resolve(path, controls, false, undefined, traversal);
+            controls.signal?.throwIfAborted();
+            if (traversal.virtual)
+                throw new FsError("ENOTSUP", { path });
+            const declared = ownedMutationCapabilities(this.#filesystem, await this.#filesystem.capabilitiesFor?.(path, { ...controls, stagingResolution: true }) ?? this.#filesystem.capabilities);
+            controls.signal?.throwIfAborted();
+            if (declared.synchronousStagingResolution !== true || !this.#filesystem.prepareStagingResolution)
+                throw new FsError("ENOTSUP", { path });
+            const receipt = snapshotStagingResolution(await this.#filesystem.prepareStagingResolution(path, controls));
+            controls.signal?.throwIfAborted();
+            if (receipt.path !== resolved)
+                throw new FsError("EAGAIN", { path });
+            if ([receipt.path, ...receipt.traversed.map(entry => entry.path)].some(entry => entry === deviceDirectory || entry.startsWith(`${deviceDirectory}/`))) {
+                throw new FsError("ENOTSUP", { path });
+            }
+            const validate = () => { controls.signal?.throwIfAborted(); runStagingGuard(receipt.validate); return true; };
+            runStagingGuard(validate);
+            return snapshotStagingResolution({ ...receipt, validate });
+        }
+        catch (error) {
+            controls.signal?.throwIfAborted();
+            throw error;
+        }
+    }
     async removeStagedFile(staging, options = {}) {
         for (const path of [staging.directory.path, staging.file.path])
             await this.#mutable(path, options, false);
@@ -558,7 +733,13 @@ export class DeviceFileSystem {
             throw new FsError("EISDIR", { path: destination });
         await this.#filesystem.writeFile(destination, new Uint8Array(), { ...options, flag: options.exclusive ? "wx" : "w" });
     }
-    async access(path, mode = 0, options = {}) {
+    access(path, mode = 0, options = {}) {
+        if (this.#tryResolveSync(path, options) !== undefined) {
+            return this.#filesystem.access(path, mode, options);
+        }
+        return this.#accessSlow(path, mode, options);
+    }
+    async #accessSlow(path, mode, options) {
         const resolved = await this.#resolve(path, options);
         if (resolved === nullPath || resolved === deviceDirectory) {
             if (!Number.isInteger(mode) || mode < 0 || mode > 7)

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

@@ -2,4 +2,6 @@ import type { FileSystem, FsOptions } from "../../contracts/filesystem.js";
 export declare const nullPath = "/dev/null";
 export declare const deviceDirectory = "/dev";
 export declare function lexicalDevicePath(path: string): string;
-export declare function resolveDevicePath(filesystem: FileSystem, path: string, options: FsOptions, followFinal?: boolean, resizeCreate?: boolean): Promise<string>;
+export declare function resolveDevicePath(filesystem: FileSystem, path: string, options: FsOptions, followFinal?: boolean, resizeCreate?: boolean, traversal?: {
+    virtual: boolean;
+}): Promise<string>;