@poe-platform/safe-fs 0.1.726 → 0.1.728

package/dist/safe-fs/fs/memory/ledger.d.ts

@@ -17,4 +17,6 @@ export declare class MemoryAllocation {
     constructor(data: Uint8Array, ledger: MemoryLedger);
     retain(): void;
     release(): void;
+    isReleased64(): boolean;
+    reuse(): void;
 }

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

@@ -7,7 +7,8 @@ export class MemoryLedger {
         this.limits = limits;
     }
     get availableBytes() {
-        return this.limits.maxRetainedBytes - this.retainedBytes;
+        const max = this.limits.maxRetainedBytes;
+        return max === Infinity ? Infinity : max - this.retainedBytes;
     }
     fileSize(length, syscall, path) {
         if (!Number.isSafeInteger(length) || length < 0 || length > this.limits.maxFileBytes) {
@@ -15,8 +16,12 @@ export class MemoryLedger {
         }
     }
     check(bytes, units, syscall, path) {
-        if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > this.availableBytes ||
-            !Number.isSafeInteger(units) || units < 0 || units > this.limits.maxMetadataUnits - this.metadataUnits) {
+        const maxRetained = this.limits.maxRetainedBytes;
+        const maxUnits = this.limits.maxMetadataUnits;
+        if (!Number.isSafeInteger(bytes) || bytes < 0 ||
+            (maxRetained !== Infinity && bytes > maxRetained - this.retainedBytes) ||
+            !Number.isSafeInteger(units) || units < 0 ||
+            (maxUnits !== Infinity && units > maxUnits - this.metadataUnits)) {
             throw new FsError("ENOSPC", { syscall, path });
         }
     }
@@ -50,4 +55,11 @@ export class MemoryAllocation {
         if (--this.references === 0)
             this.ledger.release(this.data.byteLength, 0);
     }
+    isReleased64() {
+        return this.references === 0 && this.data.byteLength === 64;
+    }
+    reuse() {
+        this.references = 1;
+        this.data.fill(0);
+    }
 }

package/dist/safe-fs/fs/memory/missing-target.js

@@ -1,4 +1,24 @@
 import { FsError } from "../../contracts/errors.js";
+function utf8ByteLength(value) {
+    let bytes = 0;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && i + 1 < value.length && value.charCodeAt(i + 1) >= 0xdc00 && value.charCodeAt(i + 1) <= 0xdfff) {
+            bytes += 4;
+            i++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
+function exceedsComponentByteLimit(value) {
+    return value.length > 85 && (value.length > 255 || utf8ByteLength(value) > 255);
+}
 function components(path, signal) {
     const result = [];
     let start = 0;
@@ -56,7 +76,7 @@ export function resolveMissingTarget(root, path, signal) {
                 first = false;
                 continue;
             }
-            if (new TextEncoder().encode(name).byteLength > 255)
+            if (exceedsComponentByteLimit(name))
                 return fail("ENAMETOOLONG");
             const node = current.entries.get(name);
             if (!node) {

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

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, 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, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
 export interface MountFileSystemOptions {
@@ -14,6 +14,11 @@ export declare class MountFileSystem implements FileSystem {
     constructor(options: MountFileSystemOptions);
     private select;
     capabilitiesFor(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;
+    private supportsStagingAncestry;
+    private supportsDirectoryValidation;
+    prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
+    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    private prepareAncestry;
     private protected;
     openReadFile(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
     resizeFile(path: string, operation: FileResizeOperation, options?: FileResizeOptions): Promise<void>;
@@ -41,7 +46,10 @@ export declare class MountFileSystem implements FileSystem {
     private localStaging;
     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>;
@@ -56,7 +64,7 @@ export declare class MountFileSystem implements FileSystem {
     readlink(path: string, options?: FsOptions): Promise<string>;
     symlink(target: string, path: string, options?: FsOptions): Promise<void>;
     link(existingPath: string, newPath: string, options?: FsOptions): Promise<void>;
-    chmod(path: string, mode: number, options?: FsOptions): Promise<void>;
+    chmod(path: string, mode: number, options?: ChmodOptions): Promise<void>;
     utimes(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
     truncate(path: string, length?: number, options?: FsOptions): Promise<void>;
     readStream(path: string, options?: ReadStreamOptions): ByteSource;

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

@@ -6,7 +6,10 @@ import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admissi
 import { normalizePath, validatePath } from "../../contracts/virtual-path.js";
 import { forwardFileDescriptor, openFileDescriptor } from "../descriptor.js";
 import { pathNamespace } from "../path-namespace.js";
+import { createStagingCleanup, snapshotStagingCreation } from "../staging-cleanup.js";
+import { directoryAncestryPaths, inspectStagingBindings, runStagingGuard, snapshotDirectoryAncestry, snapshotStagingResolution } from "../staging-ancestry.js";
 import { compareIdentity } from "./identity.js";
+import { snapshotConditionalChmod } from "../conditional-chmod.js";
 import { compareEntries, registerEntryAuthority, registerEntryView } from "./comparison.js";
 const syntheticStat = Object.freeze({
     type: "directory", size: 0, mode: 0o40555,
@@ -102,8 +105,10 @@ export class MountFileSystem {
         const common = (capability) => {
             const optional = {
                 open: ["open"],
+                retainedStagingCleanup: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
+                synchronousDirectoryValidation: ["prepareDirectoryAncestry"], guardedStagingPublication: ["createStagedFile", "publishStagedFile", "removeStagedFile"],
                 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"],
                 symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"], timestamps: ["utimes"], readlink: ["readlink"],
                 descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
             };
@@ -111,7 +116,8 @@ export class MountFileSystem {
                 if (backend.capabilities.readOnly === true
                     && !["open", "versionedDescriptors", "read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories"].includes(capability))
                     return false;
-                const declared = backend.capabilities[capability];
+                const declared = capability === "retainedStagingCleanup" || capability === "atomicEntryRemovalReceipt"
+                    ? ownedMutationCapabilities(backend)[capability] : backend.capabilities[capability];
                 if (capability === "descriptorWriteStream" && backend.capabilities.streamingWrite === false)
                     return false;
                 return declared === true && optional[capability]?.some(method => typeof backend[method] !== "function") ? false : declared;
@@ -121,6 +127,7 @@ export class MountFileSystem {
             return values.every(value => value === true) ? true : values.every(value => value === false) ? false : undefined;
         };
         const semantics = Object.fromEntries([
+            "guardedStagingPublication", "retainedStagingCleanup", "atomicEntryRemovalReceipt",
             "trustedOwnedStaging", "atomicFilePublication", "atomicEntryRemoval", "atomicTreeRemoval", "atomicFileMutation", "atomicFileStaging", "atomicDirectoryMetadata", "read", "stat", "readdir", "realpath", "access", "open", "versionedDescriptors",
             "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
             "remove", "removeDirectory", "recursiveRemove", "rename", "atomicRenameNoReplace", "copy", "exclusiveCopy", "readlink", "truncate",
@@ -131,8 +138,13 @@ export class MountFileSystem {
             readOnly: all("readOnly"),
             ...(append === undefined ? {} : { append }),
             ...semantics,
-            atomicStagingAncestry: false,
+            // Real ancestry (including synthetic mount parents) is path-dependent.
+            synchronousStagingResolution: mounts.some(({ backend }) => typeof backend.prepareStagingResolution === "function") ? undefined : false,
+            atomicStagingAncestry: mounts.some(({ backend }) => typeof backend.prepareDirectoryAncestry === "function"
+                && typeof backend.publishStagedFile === "function" && (typeof backend.capabilitiesFor === "function"
+                || backend.capabilities.guardedStagingPublication !== false && backend.capabilities.synchronousDirectoryValidation !== false)) ? undefined : false,
             atomicRename: mounts.length === 1 && all("atomicRename"),
+            conditionalChmod: all("conditionalChmod", ["chmod", "prepareDirectoryAncestry"]),
             ...(streamingRead === undefined ? {} : { streamingRead }),
             ...(streamingWrite === undefined ? {} : { streamingWrite }),
             ...(retainedRead === undefined ? {} : { retainedRead }),
@@ -143,9 +155,11 @@ export class MountFileSystem {
     }
     async capabilitiesFor(path, options = {}) {
         return this.operation("capabilitiesFor", path, options, async () => {
+            if (options.stagingResolution === true && normalizePath(globalPath(path)) !== path)
+                fail("EINVAL");
             const location = await this.resolve(path, options, {
                 allowMissing: options.create ?? true,
-                followFinal: options.create !== undefined || options.creation !== "exclusive",
+                followFinal: options.stagingResolution !== true && (options.create !== undefined || options.creation !== "exclusive"),
                 ...(options.create === undefined ? {} : { resizeCreate: options.create }),
             });
             const observed = ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(location.local, options)
@@ -155,7 +169,26 @@ export class MountFileSystem {
                 ? { ...observed, descriptorWriteStream: false } : observed;
             const resize = declared.atomicResize === true && (typeof location.mount.backend.resizeFile !== "function" || declared.readOnly === true)
                 ? { ...declared, atomicResize: false } : declared;
-            const withOpen = { ...resize, atomicStagingAncestry: false, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
+            const ancestry = options.stagingAncestry === true && location.path === normalizePath(globalPath(path))
+                && await this.supportsStagingAncestry(location, resize, options);
+            const validation = options.stagingAncestry === true ? location.stat?.type === "directory"
+                && location.path === normalizePath(globalPath(path)) && await this.supportsDirectoryValidation(location.path, options) : undefined;
+            let resolution;
+            if (options.stagingResolution === true) {
+                resolution = false;
+                if (within(location.mount.path, path) && typeof location.mount.backend.prepareStagingResolution === "function") {
+                    const input = location.mount.path === "/" ? path : path.slice(location.mount.path.length) || "/";
+                    const declared = input === location.local ? resize : ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(input, options) ?? location.mount.backend.capabilities);
+                    options.signal?.throwIfAborted();
+                    resolution = declared.synchronousStagingResolution === true && await this.supportsStagingAncestry(location, resize, options);
+                }
+            }
+            const conditionalChmod = options.conditionalChmod === true
+                ? resize.conditionalChmod === true && typeof location.mount.backend.chmod === "function"
+                    && await this.supportsDirectoryValidation(location.path.slice(0, location.path.lastIndexOf("/")) || "/", options, true)
+                : this.capabilities.conditionalChmod;
+            const { synchronousDirectoryValidation: ignoredValidation, synchronousStagingResolution: ignoredResolution, ...ordinary } = resize;
+            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
             const capabilities = location.synthetic ? { ...withOpen, open: false, retainedRead: false }
                 : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, withOpen));
             if (location.synthetic)
@@ -171,6 +204,147 @@ export class MountFileSystem {
             });
         });
     }
+    async supportsStagingAncestry(target, capabilities, options) {
+        options.signal?.throwIfAborted();
+        if (target.synthetic || target.stat !== undefined && (target.stat.type !== "file" || compareIdentity(target.stat, target.stat) !== "same")
+            || capabilities.atomicFileStaging !== true || capabilities.atomicStagingAncestry !== true
+            || capabilities.guardedStagingPublication !== true || capabilities.readOnly === true)
+            return false;
+        const parent = target.path.slice(0, target.path.lastIndexOf("/")) || "/";
+        return this.supportsDirectoryValidation(parent, options);
+    }
+    async supportsDirectoryValidation(directory, options, conditionalChmod = false) {
+        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        for (const path of directoryAncestryPaths(directory)) {
+            const entry = await this.lookup(path, controls);
+            if (entry.synthetic || entry.stat?.type !== "directory" || compareIdentity(entry.stat, entry.stat) !== "same")
+                return false;
+            const backend = entry.mount.backend;
+            const declared = await backend.capabilitiesFor?.(entry.local, { ...controls, stagingAncestry: true }) ?? backend.capabilities;
+            options.signal?.throwIfAborted();
+            if (declared.synchronousDirectoryValidation !== true && !(conditionalChmod && declared.conditionalChmod === true)
+                || typeof backend.prepareDirectoryAncestry !== "function")
+                return false;
+        }
+        return true;
+    }
+    prepareDirectoryAncestry(ancestors, options = {}) {
+        return this.operation("prepareDirectoryAncestry", ancestors.at(-1)?.path ?? "/", options, () => this.prepareAncestry(ancestors, options));
+    }
+    prepareStagingResolution(path, options = {}) {
+        const controls = options.signal === undefined ? {} : { signal: options.signal };
+        return this.operation("prepareStagingResolution", path, controls, async () => {
+            if (normalizePath(globalPath(path)) !== path)
+                fail("EINVAL");
+            const observed = [];
+            const location = await this.resolve(path, controls, { followFinal: false, allowMissing: true, resolutionSteps: observed });
+            if (location.synthetic || !within(location.mount.path, path))
+                fail("ENOTSUP");
+            const backend = location.mount.backend;
+            const input = location.mount.path === "/" ? path : path.slice(location.mount.path.length) || "/";
+            const declared = ownedMutationCapabilities(backend, await backend.capabilitiesFor?.(input, { ...controls, stagingResolution: true }) ?? backend.capabilities);
+            controls.signal?.throwIfAborted();
+            if (declared.synchronousStagingResolution !== true || !backend.prepareStagingResolution)
+                fail("ENOTSUP");
+            const prefix = directoryAncestryPaths(location.mount.path).map(ancestor => {
+                const entry = observed.find(step => step.path === ancestor);
+                if (!entry)
+                    fail("ENOTSUP");
+                return entry;
+            });
+            const outerGuard = await this.prepareAncestry(prefix, controls);
+            const bound = snapshotStagingResolution(await backend.prepareStagingResolution(input, controls));
+            controls.signal?.throwIfAborted();
+            const mapPath = (local) => location.mount.path === "/" ? local : `${location.mount.path}${local === "/" ? "" : local}`;
+            const map = (entry) => ({ ...entry, path: mapPath(entry.path) });
+            const traversed = bound.traversed.map(map);
+            const localObserved = observed.filter(entry => within(location.mount.path, entry.path));
+            if (mapPath(bound.path) !== location.path || localObserved.length !== traversed.length)
+                fail("EAGAIN");
+            for (const [index, before] of localObserved.entries()) {
+                const after = traversed[index];
+                if (this.select(after.path) !== location.mount)
+                    fail("EACCES");
+                if (before.path !== after.path || before.linkTarget !== after.linkTarget || before.stat.type !== after.stat.type
+                    || compareIdentity(before.stat, after.stat) !== "same"
+                    || before.stat.type !== "directory" && ["revision", "size", "mode", "nlink", "mtimeMs", "ctimeMs"].some(field => before.stat[field] !== after.stat[field]))
+                    fail("EAGAIN");
+            }
+            const validate = () => {
+                controls.signal?.throwIfAborted();
+                runStagingGuard(outerGuard);
+                runStagingGuard(bound.validate);
+                return true;
+            };
+            const result = snapshotStagingResolution({ ...bound, path: mapPath(bound.path),
+                ancestors: [...prefix.slice(0, -1), ...bound.ancestors.map(map)], traversed: [...prefix.slice(0, -1), ...traversed], validate });
+            runStagingGuard(validate);
+            return result;
+        });
+    }
+    async prepareAncestry(ancestors, options, conditionalChmod = false) {
+        options.signal?.throwIfAborted();
+        try {
+            const entries = snapshotDirectoryAncestry(ancestors);
+            const controls = options.signal === undefined ? {} : { signal: options.signal };
+            const groups = [];
+            for (const entry of entries) {
+                const mount = this.select(entry.path);
+                let group = groups.at(-1);
+                if (group?.mount !== mount) {
+                    group = { mount, entries: [] };
+                    groups.push(group);
+                }
+                group.entries.push({ path: mount.path === "/" ? entry.path : entry.path.slice(mount.path.length) || "/", stat: entry.stat });
+            }
+            const guards = [];
+            for (const group of groups) {
+                controls.signal?.throwIfAborted();
+                const backend = group.mount.backend;
+                for (const entry of group.entries) {
+                    let current;
+                    try {
+                        current = await backend.lstat(entry.path, controls);
+                    }
+                    catch (error) {
+                        controls.signal?.throwIfAborted();
+                        if (["ENOENT", "ENOTDIR", "ELOOP"].includes(toFsError(error).code))
+                            fail("EAGAIN");
+                        throw error;
+                    }
+                    controls.signal?.throwIfAborted();
+                    if (current.type !== "directory")
+                        fail("EAGAIN");
+                    const identity = compareIdentity(current, entry.stat);
+                    if (identity === "unknown")
+                        fail("ENOTSUP");
+                    if (identity !== "same")
+                        fail("EAGAIN");
+                    const declared = await backend.capabilitiesFor?.(entry.path, { ...controls, stagingAncestry: true }) ?? backend.capabilities;
+                    controls.signal?.throwIfAborted();
+                    if (declared.synchronousDirectoryValidation !== true && !(conditionalChmod && declared.conditionalChmod === true))
+                        fail("ENOTSUP");
+                }
+                if (typeof backend.prepareDirectoryAncestry !== "function")
+                    fail("ENOTSUP");
+                const guard = await backend.prepareDirectoryAncestry(group.entries, controls);
+                controls.signal?.throwIfAborted();
+                if (typeof guard !== "function")
+                    fail("ENOTSUP");
+                guards.push(guard);
+            }
+            return () => {
+                controls.signal?.throwIfAborted();
+                for (const guard of guards)
+                    runStagingGuard(guard);
+                return true;
+            };
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            throw error;
+        }
+    }
     protected(path) {
         return path === "/" || this.mounts.some((mount) => within(path, mount.path));
     }
@@ -324,23 +498,48 @@ export class MountFileSystem {
     async resolve(path, options, settings = {}) {
         let pending = this.components(path);
         const stack = [await this.lookup("/", options)];
+        let recordedUnits = 0;
+        const observe = (entry, linkTarget) => {
+            if (!settings.resolutionSteps || !entry.stat)
+                return;
+            recordedUnits += entry.path.length + (linkTarget?.length ?? 0);
+            if (settings.resolutionSteps.length >= 4096 || recordedUnits > 1_048_576)
+                fail("EFBIG");
+            settings.resolutionSteps.push({ path: entry.path, stat: snapshotStat(entry.stat), ...(linkTarget === undefined ? {} : { linkTarget }) });
+        };
+        observe(stack[0]);
         let boundary;
         let verification;
         let creationVerification;
+        let followedFinalLink = false;
         const verified = async (location) => {
-            const inspection = !location.stat && settings.resizeCreate === true ? creationVerification : verification;
+            let inspection = !location.stat && settings.resizeCreate === true ? creationVerification : verification;
+            // A missing entry has no realpath. Verify its existing parent while
+            // leaving dangling final symlinks on the ordinary following path.
+            if (inspection && !location.stat && settings.allowMissing && !followedFinalLink && inspection.finalName === undefined) {
+                const separator = inspection.path.lastIndexOf("/");
+                const finalName = inspection.path.slice(separator + 1);
+                if (finalName && finalName !== "." && finalName !== "..") {
+                    inspection = { ...inspection, path: inspection.path.slice(0, separator) || "/", finalName };
+                }
+            }
             if (inspection) {
                 const canonical = await inspection.mount.backend.realpath(inspection.path, options);
+                options.signal?.throwIfAborted();
+                if (!location.stat && inspection.finalName === undefined)
+                    fail("ENOTSUP");
                 validatePath(canonical);
                 if (!canonical.startsWith("/") || normalizePath(canonical) !== canonical)
                     fail("EIO");
                 if (inspection.finalName !== undefined) {
                     try {
                         await inspection.mount.backend.lstat(`${inspection.path}/${inspection.finalName}`, options);
-                        if (!location.stat && settings.resizeCreate === true)
+                        options.signal?.throwIfAborted();
+                        if (!location.stat && settings.allowMissing && settings.followFinal !== false)
                             fail("ENOTSUP");
                     }
                     catch (error) {
+                        options.signal?.throwIfAborted();
                         if (location.stat || toFsError(error).code !== "ENOENT")
                             throw error;
                     }
@@ -406,6 +605,8 @@ export class MountFileSystem {
             if (next.stat?.type === "symlink" && (settings.followFinal !== false || !final)) {
                 if (++links > 40)
                     fail("ELOOP");
+                if (final)
+                    followedFinalLink = true;
                 boundary ??= next.mount;
                 if (boundary !== next.mount)
                     fail("EACCES");
@@ -422,6 +623,7 @@ export class MountFileSystem {
                 }
                 const readlink = this.optional(next, "readlink", "symlinks");
                 const target = await readlink.call(next.mount.backend, next.local, options);
+                observe(next, target);
                 const targetParts = this.components(target);
                 if (settings.resizeCreate !== undefined && targetParts.at(-1)?.trailing && pending[0]?.trailing)
                     targetParts.pop();
@@ -446,6 +648,7 @@ export class MountFileSystem {
                 pending = [...targetParts, ...pending];
             }
             else {
+                observe(next);
                 stack.push(next);
             }
         }
@@ -672,6 +875,8 @@ export class MountFileSystem {
         }, undefined, true);
     }
     removeEntryConditional(path, options) {
+        options = { ...options };
+        const requested = options.returnRemainingStat === true;
         return this.operation("removeEntryConditional", path, options, async () => {
             const location = await this.resolve(path, options, { followFinal: false, entry: true, allowMissing: true });
             if (this.protected(location.path))
@@ -679,10 +884,13 @@ export class MountFileSystem {
             this.mutable(location);
             const backend = location.mount.backend;
             await requireOwnedMutation(backend, location.local, "atomicEntryRemoval", options);
+            if (requested)
+                await requireOwnedMutation(backend, location.local, "atomicEntryRemovalReceipt", options);
             if (!backend.removeEntryConditional)
                 fail("ENOTSUP");
-            await backend.removeEntryConditional(location.local, options);
-        });
+            const receipt = await backend.removeEntryConditional(location.local, options);
+            return requested && receipt !== undefined ? Object.freeze(snapshotStat(receipt)) : undefined;
+        }, undefined, requested);
     }
     removeFileConditional(path, options) {
         return this.operation("removeFileConditional", path, options, async () => {
@@ -710,7 +918,8 @@ export class MountFileSystem {
             await backend.removeTreeConditional(location.local, options);
         });
     }
-    createStagedFile(path, name, content, options) {
+    async createStagedFile(path, name, content, options) {
+        options = snapshotStagingCreation(options, path);
         return this.operation("createStagedFile", path, options, async () => {
             const location = await this.resolve(path, options, { followFinal: false, entry: true, allowMissing: true, missingDirectory: true });
             if (this.protected(location.path))
@@ -718,6 +927,8 @@ export class MountFileSystem {
             this.mutable(location);
             const backend = location.mount.backend;
             await requireOwnedMutation(backend, location.local, "atomicFileStaging", options, true);
+            if (options.retainCleanup === true)
+                await requireOwnedMutation(backend, location.local, "retainedStagingCleanup", options, true);
             if (!backend.createStagedFile)
                 fail("ENOTSUP");
             const receipt = await backend.createStagedFile(location.local, name, content, options);
@@ -725,23 +936,103 @@ export class MountFileSystem {
                 path: location.mount.path === "/" ? entry.path : `${location.mount.path}${entry.path === "/" ? "" : entry.path}`,
                 stat: Object.freeze(snapshotStat(entry.stat)),
             });
-            return Object.freeze({ parent: map(receipt.parent), directory: map(receipt.directory), file: map(receipt.file) });
+            try {
+                const staging = { parent: map(receipt.parent), directory: map(receipt.directory), file: map(receipt.file) };
+                if (!receipt.cleanup)
+                    return Object.freeze(staging);
+                const backendCleanup = receipt.cleanup;
+                const cleanup = createStagingCleanup(staging.directory.path, controls => this.operation("removeStagedFile", staging.directory.path, controls, () => backendCleanup.remove(controls), undefined, true), () => backendCleanup.close());
+                return Object.freeze({ ...staging, cleanup });
+            }
+            catch (error) {
+                await finishCleanup(() => receipt.cleanup?.close(), true);
+                throw error;
+            }
         }, undefined, true);
     }
     publishStagedFile(staging, destination, options) {
         return this.operation("publishStagedFile", staging.file.path, options, async () => {
+            const ancestors = options.ancestors === undefined ? undefined : snapshotDirectoryAncestry(options.ancestors);
+            const callerGuard = options.commitGuard;
+            let guard;
+            if (ancestors) {
+                const canonical = normalizePath(globalPath(destination));
+                const parent = canonical.slice(0, canonical.lastIndexOf("/")) || "/";
+                if (canonical !== destination || ancestors.at(-1)?.path !== parent)
+                    fail("EINVAL");
+                guard = await this.prepareAncestry(ancestors, options);
+                runStagingGuard(guard);
+            }
             const local = await this.localStaging(staging, options);
             const target = await this.resolve(destination, options, { followFinal: false, entry: true, allowMissing: true });
+            if (ancestors) {
+                if (target.path !== destination)
+                    fail("EAGAIN");
+                if (options.destination === null) {
+                    if (target.stat !== undefined)
+                        fail("EAGAIN");
+                }
+                else {
+                    if (target.stat === undefined || target.stat.type !== options.destination.type)
+                        fail("EAGAIN");
+                    const identity = compareIdentity(target.stat, options.destination);
+                    if (identity === "unknown")
+                        fail("ENOTSUP");
+                    if (identity !== "same")
+                        fail("EAGAIN");
+                }
+            }
             if (this.protected(target.path))
                 fail("EBUSY");
             if (local.mount !== target.mount)
                 fail("EXDEV");
             this.mutable(target);
             await requireOwnedMutation(local.mount.backend, local.staging.directory.path, "atomicFileStaging", options);
+            await requireOwnedMutation(local.mount.backend, target.local, "atomicFileStaging", options, options.destination === null);
             if (!local.mount.backend.publishStagedFile)
                 fail("ENOTSUP");
-            await local.mount.backend.publishStagedFile(local.staging, target.local, options);
-        }, destination);
+            if (ancestors || callerGuard !== undefined)
+                await requireOwnedMutation(local.mount.backend, target.local, "guardedStagingPublication", options, options.destination === null);
+            if (!ancestors) {
+                await local.mount.backend.publishStagedFile(local.staging, target.local, options);
+                return;
+            }
+            const parent = target.path.slice(0, target.path.lastIndexOf("/")) || "/";
+            if (target.path !== normalizePath(globalPath(destination)) || ancestors.at(-1)?.path !== parent)
+                fail("EINVAL");
+            try {
+                const declared = await local.mount.backend.capabilitiesFor?.(target.local, { ...options, stagingAncestry: true, ...(options.destination === null ? { create: true } : {}) }) ?? local.mount.backend.capabilities;
+                if (!await this.supportsStagingAncestry(target, declared, options))
+                    fail("ENOTSUP");
+            }
+            catch (error) {
+                options.signal?.throwIfAborted();
+                if (["ENOTSUP", "ENOENT", "ENOTDIR", "ELOOP"].includes(toFsError(error).code)) {
+                    await inspectStagingBindings(async (path) => {
+                        const entry = await this.lookup(path, options);
+                        if (!entry.stat)
+                            fail("ENOENT");
+                        return entry.stat;
+                    }, destination, options);
+                }
+                throw error;
+            }
+            const first = ancestors.findIndex(entry => entry.path === target.mount.path);
+            if (first < 0)
+                fail("EINVAL");
+            const localAncestors = ancestors.slice(first).map(entry => ({
+                path: target.mount.path === "/" ? entry.path : entry.path.slice(target.mount.path.length) || "/", stat: entry.stat,
+            }));
+            await local.mount.backend.publishStagedFile(local.staging, target.local, {
+                ...options, ancestors: localAncestors,
+                commitGuard: () => {
+                    if (callerGuard !== undefined)
+                        runStagingGuard(callerGuard);
+                    runStagingGuard(guard);
+                    return true;
+                },
+            });
+        }, destination, true);
     }
     removeStagedFile(staging, options = {}) {
         return this.operation("removeStagedFile", staging.directory.path, options, async () => {
@@ -895,9 +1186,29 @@ export class MountFileSystem {
     }
     chmod(path, mode, options = {}) {
         return this.operation("chmod", path, options, async () => {
-            const location = await this.resolve(path, options);
+            const conditional = snapshotConditionalChmod(path, options);
+            const controls = options.signal === undefined ? {} : { signal: options.signal };
+            const location = await this.resolve(path, controls, conditional ? { followFinal: false } : {});
             this.mutable(location);
-            await this.optional(location, "chmod", "permissions").call(location.mount.backend, location.local, mode, options);
+            const chmod = this.optional(location, "chmod", "permissions");
+            if (!conditional)
+                return chmod.call(location.mount.backend, location.local, mode, controls);
+            if (location.path !== path)
+                fail("EAGAIN");
+            const backend = location.mount.backend;
+            const capabilities = await backend.capabilitiesFor?.(location.local, { ...controls, conditionalChmod: true }) ?? backend.capabilities;
+            if (capabilities.conditionalChmod !== true)
+                fail("ENOTSUP");
+            const guard = await this.prepareAncestry(conditional.ancestors, controls, true);
+            const ancestors = conditional.ancestors.filter(entry => this.select(entry.path) === location.mount).map(entry => ({
+                path: location.mount.path === "/" ? entry.path : entry.path.slice(location.mount.path.length) || "/", stat: entry.stat,
+            }));
+            await chmod.call(backend, location.local, mode, { ...conditional, ancestors, commitGuard: () => {
+                    if (conditional.commitGuard)
+                        runStagingGuard(conditional.commitGuard);
+                    runStagingGuard(guard);
+                    return true;
+                } });
         });
     }
     utimes(path, atimeMs, mtimeMs, options = {}) {