@poe-platform/safe-fs 0.1.545 → 0.1.547

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

@@ -11,6 +11,7 @@ export interface FileStat {
     readonly atimeMs: number;
     readonly ctimeMs: number;
     readonly birthtimeMs?: number;
+    readonly revision?: number;
     readonly identityScope?: object | symbol;
     readonly ino?: number;
     readonly dev?: number;
@@ -51,6 +52,9 @@ export interface FileSystemCapabilities {
     readonly permissions?: boolean;
     readonly timestamps?: boolean;
     readonly atomicRename?: boolean;
+    readonly atomicFileStaging?: boolean;
+    readonly atomicFileMutation?: boolean;
+    readonly atomicDirectoryMetadata?: boolean;
     readonly atomicRenameNoReplace?: boolean;
     readonly snapshotRmdir?: boolean;
     readonly streamingRead?: boolean;
@@ -141,8 +145,57 @@ export interface ReadStreamOptions extends FsOptions {
     readonly endExclusive?: number;
     readonly chunkSize?: number;
 }
+export interface ConditionalWriteFileOptions extends FsOptions {
+    readonly parent: FileStat;
+    readonly expected: FileStat | null;
+    readonly append?: boolean;
+    readonly mode?: number;
+}
+export interface ConditionalRemoveFileOptions extends FsOptions {
+    readonly parent: FileStat;
+    readonly expected: FileStat;
+}
+export interface FileStagingEntry {
+    readonly path: string;
+    readonly stat: FileStat;
+}
+export interface FileStaging {
+    readonly parent: FileStagingEntry;
+    readonly directory: FileStagingEntry;
+    readonly file: FileStagingEntry;
+}
+export type StagedFileContent = {
+    readonly type: "file";
+    readonly data: Uint8Array;
+} | {
+    readonly type: "symlink";
+    readonly target: string;
+};
+export interface CreateStagedFileOptions extends FsOptions {
+    readonly parent: FileStat;
+    readonly mode?: number;
+    readonly atimeMs?: number;
+    readonly mtimeMs?: number;
+}
+export interface PublishStagedFileOptions extends FsOptions {
+    readonly parent: FileStat;
+    readonly destination: FileStat | null;
+}
+export interface PrepareDirectoryOptions extends FsOptions {
+    readonly expected: FileStat | null;
+    readonly parent: FileStat;
+    readonly mode?: number;
+    readonly atimeMs?: number;
+    readonly mtimeMs?: number;
+}
 export interface FileSystem {
+    writeFileConditional?(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeFileConditional?(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     readonly capabilities: FileSystemCapabilities;
+    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>;
+    removeStagedFile?(staging: FileStaging, options?: FsOptions): Promise<void>;
     openReadFile?(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
     openResizeFile?(path: string, options?: OpenResizeFileOptions): Promise<FileResizeHandle>;
     /** Missing targets reject ENOENT unless create is true; existing bytes survive refusals. */

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

@@ -1,4 +1,4 @@
-import type { FileReadHandle, FileResizeHandle, FileSystem, FileSystemCapabilities, OpenReadFileOptions, OpenResizeFileOptions } from "../contracts/filesystem.js";
+import type { FsOptions, FileReadHandle, FileResizeHandle, FileSystem, FileSystemCapabilities, OpenReadFileOptions, OpenResizeFileOptions } from "../contracts/filesystem.js";
 export declare function retainedReadCapabilities(filesystem: FileSystem, capabilities?: FileSystemCapabilities): FileSystemCapabilities;
 export declare function openRetainedReadFile(filesystem: FileSystem, path: string, options: OpenReadFileOptions): Promise<FileReadHandle>;
 export declare function requireCapabilities(...values: readonly (boolean | undefined)[]): boolean | undefined;
@@ -6,3 +6,5 @@ export declare function retainedResizeCapabilities(filesystem: FileSystem, capab
 export declare function openRetainedResizeFile(filesystem: FileSystem, path: string, options: OpenResizeFileOptions): Promise<FileResizeHandle>;
 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: "atomicFileMutation" | "atomicFileStaging" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;

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

@@ -108,7 +108,7 @@ export function readOnlyCapabilities(capabilities) {
         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, retainedResize: false, atomicResize: false,
+        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
         atomicRename: false, atomicRenameNoReplace: false, streamingWrite: false,
     });
 }
@@ -116,8 +116,26 @@ 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, descriptorWriteStream: false, atomicResize: false,
+    return Object.freeze({ ...rest, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
 }
+export function ownedMutationCapabilities(filesystem, capabilities = filesystem.capabilities) {
+    const unavailable = {};
+    if (capabilities.atomicFileMutation === true && (capabilities.readOnly === true || typeof filesystem.writeFileConditional !== "function" || typeof filesystem.removeFileConditional !== "function"))
+        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;
+    if (capabilities.atomicDirectoryMetadata === true && (capabilities.readOnly === true || typeof filesystem.prepareDirectory !== "function"))
+        unavailable.atomicDirectoryMetadata = false;
+    return Object.keys(unavailable).length ? { ...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)
+        throw new FsError("ENOTSUP", { path, syscall: capability });
+}

package/dist/safe-fs/fs/devices/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 } 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, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 export declare class DeviceFileSystem implements FileSystem {
     #private;
@@ -22,6 +22,12 @@ export declare class DeviceFileSystem implements FileSystem {
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
     rmdir(path: string, options?: FsOptions): Promise<void>;
+    writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
+    createStagedFile(path: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
+    publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
+    prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     rename(source: string, destination: string, options?: RenameOptions): Promise<void>;
     copyFile(source: string, destination: string, options?: CopyFileOptions): Promise<void>;
     access(path: string, mode?: number, options?: FsOptions): Promise<void>;

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

@@ -3,7 +3,7 @@ import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admissi
 import { compareEntries, registerEntryAuthority, registerEntryView } from "../mount/comparison.js";
 import { deviceDirectory, lexicalDevicePath, nullPath, resolveDevicePath } from "./path.js";
 import { deviceReadStream, drainDeviceFile, drainDeviceInput } from "./stream.js";
-import { openRetainedReadFile, openRetainedResizeFile, retainedResizeCapabilities } from "../capabilities.js";
+import { openRetainedReadFile, openRetainedResizeFile, retainedResizeCapabilities, ownedMutationCapabilities, requireOwnedMutation } from "../capabilities.js";
 import { pathNamespace } from "../path-namespace.js";
 const views = new WeakMap();
 const deviceCapabilities = Object.freeze({
@@ -13,11 +13,13 @@ const deviceCapabilities = Object.freeze({
     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,
+    atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
     atomicRename: false, atomicRenameNoReplace: false, descriptorWriteStream: true, retainedResize: true, atomicResize: false,
 });
 function globalCapabilities(filesystem) {
     const capabilities = { readOnly: false };
     const optional = {
+        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"],
@@ -128,7 +130,7 @@ export class DeviceFileSystem {
         options.signal?.throwIfAborted();
         const selected = query === undefined || query === null ? undefined : await Reflect.apply(query, this.#filesystem, [path, options]);
         options.signal?.throwIfAborted();
-        const observed = selected ?? this.#filesystem.capabilities;
+        const observed = ownedMutationCapabilities(this.#filesystem, selected ?? this.#filesystem.capabilities);
         options.signal?.throwIfAborted();
         const capabilities = observed.retainedResize === true ? retainedResizeCapabilities(this.#filesystem, observed) : observed;
         const unavailable = {};
@@ -351,6 +353,50 @@ export class DeviceFileSystem {
             throw new FsError("ENOTSUP", { path });
         await this.#filesystem.rmdir(path, options);
     }
+    async writeFileConditional(path, data, options) {
+        await this.#mutable(path, options, false);
+        await requireOwnedMutation(this.#filesystem, path, "atomicFileMutation", options, options.expected === null);
+        if (!this.#filesystem.writeFileConditional)
+            throw new FsError("ENOTSUP", { path });
+        return this.#filesystem.writeFileConditional(path, data, options);
+    }
+    async removeFileConditional(path, options) {
+        await this.#mutable(path, options, false);
+        await requireOwnedMutation(this.#filesystem, path, "atomicFileMutation", options);
+        if (!this.#filesystem.removeFileConditional)
+            throw new FsError("ENOTSUP", { path });
+        await this.#filesystem.removeFileConditional(path, options);
+    }
+    async createStagedFile(path, name, content, options) {
+        await this.#mutable(path, options, false);
+        await requireOwnedMutation(this.#filesystem, path, "atomicFileStaging", options, true);
+        if (!this.#filesystem.createStagedFile)
+            throw new FsError("ENOTSUP", { path });
+        return this.#filesystem.createStagedFile(path, name, content, options);
+    }
+    async publishStagedFile(staging, destination, options) {
+        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);
+        if (!this.#filesystem.publishStagedFile)
+            throw new FsError("ENOTSUP", { path: destination });
+        await this.#filesystem.publishStagedFile(staging, destination, options);
+    }
+    async removeStagedFile(staging, options = {}) {
+        for (const path of [staging.directory.path, staging.file.path])
+            await this.#mutable(path, options, false);
+        await requireOwnedMutation(this.#filesystem, staging.directory.path, "atomicFileStaging", options);
+        if (!this.#filesystem.removeStagedFile)
+            throw new FsError("ENOTSUP", { path: staging.directory.path });
+        await this.#filesystem.removeStagedFile(staging, options);
+    }
+    async prepareDirectory(path, options) {
+        await this.#mutable(path, options, false);
+        await requireOwnedMutation(this.#filesystem, path, "atomicDirectoryMetadata", options, options.expected === null);
+        if (!this.#filesystem.prepareDirectory)
+            throw new FsError("ENOTSUP", { path });
+        return this.#filesystem.prepareDirectory(path, options);
+    }
     async rename(source, destination, options = {}) {
         await this.#mutable(source, options, false);
         await this.#mutable(destination, options, false);

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

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, OpenReadFileOptions, OpenResizeFileOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, OpenReadFileOptions, OpenResizeFileOptions, WriteFileOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 import { type MemoryFileSystemOptions } from "./limits.js";
 export { defaultMemoryFileSystemLimits, type MemoryFileSystemLimits, type MemoryFileSystemOptions } from "./limits.js";
@@ -33,6 +33,9 @@ export declare class MemoryFileSystem implements FileSystem {
         permissions: true;
         timestamps: true;
         atomicRename: true;
+        atomicFileStaging: true;
+        atomicFileMutation: true;
+        atomicDirectoryMetadata: true;
         streamingRead: true;
         retainedRead: true;
         readonly retainedResize: boolean;
@@ -70,6 +73,14 @@ export declare class MemoryFileSystem implements FileSystem {
     private writeData;
     private writeAt;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    private expectEntry;
+    private stagingLocations;
+    createStagedFile(directoryPath: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
+    publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
+    prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
+    writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;

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

@@ -66,6 +66,8 @@ export class MemoryFileSystem {
             permissions: true,
             timestamps: true,
             atomicRename: true,
+            atomicFileStaging: true, atomicFileMutation: true,
+            atomicDirectoryMetadata: true,
             streamingRead: true,
             retainedRead: true,
             get retainedResize() { return stockRetainedResize(filesystem); },
@@ -115,7 +117,7 @@ export class MemoryFileSystem {
     metadata(mode) {
         const now = Date.now();
         return {
-            mode, ino: this.nextInode++, nlink: 1, references: 0,
+            mode, ino: this.nextInode++, nlink: 1, references: 0, revision: 0,
             atimeMs: now, mtimeMs: now, ctimeMs: now, birthtimeMs: now,
         };
     }
@@ -178,6 +180,7 @@ export class MemoryFileSystem {
             this.fail("EINVAL", syscall, path);
     }
     changed(node) {
+        node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, node.revision + 1);
         node.mtimeMs = node.ctimeMs = Date.now();
     }
     resolve(path, syscall, options = {}) {
@@ -259,6 +262,7 @@ export class MemoryFileSystem {
     snapshot(node) {
         return {
             type: node.type,
+            ...(Number.isSafeInteger(node.revision) ? { revision: node.revision } : {}),
             preferredIoBlockSize: 4096,
             size: node.type === "file" ? node.data.byteLength
                 : node.type === "symlink" ? new TextEncoder().encode(node.target).byteLength : 0,
@@ -405,6 +409,180 @@ export class MemoryFileSystem {
         node.atimeMs = Date.now();
         return new Uint8Array(node.data);
     }
+    expectEntry(node, expected, path, unchanged = true) {
+        if (expected === null) {
+            if (node)
+                this.fail("EAGAIN", "fileStaging", path);
+            return;
+        }
+        if (!node)
+            this.fail("EAGAIN", "fileStaging", path);
+        const current = this.snapshot(node);
+        if (!expected.identityScope || expected.identityScope !== current.identityScope
+            || !Number.isSafeInteger(expected.ino) || !Number.isSafeInteger(expected.dev))
+            this.fail("ENOTSUP", "fileStaging", path);
+        if (current.ino !== expected.ino || current.dev !== expected.dev || current.type !== expected.type)
+            this.fail("EAGAIN", "fileStaging", path);
+        if (unchanged) {
+            if (!Number.isSafeInteger(expected.revision) || !Number.isSafeInteger(current.revision))
+                this.fail("ENOTSUP", "fileStaging", path);
+            if (current.revision !== expected.revision || current.size !== expected.size || current.mode !== expected.mode
+                || current.nlink !== expected.nlink || current.mtimeMs !== expected.mtimeMs || current.ctimeMs !== expected.ctimeMs)
+                this.fail("EAGAIN", "fileStaging", path);
+        }
+    }
+    stagingLocations(staging) {
+        const parent = this.entry(staging.parent.path, "fileStaging");
+        this.expectEntry(parent.node, staging.parent.stat, staging.parent.path, false);
+        if (parent.node.type !== "directory")
+            this.fail("ENOTDIR", "fileStaging", staging.parent.path);
+        const directory = this.entry(staging.directory.path, "fileStaging");
+        this.expectEntry(directory.node, staging.directory.stat, staging.directory.path, false);
+        if (directory.parent !== parent.node || directory.node.type !== "directory" || (directory.node.mode & 0o777) !== 0o700)
+            this.fail("EAGAIN", "fileStaging", staging.directory.path);
+        const file = this.entry(staging.file.path, "fileStaging", true);
+        if (file.parent !== directory.node || !["file", "symlink"].includes(staging.file.stat.type))
+            this.fail("EAGAIN", "fileStaging", staging.file.path);
+        return { directory, file };
+    }
+    async createStagedFile(directoryPath, name, content, options) {
+        options.signal?.throwIfAborted();
+        if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\0"))
+            this.fail("EINVAL", "createStagedFile", directoryPath);
+        const location = this.entry(directoryPath, "createStagedFile", true);
+        if (location.node)
+            this.fail("EEXIST", "createStagedFile", directoryPath);
+        this.expectEntry(location.parent, options.parent, directoryPath, false);
+        this.permission(location.parent, 3, "createStagedFile", directoryPath);
+        const mode = this.mode(options.mode, content.type === "file" ? 0o666 : 0o777, "createStagedFile", directoryPath);
+        for (const time of [options.atimeMs, options.mtimeMs])
+            if (time !== undefined && !Number.isFinite(time))
+                this.fail("EINVAL", "createStagedFile", directoryPath);
+        if (content.type === "file" && !(content.data instanceof Uint8Array))
+            throw new TypeError("Staged files require Uint8Array data");
+        if (content.type === "symlink")
+            this.validatePath(content.target, "createStagedFile");
+        const retained = (location.name.length + name.length) * 2 + (content.type === "symlink" ? content.target.length * 2 : 0);
+        this.ledger.reserve(retained, 4, "createStagedFile", directoryPath);
+        let allocation;
+        let directory;
+        let file;
+        try {
+            if (content.type === "file")
+                allocation = this.bytes(content.data, "createStagedFile", directoryPath);
+            directory = this.directory(0o700);
+            file = content.type === "file"
+                ? { ...this.metadata(typeModes.file | mode), type: "file", data: allocation.data, allocation: allocation }
+                : { ...this.metadata(typeModes.symlink | mode), type: "symlink", target: content.target };
+            if (options.atimeMs !== undefined)
+                file.atimeMs = options.atimeMs;
+            if (options.mtimeMs !== undefined)
+                file.mtimeMs = options.mtimeMs;
+            directory.entries.set(name, file);
+            location.parent.entries.set(location.name, directory);
+        }
+        catch (error) {
+            allocation?.release();
+            this.ledger.release(retained, 4);
+            throw error;
+        }
+        this.changed(location.parent);
+        const parentPath = location.path.slice(0, location.path.lastIndexOf("/")) || "/";
+        const receipt = (path, node) => Object.freeze({ path, stat: Object.freeze(this.snapshot(node)) });
+        return Object.freeze({ parent: receipt(parentPath, location.parent), directory: receipt(location.path, directory), file: receipt(`${location.path}/${name}`, file) });
+    }
+    async publishStagedFile(staging, destination, options) {
+        options.signal?.throwIfAborted();
+        const { directory, file } = this.stagingLocations(staging);
+        this.expectEntry(file.node, staging.file.stat, staging.file.path);
+        const target = this.entry(destination, "publishStagedFile", true);
+        this.expectEntry(target.parent, options.parent, destination, false);
+        this.expectEntry(target.node, options.destination, destination);
+        if (target.parent === directory.node || target.node === directory.node || target.node === file.node)
+            this.fail("EINVAL", "publishStagedFile", destination);
+        if (target.node && (target.node.type !== "file" || target.node.nlink !== 1))
+            this.fail("EAGAIN", "publishStagedFile", destination);
+        return MemoryFileSystem.prototype.rename.call(this, staging.file.path, destination, { ...options, noReplace: options.destination === null });
+    }
+    async removeStagedFile(staging, options = {}) {
+        options.signal?.throwIfAborted();
+        const { directory, file } = this.stagingLocations(staging);
+        if (file.node)
+            this.expectEntry(file.node, staging.file.stat, staging.file.path);
+        const node = directory.node;
+        if (node.entries.size !== (file.node ? 1 : 0))
+            this.fail("ENOTEMPTY", "removeStagedFile", staging.directory.path);
+        this.permission(directory.parent, 3, "removeStagedFile", staging.directory.path);
+        this.permission(node, 3, "removeStagedFile", staging.file.path);
+        directory.parent.entries.delete(directory.name);
+        if (file.node) {
+            node.entries.delete(file.name);
+            this.ledger.release(file.name.length * 2, 1);
+            file.node.nlink--;
+            file.node.ctimeMs = Date.now();
+            file.node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, file.node.revision + 1);
+            this.releaseNode(file.node);
+        }
+        this.ledger.release(directory.name.length * 2, 1);
+        node.nlink = 0;
+        node.ctimeMs = Date.now();
+        node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, node.revision + 1);
+        this.releaseNode(node);
+        this.changed(directory.parent);
+    }
+    async prepareDirectory(path, options) {
+        options.signal?.throwIfAborted();
+        const location = this.entry(path, "prepareDirectory", true);
+        this.expectEntry(location.parent, options.parent, path, false);
+        this.expectEntry(location.node, options.expected, path, false);
+        const mode = options.mode === undefined ? undefined : this.mode(options.mode, 0, "prepareDirectory", path);
+        for (const time of [options.atimeMs, options.mtimeMs])
+            if (time !== undefined && !Number.isFinite(time))
+                this.fail("EINVAL", "prepareDirectory", path);
+        let node = location.node;
+        if (!node) {
+            this.permission(location.parent, 3, "prepareDirectory", path);
+            node = this.addNode(location.parent, location.name, () => this.directory(mode ?? 0o777), "prepareDirectory", path);
+        }
+        if (node.type !== "directory")
+            this.fail("ENOTDIR", "prepareDirectory", path);
+        if (mode !== undefined)
+            node.mode = typeModes.directory | mode;
+        if (options.atimeMs !== undefined)
+            node.atimeMs = options.atimeMs;
+        if (options.mtimeMs !== undefined)
+            node.mtimeMs = options.mtimeMs;
+        node.ctimeMs = Date.now();
+        node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, node.revision + 1);
+        return Object.freeze(this.snapshot(node));
+    }
+    async writeFileConditional(path, data, options) {
+        options.signal?.throwIfAborted();
+        const location = this.entry(path, "writeFileConditional", true);
+        this.expectEntry(location.parent, options.parent, path, false);
+        this.expectEntry(location.node, options.expected, path);
+        if (location.node && location.node.type !== "file")
+            this.fail("EINVAL", "writeFileConditional", path);
+        this.writeData(path, data, { ...(options.mode === undefined ? {} : { mode: options.mode }), flag: options.append ? "a" : "w" }, "writeFileConditional");
+        return Object.freeze(this.snapshot(location.parent.entries.get(location.name)));
+    }
+    async removeFileConditional(path, options) {
+        options.signal?.throwIfAborted();
+        const location = this.entry(path, "removeFileConditional", true);
+        this.expectEntry(location.parent, options.parent, path, false);
+        this.expectEntry(location.node, options.expected, path);
+        const node = location.node;
+        if (node.type !== "file")
+            this.fail("EINVAL", "removeFileConditional", path);
+        this.permission(location.parent, 3, "removeFileConditional", path);
+        location.parent.entries.delete(location.name);
+        this.ledger.release(location.name.length * 2, 1);
+        node.nlink--;
+        node.ctimeMs = Date.now();
+        node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, node.revision + 1);
+        this.releaseNode(node);
+        this.changed(location.parent);
+    }
     async writeFile(path, data, options = {}) {
         options.signal?.throwIfAborted();
         this.writeData(path, data, options, "writeFile");
@@ -467,6 +645,7 @@ export class MemoryFileSystem {
         this.ledger.release(location.name.length * 2, 1);
         node.nlink = 0;
         node.ctimeMs = Date.now();
+        node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, node.revision + 1);
         this.releaseNode(node);
         this.changed(location.parent);
     }
@@ -508,6 +687,7 @@ export class MemoryFileSystem {
             }
             entry.nlink--;
             entry.ctimeMs = Date.now();
+            entry.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, entry.revision + 1);
             this.releaseNode(entry);
         }
         this.changed(location.parent);
@@ -554,6 +734,7 @@ export class MemoryFileSystem {
                 this.ledger.release(origin.name.length * 2, 1);
                 target.node.nlink--;
                 target.node.ctimeMs = Date.now();
+                target.node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, target.node.revision + 1);
                 this.releaseNode(target.node);
             }
             else if (nameGrowth < 0)
@@ -561,6 +742,7 @@ export class MemoryFileSystem {
             this.changed(origin.parent);
             this.changed(target.parent);
             node.ctimeMs = Date.now();
+            node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, node.revision + 1);
         }
         catch (error) {
             if (error instanceof FsError)
@@ -636,6 +818,7 @@ export class MemoryFileSystem {
         }
         node.nlink++;
         node.ctimeMs = Date.now();
+        node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, node.revision + 1);
         this.changed(target.parent);
     }
     async chmod(path, mode, options = {}) {
@@ -644,6 +827,7 @@ export class MemoryFileSystem {
         const node = this.resolve(path, "chmod").node;
         node.mode = typeModes[node.type] | permissions;
         node.ctimeMs = Date.now();
+        node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, node.revision + 1);
     }
     async utimes(path, atimeMs, mtimeMs, options = {}) {
         options.signal?.throwIfAborted();
@@ -653,6 +837,7 @@ export class MemoryFileSystem {
         node.atimeMs = atimeMs;
         node.mtimeMs = mtimeMs;
         node.ctimeMs = Date.now();
+        node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, node.revision + 1);
     }
     async truncate(path, length = 0, options = {}) {
         options.signal?.throwIfAborted();

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 } 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, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 export interface MountFileSystemOptions {
     readonly root: FileSystem;
@@ -31,6 +31,13 @@ export declare class MountFileSystem implements FileSystem {
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rmdir(path: string, options?: FsOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
+    private localStaging;
+    writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
+    createStagedFile(path: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
+    publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
+    prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     rename(source: string, destination: string, options?: RenameOptions): Promise<void>;
     copyFile(source: string, destination: string, options?: CopyFileOptions): Promise<void>;
     realpath(path: string, options?: FsOptions): Promise<string>;

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

@@ -1,7 +1,7 @@
 import { FsError, isFsError, toFsError } from "../../contracts/errors.js";
 import { readBytes } from "../../contracts/io.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
-import { openRetainedReadFile, openRetainedResizeFile, readOnlyCapabilities, retainedReadCapabilities, retainedResizeCapabilities } from "../capabilities.js";
+import { requireOwnedMutation, ownedMutationCapabilities, openRetainedReadFile, openRetainedResizeFile, readOnlyCapabilities, retainedReadCapabilities, retainedResizeCapabilities } from "../capabilities.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { normalizePath, validatePath } from "../../contracts/virtual-path.js";
 import { pathNamespace } from "../path-namespace.js";
@@ -21,9 +21,10 @@ function fail(code) {
     throw new FsError(code);
 }
 function snapshotStat(stat) {
-    const { type, size, allocatedBytes, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, identityScope, ino, dev, nlink, uid, gid } = stat;
+    const { type, size, allocatedBytes, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, ino, dev, nlink, uid, gid } = stat;
     return {
         type, size, mode, mtimeMs, atimeMs, ctimeMs,
+        ...(revision === undefined ? {} : { revision }),
         ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
         ...(preferredIoBlockSize === undefined ? {} : { preferredIoBlockSize }),
         ...(birthtimeMs === undefined ? {} : { birthtimeMs }),
@@ -90,6 +91,7 @@ export class MountFileSystem {
             : mounts.every(({ backend }) => backend.capabilities.append === false) ? false : undefined;
         const common = (capability) => {
             const optional = {
+                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"],
             };
@@ -107,7 +109,7 @@ export class MountFileSystem {
             return values.every(value => value === true) ? true : values.every(value => value === false) ? false : undefined;
         };
         const semantics = Object.fromEntries([
-            "read", "stat", "readdir", "realpath", "access",
+            "atomicFileMutation", "atomicFileStaging", "atomicDirectoryMetadata", "read", "stat", "readdir", "realpath", "access",
             "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
             "remove", "removeDirectory", "recursiveRemove", "rename", "atomicRenameNoReplace", "copy", "exclusiveCopy", "readlink", "truncate",
             "streamingAppend", "randomAccessWrite", "descriptorWriteStream", "retainedResize", "atomicResize", "symlinks", "hardlinks", "permissions", "timestamps",
@@ -132,8 +134,8 @@ export class MountFileSystem {
                 allowMissing: options.create ?? true,
                 ...(options.create === undefined ? {} : { resizeCreate: options.create }),
             });
-            const observed = await location.mount.backend.capabilitiesFor?.(location.local, options)
-                ?? location.mount.backend.capabilities;
+            const observed = ownedMutationCapabilities(location.mount.backend, await location.mount.backend.capabilitiesFor?.(location.local, options)
+                ?? location.mount.backend.capabilities);
             const declared = observed.descriptorWriteStream === true
                 && (typeof location.mount.backend.writeStream !== "function" || observed.readOnly === true || observed.streamingWrite === false)
                 ? { ...observed, descriptorWriteStream: false } : observed;
@@ -214,11 +216,12 @@ export class MountFileSystem {
             cause: error, syscall, path: globalPath(path), ...(dest === undefined ? {} : { dest: globalPath(dest) }),
         });
     }
-    async operation(syscall, path, options, action, dest) {
+    async operation(syscall, path, options, action, dest, preserveReceipt = false) {
         try {
             options.signal?.throwIfAborted();
             const result = await action();
-            options.signal?.throwIfAborted();
+            if (!preserveReceipt)
+                options.signal?.throwIfAborted();
             return result;
         }
         catch (error) {
@@ -512,6 +515,102 @@ export class MountFileSystem {
             await location.mount.backend.rm(location.local, options);
         });
     }
+    async localStaging(staging, options) {
+        const parent = await this.resolve(staging.parent.path, options, { followFinal: false, entry: true });
+        const directory = await this.resolve(staging.directory.path, options, { followFinal: false, entry: true });
+        const file = await this.resolve(staging.file.path, options, { followFinal: false, entry: true, allowMissing: true });
+        if (parent.mount !== directory.mount || directory.mount !== file.mount)
+            fail("EXDEV");
+        if (this.protected(directory.path) || this.protected(file.path))
+            fail("EBUSY");
+        for (const location of [directory, file])
+            this.mutable(location);
+        return { mount: directory.mount, staging: {
+                parent: { path: parent.local, stat: staging.parent.stat },
+                directory: { path: directory.local, stat: staging.directory.stat },
+                file: { path: file.local, stat: staging.file.stat },
+            } };
+    }
+    writeFileConditional(path, data, options) {
+        return this.operation("writeFileConditional", path, options, async () => {
+            const location = await this.resolve(path, options, { followFinal: false, entry: true, allowMissing: true });
+            if (this.protected(location.path))
+                fail("EBUSY");
+            this.mutable(location);
+            const backend = location.mount.backend;
+            await requireOwnedMutation(backend, location.local, "atomicFileMutation", options, options.expected === null);
+            if (!backend.writeFileConditional)
+                fail("ENOTSUP");
+            return snapshotStat(await backend.writeFileConditional(location.local, data, options));
+        }, undefined, true);
+    }
+    removeFileConditional(path, options) {
+        return this.operation("removeFileConditional", path, options, async () => {
+            const location = await this.resolve(path, options, { followFinal: false, entry: true, allowMissing: true });
+            if (this.protected(location.path))
+                fail("EBUSY");
+            this.mutable(location);
+            const backend = location.mount.backend;
+            await requireOwnedMutation(backend, location.local, "atomicFileMutation", options);
+            if (!backend.removeFileConditional)
+                fail("ENOTSUP");
+            await backend.removeFileConditional(location.local, options);
+        });
+    }
+    createStagedFile(path, name, content, options) {
+        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))
+                fail("EBUSY");
+            this.mutable(location);
+            const backend = location.mount.backend;
+            await requireOwnedMutation(backend, location.local, "atomicFileStaging", options, true);
+            if (!backend.createStagedFile)
+                fail("ENOTSUP");
+            const receipt = await backend.createStagedFile(location.local, name, content, options);
+            const map = (entry) => Object.freeze({
+                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) });
+        }, undefined, true);
+    }
+    publishStagedFile(staging, destination, options) {
+        return this.operation("publishStagedFile", staging.file.path, options, async () => {
+            const local = await this.localStaging(staging, options);
+            const target = await this.resolve(destination, options, { followFinal: false, entry: true, allowMissing: true });
+            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);
+            if (!local.mount.backend.publishStagedFile)
+                fail("ENOTSUP");
+            await local.mount.backend.publishStagedFile(local.staging, target.local, options);
+        }, destination);
+    }
+    removeStagedFile(staging, options = {}) {
+        return this.operation("removeStagedFile", staging.directory.path, options, async () => {
+            const local = await this.localStaging(staging, options);
+            await requireOwnedMutation(local.mount.backend, local.staging.directory.path, "atomicFileStaging", options);
+            if (!local.mount.backend.removeStagedFile)
+                fail("ENOTSUP");
+            await local.mount.backend.removeStagedFile(local.staging, options);
+        });
+    }
+    prepareDirectory(path, options) {
+        return this.operation("prepareDirectory", path, options, async () => {
+            const location = await this.resolve(path, options, { followFinal: false, entry: true, allowMissing: true, missingDirectory: true });
+            if (this.protected(location.path))
+                fail("EBUSY");
+            this.mutable(location);
+            await requireOwnedMutation(location.mount.backend, location.local, "atomicDirectoryMetadata", options, options.expected === null);
+            if (!location.mount.backend.prepareDirectory)
+                fail("ENOTSUP");
+            return snapshotStat(await location.mount.backend.prepareDirectory(location.local, options));
+        }, undefined, true);
+    }
     rename(source, destination, options = {}) {
         return this.operation("rename", source, options, async () => {
             const origin = await this.resolve(source, options, { followFinal: false, entry: true });

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

@@ -8,12 +8,13 @@ import { compareIdentity } from "../mount/identity.js";
 import { compareEntries, registerEntryView } from "../mount/comparison.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 function snapshotStat(stat) {
-    const { type, size, allocatedBytes, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, identityScope, ino, dev, nlink, uid, gid } = stat;
+    const { type, size, allocatedBytes, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, ino, dev, nlink, uid, gid } = stat;
     return {
         type, size, mode, mtimeMs, atimeMs, ctimeMs,
         ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
         ...(preferredIoBlockSize === undefined ? {} : { preferredIoBlockSize }),
         ...(birthtimeMs === undefined ? {} : { birthtimeMs }),
+        ...(revision === undefined ? {} : { revision }),
         ...(identityScope === undefined ? {} : { identityScope }),
         ...(ino === undefined ? {} : { ino }),
         ...(dev === undefined ? {} : { dev }),
@@ -113,6 +114,7 @@ export class OverlayFileSystem {
         ].filter(([, value]) => value !== undefined));
         this.capabilities = Object.freeze({
             ...semantics,
+            atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
             implicitDirectories: false,
             readlink: upper.readlink === true && this.#lower.capabilities.readlink === true ? true
                 : upper.readlink === false && this.#lower.capabilities.readlink === false ? false : undefined,

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

@@ -316,7 +316,7 @@ export function withFileSystemQuota(fs, options) {
     // capabilities and methods without violating invariants on own properties.
     return new Proxy(Object.create(fs), {
         get(_target, property) {
-            if (property === "canonicalizeMissingTarget" || property === "resizeFile")
+            if (property === "writeFileConditional" || property === "removeFileConditional" || property === "resizeFile" || property === "canonicalizeMissingTarget" || property === "createStagedFile" || property === "publishStagedFile" || property === "removeStagedFile" || property === "prepareDirectory")
                 return undefined;
             if (property === "capabilities")
                 return quotaCapabilities(retainedResizeCapabilities(fs, retainedReadCapabilities(fs)));

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

@@ -9,9 +9,10 @@ function readOnly(syscall, path, dest) {
     throw new FsError("EROFS", { syscall, path, ...(dest === undefined ? {} : { dest }) });
 }
 function snapshotStat(stat) {
-    const { type, size, allocatedBytes, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, identityScope, ino, dev, nlink, uid, gid } = stat;
+    const { type, size, allocatedBytes, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, ino, dev, nlink, uid, gid } = stat;
     return {
         type, size, mode, mtimeMs, atimeMs, ctimeMs,
+        ...(revision === undefined ? {} : { revision }),
         ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
         ...(preferredIoBlockSize === undefined ? {} : { preferredIoBlockSize }),
         ...(birthtimeMs === undefined ? {} : { birthtimeMs }),

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

@@ -1,6 +1,8 @@
 import type { FileSystem, FsOptions } from "../contracts/filesystem.js";
 export declare function scopeFileSystem(filesystem: FileSystem, charge: () => void, signal: AbortSignal, cleanupCharge?: () => void): FileSystem;
 export interface RetainedFileSystemCleanupView {
+    readonly removeFileConditional?: NonNullable<FileSystem["removeFileConditional"]>;
+    readonly removeStagedFile?: NonNullable<FileSystem["removeStagedFile"]>;
     readonly lstat: FileSystem["lstat"];
     readonly realpath: FileSystem["realpath"];
     readonly rm: (path: string, options?: FsOptions) => Promise<void>;

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

@@ -1,9 +1,10 @@
 import { FsError } from "../contracts/errors.js";
 import { finishCleanup } from "../contracts/cleanup.js";
 import { registerEntryView } from "./mount/comparison.js";
-import { openRetainedResizeFile, retainedResizeCapabilities } from "./capabilities.js";
+import { openRetainedResizeFile, retainedResizeCapabilities, ownedMutationCapabilities, requireOwnedMutation } from "./capabilities.js";
 const originals = new WeakMap();
 const operations = new Set([
+    "writeFileConditional", "removeFileConditional", "createStagedFile", "publishStagedFile", "removeStagedFile", "prepareDirectory",
     "access", "appendFile", "canonicalizeMissingTarget", "capabilitiesFor", "chmod", "compareEntry",
     "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir",
     "readlink", "realpath", "rename", "resizeFile", "rm", "rmdir", "stat", "symlink", "truncate", "utimes",
@@ -151,7 +152,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
         },
         get(_target, property) {
             if (property === "capabilities")
-                return retainedResizeCapabilities(original);
+                return ownedMutationCapabilities(original, retainedResizeCapabilities(original));
             const method = Reflect.get(original, property, original);
             if (typeof method !== "function")
                 return method;
@@ -163,6 +164,15 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                     const options = args.at(-1);
                     admit(options && typeof options === "object" && "signal" in options ? options : undefined);
                 }
+                if (["writeFileConditional", "removeFileConditional", "createStagedFile", "publishStagedFile", "removeStagedFile", "prepareDirectory"].includes(String(property)))
+                    return (async () => {
+                        const path = typeof args[0] === "string" ? args[0] : args[0].directory.path;
+                        const options = args[property === "createStagedFile" ? 3 : property === "publishStagedFile" || property === "writeFileConditional" ? 2 : 1];
+                        const create = property === "createStagedFile" || (property === "writeFileConditional" || property === "prepareDirectory") && options !== undefined && "expected" in options && options.expected === null;
+                        await requireOwnedMutation(original, path, property === "prepareDirectory" ? "atomicDirectoryMetadata" : property === "writeFileConditional" || property === "removeFileConditional" ? "atomicFileMutation" : "atomicFileStaging", options ?? {}, create);
+                        assertOpen(options);
+                        return Reflect.apply(method, original, args);
+                    })();
                 if (property === "compareEntry") {
                     const peer = args[1];
                     args[1] = originals.get(peer)?.filesystem ?? peer;
@@ -187,7 +197,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                     return wrapResizeHandle(await openRetainedResizeFile(original, path, resizeOptions(options)));
                 }
                 : property === "capabilitiesFor"
-                    ? async (...args) => retainedResizeCapabilities(original, await dispatch(...args))
+                    ? async (...args) => ownedMutationCapabilities(original, retainedResizeCapabilities(original, await dispatch(...args)))
                     : property === "openReadFile"
                         ? async (...args) => wrapHandle(await dispatch(...args))
                         : property === "readStream"
@@ -219,7 +229,8 @@ export function retainFileSystemCleanup(filesystem, cleanupCallback, options) {
     let operations = 0;
     let active = false;
     let closing;
-    const invoke = (method, path, settings) => {
+    const invoke = (method, input, settings) => {
+        const path = typeof input === "string" ? input : input.directory.path;
         if (!active) {
             const rejected = Promise.reject(new FsError("EBADF", { syscall: method, path, message: "cleanup callback is not active" }));
             void rejected.catch(() => { });
@@ -237,7 +248,9 @@ export function retainFileSystemCleanup(filesystem, cleanupCallback, options) {
             if (typeof operation !== "function")
                 throw new FsError("ENOTSUP", { syscall: method, path });
             const parameters = method === "rm" ? { ...settings, recursive: false, force: false } : settings;
-            result = Promise.resolve(Reflect.apply(operation, backing, [path, parameters]));
+            result = method === "removeStagedFile" || method === "removeFileConditional"
+                ? requireOwnedMutation(backing, path, method === "removeFileConditional" ? "atomicFileMutation" : "atomicFileStaging", settings ?? {}).then(() => Reflect.apply(operation, backing, [input, parameters]))
+                : Promise.resolve(Reflect.apply(operation, backing, [input, parameters]));
         }
         catch (error) {
             result = Promise.reject(error);
@@ -249,6 +262,8 @@ export function retainFileSystemCleanup(filesystem, cleanupCallback, options) {
         return result;
     };
     const view = Object.freeze(Object.assign(Object.create(null), {
+        ...(typeof backing.removeFileConditional === "function" ? { removeFileConditional: invoke.bind(undefined, "removeFileConditional") } : {}),
+        ...(typeof backing.removeStagedFile === "function" ? { removeStagedFile: invoke.bind(undefined, "removeStagedFile") } : {}),
         lstat: invoke.bind(undefined, "lstat"),
         realpath: invoke.bind(undefined, "realpath"),
         rm: invoke.bind(undefined, "rm"),

package/package.json

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