@openclaw/fs-safe 0.19.0 → 0.21.0

package/dist/permission-exec.js

@@ -58,14 +58,11 @@ function dataProperty(value, name) {
     }
     return undefined;
 }
-function caughtPrimitiveDisplay(value) {
-    if (value !== null && (typeof value === "object" || typeof value === "function"))
-        return undefined;
-    return primitiveString(value);
-}
 /** Formats only caught permission-query failures without invoking user code. */
 export function formatCaughtPermissionFailure(error) {
-    const primitive = caughtPrimitiveDisplay(error);
+    const primitive = error !== null && (typeof error === "object" || typeof error === "function")
+        ? undefined
+        : primitiveString(error);
     if (primitive !== undefined)
         return formatBoundedCaughtDetail(primitive);
     if (!isInspectableCaughtObject(error)) {

package/dist/permissions-public.d.ts

@@ -2,3 +2,4 @@ export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspe
 export type { PermissionCommandFailure } from "./permission-exec.js";
 export { createPrivateDirectory, type CreatePrivateDirectoryOptions, } from "./private-directory.js";
 export { readOwnerAndDacl, type OwnerAndDaclResult, type WindowsAccessControlEntry, type WindowsAceFlags, } from "./owner-dacl.js";
+export { readOwnerAndDaclBatch } from "./owner-dacl-batch.js";

package/dist/permissions-public.js

@@ -1,3 +1,4 @@
 export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, safeStat, } from "./permissions.js";
 export { createPrivateDirectory, } from "./private-directory.js";
 export { readOwnerAndDacl, } from "./owner-dacl.js";
+export { readOwnerAndDaclBatch } from "./owner-dacl-batch.js";

package/dist/pinned-mutation-admission.d.ts

@@ -9,7 +9,6 @@ export type PinnedMutationPolicySnapshot = Readonly<{
 export declare function snapshotPinnedMutationPolicy(denyMutations: DenyMutationPolicy | undefined, mutationSymlinks: MutationSymlinkPolicy | undefined): PinnedMutationPolicySnapshot | undefined;
 export declare function preparePinnedWriteMutationAdmission(params: {
     rootReal: string;
-    rootWithSep: string;
     rootIdentity?: RootBoundaryIdentity;
     resolvedTargetPath: string;
     defaultRelativeParentPath: string;

package/dist/pinned-open.d.ts

@@ -14,7 +14,6 @@ export type PinnedOpenSyncResult = {
 export type PinnedOpenSyncAllowedType = "file" | "directory";
 export type PinnedOpenSyncFinalAdmission = (params: {
     path: string;
-    preRealpathIdentity: fs.BigIntStats;
     descriptorIdentity: fs.BigIntStats;
 }) => string;
 export type PinnedOpenSyncFs = Pick<typeof fs, "constants" | "lstatSync" | "realpathSync" | "openSync" | "fstatSync" | "closeSync">;

package/dist/pinned-open.js

@@ -53,14 +53,13 @@ export function openPinnedFileSync(params) {
             assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         }, preOpenStat);
-        const pathIdentity = inspectFileIdentitySync(() => {
+        inspectFileIdentitySync(() => {
             const stat = ioFs.lstatSync(realPath, { bigint: true });
             assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         }, identity);
         const admittedPath = params.finalAdmission?.({
             path: realPath,
-            preRealpathIdentity: pathIdentity,
             descriptorIdentity: identity,
         }) ?? realPath;
         const opened = { ok: true, path: admittedPath, fd, stat: openedStat, identity };

package/dist/publish-copy-stage.js

@@ -22,6 +22,10 @@ export function publishCopyStage(params) {
     // Caller authority checks can synchronously replace a parent or staged entry.
     if (params.assertBeforeMutation)
         assertCurrent();
+    // An observed collision needs no dispatch; errno after a link attempt remains ambiguous.
+    if (fs.lstatSync(targetPath, { throwIfNoEntry: false })) {
+        throw new FsSafeError("already-exists", "destination already exists");
+    }
     params.onPublicationAttempt?.();
     fs.linkSync(temporaryPath, targetPath);
     let observerRejected = false;

package/dist/read-opened-file.d.ts

@@ -7,12 +7,9 @@ export type ReadResult = {
     realPath: string;
     stat: Stats;
 };
-type OpenedFile = {
+type OpenedFile = Omit<ReadResult & {
     handle: FileHandle;
-    containment: ContainmentGuarantee;
-    realPath: string;
-    stat: Stats;
-};
+}, "buffer">;
 export declare function readOpenedFileSafely(params: {
     opened: OpenedFile;
     maxBytes?: number;

package/dist/regular-file.js

@@ -208,10 +208,10 @@ function inspectAppendPath(filePath) {
 }
 function prepareRegularAppend(filePath, rejectSymlinkParents) {
     if (rejectSymlinkParents === true) {
-        const resolvedDir = resolvePathPreservingWindowsRoot(path.dirname(filePath));
+        const unresolvedDir = path.dirname(filePath);
         assertNoSymlinkParentsSync({
-            rootDir: path.parse(resolvedDir).root,
-            targetPath: resolvedDir,
+            rootDir: path.parse(resolvePathPreservingWindowsRoot(unresolvedDir)).root,
+            targetPath: unresolvedDir,
             allowMissing: false,
             allowRootChildSymlink: true,
             requireDirectories: true,

package/dist/replace-file-buffer.d.ts

@@ -0,0 +1,4 @@
+import type syncFs from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+export declare function writeAtomicDestination(handle: FileHandle, data: Buffer, beforeWrite?: () => Promise<void>, assertBeforeMutation?: () => void, onWriting?: () => void): Promise<void>;
+export declare function writeAtomicDestinationSync(fsModule: Pick<typeof syncFs, "ftruncateSync" | "writeSync">, fd: number, data: Buffer, beforeWrite?: () => void, onWriting?: () => void): void;

package/dist/replace-file-buffer.js

@@ -0,0 +1,36 @@
+export async function writeAtomicDestination(handle, data, beforeWrite, assertBeforeMutation, onWriting) {
+    if (beforeWrite)
+        await beforeWrite();
+    assertBeforeMutation?.();
+    await handle.truncate(0);
+    onWriting?.();
+    let written = 0;
+    while (written < data.length) {
+        if (beforeWrite)
+            await beforeWrite();
+        assertBeforeMutation?.();
+        const result = await handle.write(data, written, data.length - written, written);
+        if (result.bytesWritten === 0)
+            throw new Error("Copy fallback write made no progress");
+        written += result.bytesWritten;
+    }
+    if (beforeWrite)
+        await beforeWrite();
+    assertBeforeMutation?.();
+    await handle.truncate(data.length);
+}
+export function writeAtomicDestinationSync(fsModule, fd, data, beforeWrite, onWriting) {
+    beforeWrite?.();
+    fsModule.ftruncateSync(fd, 0);
+    onWriting?.();
+    let written = 0;
+    while (written < data.length) {
+        beforeWrite?.();
+        const bytesWritten = fsModule.writeSync(fd, data, written, data.length - written, written);
+        if (bytesWritten === 0)
+            throw new Error("Copy fallback write made no progress");
+        written += bytesWritten;
+    }
+    beforeWrite?.();
+    fsModule.ftruncateSync(fd, data.length);
+}

package/dist/replace-file-copy-fallback.d.ts

@@ -1,4 +1,5 @@
 import syncFs, { type BigIntStats } from "node:fs";
+import { AtomicMutation } from "./replace-file-mutation.js";
 export type ReplaceFileDestinationHardlinkPolicy = "reject";
 export type ReplaceFileCopyFallbackRestorePolicy = "restore-original" | "none";
 export type ReplaceFileAtomicRestoreCleanup = "restored" | "restore-failed";
@@ -9,9 +10,8 @@ type AsyncFallbackFs = {
     lstat: typeof import("node:fs/promises").lstat;
     open: typeof import("node:fs/promises").open;
     rm: typeof import("node:fs/promises").rm;
-    unlink: typeof import("node:fs/promises").unlink;
 };
-type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "unlinkSync" | "writeSync">;
+type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "writeSync">;
 export declare function assertDestinationHardlinkPolicy(fsModule: AsyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): Promise<void>;
 export declare function assertDestinationHardlinkPolicySync(fsModule: SyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): void;
 export declare function copyFallbackReplace(params: {
@@ -23,6 +23,7 @@ export declare function copyFallbackReplace(params: {
     maxRestoreBytes?: number;
     expectedSourceIdentity?: BigIntStats;
     sync: boolean;
+    mutation?: AtomicMutation;
 }): Promise<void>;
 export declare function copyFallbackReplaceSync(params: Omit<Parameters<typeof copyFallbackReplace>[0], "fsModule"> & {
     fsModule: SyncFallbackFs;

package/dist/replace-file-copy-fallback.js

@@ -6,6 +6,9 @@ import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-iden
 import { readOwnedCopySource, readOwnedCopySourceSync } from "./replace-file-copy-source.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { hasErrorCode } from "./file-cleanup.js";
+import { writeAtomicDestination, writeAtomicDestinationSync } from "./replace-file-buffer.js";
+import { AtomicMutation } from "./replace-file-mutation.js";
+import { captureAtomicDestination, captureAtomicDestinationSync } from "./replace-file-destination.js";
 const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in syncFs.constants;
 const NOFOLLOW = SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0;
 const OPEN_READ_FLAGS = resolveReadOpenFlags();
@@ -44,7 +47,7 @@ function inspectPinnedDestinationSync(fsModule, fd, dest, admission, hardlinks)
     inspectFileIdentitySync(() => admitDestinationKind(fsModule.lstatSync(dest, { bigint: true }), opened, dest, admission), opened);
     assertDestinationLinks(opened, dest, admission, hardlinks);
 }
-async function openPinnedDestination(fsModule, dest, admission, hardlinks) {
+async function openPinnedDestination(fsModule, dest, admission, hardlinks, mutation) {
     let preview;
     try {
         preview = fsModule === fs ? syncFs.lstatSync(dest) : await fsModule.lstat(dest);
@@ -61,6 +64,7 @@ async function openPinnedDestination(fsModule, dest, admission, hardlinks) {
     if (admission === "restore" && preview.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
     }
+    mutation?.assert();
     const handle = await fsModule.open(dest, admission === "restore" ? OPEN_READ_WRITE_FLAGS : OPEN_READ_FLAGS);
     try {
         if (fsModule === fs)
@@ -82,7 +86,7 @@ async function openPinnedDestination(fsModule, dest, admission, hardlinks) {
         throw error;
     }
 }
-function openPinnedDestinationSync(fsModule, dest, admission, hardlinks) {
+function openPinnedDestinationSync(fsModule, dest, admission, hardlinks, mutation) {
     let preview;
     try {
         preview = fsModule.lstatSync(dest);
@@ -97,6 +101,7 @@ function openPinnedDestinationSync(fsModule, dest, admission, hardlinks) {
     if (admission === "restore" && preview.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
     }
+    mutation?.assert();
     const fd = fsModule.openSync(dest, admission === "restore" ? OPEN_READ_WRITE_FLAGS : OPEN_READ_FLAGS);
     try {
         inspectPinnedDestinationSync(fsModule, fd, dest, admission, hardlinks);
@@ -148,28 +153,6 @@ function readRestoreSnapshotSync(fsModule, fd, maxBytes, stat) {
         return bytesRead;
     }, restoreReadOptions(stat, maxBytes));
 }
-async function writeAll(handle, data) {
-    await handle.truncate(0);
-    let written = 0;
-    while (written < data.length) {
-        const result = await handle.write(data, written, data.length - written, written);
-        if (result.bytesWritten === 0)
-            throw new Error("Copy fallback write made no progress");
-        written += result.bytesWritten;
-    }
-    await handle.truncate(data.length);
-}
-function writeAllSync(fsModule, fd, data) {
-    fsModule.ftruncateSync(fd, 0);
-    let written = 0;
-    while (written < data.length) {
-        const bytesWritten = fsModule.writeSync(fd, data, written, data.length - written, written);
-        if (bytesWritten === 0)
-            throw new Error("Copy fallback write made no progress");
-        written += bytesWritten;
-    }
-    fsModule.ftruncateSync(fd, data.length);
-}
 function restoreFailure(writeError, cleanup, restoreError) {
     const primary = writeError instanceof Error ? writeError : new Error(String(writeError));
     const details = { cleanup };
@@ -180,23 +163,29 @@ function restoreFailure(writeError, cleanup, restoreError) {
         ? `Atomic copy fallback failed; original destination restored: ${primary.message}`
         : `Atomic copy fallback failed and original restoration failed: ${primary.message}`, { cause, details });
 }
-async function replacePinnedWithRestore(fsModule, handle, replacement, maxRestoreBytes, replacementMode) {
+async function replacePinnedWithRestore(fsModule, handle, replacement, maxRestoreBytes, replacementMode, destination, mutation) {
     const originalStat = fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
     const originalMode = originalStat.mode;
     const original = await readRestoreSnapshot(handle, maxRestoreBytes, originalStat);
     try {
-        await writeAll(handle, replacement);
+        await writeAtomicDestination(handle, replacement, destination?.beforeWrite, destination?.assertBeforeMutation, destination?.writing);
+        if (destination)
+            await destination.verify();
         await handle.chmod(replacementMode);
         await handle.sync();
     }
     catch (writeError) {
+        mutation.rethrowRefusal();
         try {
-            await writeAll(handle, original);
+            await writeAtomicDestination(handle, original, destination?.beforeWrite, destination?.assertBeforeMutation, destination?.writing);
+            if (destination)
+                await destination.verify();
             await handle.chmod(originalMode);
             await handle.sync();
             throw restoreFailure(writeError, "restored");
         }
         catch (restoreError) {
+            mutation.rethrowRefusal();
             if (restoreError instanceof FsSafeError && restoreError.details?.cleanup === "restored") {
                 throw restoreError;
             }
@@ -204,23 +193,27 @@ async function replacePinnedWithRestore(fsModule, handle, replacement, maxRestor
         }
     }
 }
-function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes, replacementMode, fchmodSync) {
+function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes, replacementMode, fchmodSync, destination, mutation) {
     const originalStat = fsModule.fstatSync(fd);
     const originalMode = originalStat.mode;
     const original = readRestoreSnapshotSync(fsModule, fd, maxRestoreBytes, originalStat);
     try {
-        writeAllSync(fsModule, fd, replacement);
+        writeAtomicDestinationSync(fsModule, fd, replacement, destination?.beforeWrite, destination?.writing);
+        destination?.verify();
         fchmodSync?.(fd, replacementMode);
         fsModule.fsyncSync(fd);
     }
     catch (writeError) {
+        mutation?.rethrowRefusal();
         try {
-            writeAllSync(fsModule, fd, original);
+            writeAtomicDestinationSync(fsModule, fd, original, destination?.beforeWrite, destination?.writing);
+            destination?.verify();
             fchmodSync?.(fd, originalMode);
             fsModule.fsyncSync(fd);
             throw restoreFailure(writeError, "restored");
         }
         catch (restoreError) {
+            mutation?.rethrowRefusal();
             if (restoreError instanceof FsSafeError && restoreError.details?.cleanup === "restored") {
                 throw restoreError;
             }
@@ -229,6 +222,7 @@ function replacePinnedWithRestoreSync(fsModule, fd, replacement, maxRestoreBytes
     }
 }
 export async function copyFallbackReplace(params) {
+    const mutation = params.mutation ?? new AtomicMutation({});
     const source = await readOwnedCopySource({
         fsModule: params.fsModule,
         src: params.src,
@@ -237,12 +231,16 @@ export async function copyFallbackReplace(params) {
     const { replacement } = source;
     let destHandle = null;
     let closeRequiredForSuccess = false;
+    let completed = false;
+    let destination;
     try {
         if (params.restore === "restore-original") {
-            const pinned = await openPinnedDestination(params.fsModule, params.dest, "restore", params.destinationHardlinks);
+            const pinned = await openPinnedDestination(params.fsModule, params.dest, "restore", params.destinationHardlinks, mutation);
             if (pinned) {
                 destHandle = pinned;
-                await replacePinnedWithRestore(params.fsModule, destHandle, replacement, params.maxRestoreBytes, source.mode);
+                if (mutation.active)
+                    destination = await captureAtomicDestination(params.fsModule, pinned, params.dest, mutation, params.destinationHardlinks === "reject");
+                await replacePinnedWithRestore(params.fsModule, destHandle, replacement, params.maxRestoreBytes, source.mode, destination, mutation);
             }
         }
         if (!destHandle) {
@@ -260,16 +258,31 @@ export async function copyFallbackReplace(params) {
             }
             if (destStat) {
                 await assertDestinationHardlinkPolicy(params.fsModule, params.dest, params.destinationHardlinks);
+                mutation.assert();
                 await params.fsModule.rm(params.dest, { force: true });
+                mutation.removed(params.dest);
             }
+            mutation.assert();
             destHandle = await params.fsModule.open(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, source.mode & 0o777);
-            await destHandle.writeFile(replacement);
+            if (mutation.active) {
+                destination = await captureAtomicDestination(params.fsModule, destHandle, params.dest, mutation, params.destinationHardlinks === "reject");
+                destination.writing();
+                await writeAtomicDestination(destHandle, replacement, destination.beforeWrite, destination.assertBeforeMutation);
+                await destination.verify();
+            }
+            else {
+                await destHandle.writeFile(replacement);
+            }
             await destHandle.chmod(source.mode);
             if (params.sync) {
                 await destHandle.sync();
             }
             closeRequiredForSuccess = !params.sync;
         }
+        if (destination)
+            await destination.verify();
+        destination?.published();
+        completed = true;
     }
     finally {
         if (destHandle) {
@@ -277,7 +290,7 @@ export async function copyFallbackReplace(params) {
                 await destHandle.close();
             }
             catch (closeError) {
-                if (closeRequiredForSuccess) {
+                if (closeRequiredForSuccess && completed) {
                     throw closeError;
                 }
             }
@@ -285,6 +298,7 @@ export async function copyFallbackReplace(params) {
     }
 }
 export function copyFallbackReplaceSync(params) {
+    const mutation = params.mutation ?? new AtomicMutation({});
     const source = readOwnedCopySourceSync({
         fsModule: params.fsModule,
         src: params.src,
@@ -293,12 +307,16 @@ export function copyFallbackReplaceSync(params) {
     const { replacement } = source;
     let destFd;
     let closeRequiredForSuccess = false;
+    let completed = false;
+    let destination;
     try {
         if (params.restore === "restore-original") {
-            const pinned = openPinnedDestinationSync(params.fsModule, params.dest, "restore", params.destinationHardlinks);
+            const pinned = openPinnedDestinationSync(params.fsModule, params.dest, "restore", params.destinationHardlinks, mutation);
             if (pinned !== null) {
                 destFd = pinned;
-                replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes, source.mode, params.fchmodSync);
+                if (mutation.active)
+                    destination = captureAtomicDestinationSync(params.fsModule, pinned, params.dest, mutation, params.destinationHardlinks === "reject");
+                replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes, source.mode, params.fchmodSync, destination, mutation);
             }
         }
         if (destFd === undefined) {
@@ -315,16 +333,26 @@ export function copyFallbackReplaceSync(params) {
             }
             if (destStat) {
                 assertDestinationHardlinkPolicySync(params.fsModule, params.dest, params.destinationHardlinks);
+                mutation.assert();
                 params.fsModule.rmSync(params.dest, { force: true });
+                mutation.removed(params.dest);
             }
+            mutation.assert();
             destFd = params.fsModule.openSync(params.dest, OPEN_WRITE_EXCLUSIVE_FLAGS, source.mode & 0o777);
-            writeAllSync(params.fsModule, destFd, replacement);
+            if (mutation.active)
+                destination = captureAtomicDestinationSync(params.fsModule, destFd, params.dest, mutation, params.destinationHardlinks === "reject");
+            destination?.writing();
+            writeAtomicDestinationSync(params.fsModule, destFd, replacement, destination?.beforeWrite);
+            destination?.verify();
             params.fchmodSync?.(destFd, source.mode);
             if (params.sync) {
                 params.fsModule.fsyncSync(destFd);
             }
             closeRequiredForSuccess = !params.sync;
         }
+        destination?.verify();
+        destination?.published();
+        completed = true;
     }
     finally {
         if (destFd !== undefined) {
@@ -332,7 +360,7 @@ export function copyFallbackReplaceSync(params) {
                 params.fsModule.closeSync(destFd);
             }
             catch (closeError) {
-                if (closeRequiredForSuccess) {
+                if (closeRequiredForSuccess && completed) {
                     throw closeError;
                 }
             }

package/dist/replace-file-descriptor.d.ts

@@ -1,6 +1,7 @@
 import syncFs, { type BigIntStats } from "node:fs";
 import fs, { type FileHandle } from "node:fs/promises";
 import { type DirectoryModeOwner } from "./directory-mode-node.js";
+import type { AtomicMutation } from "./replace-file-mutation.js";
 type AsyncTempFileSystem = Pick<typeof fs, "lstat" | "open" | "writeFile">;
 type SyncTempFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "lstatSync" | "openSync" | "writeFileSync">;
 export type SyncFchmod = (fd: number, mode: number) => void;
@@ -11,6 +12,7 @@ export declare function pinDirectoryForMode(params: {
     dirPath: string;
     /** Compatibility for best-effort directory modes; admission and close still fail closed. */
     ignoreChmodError?: boolean;
+    mutation?: AtomicMutation;
 }): Promise<DirectoryModeOwner | undefined>;
 export declare function applyDirectoryMode(params: Parameters<typeof pinDirectoryForMode>[0] & {
     mode: number;
@@ -20,6 +22,7 @@ export declare function applyDirectoryModeSync(params: {
     dirPath: string;
     mode: number;
     fchmodSync?: SyncFchmod;
+    mutation?: AtomicMutation;
 }): void;
 export declare function writeTempFile(params: {
     fsModule: AsyncTempFileSystem;
@@ -28,6 +31,7 @@ export declare function writeTempFile(params: {
     mode: number;
     sync: boolean;
     onIdentity?: (identity: BigIntStats) => void;
+    mutation?: AtomicMutation;
 }): Promise<{
     handle: FileHandle;
     identity: BigIntStats;

package/dist/replace-file-descriptor.js

@@ -73,7 +73,10 @@ export async function pinDirectoryForMode(params) {
                     : await inspectFileIdentity(async () => assertDirectory(await handle.stat({ bigint: true }), params.dirPath), expected);
                 return Number(opened.mode & 4095n);
             },
-            chmod: (mode) => handle.chmod(mode),
+            chmod: (mode) => {
+                params.mutation?.assert();
+                return handle.chmod(mode);
+            },
             close: () => handle.close(),
             ignoreChmodError: params.ignoreChmodError,
         });
@@ -103,6 +106,7 @@ export function applyDirectoryModeSync(params) {
     try {
         inspectFileIdentitySync(() => assertDirectory(params.fsModule.fstatSync(fd, { bigint: true }), params.dirPath), expected);
         // chmod ignores file-type bits; mask so raw stat modes are tolerated.
+        params.mutation?.assert();
         params.fchmodSync?.(fd, params.mode & 0o7777);
     }
     finally {
@@ -110,6 +114,7 @@ export function applyDirectoryModeSync(params) {
     }
 }
 export async function writeTempFile(params) {
+    params.mutation?.assert();
     const handle = await params.fsModule.open(params.tempPath, "wx", params.mode);
     try {
         // Custom adapters retain their async-only metadata contract.
@@ -117,6 +122,7 @@ export async function writeTempFile(params) {
             ? syncFs.fstatSync(handle.fd, { bigint: true }) : handle.stat({ bigint: true });
         const identity = await inspectFileIdentity(inspect);
         params.onIdentity?.(identity);
+        params.mutation?.assert();
         await params.fsModule.writeFile(handle, params.content);
         await handle.chmod(params.mode);
         if (params.sync) {
@@ -136,10 +142,12 @@ export async function writeTempFile(params) {
     }
 }
 export function writeTempFileSync(params) {
+    params.mutation?.assert();
     const fd = params.fsModule.openSync(params.tempPath, "wx", params.mode);
     try {
         const identity = inspectFileIdentitySync(() => params.fsModule.fstatSync(fd, { bigint: true }));
         params.onIdentity?.(identity);
+        params.mutation?.assert();
         params.fsModule.writeFileSync(fd, params.content);
         params.fchmodSync?.(fd, params.mode);
         if (params.sync) {

package/dist/replace-file-destination.d.ts

@@ -0,0 +1,17 @@
+import fsSync from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+import type { AtomicMutation } from "./replace-file-mutation.js";
+/** Borrow the writer's descriptor; never adopt an identity from a later pathname open. */
+export declare function captureAtomicDestination(fsModule: Pick<typeof fs, "lstat">, handle: FileHandle, pathname: string, mutation: AtomicMutation, rejectHardlinks: boolean): Promise<{
+    verify: () => Promise<void>;
+    writing: () => void;
+    beforeWrite: () => Promise<void>;
+    assertBeforeMutation: () => void;
+    published: () => void;
+}>;
+export declare function captureAtomicDestinationSync(fsModule: Pick<typeof fsSync, "lstatSync" | "fstatSync">, fd: number, pathname: string, mutation: AtomicMutation, rejectHardlinks: boolean): {
+    verify: () => void;
+    writing: () => void;
+    beforeWrite: () => void;
+    published: () => void;
+};

package/dist/replace-file-destination.js

@@ -0,0 +1,61 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+function regular(stat, pathname, rejectHardlinks) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new FsSafeError("path-mismatch", `Atomic replace destination changed: ${pathname}`);
+    }
+    if (rejectHardlinks && stat.nlink !== 1n) {
+        throw new FsSafeError("hardlink", `Hardlinked atomic replace destination not allowed: ${pathname}`);
+    }
+    return stat;
+}
+/** Borrow the writer's descriptor; never adopt an identity from a later pathname open. */
+export async function captureAtomicDestination(fsModule, handle, pathname, mutation, rejectHardlinks) {
+    const inspect = () => fsModule === fs
+        ? fsSync.fstatSync(handle.fd, { bigint: true }) : handle.stat({ bigint: true });
+    const identity = await inspectFileIdentity(inspect);
+    regular(identity, pathname, rejectHardlinks);
+    const verify = async () => {
+        try {
+            await inspectFileIdentity(async () => regular(await inspect(), pathname, rejectHardlinks), identity);
+            await inspectFileIdentity(async () => regular(await fsModule.lstat(pathname, { bigint: true }), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => mutation.destination("writing", pathname, identity),
+        beforeWrite: async () => {
+            mutation.assert();
+            await verify();
+        },
+        assertBeforeMutation: () => mutation.assert(),
+        published: () => mutation.destination("published", pathname, identity),
+    };
+}
+export function captureAtomicDestinationSync(fsModule, fd, pathname, mutation, rejectHardlinks) {
+    const identity = inspectFileIdentitySync(() => fsModule.fstatSync(fd, { bigint: true }));
+    regular(identity, pathname, rejectHardlinks);
+    const verify = () => {
+        try {
+            inspectFileIdentitySync(() => regular(fsModule.fstatSync(fd, { bigint: true }), pathname, rejectHardlinks), identity);
+            inspectFileIdentitySync(() => regular(fsModule.lstatSync(pathname, { bigint: true }), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => mutation.destination("writing", pathname, identity),
+        beforeWrite: () => {
+            mutation.assert();
+            verify();
+        },
+        published: () => mutation.destination("published", pathname, identity),
+    };
+}

package/dist/replace-file-mutation.d.ts

@@ -0,0 +1,26 @@
+import type { BigIntStats } from "node:fs";
+export type ReplaceFileAtomicDestinationState = Readonly<{
+    state: "removed";
+    path: string;
+}> | Readonly<{
+    state: "writing" | "published";
+    path: string;
+    dev: bigint;
+    ino: bigint;
+}>;
+export type AtomicMutationOptions = {
+    /** Recheck live authority before new effects; retained descriptor completion may settle. */
+    assertBeforeMutation?: () => void;
+    /** Retain observed destination facts even when later completion fails. */
+    onDestinationState?: (state: ReplaceFileAtomicDestinationState) => void;
+};
+export declare class AtomicMutation {
+    #private;
+    readonly active: boolean;
+    constructor(options: AtomicMutationOptions);
+    rethrowRefusal(): void;
+    refuse(error: unknown): never;
+    assert(): void;
+    destination(state: "writing" | "published", path: string, identity: BigIntStats): void;
+    removed(path: string): void;
+}