@openclaw/fs-safe 0.14.0 → 0.15.0

package/dist/private-temp-workspace.js

@@ -107,30 +107,83 @@ function throwTempWorkspaceOpenFailure(failure) {
         },
     });
 }
-async function createTempWorkspace(options, scopedPrefix = false) {
+function tempWorkspaceSettings(options) {
     const rootDir = options.rootDir;
     assertNoWindowsPathAlias(rootDir, "filesystem", "temp workspace root uses a Windows filesystem namespace alias");
     const dirMode = options.dirMode ?? 0o700;
     validateTempWorkspaceDirMode(dirMode);
     const mode = options.mode ?? 0o600;
     const cleanupSafety = resolveTempWorkspaceCleanupSafety(options.cleanupSafety);
-    const admission = await admitTempWorkspaceRoot(rootDir);
-    const root = admission.dir;
+    return { rootDir, dirMode, mode, cleanupSafety };
+}
+function tempWorkspaceChildPrefix(root, options, scopedPrefix) {
     assertNoWindowsPathAlias(root, "filesystem", "temp workspace root uses a Windows filesystem namespace alias");
-    // Capture and sanitize caller-controlled prefix data before retaining descriptors.
-    const rawPrefix = options.prefix;
-    const workspacePrefix = scopedPrefix
-        ? `${sanitizeTempPrefix(rawPrefix)}${randomUUID()}-`
-        : rawPrefix;
+    // Capture and sanitize caller-controlled data before retaining descriptors.
+    const prefix = options.prefix;
+    const workspacePrefix = scopedPrefix ? `${sanitizeTempPrefix(prefix)}${randomUUID()}-` : prefix;
     const childPrefix = path.join(root, sanitizeTempPrefix(workspacePrefix));
     assertNoWindowsPathAlias(childPrefix, "filesystem", "temp workspace path uses a Windows filesystem namespace alias");
+    return childPrefix;
+}
+function throwTempWorkspaceCreationFailure(error, retainedChild, capability, owner) {
+    try {
+        if (owner)
+            owner.cleanupSync();
+        else {
+            const closeErrors = [];
+            try {
+                retainedChild?.close();
+            }
+            catch (closeError) {
+                closeErrors.push(closeError);
+            }
+            try {
+                capability.close();
+            }
+            catch (closeError) {
+                closeErrors.push(closeError);
+            }
+            if (closeErrors.length === 1)
+                throw closeErrors[0];
+            if (closeErrors.length > 1) {
+                throw new AggregateError(closeErrors, "temp workspace admission descriptor close failed");
+            }
+        }
+    }
+    catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "temp workspace creation and cleanup both failed");
+    }
+    throw error;
+}
+function registerTempWorkspace(dir, retainedChild, capability, admission, dirMode) {
+    let owner;
+    let stat;
+    let unregisterTempDir;
+    try {
+        const retainChildDescriptor = capability.admitChildDescriptor(retainedChild.ensureReadable());
+        // Final adoption orders ancestry and cleanup-parent authority before the
+        // original child's descriptor and named security-state checks.
+        if (capability.parent)
+            capability.assertAncestryCurrent();
+        else
+            admission.assertAncestry();
+        stat = retainedChild.finalizeAdmission(admission.ownerUid, dirMode);
+        owner = new TempWorkspaceCleanupOwner(retainedChild, capability, retainChildDescriptor);
+        unregisterTempDir = registerTempPathForExit(dir, { cleanupSync: () => owner.cleanupSync() });
+    }
+    catch (error) {
+        throwTempWorkspaceCreationFailure(error, retainedChild, capability, owner);
+    }
+    return { owner: owner, unregisterTempDir, identity: { dev: Number(stat.dev), ino: Number(stat.ino) } };
+}
+async function createTempWorkspace(options, scopedPrefix = false) {
+    const { rootDir, dirMode, mode, cleanupSafety } = tempWorkspaceSettings(options);
+    const admission = await admitTempWorkspaceRoot(rootDir);
+    const root = admission.dir;
+    const childPrefix = tempWorkspaceChildPrefix(root, options, scopedPrefix);
     const capability = new TempWorkspaceCleanupCapability(root, cleanupSafety, admission, dirMode);
     let dir;
-    let stat;
     let retainedChild;
-    let retainChildDescriptor = false;
-    let cleanupOwner;
-    let unregisterTempDir;
     try {
         // Native capability discovery is complete before this synchronous
         // boundary. The existing canonical-root route now captures the complete
@@ -143,7 +196,7 @@ async function createTempWorkspace(options, scopedPrefix = false) {
             capability.assertCurrent();
         else
             admission.assertCurrent();
-        stat = inspectDirectoryIdentitySync(dir);
+        const stat = inspectDirectoryIdentitySync(dir);
         const needsModeInitialization = validateInitialTempWorkspaceChild(stat, admission.ownerUid, dirMode);
         // Retain while the child still has its private creation mode so an
         // explicit dirMode such as 0 cannot make identity descriptor acquisition fail.
@@ -151,52 +204,11 @@ async function createTempWorkspace(options, scopedPrefix = false) {
         const modeInitialization = admitRetainedTempWorkspaceChild(retainedChild, needsModeInitialization, admission, dirMode);
         if (modeInitialization)
             await modeInitialization;
-        retainChildDescriptor = capability.admitChildDescriptor(retainedChild.ensureReadable());
-        // Final adoption order is deliberate: complete ancestry, retained cleanup
-        // parent, then descriptor and named checks of the original child identity.
-        if (capability.parent)
-            capability.assertAncestryCurrent();
-        else
-            admission.assertAncestry();
-        stat = retainedChild.finalizeAdmission(admission.ownerUid, dirMode);
-        cleanupOwner = new TempWorkspaceCleanupOwner(retainedChild, capability, retainChildDescriptor);
-        retainedChild = undefined;
-        unregisterTempDir = registerTempPathForExit(dir, {
-            cleanupSync: () => cleanupOwner.cleanupSync(),
-        });
     }
     catch (error) {
-        try {
-            if (cleanupOwner)
-                cleanupOwner.cleanupSync();
-            else {
-                const closeErrors = [];
-                try {
-                    retainedChild?.close();
-                }
-                catch (closeError) {
-                    closeErrors.push(closeError);
-                }
-                try {
-                    capability.close();
-                }
-                catch (closeError) {
-                    closeErrors.push(closeError);
-                }
-                if (closeErrors.length === 1)
-                    throw closeErrors[0];
-                if (closeErrors.length > 1) {
-                    throw new AggregateError(closeErrors, "temp workspace admission descriptor close failed");
-                }
-            }
-        }
-        catch (cleanupError) {
-            throw new AggregateError([error, cleanupError], "temp workspace creation and cleanup both failed");
-        }
-        throw error;
+        throwTempWorkspaceCreationFailure(error, retainedChild, capability);
     }
-    const owner = cleanupOwner;
-    const identity = { dev: Number(stat.dev), ino: Number(stat.ino) };
+    const { owner, identity, unregisterTempDir } = registerTempWorkspace(dir, retainedChild, capability, admission, dirMode);
     // Once registered, even a store-construction failure remains exit-cleanable.
     const store = fileStore({ rootDir: dir, private: true, dirMode, mode });
     return {
@@ -250,30 +262,13 @@ export async function withTempWorkspace(options, run) {
     }
 }
 function createTempWorkspaceSync(options, scopedPrefix = false) {
-    const rootDir = options.rootDir;
-    assertNoWindowsPathAlias(rootDir, "filesystem", "temp workspace root uses a Windows filesystem namespace alias");
-    const dirMode = options.dirMode ?? 0o700;
-    validateTempWorkspaceDirMode(dirMode);
-    const mode = options.mode ?? 0o600;
-    const cleanupSafety = resolveTempWorkspaceCleanupSafety(options.cleanupSafety);
+    const { rootDir, dirMode, mode, cleanupSafety } = tempWorkspaceSettings(options);
     const admission = admitTempWorkspaceRootSync(rootDir);
     const root = admission.dir;
-    assertNoWindowsPathAlias(root, "filesystem", "temp workspace root uses a Windows filesystem namespace alias");
-    // Capture and sanitize caller-controlled prefix data before retaining descriptors.
-    const rawPrefix = options.prefix;
-    const workspacePrefix = scopedPrefix
-        ? `${sanitizeTempPrefix(rawPrefix)}${randomUUID()}-`
-        : rawPrefix;
-    const childPrefix = path.join(root, sanitizeTempPrefix(workspacePrefix));
-    assertNoWindowsPathAlias(childPrefix, "filesystem", "temp workspace path uses a Windows filesystem namespace alias");
+    const childPrefix = tempWorkspaceChildPrefix(root, options, scopedPrefix);
     const capability = new TempWorkspaceCleanupCapability(root, cleanupSafety, admission, dirMode);
     let dir;
-    let stat;
     let retainedChild;
-    let retainChildDescriptor = false;
-    let needsModeInitialization;
-    let cleanupOwner;
-    let unregisterTempDir;
     try {
         const directRequestedMode = canCreateTempWorkspaceWithRequestedMode(dirMode);
         if (directRequestedMode) {
@@ -288,64 +283,23 @@ function createTempWorkspaceSync(options, scopedPrefix = false) {
             capability.assertCurrent();
         else
             admission.assertCurrent();
+        let stat;
         if (directRequestedMode) {
             const created = TempWorkspaceRetainedChild.retainCreated(dir);
             retainedChild = created.retained;
             stat = created.stat;
-            needsModeInitialization = validateInitialTempWorkspaceChild(stat, admission.ownerUid, dirMode);
         }
         else {
             stat = inspectDirectoryIdentitySync(dir);
-            needsModeInitialization = validateInitialTempWorkspaceChild(stat, admission.ownerUid, dirMode);
-            retainedChild = TempWorkspaceRetainedChild.retain(dir, stat);
         }
+        const needsModeInitialization = validateInitialTempWorkspaceChild(stat, admission.ownerUid, dirMode);
+        retainedChild ??= TempWorkspaceRetainedChild.retain(dir, stat);
         admitRetainedTempWorkspaceChildSync(retainedChild, needsModeInitialization, admission, dirMode);
-        retainChildDescriptor = capability.admitChildDescriptor(retainedChild.ensureReadable());
-        // Match async adoption: complete ancestry and retained cleanup authority
-        // precede descriptor and named child security-state checks.
-        if (capability.parent)
-            capability.assertAncestryCurrent();
-        else
-            admission.assertAncestry();
-        stat = retainedChild.finalizeAdmission(admission.ownerUid, dirMode);
-        cleanupOwner = new TempWorkspaceCleanupOwner(retainedChild, capability, retainChildDescriptor);
-        retainedChild = undefined;
-        unregisterTempDir = registerTempPathForExit(dir, {
-            cleanupSync: () => cleanupOwner.cleanupSync(),
-        });
     }
     catch (error) {
-        try {
-            if (cleanupOwner)
-                cleanupOwner.cleanupSync();
-            else {
-                const closeErrors = [];
-                try {
-                    retainedChild?.close();
-                }
-                catch (closeError) {
-                    closeErrors.push(closeError);
-                }
-                try {
-                    capability.close();
-                }
-                catch (closeError) {
-                    closeErrors.push(closeError);
-                }
-                if (closeErrors.length === 1)
-                    throw closeErrors[0];
-                if (closeErrors.length > 1) {
-                    throw new AggregateError(closeErrors, "temp workspace admission descriptor close failed");
-                }
-            }
-        }
-        catch (cleanupError) {
-            throw new AggregateError([error, cleanupError], "temp workspace creation and cleanup both failed");
-        }
-        throw error;
+        throwTempWorkspaceCreationFailure(error, retainedChild, capability);
     }
-    const owner = cleanupOwner;
-    const identity = { dev: Number(stat.dev), ino: Number(stat.ino) };
+    const { owner, identity, unregisterTempDir } = registerTempWorkspace(dir, retainedChild, capability, admission, dirMode);
     // Once registered, even a store-construction failure remains exit-cleanable.
     const store = fileStoreSync({ rootDir: dir, private: true, dirMode, mode });
     return {

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

@@ -1 +1 @@
-{"version":3,"file":"regular-file.d.ts","sourceRoot":"","sources":["../src/regular-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,KAAK,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,MAAM,MAAM,SAAS,CAAC;AAuB7B,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAExF,KAAK,8BAA8B,GAAG,IAAI,CACxC,OAAO,MAAM,CAAC,SAAS,EACvB,UAAU,GAAG,SAAS,GAAG,UAAU,CACpC,GACC,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,YAAY,CAAC,CAAC,CAAC;AAEtE,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,8BAAiD,GAC3D,MAAM,CASR;AAaD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAetF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAe3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CA+D3C;AA2DD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;CACb,CAsCA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkFxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAkF7E"}
+{"version":3,"file":"regular-file.d.ts","sourceRoot":"","sources":["../src/regular-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,KAAK,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,MAAM,MAAM,SAAS,CAAC;AAuB7B,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAExF,KAAK,8BAA8B,GAAG,IAAI,CACxC,OAAO,MAAM,CAAC,SAAS,EACvB,UAAU,GAAG,SAAS,GAAG,UAAU,CACpC,GACC,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,YAAY,CAAC,CAAC,CAAC;AAEtE,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,8BAAiD,GAC3D,MAAM,CASR;AAaD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAEtF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAe3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CA+D3C;AA2DD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;CACb,CAsCA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkFxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAkF7E"}

package/dist/regular-file.js

@@ -30,21 +30,7 @@ function translateBoundedReadOverflow(error, filePath, maxBytes) {
     throw error;
 }
 export async function statRegularFile(filePath) {
-    assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
-    let stat;
-    try {
-        stat = fsSync.lstatSync(filePath);
-    }
-    catch (err) {
-        if (isNotFoundPathError(err)) {
-            return { missing: true };
-        }
-        throw err;
-    }
-    if (stat.isSymbolicLink() || !stat.isFile()) {
-        throw new Error("path must be a regular file");
-    }
-    return { missing: false, stat };
+    return statRegularFileSync(filePath);
 }
 export function statRegularFileSync(filePath) {
     assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");

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

@@ -1 +1 @@
-{"version":3,"file":"replace-directory.d.ts","sourceRoot":"","sources":["../src/replace-directory.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAiBf"}
+{"version":3,"file":"replace-directory.d.ts","sourceRoot":"","sources":["../src/replace-directory.ts"],"names":[],"mappings":"AAuBA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAqIF,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAiBf"}

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"}