@openclaw/fs-safe 0.20.0 → 0.21.1

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?.beforeRestore, destination?.assertBeforeMutation, destination?.writing);
+            if (destination)
+                await destination.verifyRestore();
             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?.beforeRestore, destination?.writing);
+            destination?.verifyRestore();
             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,21 @@
+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>;
+    beforeRestore: () => Promise<void>;
+    verifyRestore: () => 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;
+    beforeRestore: () => void;
+    verifyRestore: () => void;
+    published: () => void;
+};

package/dist/replace-file-destination.js

@@ -0,0 +1,123 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { hasErrorCode } from "./file-cleanup.js";
+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);
+    let writing = false;
+    let restoreDescriptorOnly = false;
+    const verifyDescriptor = async () => {
+        await inspectFileIdentity(async () => regular(await inspect(), pathname, rejectHardlinks), identity);
+    };
+    const verify = async () => {
+        let metadataFailure = false;
+        const observe = async (read) => {
+            try {
+                return await read();
+            }
+            catch (error) {
+                metadataFailure = hasErrorCode(error, "EIO");
+                throw error;
+            }
+        };
+        try {
+            await inspectFileIdentity(async () => regular(await observe(inspect), pathname, rejectHardlinks), identity);
+            await inspectFileIdentity(async () => regular(await observe(() => fsModule.lstat(pathname, { bigint: true })), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            if (writing && metadataFailure) {
+                // A metadata observation failed, but the already-owned descriptor can
+                // still restore its bytes after fresh exact descriptor verification.
+                restoreDescriptorOnly = true;
+                throw error;
+            }
+            mutation.refuse(error);
+        }
+    };
+    const verifyRestore = async () => {
+        if (!restoreDescriptorOnly)
+            return await verify();
+        try {
+            await verifyDescriptor();
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => { writing = true; mutation.destination("writing", pathname, identity); },
+        beforeWrite: async () => {
+            mutation.assert();
+            await verify();
+        },
+        beforeRestore: async () => { mutation.assert(); await verifyRestore(); },
+        verifyRestore,
+        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);
+    let writing = false;
+    let restoreDescriptorOnly = false;
+    const verify = () => {
+        let metadataFailure = false;
+        const observe = (read) => {
+            try {
+                return read();
+            }
+            catch (error) {
+                metadataFailure = hasErrorCode(error, "EIO");
+                throw error;
+            }
+        };
+        try {
+            inspectFileIdentitySync(() => regular(observe(() => fsModule.fstatSync(fd, { bigint: true })), pathname, rejectHardlinks), identity);
+            inspectFileIdentitySync(() => regular(observe(() => fsModule.lstatSync(pathname, { bigint: true })), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            if (writing && metadataFailure) {
+                restoreDescriptorOnly = true;
+                throw error;
+            }
+            mutation.refuse(error);
+        }
+    };
+    const verifyRestore = () => {
+        if (!restoreDescriptorOnly)
+            return verify();
+        try {
+            inspectFileIdentitySync(() => regular(fsModule.fstatSync(fd, { bigint: true }), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => { writing = true; mutation.destination("writing", pathname, identity); },
+        beforeWrite: () => {
+            mutation.assert();
+            verify();
+        },
+        beforeRestore: () => { mutation.assert(); verifyRestore(); },
+        verifyRestore,
+        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;
+}

package/dist/replace-file-mutation.js

@@ -0,0 +1,47 @@
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+export class AtomicMutation {
+    active;
+    #assertion;
+    #observer;
+    #refusal;
+    #writingReported = false;
+    constructor(options) {
+        this.#assertion = options.assertBeforeMutation;
+        this.#observer = options.onDestinationState;
+        this.active = Boolean(this.#assertion || this.#observer);
+    }
+    rethrowRefusal() {
+        if (this.#refusal)
+            throw this.#refusal.error;
+    }
+    refuse(error) {
+        this.#refusal ??= { error };
+        throw this.#refusal.error;
+    }
+    #invoke(operation, name) {
+        this.rethrowRefusal();
+        try {
+            const result = operation();
+            assertSynchronousCallbackResult(result, name);
+        }
+        catch (error) {
+            this.refuse(error);
+        }
+    }
+    assert() {
+        this.#invoke(() => this.#assertion?.(), "assertBeforeMutation");
+    }
+    destination(state, path, identity) {
+        if (state === "writing") {
+            if (this.#writingReported)
+                return;
+            this.#writingReported = true;
+        }
+        this.#invoke(() => this.#observer?.(Object.freeze({
+            state, path, dev: identity.dev, ino: identity.ino,
+        })), "onDestinationState");
+    }
+    removed(path) {
+        this.#invoke(() => this.#observer?.(Object.freeze({ state: "removed", path })), "onDestinationState");
+    }
+}

package/dist/replace-file-temp-owner.d.ts

@@ -26,7 +26,7 @@ export declare class AsyncAtomicTempOwner extends AtomicTempOwner<FileHandle> {
         identity: BigIntStats;
     }): void;
     assertCurrent(fsModule: AsyncOwnerFileSystem, pathname?: string): Promise<void>;
-    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string): Promise<void>;
+    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string, onVerified?: (identity: BigIntStats) => void): Promise<void>;
     finish(params: {
         fsModule: AsyncOwnerFileSystem;
         originalFailure?: AtomicTempFailure;
@@ -39,7 +39,7 @@ export declare class SyncAtomicTempOwner extends AtomicTempOwner<number> {
         identity: BigIntStats;
     }): void;
     assertCurrent(fsModule: SyncOwnerFileSystem, pathname?: string): void;
-    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string): void;
+    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string, onVerified?: (identity: BigIntStats) => void): void;
     finish(params: {
         fsModule: SyncOwnerFileSystem;
         originalFailure?: AtomicTempFailure;

package/dist/replace-file-temp-owner.js

@@ -161,16 +161,21 @@ export class AsyncAtomicTempOwner extends AtomicTempOwner {
             throw error;
         }
     }
-    async assertPublished(fsModule, pathname, expectedHash) {
+    async assertPublished(fsModule, pathname, expectedHash, onVerified) {
+        let identityCurrent = false;
         try {
             await this.assertCurrent(fsModule, pathname);
-            return;
+            identityCurrent = true;
         }
         catch (error) {
             if (!(error instanceof FsSafeError) || !hasErrorCode(error, "path-mismatch") || !expectedHash) {
                 throw error;
             }
         }
+        if (identityCurrent) {
+            onVerified?.(this.identity);
+            return;
+        }
         let published;
         try {
             try {
@@ -199,6 +204,7 @@ export class AsyncAtomicTempOwner extends AtomicTempOwner {
             if (sha256Hex(await published.readFile()) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
+            onVerified?.(identity);
             const previousHandle = this.takeResource();
             await previousHandle?.close();
             this.resource = published;
@@ -269,16 +275,21 @@ export class SyncAtomicTempOwner extends AtomicTempOwner {
             throw error;
         }
     }
-    assertPublished(fsModule, pathname, expectedHash) {
+    assertPublished(fsModule, pathname, expectedHash, onVerified) {
+        let identityCurrent = false;
         try {
             this.assertCurrent(fsModule, pathname);
-            return;
+            identityCurrent = true;
         }
         catch (error) {
             if (!(error instanceof FsSafeError) || !hasErrorCode(error, "path-mismatch") || !expectedHash) {
                 throw error;
             }
         }
+        if (identityCurrent) {
+            onVerified?.(this.identity);
+            return;
+        }
         let publishedFd;
         try {
             try {
@@ -305,6 +316,7 @@ export class SyncAtomicTempOwner extends AtomicTempOwner {
             if (sha256Hex(fsModule.readFileSync(publishedFd)) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
+            onVerified?.(identity);
             const previousFd = this.takeResource();
             fsModule.closeSync(previousFd);
             this.resource = publishedFd;