@poe-platform/safe-fs 0.1.727 → 0.1.728

package/README.md

@@ -98,6 +98,13 @@ creation and updates without inode numbers, staging directories or permission
 APIs. Read the [conditional publication contract](src/contracts/conditional-publication.md)
 before implementing the host operation; ordinary writes do not provide it.
 
+For temporary staging that must be cleaned up after its parent moves, adapters
+advertising `retainedStagingCleanup` accept `createStagedFile(..., { parent,
+retainCleanup: true })`. Use the returned `staging.cleanup.remove()` and always
+call `staging.cleanup.close()` in `finally`. Memory and its supported wrappers
+retain only the owned staging entries; replacement entries remain protected.
+See the [staging contract](src/contracts/filesystem.md#atomic-owned-staging).
+
 | Backend or wrapper | Use it for |
 | --- | --- |
 | `createMemoryFileSystem()` | Isolated, nonpersistent storage with links, permissions, timestamps, and streams; each path resolution admits at most 65,536 cumulative UTF-16 code units across the input and followed symlink targets, rejecting excess with `ENAMETOOLONG` before component allocation |
@@ -251,7 +258,7 @@ Every raw filesystem operation accepts an optional `signal`. Additional fields a
 | `copyFile` | `exclusive` (default false) |
 | `readStream` | `start` (default 0), `endExclusive` (default end of file), `chunkSize` (built-in default 64 KiB) |
 
-`access` takes a separate mode bitmask from `ACCESS_MODES`. `chmod` takes a mode, `utimes` takes millisecond timestamps, and `truncate` takes a byte length (default 0). Backend limits still apply. Node-shaped bridge methods translate their own options rather than accepting these raw option objects; see the [bridge signatures](src/bridge/filesystem.ts).
+`access` takes a separate mode bitmask from `ACCESS_MODES`. `chmod` takes a mode, `utimes` takes millisecond timestamps, and `truncate` takes a byte length (default 0). For conditional chmod, check `capabilitiesFor(path, { conditionalChmod: true })` (or `capabilities`) and require `conditionalChmod: true`; supply `parent`, `expected`, and complete root-to-parent `ancestors` together. An optional mutation-free `commitGuard` must return literal `true` synchronously. Memory validates at its metadata commit; mount and supported Memory overlays preserve wrapper ancestry. Real uses its existing externally isolated host-tree boundary and does not prevent races with other processes. Backend limits still apply. Node-shaped bridge methods translate their own options rather than accepting these raw option objects; see the [bridge signatures](src/bridge/filesystem.ts).
 
 `collectBytes(source, { maxBytes, maxMemoryBytes, signal })` snapshots streamed chunks into one growing buffer. `maxMemoryBytes` limits owned capacity, the current input's full backing buffer, and overlapping allocations during growth; exhaustion throws `EFBIG`. Browser and Worker bundles additionally share a fixed 32 MiB budget across active collectors, even when byte limits are omitted. The returned view may retain geometric spare capacity. This budget covers collection, not caller-retained results, transport buffering, archive decoding, strings, or the rest of the runtime; use streaming APIs and limit concurrent workloads for larger inputs.
 

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

@@ -44,7 +44,14 @@ export class FsError extends Error {
         const operation = options.syscall ? `, ${options.syscall}` : "";
         const path = options.path === undefined ? "" : ` '${options.path}'`;
         const destination = options.dest === undefined ? "" : ` -> '${options.dest}'`;
-        super(`${code}: ${options.message ?? descriptions[code]}${operation}${path}${destination}`, options);
+        const prevStackLimit = Error.stackTraceLimit;
+        Error.stackTraceLimit = 0;
+        try {
+            super(`${code}: ${options.message ?? descriptions[code]}${operation}${path}${destination}`, options);
+        }
+        finally {
+            Error.stackTraceLimit = prevStackLimit;
+        }
         this.name = "FsError";
         this.code = code;
         this.errno = errno;

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

@@ -68,16 +68,29 @@ export interface FileSystemCapabilities {
     readonly symlinks?: boolean;
     readonly hardlinks?: boolean;
     readonly permissions?: boolean;
+    /** Enforces chmod target/ancestry receipts and a synchronous guard at the metadata commit.
+     * Host adapters retain their documented external-filesystem isolation requirements. */
+    readonly conditionalChmod?: boolean;
     readonly timestamps?: boolean;
     readonly atomicRename?: boolean;
     /** Owned staging serialized within a trusted host; requires external tree isolation. */
     readonly trustedOwnedStaging?: boolean;
     readonly atomicFileStaging?: boolean;
+    /** Creates a cleanup handle bound to owned staging entries, independent of ancestor paths. */
+    readonly retainedStagingCleanup?: boolean;
     /** Atomically verifies every supplied root-to-parent directory identity at publication. */
     readonly atomicStagingAncestry?: boolean;
+    /** Prepares directory guards that validate without yielding or mutating state. */
+    readonly synchronousDirectoryValidation?: boolean;
+    /** Captures a followed destination path with a synchronous commit validator. */
+    readonly synchronousStagingResolution?: boolean;
+    /** Invokes commitGuard in the same synchronous section as staged replacement. */
+    readonly guardedStagingPublication?: boolean;
     readonly atomicFilePublication?: boolean;
     readonly atomicFileMutation?: boolean;
     readonly atomicEntryRemoval?: boolean;
+    /** Returns an atomic post-unlink inode snapshot when explicitly requested. */
+    readonly atomicEntryRemovalReceipt?: boolean;
     readonly atomicTreeRemoval?: boolean;
     readonly atomicDirectoryMetadata?: boolean;
     readonly atomicRenameNoReplace?: boolean;
@@ -93,10 +106,24 @@ export interface FileSystemCapabilities {
 export interface FsOptions {
     readonly signal?: AbortSignal;
 }
+export interface ChmodOptions extends FsOptions {
+    /** Conditional fields require conditionalChmod and a complete parent/target/ancestry receipt. */
+    readonly parent?: FileStat;
+    readonly expected?: FileStat;
+    readonly ancestors?: readonly FileStagingEntry[];
+    /** Trusted, mutation-free validation; must return literal true synchronously. */
+    readonly commitGuard?: () => true;
+}
 export interface OpenReadFileOptions extends FsOptions {
     readonly allowDirectory?: boolean;
 }
 export interface CapabilityQueryOptions extends OpenReadFileOptions {
+    /** Include complete wrapper ancestry when checking conditional chmod support. */
+    readonly conditionalChmod?: boolean;
+    /** Inspect complete ancestry for staged publication, including other mounts.
+     * Omission retains the ordinary per-target query and its acquisition intent. */
+    readonly stagingAncestry?: boolean;
+    readonly stagingResolution?: boolean;
     readonly create?: boolean;
     readonly creation?: OpenFileOptions["creation"];
 }
@@ -182,20 +209,46 @@ export interface ConditionalWriteFileOptions extends FsOptions {
     readonly expected: FileStat | null;
     readonly append?: boolean;
     readonly mode?: number;
+    readonly atimeMs?: number;
+    readonly mtimeMs?: number;
 }
 export interface ConditionalRemoveEntryOptions extends FsOptions {
     readonly parent: FileStat;
     readonly expected: FileStat;
 }
+export interface ConditionalRemoveEntryReceiptOptions extends ConditionalRemoveEntryOptions {
+    readonly returnRemainingStat?: boolean | undefined;
+}
 export type ConditionalRemoveFileOptions = ConditionalRemoveEntryOptions;
 export interface FileStagingEntry {
     readonly path: string;
     readonly stat: FileStat;
 }
+export interface FileResolutionStep extends FileStagingEntry {
+    readonly linkTarget?: string;
+}
+export interface FileStagingResolution {
+    readonly path: string;
+    readonly parent: FileStat;
+    readonly destination: FileStat | null;
+    readonly ancestors: readonly FileStagingEntry[];
+    readonly traversed: readonly FileResolutionStep[];
+    readonly validate: () => true;
+}
+/** Ownership acquired with staging creation. remove is one-shot with shared
+ * completion; close drains admitted removal and releases without new mutation.
+ * Both release retained resources even after a failed removal. Call close when
+ * abandoning the staging receipt. An explicit cleanup signal is independent of
+ * the creation signal; scoped cleanup consumes the cleanup operation budget. */
+export interface FileStagingCleanup {
+    remove(options?: FsOptions): Promise<void>;
+    close(): Promise<void>;
+}
 export interface FileStaging {
     readonly parent: FileStagingEntry;
     readonly directory: FileStagingEntry;
     readonly file: FileStagingEntry;
+    readonly cleanup?: FileStagingCleanup;
 }
 export type StagedFileContent = {
     readonly type: "file";
@@ -205,6 +258,8 @@ export type StagedFileContent = {
     readonly target: string;
 };
 export interface CreateStagedFileOptions extends FsOptions {
+    /** Requires retainedStagingCleanup; unsupported backends reject before creation. */
+    readonly retainCleanup?: boolean;
     readonly parent: FileStat;
     readonly mode?: number;
     readonly atimeMs?: number;
@@ -212,6 +267,9 @@ export interface CreateStagedFileOptions extends FsOptions {
 }
 export interface PublishStagedFileOptions extends FsOptions {
     readonly ancestors?: readonly FileStagingEntry[];
+    /** Trusted, mutation-free validation. Must return literal true synchronously;
+     * a promise is not acceptance. Requires guardedStagingPublication. */
+    readonly commitGuard?: () => true;
     readonly parent: FileStat;
     readonly destination: FileStat | null;
 }
@@ -241,7 +299,10 @@ export interface FileSystem {
      * Failures before commit preserve the destination. No stat/write fallback. */
     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>;
     removeTreeConditional?(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
     removeFileConditional?(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     readonly capabilities: FileSystemCapabilities;
@@ -249,6 +310,11 @@ export interface FileSystem {
     prepareDirectory?(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     createStagedFile?(directoryPath: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     publishStagedFile?(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    /** Admit a complete canonical root-to-directory prefix and prepare a guard.
+     * The returned guard checks current identities/search access synchronously;
+     * preparation is not validation, and the guard's result is not an async lease. */
+    prepareDirectoryAncestry?(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
+    prepareStagingResolution?(path: string, options?: FsOptions): Promise<FileStagingResolution>;
     removeStagedFile?(staging: FileStaging, options?: FsOptions): Promise<void>;
     openReadFile?(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
     openResizeFile?(path: string, options?: OpenResizeFileOptions): Promise<FileResizeHandle>;
@@ -275,7 +341,7 @@ export interface 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/contracts/io.js

@@ -1,15 +1,56 @@
 import { FsError } from "./errors.js";
 import { finishCleanup } from "./cleanup.js";
 import { platform } from "#safe-fs-platform";
+let sharedTextEncoder;
+const EMPTY_BYTES = new Uint8Array(0);
+const DONE_RESULT = Object.freeze({ done: true, value: undefined });
+const RESOLVED_DONE = Promise.resolve(DONE_RESULT);
+const readBytesSignal = Symbol.for("safe-fs.readBytesSignal");
+const EMPTY_BYTE_ITERATOR = Object.freeze({
+    [Symbol.asyncIterator]() { return this; },
+    tryNextSync() { return DONE_RESULT; },
+    next() { return RESOLVED_DONE; },
+    return() { return RESOLVED_DONE; },
+});
+const EMPTY_BYTE_SOURCE = Object.freeze({
+    [Symbol.asyncIterator]() { return EMPTY_BYTE_ITERATOR; },
+});
 export function toByteSource(input) {
     if (typeof input !== "string" && !(input instanceof Uint8Array)) {
         throw new TypeError("Byte source input must be a string or Uint8Array");
     }
-    const bytes = typeof input === "string" ? new TextEncoder().encode(input) : new Uint8Array(input);
-    return (async function* () {
-        if (bytes.byteLength > 0)
-            yield bytes;
-    })();
+    if (typeof input === "string") {
+        if (input.length === 0)
+            return EMPTY_BYTE_SOURCE;
+    }
+    else if (input.byteLength === 0) {
+        return EMPTY_BYTE_SOURCE;
+    }
+    const bytes = typeof input === "string" ? (sharedTextEncoder ??= new TextEncoder()).encode(input) : new Uint8Array(input);
+    return {
+        [Symbol.asyncIterator]() {
+            let consumed = false;
+            return {
+                [Symbol.asyncIterator]() { return this; },
+                tryNextSync() {
+                    if (consumed)
+                        return DONE_RESULT;
+                    consumed = true;
+                    return { done: false, value: bytes };
+                },
+                next() {
+                    if (consumed)
+                        return RESOLVED_DONE;
+                    consumed = true;
+                    return Promise.resolve({ done: false, value: bytes });
+                },
+                return() {
+                    consumed = true;
+                    return RESOLVED_DONE;
+                },
+            };
+        },
+    };
 }
 let activeCollectionBytes = 0;
 export async function collectBytes(source, options) {
@@ -91,34 +132,149 @@ async function abortable(operation, signal) {
         }
     });
 }
-export async function* readBytes(source, signal) {
-    signal?.throwIfAborted();
-    const iterator = source[Symbol.asyncIterator]();
+export function readBytes(source, signal) {
+    if (signal !== undefined && source[readBytesSignal] === signal) {
+        return source;
+    }
+    let iterator;
+    let nativeAbort = false;
     let finished = false;
-    let failed = false;
-    try {
-        while (true) {
-            const result = await abortable(() => iterator.next(), signal);
+    let closing;
+    let turn;
+    let readingSync = false;
+    let syncFailure;
+    const schedule = (action) => {
+        const previous = turn;
+        let release;
+        const reserved = new Promise(resolve => { release = resolve; });
+        turn = reserved;
+        const result = previous ? previous.then(action) : readingSync ? Promise.resolve().then(action) : action();
+        const finish = () => { if (turn === reserved)
+            turn = undefined; release(); };
+        void result.then(finish, finish);
+        return result;
+    };
+    const ensureIterator = () => {
+        if (!iterator) {
+            signal?.throwIfAborted();
+            iterator = source[Symbol.asyncIterator]();
+            nativeAbort = signal !== undefined && iterator.abortSignal === signal;
+        }
+        return iterator;
+    };
+    const cleanupIterator = async (failed) => {
+        if (!finished && iterator?.return) {
+            finished = true;
+            const cleanup = Promise.resolve().then(() => iterator.return());
+            if (signal?.aborted)
+                void cleanup.catch(() => { });
+            else
+                closing = abortable(() => cleanup, signal).then(() => { });
+        }
+        else {
+            finished = true;
+        }
+        if (closing) {
+            const pending = closing;
+            try {
+                await finishCleanup(() => pending, failed);
+            }
+            finally {
+                if (closing === pending)
+                    closing = undefined;
+            }
+        }
+    };
+    const tryNextSync = () => {
+        if (turn || readingSync || syncFailure)
+            return undefined;
+        if (finished)
+            return DONE_RESULT;
+        readingSync = true;
+        try {
+            const it = ensureIterator();
+            if (typeof it.tryNextSync !== "function")
+                return undefined;
+            signal?.throwIfAborted();
+            const syncResult = it.tryNextSync();
+            signal?.throwIfAborted();
+            if (syncResult === undefined)
+                return undefined;
+            if (syncResult.done) {
+                finished = true;
+                return DONE_RESULT;
+            }
+            if (!(syncResult.value instanceof Uint8Array))
+                throw new TypeError("Byte sources must yield Uint8Array chunks");
+            return syncResult;
+        }
+        catch (error) {
+            syncFailure = { reason: error };
+            return undefined;
+        }
+        finally {
+            readingSync = false;
+        }
+    };
+    const runNext = async () => {
+        if (finished)
+            return DONE_RESULT;
+        try {
+            if (syncFailure) {
+                const { reason } = syncFailure;
+                syncFailure = undefined;
+                throw reason;
+            }
+            const it = ensureIterator();
+            signal?.throwIfAborted();
+            const syncResult = typeof it.tryNextSync === "function" ? it.tryNextSync() : undefined;
+            const result = syncResult ?? (nativeAbort ? await it.next() : await abortable(() => it.next(), signal));
+            signal?.throwIfAborted();
             if (result.done) {
                 finished = true;
-                return;
+                return DONE_RESULT;
             }
             if (!(result.value instanceof Uint8Array))
                 throw new TypeError("Byte sources must yield Uint8Array chunks");
-            yield result.value;
+            return result;
         }
-    }
-    catch (error) {
-        failed = true;
-        throw error;
-    }
-    finally {
-        if (!finished && iterator.return) {
-            const cleanup = Promise.resolve().then(() => iterator.return());
-            if (signal?.aborted)
-                void cleanup.catch(() => { });
-            else
-                await finishCleanup(() => abortable(() => cleanup, signal), failed);
+        catch (error) {
+            await cleanupIterator(true);
+            throw error;
         }
-    }
+    };
+    const gen = {
+        [readBytesSignal]: signal,
+        abortSignal: signal,
+        [Symbol.asyncIterator]() { return this; },
+        tryNextSync,
+        next() {
+            if (!turn && !readingSync && !syncFailure) {
+                if (finished && !closing)
+                    return RESOLVED_DONE;
+                const syncResult = tryNextSync();
+                if (syncResult !== undefined) {
+                    return syncResult.done ? RESOLVED_DONE : Promise.resolve(syncResult);
+                }
+            }
+            return schedule(runNext);
+        },
+        return(value) {
+            if ((finished || !iterator?.return) && !turn && !readingSync && !closing && value === undefined) {
+                finished = true;
+                return RESOLVED_DONE;
+            }
+            return schedule(async () => {
+                await cleanupIterator(false);
+                return { done: true, value: await value };
+            });
+        },
+        throw(error) {
+            return schedule(async () => {
+                await cleanupIterator(true);
+                throw error;
+            });
+        },
+    };
+    return gen;
 }

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

@@ -1,4 +1,6 @@
-export declare function validatePath(path: string): void;
+export declare const MAX_PATH_BYTES = 65536;
+export declare const MAX_PATH_COMPONENTS = 2048;
+export declare function validatePath(path: string, maxComponents?: number): void;
 export declare function resolvePath(cwd: string, ...paths: string[]): string;
 export declare function normalizePath(path: string, cwd?: string): string;
 export declare function dirname(path: string): string;

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

@@ -1,8 +1,27 @@
 import { FsError } from "./errors.js";
-export function validatePath(path) {
+export const MAX_PATH_BYTES = 65_536;
+export const MAX_PATH_COMPONENTS = 2048;
+export function validatePath(path, maxComponents = MAX_PATH_COMPONENTS) {
     if (typeof path !== "string" || path.includes("\0")) {
         throw new FsError("EINVAL", { syscall: "resolve", message: "paths must be strings without NUL bytes" });
     }
+    if (path.length > MAX_PATH_BYTES) {
+        throw new FsError("ENAMETOOLONG", { syscall: "resolve", path });
+    }
+    const limit = Math.min(maxComponents, MAX_PATH_COMPONENTS);
+    let components = 0;
+    let inComponent = false;
+    for (let i = 0; i < path.length; i++) {
+        if (path.charCodeAt(i) === 47) {
+            inComponent = false;
+        }
+        else if (!inComponent) {
+            inComponent = true;
+            if (++components > limit) {
+                throw new FsError("ENAMETOOLONG", { syscall: "resolve", path });
+            }
+        }
+    }
 }
 export function resolvePath(cwd, ...paths) {
     validatePath(cwd);

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

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

package/dist/safe-fs/core.js

@@ -19,3 +19,4 @@ export { compareEntries, registerEntryView } from "./fs/mount/comparison.js";
 export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
+export { bindConditionalMutation } from "./fs/memory/index.js";

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

@@ -7,4 +7,4 @@ export declare function openRetainedResizeFile(filesystem: FileSystem, path: str
 export declare function readOnlyCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function quotaCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function ownedMutationCapabilities(filesystem: FileSystem, capabilities?: FileSystemCapabilities): FileSystemCapabilities;
-export declare function requireOwnedMutation(filesystem: FileSystem, path: string, capability: "atomicFilePublication" | "atomicEntryRemoval" | "atomicTreeRemoval" | "atomicFileMutation" | "atomicFileStaging" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;
+export declare function requireOwnedMutation(filesystem: FileSystem, path: string, capability: "retainedStagingCleanup" | "atomicFilePublication" | "atomicEntryRemoval" | "atomicEntryRemovalReceipt" | "atomicTreeRemoval" | "atomicFileMutation" | "atomicFileStaging" | "guardedStagingPublication" | "atomicStagingAncestry" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;

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

@@ -1,5 +1,6 @@
-import { FsError } from "../contracts/errors.js";
+import { FsError, toFsError } from "../contracts/errors.js";
 import { finishCleanup } from "../contracts/cleanup.js";
+import { inspectStagingBindings } from "./staging-ancestry.js";
 export function retainedReadCapabilities(filesystem, capabilities = filesystem.capabilities) {
     return typeof filesystem.openReadFile === "function" ? capabilities : { ...capabilities, retainedRead: false };
 }
@@ -104,11 +105,12 @@ export function readOnlyCapabilities(capabilities) {
         "symlinks", "streamingRead", "open", "retainedRead", "versionedDescriptors",
     ].filter(name => capabilities[name] !== undefined).map(name => [name, capabilities[name]]));
     return Object.freeze({
-        ...inspection, readOnly: true, write: false, append: false, exclusiveCreate: false,
+        ...inspection, retainedStagingCleanup: false, readOnly: true, write: false, append: false, exclusiveCreate: false,
+        synchronousStagingResolution: false,
         mkdir: false, recursiveMkdir: false, remove: false, removeDirectory: false, recursiveRemove: false,
         rename: false, copy: false, exclusiveCopy: false, truncate: false, streamingAppend: false,
-        randomAccessWrite: false, hardlinks: false, permissions: false, timestamps: false,
-        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+        randomAccessWrite: false, hardlinks: false, permissions: false, conditionalChmod: false, timestamps: false,
+        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         atomicFilePublication: false, atomicRename: false, atomicRenameNoReplace: false, streamingWrite: false,
     });
 }
@@ -116,35 +118,71 @@ export function quotaCapabilities(capabilities) {
     const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, !capabilities.readOnly);
     const streamingAppend = requireCapabilities(capabilities.append, !capabilities.readOnly);
     const { streamingWrite: ignoredWrite, streamingAppend: ignoredAppend, ...rest } = capabilities;
-    return Object.freeze({ ...rest, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+    return Object.freeze({ ...rest, synchronousStagingResolution: false, retainedStagingCleanup: false, atomicStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
 }
+const TRUSTED_OWNED_STAGING_METHODS = [
+    "createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory",
+];
 export function ownedMutationCapabilities(filesystem, capabilities = filesystem.capabilities) {
-    const unavailable = {};
+    let unavailable;
     if (capabilities.atomicFilePublication === true && (capabilities.readOnly === true || typeof filesystem.publishFileConditional !== "function"))
-        unavailable.atomicFilePublication = false;
+        (unavailable ??= {}).atomicFilePublication = false;
     if (capabilities.atomicEntryRemoval === true && (capabilities.readOnly === true || typeof filesystem.removeEntryConditional !== "function"))
-        unavailable.atomicEntryRemoval = false;
+        (unavailable ??= {}).atomicEntryRemoval = false;
+    if (capabilities.atomicEntryRemovalReceipt === true && (capabilities.atomicEntryRemoval !== true || unavailable?.atomicEntryRemoval === false))
+        (unavailable ??= {}).atomicEntryRemovalReceipt = false;
     if (capabilities.atomicTreeRemoval === true && (capabilities.readOnly === true || typeof filesystem.removeTreeConditional !== "function"))
-        unavailable.atomicTreeRemoval = false;
+        (unavailable ??= {}).atomicTreeRemoval = false;
     if (capabilities.atomicFileMutation === true && (capabilities.readOnly === true || typeof filesystem.writeFileConditional !== "function" || typeof filesystem.removeFileConditional !== "function"))
-        unavailable.atomicFileMutation = false;
+        (unavailable ??= {}).atomicFileMutation = false;
     if (capabilities.atomicFileStaging === true && (capabilities.readOnly === true
         || typeof filesystem.createStagedFile !== "function" || typeof filesystem.publishStagedFile !== "function" || typeof filesystem.removeStagedFile !== "function"))
-        unavailable.atomicFileStaging = false;
+        (unavailable ??= {}).atomicFileStaging = false;
+    if (capabilities.retainedStagingCleanup === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
+        (unavailable ??= {}).retainedStagingCleanup = false;
+    if (capabilities.atomicStagingAncestry === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
+        (unavailable ??= {}).atomicStagingAncestry = false;
+    if (capabilities.synchronousDirectoryValidation === true && typeof filesystem.prepareDirectoryAncestry !== "function")
+        (unavailable ??= {}).synchronousDirectoryValidation = false;
+    if (capabilities.synchronousStagingResolution === true && (capabilities.readOnly === true || typeof filesystem.prepareStagingResolution !== "function"))
+        (unavailable ??= {}).synchronousStagingResolution = false;
+    if (capabilities.guardedStagingPublication === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
+        (unavailable ??= {}).guardedStagingPublication = false;
     if (capabilities.atomicDirectoryMetadata === true && (capabilities.readOnly === true || typeof filesystem.prepareDirectory !== "function"))
-        unavailable.atomicDirectoryMetadata = false;
-    if (capabilities.trustedOwnedStaging === true && (capabilities.readOnly === true
-        || ["createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory"].some(method => typeof filesystem[method] !== "function")))
-        unavailable.trustedOwnedStaging = false;
-    return Object.keys(unavailable).length ? { ...capabilities, ...unavailable } : capabilities;
+        (unavailable ??= {}).atomicDirectoryMetadata = false;
+    if (capabilities.trustedOwnedStaging === true) {
+        let missing = capabilities.readOnly === true;
+        if (!missing) {
+            for (let i = 0; i < TRUSTED_OWNED_STAGING_METHODS.length; i++) {
+                if (typeof filesystem[TRUSTED_OWNED_STAGING_METHODS[i]] !== "function") {
+                    missing = true;
+                    break;
+                }
+            }
+        }
+        if (missing)
+            (unavailable ??= {}).trustedOwnedStaging = false;
+    }
+    return unavailable ? { ...capabilities, ...unavailable } : capabilities;
 }
 export async function requireOwnedMutation(filesystem, path, capability, options, create = false) {
-    options.signal?.throwIfAborted();
-    const capabilities = ownedMutationCapabilities(filesystem, await filesystem.capabilitiesFor?.(path, create ? { ...options, create: true } : options) ?? filesystem.capabilities);
-    options.signal?.throwIfAborted();
-    if (capabilities[capability] !== true && !(capabilities.trustedOwnedStaging === true && ["atomicFileStaging", "atomicFileMutation", "atomicDirectoryMetadata"].includes(capability)))
-        throw new FsError("ENOTSUP", { path, syscall: capability });
+    try {
+        options.signal?.throwIfAborted();
+        const query = create ? { ...options, create: true } : options;
+        const capabilities = ownedMutationCapabilities(filesystem, await filesystem.capabilitiesFor?.(path, capability === "atomicStagingAncestry" ? { ...query, stagingAncestry: true } : query) ?? filesystem.capabilities);
+        options.signal?.throwIfAborted();
+        if (capabilities[capability] !== true && !(capabilities.trustedOwnedStaging === true && ["atomicFileStaging", "atomicFileMutation", "atomicDirectoryMetadata"].includes(capability)))
+            throw new FsError("ENOTSUP", { path, syscall: capability });
+    }
+    catch (error) {
+        options.signal?.throwIfAborted();
+        if (capability === "atomicStagingAncestry" && "ancestors" in options && options.ancestors !== undefined
+            && "destination" in options && ["ENOTSUP", "ENOENT", "ENOTDIR", "ELOOP"].includes(toFsError(error).code)) {
+            await inspectStagingBindings(entry => filesystem.lstat(entry, options), path, options);
+        }
+        throw error;
+    }
 }

package/dist/safe-fs/fs/conditional-chmod.d.ts

@@ -0,0 +1,7 @@
+import type { ChmodOptions, FileStagingEntry, FileStat } from "../contracts/filesystem.js";
+export interface ConditionalChmodOptions extends ChmodOptions {
+    readonly parent: FileStat;
+    readonly expected: FileStat;
+    readonly ancestors: readonly FileStagingEntry[];
+}
+export declare function snapshotConditionalChmod(path: string, options: ChmodOptions): ConditionalChmodOptions | undefined;

package/dist/safe-fs/fs/conditional-chmod.js

@@ -0,0 +1,19 @@
+import { FsError } from "../contracts/errors.js";
+import { dirname } from "../contracts/virtual-path.js";
+import { snapshotDirectoryAncestry } from "./staging-ancestry.js";
+export function snapshotConditionalChmod(path, options) {
+    const { signal, parent, expected, ancestors, commitGuard } = options;
+    signal?.throwIfAborted();
+    if (parent === undefined && expected === undefined && ancestors === undefined && commitGuard === undefined)
+        return undefined;
+    if (parent === undefined || expected === undefined || ancestors === undefined) {
+        throw new FsError("EINVAL", { syscall: "chmod", path, message: "complete conditional chmod receipt is required" });
+    }
+    if (commitGuard !== undefined && typeof commitGuard !== "function")
+        throw new FsError("EINVAL", { syscall: "chmod", path });
+    const entries = snapshotDirectoryAncestry(ancestors);
+    if (entries.at(-1)?.path !== dirname(path))
+        throw new FsError("EINVAL", { syscall: "chmod", path });
+    return { ...(signal === undefined ? {} : { signal }), parent: { ...parent }, expected: { ...expected }, ancestors: entries,
+        ...(commitGuard === undefined ? {} : { commitGuard }) };
+}