@openclaw/fs-safe 0.6.0 → 0.7.1

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

@@ -1,5 +1,5 @@
 import syncFs, { type BigIntStats } from "node:fs";
-import fs from "node:fs/promises";
+import fs, { type FileHandle } from "node:fs/promises";
 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;
@@ -7,6 +7,8 @@ export declare function applyDirectoryMode(params: {
     fsModule: AsyncTempFileSystem;
     dirPath: string;
     mode: number;
+    /** Compatibility for best-effort directory modes; admission and close still fail closed. */
+    ignoreChmodError?: boolean;
 }): Promise<void>;
 export declare function applyDirectoryModeSync(params: {
     fsModule: SyncTempFileSystem;
@@ -20,7 +22,11 @@ export declare function writeTempFile(params: {
     content: string | Uint8Array;
     mode: number;
     sync: boolean;
-}): Promise<BigIntStats>;
+    onIdentity?: (identity: BigIntStats) => void;
+}): Promise<{
+    handle: FileHandle;
+    identity: BigIntStats;
+}>;
 export declare function writeTempFileSync(params: {
     fsModule: SyncTempFileSystem;
     tempPath: string;
@@ -28,6 +34,10 @@ export declare function writeTempFileSync(params: {
     mode: number;
     fchmodSync?: SyncFchmod;
     sync: boolean;
-}): BigIntStats;
+    onIdentity?: (identity: BigIntStats) => void;
+}): {
+    fd: number;
+    identity: BigIntStats;
+};
 export {};
 //# sourceMappingURL=replace-file-descriptor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"replace-file-descriptor.d.ts","sourceRoot":"","sources":["../src/replace-file-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAuB,MAAM,kBAAkB,CAAC;AAIvD,KAAK,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAC3E,KAAK,kBAAkB,GAAG,IAAI,CAC5B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,CACrF,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AA2B5D,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,CAcP;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,WAAW,CAAC,CAkBvB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,WAAW,CAkBd"}
+{"version":3,"file":"replace-file-descriptor.d.ts","sourceRoot":"","sources":["../src/replace-file-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKvD,KAAK,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAC3E,KAAK,kBAAkB,GAAG,IAAI,CAC5B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,CACrF,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AA2B5D,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,CAcP;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CAAC,CA0BzD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CA0BxC"}

package/dist/replace-file-descriptor.js

@@ -2,6 +2,7 @@ import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 function directoryOpenFlags() {
     return (syncFs.constants.O_RDONLY |
         syncFs.constants.O_DIRECTORY |
@@ -31,7 +32,13 @@ export async function applyDirectoryMode(params) {
     const handle = await params.fsModule.open(params.dirPath, directoryOpenFlags());
     try {
         assertSameDirectory(expected, await handle.stat(), params.dirPath);
-        await handle.chmod(params.mode);
+        try {
+            await handle.chmod(params.mode);
+        }
+        catch (error) {
+            if (params.ignoreChmodError !== true)
+                throw error;
+        }
     }
     finally {
         await handle.close();
@@ -55,6 +62,8 @@ export function applyDirectoryModeSync(params) {
 export async function writeTempFile(params) {
     const handle = await params.fsModule.open(params.tempPath, "wx", params.mode);
     try {
+        const identity = await inspectFileIdentity(() => handle.stat({ bigint: true }));
+        params.onIdentity?.(identity);
         await params.fsModule.writeFile(handle, params.content);
         await handle.chmod(params.mode);
         if (params.sync) {
@@ -67,15 +76,24 @@ export async function writeTempFile(params) {
                 }
             }
         }
-        return await handle.stat({ bigint: true });
+        await inspectFileIdentity(() => handle.stat({ bigint: true }), identity);
+        return { handle, identity };
     }
-    finally {
-        await handle.close();
+    catch (error) {
+        try {
+            await handle.close();
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "Atomic temp write and close failed");
+        }
+        throw error;
     }
 }
 export function writeTempFileSync(params) {
     const fd = params.fsModule.openSync(params.tempPath, "wx", params.mode);
     try {
+        const identity = inspectFileIdentitySync(() => params.fsModule.fstatSync(fd, { bigint: true }));
+        params.onIdentity?.(identity);
         params.fsModule.writeFileSync(fd, params.content);
         params.fchmodSync?.(fd, params.mode);
         if (params.sync) {
@@ -88,9 +106,16 @@ export function writeTempFileSync(params) {
                 }
             }
         }
-        return params.fsModule.fstatSync(fd, { bigint: true });
+        inspectFileIdentitySync(() => params.fsModule.fstatSync(fd, { bigint: true }), identity);
+        return { fd, identity };
     }
-    finally {
-        params.fsModule.closeSync(fd);
+    catch (error) {
+        try {
+            params.fsModule.closeSync(fd);
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "Atomic temp write and close failed");
+        }
+        throw error;
     }
 }

package/dist/replace-file-rename-policy.d.ts

@@ -0,0 +1,7 @@
+import type { RenameIdentityPolicy } from "./pinned-write.js";
+export type { RenameIdentityPolicy };
+export declare function validateRenameIdentity(policy: RenameIdentityPolicy | undefined): void;
+export declare function atomicExpectedContentHash(policy: RenameIdentityPolicy | undefined, content: string | Uint8Array): string | undefined;
+export declare function withAtomicRenameIdentityLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+export declare function withAtomicRenameIdentityLockSync<T>(filePath: string, fn: () => T): T;
+//# sourceMappingURL=replace-file-rename-policy.d.ts.map

package/dist/replace-file-rename-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-file-rename-policy.d.ts","sourceRoot":"","sources":["../src/replace-file-rename-policy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAErC,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAIrF;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,oBAAoB,GAAG,SAAS,EACxC,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,MAAM,GAAG,SAAS,CAGpB;AAcD,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,wBAAgB,gCAAgC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEpF"}

package/dist/replace-file-rename-policy.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { withFileLock, withFileLockSync } from "./file-lock.js";
+import { sha256Hex } from "./file-identity.js";
+export function validateRenameIdentity(policy) {
+    if (policy !== undefined && policy !== "strict" && policy !== "verify-content-with-lock") {
+        throw new RangeError("renameIdentity must be strict or verify-content-with-lock");
+    }
+}
+export function atomicExpectedContentHash(policy, content) {
+    if (policy !== "verify-content-with-lock")
+        return undefined;
+    return sha256Hex(typeof content === "string" ? content : Buffer.from(content));
+}
+function lockOptions(filePath) {
+    const resolved = path.resolve(filePath);
+    return {
+        managerKey: `fs-safe.atomic:${resolved}`,
+        lockPath: path.join(path.dirname(resolved), `.fs-safe-atomic-${sha256Hex(resolved)}.lock`),
+        staleMs: 30_000,
+        timeoutMs: 5_000,
+        payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
+        retry: { retries: 5, minTimeout: 100, maxTimeout: 2_000, factor: 2 },
+    };
+}
+export async function withAtomicRenameIdentityLock(filePath, fn) {
+    return await withFileLock(filePath, lockOptions(filePath), fn);
+}
+export function withAtomicRenameIdentityLockSync(filePath, fn) {
+    return withFileLockSync(filePath, lockOptions(filePath), fn);
+}

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

@@ -0,0 +1,46 @@
+import syncFs, { type BigIntStats } from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+type AsyncOwnerFileSystem = Pick<typeof fs, "lstat" | "open" | "unlink">;
+type SyncOwnerFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "unlinkSync">;
+export declare class AsyncAtomicTempOwner {
+    #private;
+    readonly pathname: string;
+    constructor(pathname: string);
+    start(): void;
+    readonly onIdentity: (identity: BigIntStats) => void;
+    adopt(temp: {
+        handle: FileHandle;
+        identity: BigIntStats;
+    }): void;
+    get identity(): BigIntStats;
+    assertCurrent(fsModule: AsyncOwnerFileSystem, pathname?: string): Promise<void>;
+    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string): Promise<void>;
+    markRenamed(): void;
+    finish(params: {
+        fsModule: AsyncOwnerFileSystem;
+        originalError?: unknown;
+        throwOnCleanupError: boolean;
+    }): Promise<void>;
+}
+export declare class SyncAtomicTempOwner {
+    #private;
+    readonly pathname: string;
+    constructor(pathname: string);
+    start(): void;
+    readonly onIdentity: (identity: BigIntStats) => void;
+    adopt(temp: {
+        fd: number;
+        identity: BigIntStats;
+    }): void;
+    get identity(): BigIntStats;
+    assertCurrent(fsModule: SyncOwnerFileSystem, pathname?: string): void;
+    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string): void;
+    markRenamed(): void;
+    finish(params: {
+        fsModule: SyncOwnerFileSystem;
+        originalError?: unknown;
+        throwOnCleanupError: boolean;
+    }): void;
+}
+export {};
+//# sourceMappingURL=replace-file-temp-owner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"replace-file-temp-owner.d.ts","sourceRoot":"","sources":["../src/replace-file-temp-owner.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMvD,KAAK,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC;AACzE,KAAK,mBAAmB,GAAG,IAAI,CAC7B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,YAAY,CACrF,CAAC;AAiGF,qBAAa,oBAAoB;;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,QAAQ,EAAE,MAAM,EAG3B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,QAAQ,CAAC,UAAU,aAAc,WAAW,KAAG,IAAI,CAGjD;IAEF,KAAK,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAG/D;IAED,IAAI,QAAQ,IAAI,WAAW,CAG1B;IAEK,aAAa,CAAC,QAAQ,EAAE,oBAAoB,EAAE,QAAQ,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB3F;IAEK,eAAe,CACnB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CA0Cf;IAED,WAAW,IAAI,IAAI,CAGlB;IAEK,MAAM,CAAC,MAAM,EAAE;QACnB,QAAQ,EAAE,oBAAoB,CAAC;QAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhB;CACF;AAED,qBAAa,mBAAmB;;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAM1B,YAAY,QAAQ,EAAE,MAAM,EAG3B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,QAAQ,CAAC,UAAU,aAAc,WAAW,KAAG,IAAI,CAGjD;IAEF,KAAK,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAGvD;IAED,IAAI,QAAQ,IAAI,WAAW,CAG1B;IAED,aAAa,CAAC,QAAQ,EAAE,mBAAmB,EAAE,QAAQ,SAAgB,GAAG,IAAI,CAkB3E;IAED,eAAe,CACb,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAgDN;IAED,WAAW,IAAI,IAAI,CAGlB;IAED,MAAM,CAAC,MAAM,EAAE;QACb,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,IAAI,CAgCP;CACF"}

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

@@ -0,0 +1,346 @@
+import syncFs, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+import { registerTempPathForExit } from "./temp-cleanup.js";
+const PUBLISHED_READ_FLAGS = syncFs.constants.O_RDONLY |
+    (process.platform !== "win32" && typeof syncFs.constants.O_NOFOLLOW === "number"
+        ? syncFs.constants.O_NOFOLLOW
+        : 0) |
+    (process.platform !== "win32" && typeof syncFs.constants.O_NONBLOCK === "number"
+        ? syncFs.constants.O_NONBLOCK
+        : 0);
+function assertOwnedFile(stat, pathname, pathnameEntry) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", `Atomic replace owned file became a symlink: ${pathname}`);
+    }
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", `Atomic replace owned file must remain regular: ${pathname}`);
+    }
+    if (stat.nlink > 1n || (pathnameEntry && stat.nlink !== 1n)) {
+        throw new FsSafeError("hardlink", `Atomic replace owned file must retain one link: ${pathname}`);
+    }
+}
+function missingOwnedFile(pathname, cause) {
+    return new FsSafeError("path-mismatch", `Atomic replace owned file disappeared: ${pathname}`, {
+        cause,
+    });
+}
+function cleanupFailure(originalError, cleanupError) {
+    if (originalError !== undefined) {
+        return new Error(`Atomic file replace failed (${String(originalError)}); cleanup also failed (${String(cleanupError)})`, { cause: originalError });
+    }
+    return cleanupError instanceof Error ? cleanupError : new Error(String(cleanupError));
+}
+async function cleanupOwnedPath(params) {
+    if (!params.identity)
+        return true;
+    try {
+        const current = await params.fsModule.lstat(params.pathname, { bigint: true });
+        if (current.isSymbolicLink() ||
+            !current.isFile() ||
+            current.nlink !== 1n ||
+            !sameFileIdentityForCleanup(current, params.identity)) {
+            return true;
+        }
+        await params.fsModule.unlink(params.pathname);
+        return true;
+    }
+    catch (cleanupError) {
+        if (cleanupError.code === "ENOENT")
+            return true;
+        if (params.throwOnCleanupError) {
+            throw cleanupFailure(params.originalError, cleanupError);
+        }
+        return false;
+    }
+}
+function cleanupOwnedPathSync(params) {
+    if (!params.identity)
+        return true;
+    try {
+        const current = params.fsModule.lstatSync(params.pathname, { bigint: true });
+        if (current.isSymbolicLink() ||
+            !current.isFile() ||
+            current.nlink !== 1n ||
+            !sameFileIdentityForCleanup(current, params.identity)) {
+            return true;
+        }
+        params.fsModule.unlinkSync(params.pathname);
+        return true;
+    }
+    catch (cleanupError) {
+        if (cleanupError.code === "ENOENT")
+            return true;
+        if (params.throwOnCleanupError) {
+            throw cleanupFailure(params.originalError, cleanupError);
+        }
+        return false;
+    }
+}
+export class AsyncAtomicTempOwner {
+    pathname;
+    #handle;
+    #identity;
+    #exists = false;
+    #unregister;
+    constructor(pathname) {
+        this.pathname = pathname;
+        this.#unregister = registerTempPathForExit(pathname, { singleLinkFile: true });
+    }
+    start() {
+        this.#exists = true;
+    }
+    onIdentity = (identity) => {
+        this.#identity = identity;
+        this.#unregister.setIdentity(identity);
+    };
+    adopt(temp) {
+        this.#handle = temp.handle;
+        this.onIdentity(temp.identity);
+    }
+    get identity() {
+        if (!this.#identity)
+            throw new Error("Atomic temp owner has no identity");
+        return this.#identity;
+    }
+    async assertCurrent(fsModule, pathname = this.pathname) {
+        const opened = await inspectFileIdentity(async () => {
+            const stat = await this.#handle.stat({ bigint: true });
+            assertOwnedFile(stat, pathname, false);
+            return stat;
+        }, this.identity);
+        try {
+            await inspectFileIdentity(async () => {
+                const stat = await fsModule.lstat(pathname, { bigint: true });
+                assertOwnedFile(stat, pathname, true);
+                return stat;
+            }, opened);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw missingOwnedFile(pathname, error);
+            }
+            throw error;
+        }
+    }
+    async assertPublished(fsModule, pathname, expectedHash) {
+        try {
+            await this.assertCurrent(fsModule, pathname);
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof FsSafeError) || error.code !== "path-mismatch" || !expectedHash) {
+                throw error;
+            }
+        }
+        let published;
+        try {
+            try {
+                published = await fsModule.open(pathname, PUBLISHED_READ_FLAGS);
+            }
+            catch (error) {
+                if (error.code === "ELOOP") {
+                    throw new FsSafeError("symlink", `Atomic replace published file became a symlink: ${pathname}`, {
+                        cause: error,
+                    });
+                }
+                throw error;
+            }
+            const identity = await inspectFileIdentity(async () => {
+                const stat = await published.stat({ bigint: true });
+                assertOwnedFile(stat, pathname, false);
+                return stat;
+            });
+            await inspectFileIdentity(async () => {
+                const stat = await fsModule.lstat(pathname, { bigint: true });
+                assertOwnedFile(stat, pathname, true);
+                return stat;
+            }, identity);
+            if (sha256Hex(await published.readFile()) !== expectedHash) {
+                throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
+            }
+            await this.#handle?.close();
+            this.#handle = published;
+            this.#identity = identity;
+            published = undefined;
+        }
+        finally {
+            await published?.close().catch(() => undefined);
+        }
+    }
+    markRenamed() {
+        this.#exists = false;
+        this.#unregister();
+    }
+    async finish(params) {
+        let deferredError;
+        let cleanupComplete = !this.#exists;
+        if (this.#exists) {
+            try {
+                cleanupComplete = await cleanupOwnedPath({
+                    fsModule: params.fsModule,
+                    pathname: this.pathname,
+                    identity: this.#identity,
+                    originalError: params.originalError,
+                    throwOnCleanupError: params.throwOnCleanupError,
+                });
+            }
+            catch (error) {
+                deferredError = error;
+            }
+        }
+        if (cleanupComplete)
+            this.#unregister();
+        try {
+            await this.#handle?.close();
+        }
+        catch (closeError) {
+            deferredError = deferredError
+                ? new AggregateError([deferredError, closeError], "Atomic temp cleanup and close failed")
+                : params.originalError !== undefined
+                    ? new AggregateError([params.originalError, closeError], "Atomic file replace and close failed")
+                    : closeError;
+        }
+        if (deferredError)
+            throw deferredError;
+    }
+}
+export class SyncAtomicTempOwner {
+    pathname;
+    #fd;
+    #identity;
+    #exists = false;
+    #unregister;
+    constructor(pathname) {
+        this.pathname = pathname;
+        this.#unregister = registerTempPathForExit(pathname, { singleLinkFile: true });
+    }
+    start() {
+        this.#exists = true;
+    }
+    onIdentity = (identity) => {
+        this.#identity = identity;
+        this.#unregister.setIdentity(identity);
+    };
+    adopt(temp) {
+        this.#fd = temp.fd;
+        this.onIdentity(temp.identity);
+    }
+    get identity() {
+        if (!this.#identity)
+            throw new Error("Atomic temp owner has no identity");
+        return this.#identity;
+    }
+    assertCurrent(fsModule, pathname = this.pathname) {
+        const opened = inspectFileIdentitySync(() => {
+            const stat = fsModule.fstatSync(this.#fd, { bigint: true });
+            assertOwnedFile(stat, pathname, false);
+            return stat;
+        }, this.identity);
+        try {
+            inspectFileIdentitySync(() => {
+                const stat = fsModule.lstatSync(pathname, { bigint: true });
+                assertOwnedFile(stat, pathname, true);
+                return stat;
+            }, opened);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                throw missingOwnedFile(pathname, error);
+            }
+            throw error;
+        }
+    }
+    assertPublished(fsModule, pathname, expectedHash) {
+        try {
+            this.assertCurrent(fsModule, pathname);
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof FsSafeError) || error.code !== "path-mismatch" || !expectedHash) {
+                throw error;
+            }
+        }
+        let publishedFd;
+        try {
+            try {
+                publishedFd = fsModule.openSync(pathname, PUBLISHED_READ_FLAGS);
+            }
+            catch (error) {
+                if (error.code === "ELOOP") {
+                    throw new FsSafeError("symlink", `Atomic replace published file became a symlink: ${pathname}`, {
+                        cause: error,
+                    });
+                }
+                throw error;
+            }
+            const identity = inspectFileIdentitySync(() => {
+                const stat = fsModule.fstatSync(publishedFd, { bigint: true });
+                assertOwnedFile(stat, pathname, false);
+                return stat;
+            });
+            inspectFileIdentitySync(() => {
+                const stat = fsModule.lstatSync(pathname, { bigint: true });
+                assertOwnedFile(stat, pathname, true);
+                return stat;
+            }, identity);
+            if (sha256Hex(fsModule.readFileSync(publishedFd)) !== expectedHash) {
+                throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
+            }
+            fsModule.closeSync(this.#fd);
+            this.#fd = publishedFd;
+            this.#identity = identity;
+            publishedFd = undefined;
+        }
+        finally {
+            if (publishedFd !== undefined) {
+                try {
+                    fsModule.closeSync(publishedFd);
+                }
+                catch {
+                    // Best-effort close after a rejected content verification.
+                }
+            }
+        }
+    }
+    markRenamed() {
+        this.#exists = false;
+        this.#unregister();
+    }
+    finish(params) {
+        let deferredError;
+        let cleanupComplete = !this.#exists;
+        if (this.#exists) {
+            try {
+                cleanupComplete = cleanupOwnedPathSync({
+                    fsModule: params.fsModule,
+                    pathname: this.pathname,
+                    identity: this.#identity,
+                    originalError: params.originalError,
+                    throwOnCleanupError: params.throwOnCleanupError,
+                });
+            }
+            catch (error) {
+                deferredError = error;
+            }
+        }
+        if (cleanupComplete)
+            this.#unregister();
+        if (this.#fd !== undefined) {
+            try {
+                params.fsModule.closeSync(this.#fd);
+            }
+            catch (closeError) {
+                deferredError = deferredError
+                    ? new AggregateError([deferredError, closeError], "Atomic temp cleanup and close failed")
+                    : params.originalError !== undefined
+                        ? new AggregateError([params.originalError, closeError], "Atomic file replace and close failed")
+                        : closeError;
+            }
+        }
+        if (deferredError)
+            throw deferredError;
+    }
+}

package/dist/replace-file.d.ts

@@ -1,6 +1,7 @@
 import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import { type ReplaceFileAtomicRestoreCleanup, type ReplaceFileAtomicRestoreFailureDetails, type ReplaceFileCopyFallbackRestorePolicy, type ReplaceFileDestinationHardlinkPolicy } from "./replace-file-copy-fallback.js";
+import { type RenameIdentityPolicy } from "./replace-file-rename-policy.js";
 export type ReplaceFileAtomicFileSystem = {
     promises: Pick<typeof fs, "mkdir" | "writeFile" | "rename" | "copyFile" | "unlink" | "rm" | "open" | "stat" | "lstat"> & {
         /** @deprecated Accepted for adapter compatibility but never called. */
@@ -12,7 +13,7 @@ export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" |
     chmodSync?: typeof syncFs.chmodSync;
     fchmodSync?: typeof syncFs.fchmodSync;
 };
-export type { ReplaceFileAtomicRestoreCleanup, ReplaceFileAtomicRestoreFailureDetails, ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy, };
+export type { RenameIdentityPolicy, ReplaceFileAtomicRestoreCleanup, ReplaceFileAtomicRestoreFailureDetails, ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy, };
 type ReplaceFileAtomicBaseOptions = {
     filePath: string;
     content: string | Uint8Array;
@@ -26,12 +27,15 @@ type ReplaceFileAtomicBaseOptions = {
     copyFallbackRestore?: ReplaceFileCopyFallbackRestorePolicy;
     maxRestoreBytes?: number;
     destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
+    /** Strict by default; locked content verification is an explicit FUSE compatibility policy. */
+    renameIdentity?: RenameIdentityPolicy;
     syncTempFile?: boolean;
     syncParentDir?: boolean;
     throwOnCleanupError?: boolean;
 };
 export type ReplaceFileAtomicOptions = ReplaceFileAtomicBaseOptions & {
     fileSystem?: ReplaceFileAtomicFileSystem;
+    /** Runs while the exact staged file is retained; replacing or hardlinking it is rejected. */
     beforeRename?: (params: {
         filePath: string;
         tempPath: string;
@@ -39,6 +43,7 @@ export type ReplaceFileAtomicOptions = ReplaceFileAtomicBaseOptions & {
 };
 export type ReplaceFileAtomicSyncOptions = ReplaceFileAtomicBaseOptions & {
     fileSystem?: ReplaceFileAtomicSyncFileSystem;
+    /** Runs while the exact staged file is retained; replacing or hardlinking it is rejected. */
     beforeRename?: (params: {
         filePath: string;
         tempPath: string;

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

@@ -1 +1 @@
-{"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAElC,OAAO,EAKL,KAAK,+BAA+B,EACpC,KAAK,sCAAsC,EAC3C,KAAK,oCAAoC,EACzC,KAAK,oCAAoC,EAC1C,MAAM,iCAAiC,CAAC;AAazC,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,EAAE,IAAI,CACZ,OAAO,EAAE,EACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,CACV,GAAG;QACF,uEAAuE;QACvE,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC;KACzB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,IAAI,CAChD,OAAO,MAAM,EACX,WAAW,GACX,cAAc,GACd,eAAe,GACf,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,WAAW,GACX,eAAe,GACf,UAAU,GACV,WAAW,CACd,GAAG;IACF,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,MAAM,CAAC,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,OAAO,MAAM,CAAC,UAAU,CAAC;CACvC,CAAC;AAEF,YAAY,EACV,+BAA+B,EAC/B,sCAAsC,EACtC,oCAAoC,EACpC,oCAAoC,GACrC,CAAC;AAEF,KAAK,4BAA4B,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC,mBAAmB,CAAC,EAAE,oCAAoC,CAAC;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,4BAA4B,GAAG;IACpE,UAAU,CAAC,EAAE,2BAA2B,CAAC;IACzC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClF,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,4BAA4B,GAAG;IACxE,UAAU,CAAC,EAAE,+BAA+B,CAAC;IAC7C,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACzE,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,QAAQ,GAAG,eAAe,CAAC;CACpC,CAAC;AAgNF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAOlC;AAkED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,uBAAuB,CAoFzB"}
+{"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"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"}