@openclaw/fs-safe 0.14.0 → 0.16.0

package/dist/replace-directory.js

@@ -1,12 +1,94 @@
 import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { guardedRename, guardedRm } from "./guarded-mutation.js";
+import { assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { classifyNativeRenameFailure, NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH, } from "./native-rename-outcome.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { RetainedDirectoryReplacement } from "./retained-directory-replacement.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
 import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
 import { serializePathWrite } from "./write-queue.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+function distinctGuards(source, target) {
+    return source === target ? [source] : [source, target];
+}
+function assertGuardsCurrent(guards) {
+    for (const guard of guards)
+        assertSyncDirectoryGuard(guard);
+}
+function copyOperationalCode(target, source) {
+    const code = source?.code;
+    if (typeof code === "string") {
+        Object.defineProperty(target, "code", { configurable: true, value: code });
+    }
+}
+function replacementFailure(error, message, details) {
+    if (error instanceof FsSafeError) {
+        return new FsSafeError(error.code, message, { cause: error, details });
+    }
+    const failure = new Error(message, { cause: error });
+    copyOperationalCode(failure, error);
+    Object.defineProperty(failure, "details", { configurable: true, value: details });
+    return failure;
+}
+function replacementAggregate(error, recoveryError, message, details) {
+    const combined = new AggregateError([error, recoveryError], "directory replacement operation and recovery both failed");
+    if (error instanceof FsSafeError) {
+        return new FsSafeError(error.code, message, { cause: combined, details });
+    }
+    const failure = new Error(message, { cause: combined });
+    copyOperationalCode(failure, error);
+    Object.defineProperty(failure, "details", { configurable: true, value: details });
+    return failure;
+}
+function isMissingDirectoryEntry(error) {
+    return error?.code === "ENOENT";
+}
+function observeOptionalDirectory(pathname) {
+    let initial;
+    try {
+        initial = fsSync.lstatSync(pathname, { bigint: true });
+    }
+    catch (error) {
+        if (isMissingDirectoryEntry(error))
+            return undefined;
+        throw error;
+    }
+    return inspectDirectoryIdentitySync(pathname, undefined, initial);
+}
+function normalizeNativeRenameFailure(error) {
+    const code = error?.code;
+    if (code === NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH) {
+        return new FsSafeError("path-mismatch", "directory replacement source identity changed before native rename", { cause: error });
+    }
+    if (code === "EINVAL" || code === "ENOSYS" || code === "ENOTSUP" ||
+        code === "EOPNOTSUPP") {
+        return new FsSafeError("helper-unavailable", "native no-replace directory rename is unavailable on this filesystem", { cause: error });
+    }
+    return error;
+}
+function renameRetainedDirectory(params) {
+    const guards = distinctGuards(params.sourceParent, params.targetParent);
+    assertGuardsCurrent(guards);
+    const initial = fsSync.lstatSync(params.from, { bigint: true });
+    const identity = inspectDirectoryIdentitySync(params.from, params.expectedSource, initial);
+    try {
+        params.renameNoReplace(identity);
+    }
+    catch (error) {
+        if (classifyNativeRenameFailure(error) === "indeterminate") {
+            params.onIndeterminate();
+        }
+        throw normalizeNativeRenameFailure(error);
+    }
+    // Record the transition synchronously before any post-rename observation.
+    params.onRenamed?.(identity);
+    inspectDirectoryIdentitySync(params.to, identity);
+    assertGuardsCurrent(guards);
+    return identity;
+}
 export async function replaceDirectoryAtomic(options) {
     const stagedDirInput = admitStandalonePublicationPath(options.stagedDir, "staged directory uses a Windows filesystem namespace alias");
     const targetDirInput = admitStandalonePublicationPath(options.targetDir, "target directory uses a Windows filesystem namespace alias");
@@ -23,28 +105,184 @@ async function replaceDirectoryAtomicUnserialized(stagedDir, targetDir, backupPr
     const parentDir = path.dirname(targetDir);
     const backupPrefix = assertSafePathPrefix(backupPrefixInput ?? ".fs-safe-dir-backup-", { label: "atomic directory backup prefix" });
     const backupDir = path.join(parentDir, `${backupPrefix}${process.pid}-${randomUUID()}`);
-    let backupCreated = false;
+    const backup = {
+        identity: undefined,
+        transition: "not-renamed",
+    };
+    const publication = {
+        status: "not-published",
+    };
+    let operationFailed = false;
+    let operationError;
+    let operationDetails = {
+        phase: "backup",
+        publication: publication.status,
+        recovery: "none",
+    };
+    const retainedBinding = RetainedDirectoryReplacement.requireBinding();
     await fs.mkdir(recursiveMkdirPath(parentDir), { recursive: true });
+    const targetParent = await createAsyncDirectoryGuard(parentDir, { bigint: true });
+    const stagedParentDir = path.dirname(stagedDir);
+    const stagedParent = stagedParentDir === parentDir
+        ? targetParent
+        : await createAsyncDirectoryGuard(stagedParentDir, { bigint: true });
+    const stagedIdentity = inspectDirectoryIdentitySync(stagedDir);
+    const targetIdentity = observeOptionalDirectory(targetDir);
+    const retained = RetainedDirectoryReplacement.retain({
+        targetParent: {
+            path: parentDir,
+            realPath: targetParent.realPath,
+            identity: targetParent.stat,
+        },
+        stagedParent: {
+            path: stagedParentDir,
+            realPath: stagedParent.realPath,
+            identity: stagedParent.stat,
+        },
+        ...(targetIdentity ? {
+            originalTarget: { path: targetDir, identity: targetIdentity },
+        } : {}),
+    }, retainedBinding);
+    const targetBasename = path.basename(targetDir);
+    const stagedBasename = path.basename(stagedDir);
+    const backupBasename = path.basename(backupDir);
+    const details = (phase, recovery) => {
+        operationDetails = {
+            phase,
+            publication: publication.status,
+            recovery,
+            ...(backup.transition === "not-renamed" ? {} : { backupPath: backupDir }),
+        };
+        return operationDetails;
+    };
+    const rollback = (error, failedPhase, identity) => {
+        const rollbackState = {
+            transition: "not-renamed",
+        };
+        try {
+            renameRetainedDirectory({
+                from: backupDir,
+                to: targetDir,
+                sourceParent: targetParent,
+                targetParent,
+                expectedSource: identity,
+                renameNoReplace: expectedSource => {
+                    retained.renameNoReplace("target", backupBasename, targetBasename, expectedSource);
+                },
+                onIndeterminate() {
+                    rollbackState.transition = "indeterminate";
+                    backup.transition = "indeterminate";
+                },
+                onRenamed() {
+                    rollbackState.transition = "renamed";
+                    backup.transition = "not-renamed";
+                },
+            });
+        }
+        catch (rollbackError) {
+            const recovery = rollbackState.transition === "renamed"
+                ? "restored-unverified"
+                : rollbackState.transition === "indeterminate"
+                    ? "indeterminate"
+                    : "backup-path-preserved";
+            throw replacementAggregate(error, rollbackError, `directory ${failedPhase} and rollback failed`, details("rollback", recovery));
+        }
+        throw replacementFailure(error, `directory ${failedPhase} failed after restoring the original target`, details(failedPhase, "restored"));
+    };
     try {
-        await guardedRename({ from: targetDir, to: backupDir });
-        backupCreated = true;
-    }
-    catch (err) {
-        if (err.code !== "ENOENT") {
-            throw err;
+        if (targetIdentity) {
+            try {
+                backup.identity = renameRetainedDirectory({
+                    from: targetDir,
+                    to: backupDir,
+                    sourceParent: targetParent,
+                    targetParent,
+                    expectedSource: targetIdentity,
+                    renameNoReplace: expectedSource => {
+                        retained.renameNoReplace("target", targetBasename, backupBasename, expectedSource);
+                    },
+                    onIndeterminate() {
+                        backup.transition = "indeterminate";
+                    },
+                    onRenamed(identity) {
+                        backup.identity = identity;
+                        backup.transition = "renamed";
+                    },
+                });
+            }
+            catch (err) {
+                if (backup.transition === "renamed" && backup.identity) {
+                    rollback(err, "backup", backup.identity);
+                }
+                const recovery = backup.transition === "indeterminate" ? "indeterminate" : "none";
+                throw replacementFailure(err, "directory backup failed before publication", details("backup", recovery));
+            }
+        }
+        try {
+            renameRetainedDirectory({
+                from: stagedDir,
+                to: targetDir,
+                sourceParent: stagedParent,
+                targetParent,
+                expectedSource: stagedIdentity,
+                renameNoReplace: expectedSource => {
+                    retained.renameNoReplace("staged", stagedBasename, targetBasename, expectedSource);
+                },
+                onIndeterminate() {
+                    publication.status = "indeterminate";
+                },
+                onRenamed() {
+                    publication.status = "published";
+                },
+            });
+        }
+        catch (err) {
+            if (publication.status === "published") {
+                throw replacementFailure(err, "published directory failed retained identity verification", details("publish", backup.transition === "renamed" ? "backup-path-preserved" : "none"));
+            }
+            if (publication.status === "indeterminate") {
+                throw replacementFailure(err, "directory publication outcome is indeterminate", details("publish", backup.transition === "renamed" ? "backup-path-preserved" : "none"));
+            }
+            if (backup.transition === "renamed" && backup.identity) {
+                rollback(err, "publish", backup.identity);
+            }
+            throw replacementFailure(err, "directory publication failed before commit", details("publish", "none"));
+        }
+        details("publish", backup.transition === "renamed" ? "backup-path-preserved" : "none");
+        if (backup.transition === "renamed" && backup.identity) {
+            let cleanupAttempted = false;
+            try {
+                assertSyncDirectoryGuard(targetParent);
+                inspectDirectoryIdentitySync(backupDir, backup.identity);
+                cleanupAttempted = true;
+                const outcome = await retained.removeOriginal(backupBasename);
+                if (outcome !== "removed") {
+                    throw new FsSafeError("path-mismatch", "retained backup changed before bounded cleanup");
+                }
+                backup.transition = "not-renamed";
+                details("cleanup", "none");
+            }
+            catch (error) {
+                throw replacementFailure(error, "published directory but retained backup cleanup failed", {
+                    ...details("cleanup", cleanupAttempted ? "cleanup-incomplete" : "backup-path-preserved"),
+                });
+            }
         }
     }
-    try {
-        await guardedRename({ from: stagedDir, to: targetDir });
+    catch (error) {
+        operationFailed = true;
+        operationError = error;
+        throw error;
     }
-    catch (err) {
-        if (backupCreated) {
-            await guardedRename({ from: backupDir, to: targetDir }).catch(() => undefined);
-            backupCreated = false;
+    finally {
+        try {
+            retained.close();
+        }
+        catch (closeError) {
+            if (operationFailed) {
+                throw replacementAggregate(operationError, closeError, "directory replacement and retained descriptor close failed", operationDetails);
+            }
+            throw replacementFailure(closeError, "directory replacement retained descriptor close failed", operationDetails);
         }
-        throw err;
-    }
-    if (backupCreated) {
-        await guardedRm({ target: backupDir, recursive: true, force: true, verifyAfter: false });
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"replace-file-copy-fallback.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAQ/D,MAAM,MAAM,oCAAoC,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,oCAAoC,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAC/E,MAAM,MAAM,+BAA+B,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC5E,MAAM,MAAM,sCAAsC,GAAG;IACnD,OAAO,EAAE,+BAA+B,CAAC;CAC1C,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,cAAc,kBAAkB,EAAE,KAAK,CAAC;IAC/C,IAAI,EAAE,cAAc,kBAAkB,EAAE,IAAI,CAAC;IAC7C,EAAE,EAAE,cAAc,kBAAkB,EAAE,EAAE,CAAC;IACzC,MAAM,EAAE,cAAc,kBAAkB,EAAE,MAAM,CAAC;CAClD,CAAC;AAEF,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,WAAW,GACX,UAAU,GACV,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,WAAW,CACd,CAAC;AAyFF,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,IAAI,CAwBN;AA+HD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DhB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,IAAI,CAkEP"}
+{"version":3,"file":"replace-file-copy-fallback.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAQ/D,MAAM,MAAM,oCAAoC,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,oCAAoC,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAC/E,MAAM,MAAM,+BAA+B,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC5E,MAAM,MAAM,sCAAsC,GAAG;IACnD,OAAO,EAAE,+BAA+B,CAAC;CAC1C,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,cAAc,kBAAkB,EAAE,KAAK,CAAC;IAC/C,IAAI,EAAE,cAAc,kBAAkB,EAAE,IAAI,CAAC;IAC7C,EAAE,EAAE,cAAc,kBAAkB,EAAE,EAAE,CAAC;IACzC,MAAM,EAAE,cAAc,kBAAkB,EAAE,MAAM,CAAC;CAClD,CAAC;AAEF,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,WAAW,GACX,UAAU,GACV,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,WAAW,CACd,CAAC;AAqHF,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,IAAI,CAIN;AA+HD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAuEhB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,IAAI,CAuEP"}

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

@@ -10,10 +10,28 @@ const NOFOLLOW = SUPPORTS_NOFOLLOW ? syncFs.constants.O_NOFOLLOW : 0;
 const OPEN_READ_FLAGS = resolveReadOpenFlags();
 const OPEN_READ_WRITE_FLAGS = syncFs.constants.O_RDWR | NOFOLLOW;
 const OPEN_WRITE_EXCLUSIVE_FLAGS = syncFs.constants.O_WRONLY | syncFs.constants.O_CREAT | syncFs.constants.O_EXCL | NOFOLLOW;
+function closeSyncAfterAdmissionFailure(fsModule, fd, error) {
+    try {
+        fsModule.closeSync(fd);
+    }
+    catch {
+        // Preserve the already-selected admission failure.
+    }
+    throw error;
+}
 function notFound(error) {
     return error.code === "ENOENT";
 }
-function assertPinnedDestination(pathname, opened, dest, hardlinks) {
+function assertPinnedDestination(pathname, opened, dest, hardlinks, admission) {
+    if (admission === "hardlinks") {
+        if (pathname.isSymbolicLink() || !pathname.isFile() || !sameFileIdentity(pathname, opened)) {
+            throw new FsSafeError("path-mismatch", `Atomic replace destination changed while opening: ${dest}`);
+        }
+        if (opened.nlink > 1) {
+            throw new FsSafeError("hardlink", `Hardlinked atomic replace destination not allowed: ${dest}`);
+        }
+        return;
+    }
     if (pathname.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
     }
@@ -27,7 +45,7 @@ function assertPinnedDestination(pathname, opened, dest, hardlinks) {
         throw new FsSafeError("hardlink", `Hardlinked copy fallback destination not allowed: ${dest}`);
     }
 }
-async function openPinnedDestination(fsModule, dest, hardlinks) {
+async function openPinnedDestination(fsModule, dest, admission, hardlinks) {
     let preview;
     try {
         preview = fsModule === fs ? syncFs.lstatSync(dest) : await fsModule.lstat(dest);
@@ -39,22 +57,24 @@ async function openPinnedDestination(fsModule, dest, hardlinks) {
     }
     if (!preview)
         return null;
-    if (preview.isSymbolicLink()) {
+    if (admission === "hardlinks" && (preview.isSymbolicLink() || !preview.isFile()))
+        return null;
+    if (admission === "restore" && preview.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
     }
-    const handle = await fsModule.open(dest, OPEN_READ_WRITE_FLAGS);
+    const handle = await fsModule.open(dest, admission === "restore" ? OPEN_READ_WRITE_FLAGS : OPEN_READ_FLAGS);
     try {
         const opened = fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
         const current = fsModule === fs ? syncFs.lstatSync(dest) : await fsModule.lstat(dest);
-        assertPinnedDestination(current, opened, dest, hardlinks);
-        return { handle, stat: opened };
+        assertPinnedDestination(current, opened, dest, hardlinks, admission);
+        return handle;
     }
     catch (error) {
         await handle.close().catch(() => undefined);
         throw error;
     }
 }
-function openPinnedDestinationSync(fsModule, dest, hardlinks) {
+function openPinnedDestinationSync(fsModule, dest, admission, hardlinks) {
     let preview;
     try {
         preview = fsModule.lstatSync(dest);
@@ -64,77 +84,34 @@ function openPinnedDestinationSync(fsModule, dest, hardlinks) {
             return null;
         throw error;
     }
-    if (preview.isSymbolicLink()) {
+    if (admission === "hardlinks" && (preview.isSymbolicLink() || !preview.isFile()))
+        return null;
+    if (admission === "restore" && preview.isSymbolicLink()) {
         throw new FsSafeError("symlink", `Refusing copy fallback through symlink destination: ${dest}`);
     }
-    const fd = fsModule.openSync(dest, OPEN_READ_WRITE_FLAGS);
+    const fd = fsModule.openSync(dest, admission === "restore" ? OPEN_READ_WRITE_FLAGS : OPEN_READ_FLAGS);
     try {
         const opened = fsModule.fstatSync(fd);
-        assertPinnedDestination(fsModule.lstatSync(dest), opened, dest, hardlinks);
-        return { fd, stat: opened };
+        assertPinnedDestination(fsModule.lstatSync(dest), opened, dest, hardlinks, admission);
+        return fd;
     }
     catch (error) {
-        fsModule.closeSync(fd);
-        throw error;
+        closeSyncAfterAdmissionFailure(fsModule, fd, error);
     }
 }
 export async function assertDestinationHardlinkPolicy(fsModule, dest, policy) {
     if (policy !== "reject")
         return;
-    let preview;
-    try {
-        preview = fsModule === fs ? syncFs.lstatSync(dest) : await fsModule.lstat(dest);
-    }
-    catch (error) {
-        if (notFound(error))
-            return;
-        throw error;
-    }
-    if (!preview || preview.isSymbolicLink() || !preview.isFile())
-        return;
-    const handle = await fsModule.open(dest, OPEN_READ_FLAGS);
-    try {
-        const opened = fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
-        const current = fsModule === fs ? syncFs.lstatSync(dest) : await fsModule.lstat(dest);
-        if (current.isSymbolicLink() || !current.isFile() || !sameFileIdentity(current, opened)) {
-            throw new FsSafeError("path-mismatch", `Atomic replace destination changed while opening: ${dest}`);
-        }
-        if (opened.nlink > 1) {
-            throw new FsSafeError("hardlink", `Hardlinked atomic replace destination not allowed: ${dest}`);
-        }
-    }
-    finally {
+    const handle = await openPinnedDestination(fsModule, dest, "hardlinks");
+    if (handle)
         await handle.close().catch(() => undefined);
-    }
 }
 export function assertDestinationHardlinkPolicySync(fsModule, dest, policy) {
     if (policy !== "reject")
         return;
-    let preview;
-    try {
-        preview = fsModule.lstatSync(dest);
-    }
-    catch (error) {
-        if (notFound(error))
-            return;
-        throw error;
-    }
-    if (preview.isSymbolicLink() || !preview.isFile())
-        return;
-    const fd = fsModule.openSync(dest, OPEN_READ_FLAGS);
-    try {
-        const opened = fsModule.fstatSync(fd);
-        const current = fsModule.lstatSync(dest);
-        if (current.isSymbolicLink() || !current.isFile() || !sameFileIdentity(current, opened)) {
-            throw new FsSafeError("path-mismatch", `Atomic replace destination changed while opening: ${dest}`);
-        }
-        if (opened.nlink > 1) {
-            throw new FsSafeError("hardlink", `Hardlinked atomic replace destination not allowed: ${dest}`);
-        }
-    }
-    finally {
+    const fd = openPinnedDestinationSync(fsModule, dest, "hardlinks");
+    if (fd !== null)
         fsModule.closeSync(fd);
-    }
 }
 function restoreReadOptions(stat, maxBytes) {
     return {
@@ -183,7 +160,7 @@ function writeAllSync(fsModule, fd, data) {
 function restoreFailure(writeError, cleanup, restoreError) {
     const primary = writeError instanceof Error ? writeError : new Error(String(writeError));
     const details = { cleanup };
-    const cause = restoreError
+    const cause = cleanup === "restore-failed"
         ? new AggregateError([primary, restoreError], "copy fallback and original restoration both failed")
         : primary;
     return new FsSafeError("helper-failed", cleanup === "restored"
@@ -246,11 +223,12 @@ export async function copyFallbackReplace(params) {
     });
     const { replacement } = source;
     let destHandle = null;
+    let closeRequiredForSuccess = false;
     try {
         if (params.restore === "restore-original") {
-            const pinned = await openPinnedDestination(params.fsModule, params.dest, params.destinationHardlinks);
+            const pinned = await openPinnedDestination(params.fsModule, params.dest, "restore", params.destinationHardlinks);
             if (pinned) {
-                destHandle = pinned.handle;
+                destHandle = pinned;
                 await replacePinnedWithRestore(params.fsModule, destHandle, replacement, params.maxRestoreBytes, source.mode);
             }
         }
@@ -277,10 +255,20 @@ export async function copyFallbackReplace(params) {
             if (params.sync) {
                 await destHandle.sync();
             }
+            closeRequiredForSuccess = !params.sync;
         }
     }
     finally {
-        await destHandle?.close().catch(() => undefined);
+        if (destHandle) {
+            try {
+                await destHandle.close();
+            }
+            catch (closeError) {
+                if (closeRequiredForSuccess) {
+                    throw closeError;
+                }
+            }
+        }
     }
 }
 export function copyFallbackReplaceSync(params) {
@@ -291,11 +279,12 @@ export function copyFallbackReplaceSync(params) {
     });
     const { replacement } = source;
     let destFd;
+    let closeRequiredForSuccess = false;
     try {
         if (params.restore === "restore-original") {
-            const pinned = openPinnedDestinationSync(params.fsModule, params.dest, params.destinationHardlinks);
-            if (pinned) {
-                destFd = pinned.fd;
+            const pinned = openPinnedDestinationSync(params.fsModule, params.dest, "restore", params.destinationHardlinks);
+            if (pinned !== null) {
+                destFd = pinned;
                 replacePinnedWithRestoreSync(params.fsModule, destFd, replacement, params.maxRestoreBytes, source.mode, params.fchmodSync);
             }
         }
@@ -321,6 +310,7 @@ export function copyFallbackReplaceSync(params) {
             if (params.sync) {
                 params.fsModule.fsyncSync(destFd);
             }
+            closeRequiredForSuccess = !params.sync;
         }
     }
     finally {
@@ -328,8 +318,10 @@ export function copyFallbackReplaceSync(params) {
             try {
                 params.fsModule.closeSync(destFd);
             }
-            catch {
-                // Best-effort close after fallback replacement.
+            catch (closeError) {
+                if (closeRequiredForSuccess) {
+                    throw closeError;
+                }
             }
         }
     }

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

@@ -1 +1 @@
-{"version":3,"file":"replace-file-copy-source.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-source.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAQnD,KAAK,qBAAqB,GAAG,IAAI,CAAC,cAAc,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;AACvF,KAAK,oBAAoB,GAAG,IAAI,CAC9B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAClE,CAAC;AAqDF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA8BjD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA8BxC"}
+{"version":3,"file":"replace-file-copy-source.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-source.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAQ/D,KAAK,qBAAqB,GAAG,IAAI,CAAC,cAAc,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;AACvF,KAAK,oBAAoB,GAAG,IAAI,CAC9B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAClE,CAAC;AA8DF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAyBjD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,WAAW,CAAC;CAChC,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAyBxC"}

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

@@ -17,6 +17,14 @@ function assertSourcePreview(source, src) {
         throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${src}`);
     }
 }
+function assertOpenedSource(opened, current, src) {
+    if (!opened.isFile() || current.isSymbolicLink() || !sameFileIdentity(opened, current)) {
+        throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${src}`);
+    }
+    if (opened.nlink !== 1) {
+        throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${src}`);
+    }
+}
 function sourceSymlinkError(src, cause) {
     return new FsSafeError("symlink", `Refusing copy fallback from non-file source: ${src}`, {
         cause,
@@ -66,12 +74,7 @@ export async function readOwnedCopySource(params) {
         const opened = params.fsModule === fs ? syncFs.fstatSync(handle.fd) : await handle.stat();
         const current = params.fsModule === fs
             ? syncFs.lstatSync(params.src) : await params.fsModule.lstat(params.src);
-        if (!opened.isFile() || current.isSymbolicLink() || !sameFileIdentity(opened, current)) {
-            throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${params.src}`);
-        }
-        if (opened.nlink !== 1) {
-            throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${params.src}`);
-        }
+        assertOpenedSource(opened, current, params.src);
         return { replacement: await handle.readFile(), mode: opened.mode };
     }
     finally {
@@ -88,12 +91,7 @@ export function readOwnedCopySourceSync(params) {
         }
         const opened = params.fsModule.fstatSync(fd);
         const current = params.fsModule.lstatSync(params.src);
-        if (!opened.isFile() || current.isSymbolicLink() || !sameFileIdentity(opened, current)) {
-            throw new FsSafeError("path-mismatch", `Copy fallback source changed while opening: ${params.src}`);
-        }
-        if (opened.nlink !== 1) {
-            throw new FsSafeError("hardlink", `Hardlinked copy fallback source not allowed: ${params.src}`);
-        }
+        assertOpenedSource(opened, current, params.src);
         return { replacement: readAllSync(params.fsModule, fd, opened.size), mode: opened.mode };
     }
     finally {

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

@@ -1,15 +1,11 @@
 import syncFs, { type BigIntStats } from "node:fs";
 import fs, { type FileHandle } from "node:fs/promises";
-import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 type AsyncOwnerFileSystem = Pick<typeof fs, "lstat" | "open" | "unlink">;
 type SyncOwnerFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "unlinkSync">;
+export type AtomicTempFailure = Readonly<{
+    error: unknown;
+}>;
 export declare function removePathIfIdentityUnchanged(targetPath: string, identity: Pick<BigIntStats, "dev" | "ino">): Promise<void>;
-export declare function cleanupPinnedFilePath(params: {
-    pathname: string;
-    handle: FileHandle;
-    identity?: BigIntStats;
-    parentGuard: AnyAsyncDirectoryGuard;
-}): Promise<void>;
 export declare class AsyncAtomicTempOwner {
     #private;
     readonly pathname: string;
@@ -26,7 +22,7 @@ export declare class AsyncAtomicTempOwner {
     markRenamed(): void;
     finish(params: {
         fsModule: AsyncOwnerFileSystem;
-        originalError?: unknown;
+        originalFailure?: AtomicTempFailure;
         throwOnCleanupError: boolean;
     }): Promise<void>;
 }
@@ -46,7 +42,7 @@ export declare class SyncAtomicTempOwner {
     markRenamed(): void;
     finish(params: {
         fsModule: SyncOwnerFileSystem;
-        originalError?: unknown;
+        originalFailure?: AtomicTempFailure;
         throwOnCleanupError: boolean;
     }): void;
 }

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

@@ -1 +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;AAEvD,OAAO,EAAwD,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAQzH,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;AAIF,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GACzC,OAAO,CAAC,IAAI,CAAC,CAOf;AA8DD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,WAAW,EAAE,sBAAsB,CAAC;CACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhB;AA+BD,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,CAoB3F;IAEK,eAAe,CACnB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CA4Cf;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,CAkDN;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,CAkCP;CACF"}
+{"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;AAWvD,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;AAIF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAmB7D,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GACzC,OAAO,CAAC,IAAI,CAAC,CAOf;AAkFD,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,CAoB3F;IAEK,eAAe,CACnB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CA8Cf;IAED,WAAW,IAAI,IAAI,CAGlB;IAEK,MAAM,CAAC,MAAM,EAAE;QACnB,QAAQ,EAAE,oBAAoB,CAAC;QAC/B,eAAe,CAAC,EAAE,iBAAiB,CAAC;QACpC,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAqChB;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,CAkDN;IAED,WAAW,IAAI,IAAI,CAGlB;IAED,MAAM,CAAC,MAAM,EAAE;QACb,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,eAAe,CAAC,EAAE,iBAAiB,CAAC;QACpC,mBAAmB,EAAE,OAAO,CAAC;KAC9B,GAAG,IAAI,CAuCP;CACF"}