@openclaw/fs-safe 0.13.1 → 0.15.0

package/dist/file-lock-sync.js

@@ -1,24 +1,17 @@
 import fs from "node:fs";
+import { acquireFileLockSyncWithRoot } from "./file-lock-sync-root-acquire.js";
+import { isRootSyncHeldLockHandle, withRootSyncHeldLockHandle } from "./file-lock-sync-root-held.js";
 import path from "node:path";
-import { FsSafeError } from "./errors.js";
-import { readSidecarLockSnapshotSync, readSidecarLockRawSnapshotSync, parseSidecarLockSnapshot, relativeSidecarLockPath, removeSidecarLockIfUnchangedSync, serializeSidecarLockPayload, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
-import { computeSidecarLockDelayMs, isTransientLockFileDenial, maxTransientLockDenials, sidecarLockPayloadCreatedAtMs, validateSidecarLockStaleMs, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
+import { readSidecarLockSnapshotSync, removeSidecarLockIfUnchangedSync, serializeSidecarLockPayload, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { computeSidecarLockDelayMs, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockStaleMs, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
 import { getFsSafeLockConfig } from "./lock-config.js";
 import { sleepSync } from "./timing.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { realpathSync } from "./realpath.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { createSuppressedError } from "./suppressed-error.js";
-const SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncSidecarLocks");
-const SYNC_CLEANUP_REGISTERED_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistered");
-const SYNC_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupHandler");
-function getSyncHeldLocks() {
-    const globalWithState = globalThis;
-    if (!globalWithState[SYNC_HELD_LOCKS_KEY]) {
-        globalWithState[SYNC_HELD_LOCKS_KEY] = new Map();
-    }
-    return globalWithState[SYNC_HELD_LOCKS_KEY];
-}
+import { ensureSyncLockExitCleanupRegistered, getSyncHeldLocks, foreignSyncHeldLock, getSyncLockAdmissions, syncReclaimGuardExists, syncLockTimeout, } from "./file-lock-sync-admission.js";
+import { handleSyncStaleAdmission, } from "./file-lock-sync-stale-admission.js";
 function releaseAllSyncHeldLocks() {
     const heldLocks = getSyncHeldLocks();
     for (const [normalizedTargetPath, held] of heldLocks) {
@@ -41,14 +34,7 @@ function releaseAllSyncHeldLocks() {
         }
         heldLocks.delete(normalizedTargetPath);
     }
-}
-function ensureSyncExitCleanupRegistered() {
-    const globalWithCleanup = globalThis;
-    if (globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY])
-        return;
-    globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY] = true;
-    globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY] = releaseAllSyncHeldLocks;
-    process.on("exit", releaseAllSyncHeldLocks);
+    getSyncLockAdmissions().clear();
 }
 function verifySyncHeldLock(held) {
     const current = readSidecarLockSnapshotSync(held.lockPath, held.parsePayload);
@@ -113,42 +99,10 @@ function normalizeTargetPath(targetPath) {
     assertNoWindowsPathAlias(normalized);
     return normalized;
 }
-function boundedLockPath(lockPath, lockRoot) {
-    const resolved = path.resolve(lockPath);
-    assertNoWindowsPathAlias(resolved);
-    if (!lockRoot)
-        return resolved;
-    relativeSidecarLockPath(lockRoot, resolved);
-    const parent = path.dirname(resolved);
-    const parentReal = canonicalLockParentSync(parent);
-    assertNoWindowsPathAlias(parentReal);
-    const parentRelative = path.relative(lockRoot.rootReal, parentReal);
-    if (parentRelative === ".." || parentRelative.startsWith(`..${path.sep}`) || path.isAbsolute(parentRelative)) {
-        throw new FsSafeError("outside-workspace", "sidecar lock parent is outside lockRoot");
-    }
-    const bounded = path.join(parentReal, path.basename(resolved));
-    assertNoWindowsPathAlias(bounded);
-    return bounded;
-}
-function defaultShouldReclaim(snapshot, staleMs, nowMs) {
-    const createdAtMs = sidecarLockPayloadCreatedAtMs(snapshot.payload);
-    if (createdAtMs !== null)
-        return nowMs - createdAtMs > staleMs;
-    // A cooperating holder can unlink after the snapshot; use its observed age.
-    return !snapshot.stat || nowMs - snapshot.stat.mtimeMs > staleMs;
-}
-function reclaimGuardExists(reclaimGuardPath) {
-    try {
-        fs.lstatSync(reclaimGuardPath);
-        return true;
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return false;
-        throw error;
-    }
-}
 export function acquireFileLockSync(targetPath, options) {
+    const lockRoot = options.lockRoot;
+    if (lockRoot)
+        return acquireFileLockSyncWithRoot(targetPath, options, lockRoot);
     const defaults = getFsSafeLockConfig();
     const retry = options.retry ?? defaults.retry ?? {};
     const timeoutMs = options.timeoutMs ?? defaults.timeoutMs;
@@ -156,38 +110,54 @@ export function acquireFileLockSync(targetPath, options) {
     validateSidecarLockTimeoutMs(timeoutMs);
     const staleMs = options.staleMs ?? defaults.staleMs ?? 30_000;
     validateSidecarLockStaleMs(staleMs);
-    validateSidecarLockCompromiseCheckIntervalMs(options.compromiseCheckIntervalMs);
+    const compromiseCheckIntervalMs = options.compromiseCheckIntervalMs;
+    validateSidecarLockCompromiseCheckIntervalMs(compromiseCheckIntervalMs);
     const explicitLockPath = options.lockPath;
     assertNoWindowsPathAlias(targetPath);
     if (explicitLockPath !== undefined)
         assertNoWindowsPathAlias(explicitLockPath);
     const normalizedTargetPath = normalizeTargetPath(targetPath);
-    const lockPath = boundedLockPath(explicitLockPath ?? `${normalizedTargetPath}.lock`, options.lockRoot);
+    const lockPath = path.resolve(explicitLockPath ?? `${normalizedTargetPath}.lock`);
+    assertNoWindowsPathAlias(lockPath);
+    const requestedReentrantOwner = options.reentrantOwner;
     const heldLocks = getSyncHeldLocks();
-    const held = heldLocks.get(normalizedTargetPath);
-    if (held &&
-        options.reentrantOwner !== undefined &&
-        held.reentrantOwner !== undefined &&
-        options.reentrantOwner === held.reentrantOwner) {
-        held.refCount += 1;
-        return createSyncHeldLockHandle(held);
+    const currentTargetHolder = () => heldLocks.get(normalizedTargetPath) ??
+        foreignSyncHeldLock("raw", normalizedTargetPath);
+    const initiallyHeld = heldLocks.get(normalizedTargetPath);
+    if (initiallyHeld && !foreignSyncHeldLock("raw", normalizedTargetPath) &&
+        requestedReentrantOwner !== undefined &&
+        initiallyHeld.reentrantOwner !== undefined &&
+        requestedReentrantOwner === initiallyHeld.reentrantOwner) {
+        initiallyHeld.refCount += 1;
+        return createSyncHeldLockHandle(initiallyHeld);
     }
-    // Process defaults fill the same fields here as withLockDefaults() fills for
-    // the asynchronous manager, so both acquirers honor configureFsSafeLocks().
-    const staleRecovery = options.staleRecovery ?? defaults.staleRecovery;
+    const admissions = getSyncLockAdmissions();
+    const admissionToken = {};
+    let ownsAdmission = false;
+    const hasAdmissionToken = () => admissions.get(normalizedTargetPath) === admissionToken;
+    const releaseAdmission = () => {
+        if (ownsAdmission && hasAdmissionToken())
+            admissions.delete(normalizedTargetPath);
+        ownsAdmission = false;
+    };
+    let payloadCallback;
+    let onCompromised = undefined;
+    let onCompromisedObserved = false;
+    let parsePayload = undefined;
+    let parsePayloadObserved = false;
+    let staleRecovery = undefined;
+    let staleRecoveryObserved = false;
+    const staleOptions = {};
     const startedAt = Date.now();
     let attempt = 0;
     let transientDenials = 0;
     const reclaimGuardPath = `${lockPath}.reclaim`;
     const waitForRetry = () => {
+        releaseAdmission();
         const elapsed = Date.now() - startedAt;
         const timedOut = timeoutMs !== undefined && elapsed >= timeoutMs;
         if (timedOut || (retry.retries !== undefined && attempt >= retry.retries)) {
-            throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
-                code: "file_lock_timeout",
-                lockPath,
-                normalizedTargetPath,
-            });
+            throw syncLockTimeout(lockPath, normalizedTargetPath);
         }
         const remaining = timeoutMs === undefined || timeoutMs === Number.POSITIVE_INFINITY
             ? Number.POSITIVE_INFINITY
@@ -210,170 +180,240 @@ export function acquireFileLockSync(targetPath, options) {
         }
         return true;
     };
-    while (true) {
-        if (reclaimGuardExists(reclaimGuardPath)) {
-            waitForRetry();
-            continue;
-        }
-        let fd;
-        const payload = options.payload();
-        const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
-        let lockFileCreateDenied = false;
+    const assertAdmissionToken = () => {
+        if (!hasAdmissionToken())
+            throw syncLockTimeout(lockPath, normalizedTargetPath);
+    };
+    const runAdmissionBoundary = (callback) => {
+        assertAdmissionToken();
         try {
-            const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number"
-                ? fs.constants.O_NOFOLLOW
-                : 0;
-            try {
-                fd = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, 0o600);
-            }
-            catch (error) {
-                lockFileCreateDenied = isTransientLockFileDenial(error, lockPath);
-                throw error;
-            }
-            fs.writeFileSync(fd, raw, "utf8");
-            fs.fsyncSync(fd);
-            const snapshot = {
-                raw,
-                payload,
-                stat: fs.fstatSync(fd),
-                ownershipToken,
-            };
-            const createdHeld = {
-                fd,
-                lockPath,
-                normalizedTargetPath,
-                parsePayload: options.parsePayload,
-                refCount: 1,
-                reentrantOwner: options.reentrantOwner,
-                snapshot,
-            };
-            heldLocks.set(normalizedTargetPath, createdHeld);
-            ensureSyncExitCleanupRegistered();
-            const returnedHandle = createSyncHeldLockHandle(createdHeld);
-            if (options.onCompromised && (options.compromiseCheckIntervalMs ?? 0) > 0) {
-                createdHeld.timer = setInterval(() => {
-                    let stillHeld;
-                    try {
-                        stillHeld = returnedHandle.verifyStillHeld();
-                    }
-                    catch {
-                        stillHeld = false;
-                    }
-                    if (!stillHeld && createdHeld.timer) {
-                        clearInterval(createdHeld.timer);
-                        createdHeld.timer = undefined;
-                        options.onCompromised?.({ lockPath, normalizedTargetPath });
-                    }
-                }, options.compromiseCheckIntervalMs);
-                createdHeld.timer.unref();
-            }
-            fd = undefined;
-            return returnedHandle;
+            return callback();
         }
-        catch (error) {
-            if (fd !== undefined) {
-                const failed = { payload: null };
-                try {
-                    failed.stat = fs.fstatSync(fd);
+        finally {
+            assertAdmissionToken();
+        }
+    };
+    try {
+        while (true) {
+            if (!ownsAdmission) {
+                const held = heldLocks.get(normalizedTargetPath);
+                if (held && !foreignSyncHeldLock("raw", normalizedTargetPath) &&
+                    requestedReentrantOwner !== undefined &&
+                    held.reentrantOwner !== undefined &&
+                    requestedReentrantOwner === held.reentrantOwner) {
+                    held.refCount += 1;
+                    return createSyncHeldLockHandle(held);
                 }
-                catch {
-                    // Missing identity leaves the sidecar in place, but must not skip close.
+                if (admissions.has(normalizedTargetPath)) {
+                    // The owner can only finish after this synchronous callback unwinds.
+                    throw syncLockTimeout(lockPath, normalizedTargetPath);
                 }
-                const failedFd = fd;
-                // A close error may still free the number; consume ownership before closing.
-                fd = undefined;
-                try {
-                    fs.closeSync(failedFd);
-                    if (failed.stat)
-                        removeSidecarLockIfUnchangedSync(lockPath, failed);
-                }
-                catch (cleanupError) {
-                    throw createSuppressedError(error, cleanupError, "file lock acquisition and cleanup both failed");
+                admissions.set(normalizedTargetPath, admissionToken);
+                ownsAdmission = true;
+            }
+            const attemptHeld = currentTargetHolder();
+            const holderWasReplaced = () => {
+                const current = currentTargetHolder();
+                return current !== undefined && current !== attemptHeld;
+            };
+            if (!staleRecoveryObserved) {
+                staleRecovery = runAdmissionBoundary(() => options.staleRecovery ?? defaults.staleRecovery);
+                staleRecoveryObserved = true;
+                if (holderWasReplaced()) {
+                    waitForRetry();
+                    continue;
                 }
             }
-            if (lockFileCreateDenied && retryLockFileDenial(error))
+            const reclaimGuardExists = syncReclaimGuardExists(reclaimGuardPath);
+            if (!hasAdmissionToken())
+                throw syncLockTimeout(lockPath, normalizedTargetPath);
+            if (holderWasReplaced()) {
+                waitForRetry();
                 continue;
-            if (error.code !== "EEXIST")
-                throw error;
-            if (heldLocks.has(normalizedTargetPath)) {
+            }
+            if (reclaimGuardExists) {
                 waitForRetry();
                 continue;
             }
-            let rawSnapshot;
-            let lockFileOpenDenied = false;
-            try {
-                rawSnapshot = readSidecarLockRawSnapshotSync(lockPath, {
-                    rejectNonFile: true,
-                    onOpenFailure: (error) => { lockFileOpenDenied = isTransientLockFileDenial(error, lockPath); },
-                });
+            let fd;
+            let createdHeld;
+            let createdSnapshot;
+            if (!payloadCallback)
+                payloadCallback = runAdmissionBoundary(() => options.payload);
+            if (holderWasReplaced()) {
+                waitForRetry();
+                continue;
             }
-            catch (readError) {
-                if (lockFileOpenDenied && retryLockFileDenial(readError))
-                    continue;
-                throw readError;
+            const payload = runAdmissionBoundary(() => Reflect.apply(payloadCallback, options, []));
+            if (holderWasReplaced()) {
+                waitForRetry();
+                continue;
+            }
+            const { raw, ownershipToken } = runAdmissionBoundary(() => serializeSidecarLockPayload(payload));
+            if (holderWasReplaced()) {
+                waitForRetry();
+                continue;
             }
-            const snapshot = parseSidecarLockSnapshot(rawSnapshot, options.parsePayload);
-            if (!snapshot) {
+            if (currentTargetHolder() !== undefined) {
                 waitForRetry();
                 continue;
             }
-            const nowMs = Date.now();
-            const reclaim = options.shouldReclaim
-                ? options.shouldReclaim({
+            if (!onCompromisedObserved) {
+                onCompromised = runAdmissionBoundary(() => options.onCompromised);
+                onCompromisedObserved = true;
+                if (currentTargetHolder() !== undefined) {
+                    waitForRetry();
+                    continue;
+                }
+            }
+            if (!parsePayloadObserved) {
+                parsePayload = runAdmissionBoundary(() => options.parsePayload);
+                parsePayloadObserved = true;
+                if (currentTargetHolder() !== undefined) {
+                    waitForRetry();
+                    continue;
+                }
+            }
+            let lockFileCreateDenied = false;
+            let exclusiveCreateConflict = false;
+            try {
+                const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number"
+                    ? fs.constants.O_NOFOLLOW
+                    : 0;
+                try {
+                    fd = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, 0o600);
+                }
+                catch (error) {
+                    lockFileCreateDenied = isTransientLockFileDenial(error, lockPath);
+                    exclusiveCreateConflict = error.code === "EEXIST";
+                    throw error;
+                }
+                fs.writeFileSync(fd, raw, "utf8");
+                fs.fsyncSync(fd);
+                createdSnapshot = {
+                    raw,
+                    payload,
+                    stat: fs.fstatSync(fd),
+                    ownershipToken,
+                };
+                createdHeld = {
+                    fd,
                     lockPath,
                     normalizedTargetPath,
-                    payload: snapshot.payload,
-                    staleMs,
-                    nowMs,
-                    heldByThisProcess: false,
-                })
-                : defaultShouldReclaim(snapshot, staleMs, nowMs);
-            if (reclaim) {
-                if (staleRecovery === "remove-if-unchanged" &&
-                    snapshot.raw !== undefined &&
-                    options.shouldRemoveStaleLock?.({
-                        lockPath,
-                        normalizedTargetPath,
-                        raw: snapshot.raw,
-                        payload: snapshot.payload,
-                    })) {
-                    let ownsReclaimGuard = false;
+                    parsePayload,
+                    refCount: 1,
+                    reentrantOwner: requestedReentrantOwner,
+                    snapshot: createdSnapshot,
+                };
+                const candidateHeld = createdHeld;
+                ensureSyncLockExitCleanupRegistered(releaseAllSyncHeldLocks, lockPath, normalizedTargetPath);
+                if (!hasAdmissionToken() || currentTargetHolder() !== undefined) {
+                    throw syncLockTimeout(lockPath, normalizedTargetPath);
+                }
+                const returnedHandle = createSyncHeldLockHandle(candidateHeld);
+                if (onCompromised && (compromiseCheckIntervalMs ?? 0) > 0) {
+                    const compromisedCallback = onCompromised;
+                    candidateHeld.timer = setInterval(() => {
+                        let stillHeld;
+                        try {
+                            stillHeld = returnedHandle.verifyStillHeld();
+                        }
+                        catch {
+                            stillHeld = false;
+                        }
+                        if (!stillHeld && candidateHeld.timer) {
+                            clearInterval(candidateHeld.timer);
+                            candidateHeld.timer = undefined;
+                            Reflect.apply(compromisedCallback, options, [{ lockPath, normalizedTargetPath }]);
+                        }
+                    }, compromiseCheckIntervalMs);
+                    candidateHeld.timer.unref();
+                }
+                if (!hasAdmissionToken() ||
+                    currentTargetHolder() !== undefined) {
+                    throw syncLockTimeout(lockPath, normalizedTargetPath);
+                }
+                heldLocks.set(normalizedTargetPath, candidateHeld);
+                releaseAdmission();
+                fd = undefined;
+                return returnedHandle;
+            }
+            catch (error) {
+                if (createdHeld?.timer) {
+                    clearInterval(createdHeld.timer);
+                    createdHeld.timer = undefined;
+                }
+                if (createdHeld && heldLocks.get(normalizedTargetPath) === createdHeld) {
+                    heldLocks.delete(normalizedTargetPath);
+                }
+                if (fd !== undefined) {
+                    const failed = createdSnapshot ?? { payload: null };
+                    if (!failed.stat) {
+                        try {
+                            failed.stat = fs.fstatSync(fd);
+                        }
+                        catch {
+                            // Missing identity leaves the sidecar in place, but must not skip close.
+                        }
+                    }
+                    const failedFd = fd;
+                    fd = undefined;
+                    if (createdHeld)
+                        createdHeld.fd = undefined;
                     try {
-                        fs.mkdirSync(reclaimGuardPath);
-                        ownsReclaimGuard = true;
-                        if (removeSidecarLockIfUnchangedSync(lockPath, snapshot))
-                            continue;
+                        fs.closeSync(failedFd);
+                        if (failed.stat)
+                            removeSidecarLockIfUnchangedSync(lockPath, failed);
                     }
-                    catch (reclaimError) {
-                        if (reclaimError.code !== "EEXIST") {
-                            throw reclaimError;
-                        }
+                    catch (cleanupError) {
+                        throw createSuppressedError(error, cleanupError, "file lock acquisition and cleanup both failed");
+                    }
+                }
+                if (lockFileCreateDenied) {
+                    if (!hasAdmissionToken())
+                        throw syncLockTimeout(lockPath, normalizedTargetPath);
+                    if (currentTargetHolder() !== undefined) {
                         waitForRetry();
                         continue;
                     }
-                    finally {
-                        if (ownsReclaimGuard) {
-                            try {
-                                fs.rmdirSync(reclaimGuardPath);
-                            }
-                            catch {
-                                // A surviving reclaim guard fails closed.
-                            }
-                        }
-                    }
+                    if (retryLockFileDenial(error))
+                        continue;
+                    throw error;
+                }
+                if (!exclusiveCreateConflict)
+                    throw error;
+                if (!hasAdmissionToken())
+                    throw syncLockTimeout(lockPath, normalizedTargetPath);
+                if (currentTargetHolder() !== undefined) {
+                    waitForRetry();
+                    continue;
                 }
-                throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-                    code: "file_lock_stale",
+                handleSyncStaleAdmission({
+                    hasToken: hasAdmissionToken,
+                    currentHeld: currentTargetHolder,
                     lockPath,
                     normalizedTargetPath,
+                    options,
+                    parsePayload,
+                    reclaimGuardPath,
+                    retryLockFileDenial,
+                    staleMs,
+                    staleOptions,
+                    staleRecovery,
+                    waitForRetry,
                 });
+                continue;
             }
-            waitForRetry();
         }
     }
+    finally {
+        releaseAdmission();
+    }
 }
 export function withFileLockSync(targetPath, options, fn) {
     const lock = acquireFileLockSync(targetPath, options);
+    if (isRootSyncHeldLockHandle(lock))
+        return withRootSyncHeldLockHandle(lock, fn);
     try {
         return fn();
     }

package/dist/file-store-prune.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-store-prune.d.ts","sourceRoot":"","sources":["../src/file-store-prune.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,qBAAqB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CA8FhB"}
+{"version":3,"file":"file-store-prune.d.ts","sourceRoot":"","sources":["../src/file-store-prune.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAQF,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,qBAAqB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CA8FhB"}

package/dist/file-store-prune.js

@@ -6,7 +6,11 @@ import { isPathInside } from "./path.js";
 import { realpathSync } from "./realpath.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { root } from "./root.js";
+import { nonrecursiveRemovalKind } from "./root-remove.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
+const REMOVE_EMPTY_DIRECTORY_OPTIONS = Object.freeze({
+    [nonrecursiveRemovalKind]: "directory",
+});
 export async function pruneExpiredStoreEntries(params) {
     const now = Date.now();
     const recursive = params.options.recursive ?? false;
@@ -70,7 +74,7 @@ export async function pruneExpiredStoreEntries(params) {
                     await assertRootGuard();
                     // Keep empty-dir pruning on the same root-bounded remove path as files;
                     // the Root fallback handles empty directories without recursive delete.
-                    await scopedRoot.remove(relativePath).catch(() => undefined);
+                    await scopedRoot.remove(relativePath, REMOVE_EMPTY_DIRECTORY_OPTIONS).catch(() => undefined);
                 }
                 continue;
             }

package/dist/file-store-sync-directory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-store-sync-directory.d.ts","sourceRoot":"","sources":["../src/file-store-sync-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAc/C,KAAK,kBAAkB,GAAG,eAAe,GAAG,OAAO,CAAC;AAOpD,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,WAAW,CAAC;CACxB,CAAC,CAAC;AAkVH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,kBAAkB,CAAC;CACnC,GAAG,yBAAyB,CA4D5B;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,yBAAyB,GACjC,IAAI,CAsBN"}
+{"version":3,"file":"file-store-sync-directory.d.ts","sourceRoot":"","sources":["../src/file-store-sync-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAc/C,KAAK,kBAAkB,GAAG,eAAe,GAAG,OAAO,CAAC;AAOpD,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,WAAW,CAAC;CACxB,CAAC,CAAC;AA0VH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,kBAAkB,CAAC;CACnC,GAAG,yBAAyB,CA4D5B;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,yBAAyB,GACjC,IAAI,CAsBN"}

package/dist/file-store-sync-directory.js

@@ -11,7 +11,9 @@ function changedStoreDirectory(messagePrefix, cause) {
     return new FsSafeError("outside-workspace", `${messagePrefix} directory escapes root`, { cause });
 }
 function storeDirectoryRealPath(dir) {
-    const realPath = realpathSync(pathForWindowsFilesystem(dir));
+    const operationPath = pathForWindowsFilesystem(dir);
+    const realPath = process.platform === "win32"
+        ? realpathSync(operationPath) : realpathSync.native(operationPath);
     assertNoWindowsPathAlias(realPath, "filesystem");
     return realPath;
 }
@@ -72,7 +74,9 @@ function assertAdmittedEdgeCurrent(receipts, rootReal, messagePrefix) {
     if (!rootReceipt || !targetReceipt) {
         throw new FsSafeError("helper-failed", "store directory receipt is missing");
     }
-    const rootStat = assertRootCurrent(rootReceipt, rootReal, messagePrefix);
+    const rootStat = rootReal === undefined
+        ? inspectReceiptCurrent(rootReceipt, messagePrefix, true)
+        : assertRootCurrent(rootReceipt, rootReal, messagePrefix);
     if (targetIndex === 0)
         return rootStat;
     const parent = receipts[targetIndex - 1];
@@ -87,10 +91,13 @@ function assertAdmittedEdgeCurrent(receipts, rootReal, messagePrefix) {
     return targetStat;
 }
 function assertModeTargetCurrent(receipts, rootReal, messagePrefix) {
+    const root = receipts[0];
     const target = receipts.at(-1);
-    if (!target)
+    if (!root || !target)
         throw new FsSafeError("helper-failed", "store directory receipt is missing");
-    const stat = assertAdmittedEdgeCurrent(receipts, rootReal, messagePrefix);
+    // The target's canonical observation shares the exact identity fence. Keep
+    // the trailing root canonical check: an ancestor relocation can retain IDs.
+    assertAdmittedEdgeCurrent(receipts, undefined, messagePrefix);
     let targetReal;
     try {
         targetReal = storeDirectoryRealPath(target.dir);
@@ -98,10 +105,10 @@ function assertModeTargetCurrent(receipts, rootReal, messagePrefix) {
     catch (error) {
         throw changedStoreDirectory(messagePrefix, error);
     }
-    if (!isPathInside(rootReal, targetReal))
+    if (target === root ? targetReal !== rootReal : !isPathInside(rootReal, targetReal)) {
         throw changedStoreDirectory(messagePrefix);
-    assertAdmittedEdgeCurrent(receipts, rootReal, messagePrefix);
-    return stat;
+    }
+    return assertAdmittedEdgeCurrent(receipts, rootReal, messagePrefix);
 }
 function assertReceiptChain(receipts, rootReal, messagePrefix) {
     const rootReceipt = receipts[0];

package/dist/file-store-sync-write.js

@@ -76,7 +76,7 @@ export function writeFileSyncAtomic(params) {
     }
     const tempPath = path.join(parentGuard?.dir ?? path.dirname(filePath), `.fs-safe-${process.pid}-${randomUUID()}.tmp`);
     const owner = new SyncAtomicTempOwner(tempPath);
-    let originalError;
+    let originalFailure;
     try {
         getFsSafeTestHooks()?.beforeFileStoreSyncPrivateWrite?.(filePath);
         if (parentGuard) {
@@ -133,10 +133,10 @@ export function writeFileSyncAtomic(params) {
         return filePath;
     }
     catch (error) {
-        originalError = error;
+        originalFailure = { error };
         throw error;
     }
     finally {
-        owner.finish({ fsModule: fs, originalError, throwOnCleanupError: false });
+        owner.finish({ fsModule: fs, originalFailure, throwOnCleanupError: false });
     }
 }