@openclaw/fs-safe 0.16.0 → 0.18.0

package/dist/file-lock-sync-root-acquire.js

@@ -2,11 +2,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { captureRootSyncAcquireOptions } from "./file-lock-sync-root-options.js";
-import { defaultSyncShouldReclaim, foreignSyncHeldLock, getSyncLockAdmissions, syncLockTimeout } from "./file-lock-sync-admission.js";
-import { computeSidecarLockDelayMs, isTransientLockFileDenial, maxTransientLockDenials, } from "./sidecar-lock-policy.js";
+import { defaultSyncShouldReclaim, foreignSyncHeldLock } from "./file-lock-sync-admission.js";
+import { isTransientLockFileDenial } from "./sidecar-lock-policy.js";
 import { serializeSidecarLockPayload, } from "./sidecar-lock-reclaim.js";
 import { createSuppressedError } from "./suppressed-error.js";
-import { sleepSync } from "./timing.js";
+import { SyncLockAcquisition } from "./file-lock-sync-acquisition.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { admitFileLockSyncRootPath, assertFileLockSyncRootPathsCurrent, captureFileLockSyncRootAuthority, normalizeFileLockSyncTargetWithRoot, } from "./file-lock-sync-root.js";
 import { cleanupCreatedRootSyncLock, FileLockSyncRootArbitrationCollision, tryReuseCurrentRootSyncHeldLock, } from "./file-lock-sync-root-arbitration.js";
@@ -36,20 +37,6 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
     const heldLocks = getRootSyncHeldLocks();
     const currentTargetHolder = () => heldLocks.get(normalizedTargetPath) ??
         foreignSyncHeldLock("root", normalizedTargetPath);
-    const admissions = getSyncLockAdmissions();
-    const admissionToken = {};
-    let ownsAdmission = false;
-    const assertAdmission = () => {
-        if (admissions.get(normalizedTargetPath) !== admissionToken) {
-            throw syncLockTimeout(lockPath, normalizedTargetPath);
-        }
-    };
-    const releaseAdmission = () => {
-        if (ownsAdmission && admissions.get(normalizedTargetPath) === admissionToken) {
-            admissions.delete(normalizedTargetPath);
-        }
-        ownsAdmission = false;
-    };
     const arbitration = Object.freeze({
         authority,
         heldLocks,
@@ -58,44 +45,15 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
         reentrantOwner: options.reentrantOwner,
     });
     if (heldLocks.has(normalizedTargetPath) && !foreignSyncHeldLock("root", normalizedTargetPath)) {
-        assertFileLockSyncRootPathsCurrent(guardedPaths, true, true);
+        assertFileLockSyncRootPathsCurrent(guardedPaths);
         const initiallyReusable = tryReuseCurrentRootSyncHeldLock(arbitration);
         if (initiallyReusable)
             return initiallyReusable;
     }
-    const startedAt = Date.now();
-    let attempt = 0;
-    let transientDenials = 0;
+    const acquisition = new SyncLockAcquisition(lockPath, normalizedTargetPath, options.retry, options.timeoutMs);
     let ownedReclaimGuard;
     let reclaimCleanupAttempted = false;
     const reuseCurrentHeld = () => ownedReclaimGuard ? undefined : tryReuseCurrentRootSyncHeldLock(arbitration);
-    const waitForRetry = () => {
-        releaseAdmission();
-        const elapsed = Date.now() - startedAt;
-        const timedOut = options.timeoutMs !== undefined && elapsed >= options.timeoutMs;
-        if (timedOut || (options.retry.retries !== undefined && attempt >= options.retry.retries)) {
-            throw syncLockTimeout(lockPath, normalizedTargetPath);
-        }
-        const remaining = options.timeoutMs === undefined || options.timeoutMs === Number.POSITIVE_INFINITY
-            ? Number.POSITIVE_INFINITY
-            : Math.max(0, options.timeoutMs - elapsed);
-        sleepSync(Math.min(computeSidecarLockDelayMs(options.retry, attempt), remaining));
-        attempt += 1;
-    };
-    const retryLockFileDenial = (error) => {
-        if (!isTransientLockFileDenial(error, lockPath) ||
-            ++transientDenials > maxTransientLockDenials)
-            return false;
-        try {
-            waitForRetry();
-        }
-        catch (waitError) {
-            if (waitError.code === "file_lock_timeout")
-                throw error;
-            throw waitError;
-        }
-        return true;
-    };
     const releaseReclaimGuard = () => {
         const receipt = ownedReclaimGuard;
         if (!receipt)
@@ -115,19 +73,14 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
     };
     try {
         while (true) {
-            if (!ownsAdmission) {
-                if (admissions.has(normalizedTargetPath))
-                    throw syncLockTimeout(lockPath, normalizedTargetPath);
-                admissions.set(normalizedTargetPath, admissionToken);
-                ownsAdmission = true;
-            }
-            assertAdmission();
-            assertFileLockSyncRootPathsCurrent(guardedPaths, true, true);
-            assertAdmission();
+            acquisition.reserve();
+            acquisition.assert();
+            assertFileLockSyncRootPathsCurrent(guardedPaths);
+            acquisition.assert();
             if (ownedReclaimGuard)
                 assertOwnedReclaimGuardCurrent();
-            if (!ownedReclaimGuard && fileLockSyncRootGuardExists(reclaimRootPath, true)) {
-                waitForRetry();
+            if (!ownedReclaimGuard && fileLockSyncRootGuardExists(reclaimRootPath)) {
+                acquisition.waitForRetry();
                 continue;
             }
             if (currentTargetHolder() !== undefined) {
@@ -136,16 +89,16 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                     return reused;
             }
             const payload = Reflect.apply(options.payload, options.optionsReceiver, []);
-            assertAdmission();
+            acquisition.assert();
             const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
-            assertAdmission();
+            acquisition.assert();
             if (ownedReclaimGuard)
                 assertOwnedReclaimGuardCurrent();
             if (currentTargetHolder() !== undefined) {
                 const reused = reuseCurrentHeld();
                 if (reused)
                     return reused;
-                waitForRetry();
+                acquisition.waitForRetry();
                 continue;
             }
             let fd;
@@ -153,9 +106,9 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
             let unpublishedTimer;
             let lockFileCreateOpenFailure;
             try {
-                const created = createFileLockSyncRootFile(lockRootPath, 0o600, {
+                const created = createFileLockSyncRootFile(lockRootPath, {
                     assertBeforeOpen: () => {
-                        assertAdmission();
+                        acquisition.assert();
                         if (ownedReclaimGuard)
                             assertOwnedReclaimGuardCurrent();
                         if (currentTargetHolder() !== undefined)
@@ -192,29 +145,11 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                     snapshot,
                 };
                 const returnedHandle = createRootSyncHeldLockHandle(createdHeld);
-                if (options.onCompromised && (options.compromiseCheckIntervalMs ?? 0) > 0) {
-                    const timer = setInterval(() => {
-                        let stillHeld;
-                        try {
-                            stillHeld = returnedHandle.verifyStillHeld();
-                        }
-                        catch {
-                            stillHeld = false;
-                        }
-                        if (!stillHeld && createdHeld.timer) {
-                            clearInterval(createdHeld.timer);
-                            createdHeld.timer = undefined;
-                            Reflect.apply(options.onCompromised, options.optionsReceiver, [{ lockPath, normalizedTargetPath }]);
-                        }
-                    }, options.compromiseCheckIntervalMs);
-                    unpublishedTimer = timer;
-                    createdHeld.timer = timer;
-                    timer.unref();
-                }
+                acquisition.monitor(createdHeld, returnedHandle, options.onCompromised, options.compromiseCheckIntervalMs, options.optionsReceiver, (timer) => { unpublishedTimer = timer; });
                 if (currentTargetHolder() !== undefined) {
                     throw new FileLockSyncRootArbitrationCollision();
                 }
-                assertAdmission();
+                acquisition.assert();
                 heldLocks.set(normalizedTargetPath, createdHeld);
                 fd = undefined;
                 unpublishedTimer = undefined;
@@ -239,12 +174,12 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                     const reused = reuseCurrentHeld();
                     if (reused)
                         return reused;
-                    waitForRetry();
+                    acquisition.waitForRetry();
                     continue;
                 }
                 const fromLockFileOpen = lockFileCreateOpenFailure !== undefined &&
                     lockFileCreateOpenFailure.error === error;
-                if (fromLockFileOpen && retryLockFileDenial(error))
+                if (fromLockFileOpen && acquisition.retryDenial(error))
                     continue;
                 if (!fromLockFileOpen || error.code !== "EEXIST")
                     throw error;
@@ -253,14 +188,14 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                     const reused = reuseCurrentHeld();
                     if (reused)
                         return reused;
-                    waitForRetry();
+                    acquisition.waitForRetry();
                     continue;
                 }
                 if (currentTargetHolder() !== undefined) {
                     const reused = reuseCurrentHeld();
                     if (reused)
                         return reused;
-                    waitForRetry();
+                    acquisition.waitForRetry();
                     continue;
                 }
                 let lockFileOpenDenied = false;
@@ -271,7 +206,7 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                     });
                 }
                 catch (readError) {
-                    if (lockFileOpenDenied && retryLockFileDenial(readError))
+                    if (lockFileOpenDenied && acquisition.retryDenial(readError))
                         continue;
                     throw readError;
                 }
@@ -279,12 +214,12 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                     const reused = reuseCurrentHeld();
                     if (reused)
                         return reused;
-                    waitForRetry();
+                    acquisition.waitForRetry();
                     continue;
                 }
-                assertAdmission();
+                acquisition.assert();
                 if (!current) {
-                    waitForRetry();
+                    acquisition.waitForRetry();
                     continue;
                 }
                 const snapshot = current.snapshot;
@@ -299,7 +234,8 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                             nowMs,
                             heldByThisProcess: false,
                         }]);
-                    assertAdmission();
+                    assertSynchronousCallbackResult(reclaim, "shouldReclaim");
+                    acquisition.assert();
                     if (!fileLockSyncRootSnapshotStillCurrent(lockRootPath, current)) {
                         throw new FsSafeError("path-mismatch", "sidecar changed during reclaim policy callback");
                     }
@@ -313,7 +249,7 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                         options.shouldRemoveStaleLock) {
                         const guard = createFileLockSyncRootDirectory(reclaimRootPath);
                         if (!guard) {
-                            waitForRetry();
+                            acquisition.waitForRetry();
                             continue;
                         }
                         ownedReclaimGuard = guard;
@@ -324,11 +260,12 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                                 raw: snapshot.raw,
                                 payload: snapshot.payload,
                             }]);
-                        assertAdmission();
+                        assertSynchronousCallbackResult(approved, "shouldRemoveStaleLock");
+                        acquisition.assert();
                         assertOwnedReclaimGuardCurrent();
                         if (approved) {
                             const removed = removeFileLockSyncRootFile(lockRootPath, current.receipt, snapshot, () => {
-                                assertAdmission();
+                                acquisition.assert();
                                 assertOwnedReclaimGuardCurrent();
                                 if (currentTargetHolder() !== undefined)
                                     throw new FileLockSyncRootArbitrationCollision();
@@ -349,7 +286,7 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                         normalizedTargetPath,
                     });
                 }
-                waitForRetry();
+                acquisition.waitForRetry();
             }
         }
     }
@@ -365,6 +302,6 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
         throw error;
     }
     finally {
-        releaseAdmission();
+        acquisition.release();
     }
 }

package/dist/file-lock-sync-root-arbitration.d.ts

@@ -15,4 +15,3 @@ export type FileLockSyncRootArbitration = Readonly<{
 }>;
 export declare function tryReuseCurrentRootSyncHeldLock(arbitration: FileLockSyncRootArbitration): FileLockSyncHandle | undefined;
 export declare function cleanupCreatedRootSyncLock(lockRootPath: FileLockSyncRootPath, fd: number, receipt: FileLockSyncRootFileReceipt, timer?: NodeJS.Timeout): void;
-//# sourceMappingURL=file-lock-sync-root-arbitration.d.ts.map

package/dist/file-lock-sync-root-held.d.ts

@@ -28,7 +28,5 @@ export declare function getRootSyncHeldLocks(): Map<string, RootSyncHeldLock>;
 export declare function ensureRootSyncExitCleanupRegistered(): void;
 export declare function verifyRootSyncHeldLock(held: RootSyncHeldLock): boolean;
 export declare function createRootSyncHeldLockHandle(held: RootSyncHeldLock): FileLockSyncHandle;
-export declare function isRootSyncHeldLockHandle(handle: FileLockSyncHandle): boolean;
-export declare function withRootSyncHeldLockHandle<T>(lock: FileLockSyncHandle, fn: () => T): T;
+export declare function withSyncHeldLockHandle<T>(lock: FileLockSyncHandle, fn: () => T): T;
 export {};
-//# sourceMappingURL=file-lock-sync-root-held.d.ts.map

package/dist/file-lock-sync-root-held.js

@@ -223,7 +223,12 @@ export function ensureRootSyncExitCleanupRegistered() {
     ensureFileLockSyncRootExitCleanupRegistered(releaseAllRootSyncHeldLocks);
 }
 export function verifyRootSyncHeldLock(held) {
-    const current = readRootSidecarSnapshotSync(held.rootPath, held.parsePayload, undefined, held.rootReceipt);
+    const rootPath = held.rootPath;
+    const parsePayload = held.parsePayload;
+    const rootReceipt = held.rootReceipt;
+    const current = parsePayload
+        ? readRootSidecarSnapshotSync(rootPath, parsePayload, undefined, rootReceipt)
+        : readFileLockSyncRootSnapshot(rootPath, { expectedReceipt: rootReceipt });
     if (!current)
         return false;
     return current.receipt.identity.dev === held.rootReceipt.identity.dev &&
@@ -369,10 +374,7 @@ export function createRootSyncHeldLockHandle(held) {
     rootSyncHandleDispositions.set(handle, disposition);
     return handle;
 }
-export function isRootSyncHeldLockHandle(handle) {
-    return rootSyncHandleDispositions.has(handle);
-}
-export function withRootSyncHeldLockHandle(lock, fn) {
+export function withSyncHeldLockHandle(lock, fn) {
     let result;
     try {
         result = fn();

package/dist/file-lock-sync-root-io.d.ts

@@ -41,4 +41,3 @@ export declare function readFileLockSyncRootSnapshot(pathAuthority: FileLockSync
 export declare function fileLockSyncRootSnapshotStillCurrent(pathAuthority: FileLockSyncRootPath, observed: FileLockSyncRootSnapshot): boolean;
 export declare function fileReceiptCurrentAfterParentCheck(pathAuthority: FileLockSyncRootPath, receipt: FileLockSyncRootFileReceipt): boolean;
 export declare function fileLockSyncRootReceiptStillCurrent(pathAuthority: FileLockSyncRootPath, receipt: FileLockSyncRootFileReceipt): boolean;
-//# sourceMappingURL=file-lock-sync-root-io.d.ts.map

package/dist/file-lock-sync-root-mutation.d.ts

@@ -1,17 +1,16 @@
 import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
 import { type FileLockSyncRootPath } from "./file-lock-sync-root.js";
 import { type FileLockSyncRootDirectoryReceipt, type FileLockSyncRootFileReceipt } from "./file-lock-sync-root-io.js";
-export declare function createFileLockSyncRootFile(pathAuthority: FileLockSyncRootPath, mode: number, options?: {
-    assertBeforeOpen?: () => void;
-    onOpenFailure?: (error: unknown) => void;
+export declare function createFileLockSyncRootFile(pathAuthority: FileLockSyncRootPath, options: {
+    assertBeforeOpen: () => void;
+    onOpenFailure: (error: unknown) => void;
 }): {
     fd: number;
     receipt: FileLockSyncRootFileReceipt;
 };
 export declare function refreshFileLockSyncRootFileReceipt(pathAuthority: FileLockSyncRootPath, receipt: FileLockSyncRootFileReceipt): FileLockSyncRootFileReceipt;
 export declare function removeFileLockSyncRootFile(pathAuthority: FileLockSyncRootPath, receipt: FileLockSyncRootFileReceipt, expected?: SidecarLockSnapshot, assertBeforeRemove?: () => boolean | void): boolean;
-export declare function fileLockSyncRootGuardExists(pathAuthority: FileLockSyncRootPath, pathAlreadyCurrent?: boolean): boolean;
+export declare function fileLockSyncRootGuardExists(pathAuthority: FileLockSyncRootPath): boolean;
 export declare function createFileLockSyncRootDirectory(pathAuthority: FileLockSyncRootPath): FileLockSyncRootDirectoryReceipt | null;
 export declare function removeFileLockSyncRootDirectory(pathAuthority: FileLockSyncRootPath, receipt: FileLockSyncRootDirectoryReceipt): boolean;
 export declare function fileLockSyncRootDirectoryReceiptStillCurrent(pathAuthority: FileLockSyncRootPath, receipt: FileLockSyncRootDirectoryReceipt): boolean;
-//# sourceMappingURL=file-lock-sync-root-mutation.d.ts.map

package/dist/file-lock-sync-root-mutation.js

@@ -76,7 +76,7 @@ function ensureParent(pathAuthority) {
     assertDirectoryCurrent(currentReceipt);
     return currentReceipt;
 }
-export function createFileLockSyncRootFile(pathAuthority, mode, options = {}) {
+export function createFileLockSyncRootFile(pathAuthority, options) {
     const parent = ensureParent(pathAuthority);
     if (invokeFileLockSyncRootMutationAuthority(pathAuthority.authority)) {
         assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
@@ -88,12 +88,12 @@ export function createFileLockSyncRootFile(pathAuthority, mode, options = {}) {
     let fd;
     let receipt;
     try {
-        options.assertBeforeOpen?.();
+        options.assertBeforeOpen();
         try {
-            fd = fs.openSync(pathForWindowsFilesystem(pathAuthority.path), fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, mode);
+            fd = fs.openSync(pathForWindowsFilesystem(pathAuthority.path), fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, 0o600);
         }
         catch (error) {
-            options.onOpenFailure?.(error);
+            options.onOpenFailure(error);
             throw error;
         }
         const opened = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }));
@@ -193,11 +193,9 @@ export function removeFileLockSyncRootFile(pathAuthority, receipt, expected, ass
     }
     throw new FsSafeError("path-mismatch", "sidecar lock was replaced during removal");
 }
-export function fileLockSyncRootGuardExists(pathAuthority, pathAlreadyCurrent = false) {
-    if (!pathAlreadyCurrent)
-        assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
-    // A shared path admission may skip only duplicate resolution, never this
-    // operation-local Root identity fence before fresh directory inspection.
+export function fileLockSyncRootGuardExists(pathAuthority) {
+    // The caller already admitted this path; every guard observation still needs
+    // an operation-local Root identity fence before fresh directory inspection.
     assertRootIdentityCurrentSync(pathAuthority.authority.context);
     let stat;
     try {

package/dist/file-lock-sync-root-options.d.ts

@@ -17,4 +17,3 @@ type CapturedRootSyncAcquireOptions<TPayload extends Record<string, unknown>> =
 }>;
 export declare function captureRootSyncAcquireOptions<TPayload extends Record<string, unknown>>(options: FileLockSyncAcquireOptions<TPayload>): CapturedRootSyncAcquireOptions<TPayload>;
 export {};
-//# sourceMappingURL=file-lock-sync-root-options.d.ts.map

package/dist/file-lock-sync-root-registration.d.ts

@@ -1,2 +1 @@
 export declare function ensureFileLockSyncRootExitCleanupRegistered(cleanupHandler: () => void): void;
-//# sourceMappingURL=file-lock-sync-root-registration.d.ts.map

package/dist/file-lock-sync-root.d.ts

@@ -30,7 +30,6 @@ type RootPathResolutionPolicy = Readonly<{
 }>;
 export declare function admitFileLockSyncRootPath(authority: FileLockSyncRootAuthority, requestedPath: string): FileLockSyncRootPath;
 export declare function assertFileLockSyncRootResolvedPathCurrent(pathAuthority: FileLockSyncRootPath): void;
-export declare function assertFileLockSyncRootPathsCurrent(paths: readonly FileLockSyncRootPath[], invokeAuthority?: boolean, pathsAlreadyCurrent?: boolean): void;
+export declare function assertFileLockSyncRootPathsCurrent(paths: readonly FileLockSyncRootPath[]): void;
 export declare function normalizeFileLockSyncTargetWithRoot(authority: FileLockSyncRootAuthority, resolvedTargetPath: string): string;
 export {};
-//# sourceMappingURL=file-lock-sync-root.d.ts.map

package/dist/file-lock-sync-root.js

@@ -1,8 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
-import {} from "./deny-mutations.js";
+import { assertMutationNotDenied } from "./deny-mutations.js";
 import { FsSafeError } from "./errors.js";
-import { assertNoNulPathInput, isNotFoundPathError, isPathInside } from "./path.js";
+import { assertNoNulPathInput, isNotFoundPathError } from "./path.js";
 import { resolveRootPathSync } from "./root-path.js";
 import { isRootPathEscapeError } from "./root-path-errors.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
@@ -100,68 +100,8 @@ function absoluteRootPath(authority, relativePath) {
     assertNoWindowsPathAlias(absolute, "filesystem", "sidecar lock path uses a Windows filesystem namespace alias");
     return absolute;
 }
-function assertValidPolicyEntries(entries) {
-    const captured = [];
-    for (const entry of entries ?? []) {
-        if (!entry || !path.isAbsolute(entry)) {
-            throw new FsSafeError("invalid-path", "deny mutation paths must be non-empty absolute paths");
-        }
-        assertNoNulPathInput(entry, "deny mutation path contains a NUL byte");
-        assertNoWindowsPathAlias(entry, "filesystem", "deny mutation path uses a Windows filesystem namespace alias");
-        captured.push(resolvePathPreservingWindowsRoot(entry));
-    }
-    return captured;
-}
-function mutationComparablePaths(pathname) {
-    const resolved = resolvePathPreservingWindowsRoot(pathname);
-    assertNoWindowsPathAlias(resolved, "filesystem", "mutation path uses a Windows filesystem namespace alias");
-    let cursor = resolved;
-    const missing = [];
-    while (path.parse(cursor).root !== cursor) {
-        try {
-            fs.lstatSync(pathForWindowsFilesystem(cursor));
-            break;
-        }
-        catch (error) {
-            if (!isNotFoundPathError(error))
-                throw error;
-            missing.unshift(path.basename(cursor));
-            cursor = path.dirname(cursor);
-        }
-    }
-    // Deny policy is an authority boundary: unlike advisory key normalization,
-    // an ambiguous existing ancestor must not silently fall back to lexical form.
-    const canonicalAncestor = realpathSync.native(pathForWindowsFilesystem(cursor));
-    assertNoWindowsPathAlias(canonicalAncestor, "filesystem", "mutation path uses a Windows filesystem namespace alias");
-    const canonical = missing.length === 0
-        ? canonicalAncestor
-        : path.resolve(canonicalAncestor, ...missing);
-    assertNoWindowsPathAlias(canonical, "filesystem", "mutation path uses a Windows filesystem namespace alias");
-    return samePath(resolved, canonical) ? [resolved] : [resolved, canonical];
-}
 export function assertFileLockSyncRootMutationAllowed(pathname, policy, protectAncestors = false) {
-    if (!policy?.paths?.length && !policy?.prefixes?.length)
-        return;
-    const targets = mutationComparablePaths(pathname);
-    for (const entry of assertValidPolicyEntries(policy.paths)) {
-        for (const denied of mutationComparablePaths(entry)) {
-            for (const target of targets) {
-                if ((isPathInside(denied, target) && isPathInside(target, denied)) ||
-                    (protectAncestors && isPathInside(target, denied))) {
-                    throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
-                }
-            }
-        }
-    }
-    for (const entry of assertValidPolicyEntries(policy.prefixes)) {
-        for (const denied of mutationComparablePaths(entry)) {
-            for (const target of targets) {
-                if (isPathInside(denied, target) || (protectAncestors && isPathInside(target, denied))) {
-                    throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
-                }
-            }
-        }
-    }
+    assertMutationNotDenied(pathname, policy, { protectAncestors }, "sync-root-lock");
 }
 function resolveAdmittedPath(authority, absolutePath, policy, rootPath) {
     const context = authority.context;
@@ -279,24 +219,14 @@ function assertMissingParentMutationsAllowed(pathAuthority) {
             assertFileLockSyncRootMutationAllowed(current, authority.denyMutations);
     }
 }
-export function assertFileLockSyncRootPathsCurrent(paths, invokeAuthority = false, pathsAlreadyCurrent = false) {
+export function assertFileLockSyncRootPathsCurrent(paths) {
     const authority = paths[0]?.authority;
     for (const pathAuthority of paths) {
         if (authority && pathAuthority.authority !== authority) {
             throw new FsSafeError("path-mismatch", "sidecar paths use different Root authority");
         }
     }
-    if (!pathsAlreadyCurrent) {
-        if (authority)
-            assertRootIdentityCurrentSync(authority.context);
-        for (const pathAuthority of paths) {
-            assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
-            assertMissingParentMutationsAllowed(pathAuthority);
-        }
-        if (authority)
-            assertRootIdentityCurrentSync(authority.context);
-    }
-    if (invokeAuthority && authority && invokeFileLockSyncRootMutationAuthority(authority)) {
+    if (authority && invokeFileLockSyncRootMutationAuthority(authority)) {
         assertRootIdentityCurrentSync(authority.context);
         for (const pathAuthority of paths) {
             assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
@@ -309,16 +239,13 @@ function resolveTargetPathViaExistingAncestorSync(targetPath) {
     const normalized = resolvePathPreservingWindowsRoot(targetPath);
     const canonicalize = process.platform === "win32" ? realpathSync.native : realpathSync;
     let cursor = normalized;
-    const missing = [];
+    let canonicalAncestor;
     while (true) {
         try {
             fs.lstatSync(pathForWindowsFilesystem(cursor));
             try {
-                const canonicalAncestor = canonicalize(pathForWindowsFilesystem(cursor));
-                assertNoWindowsPathAlias(canonicalAncestor, "filesystem", "file-lock target ancestor uses a Windows filesystem namespace alias");
-                return missing.length === 0
-                    ? resolvePathPreservingWindowsRoot(canonicalAncestor)
-                    : resolvePathPreservingWindowsRoot(path.resolve(canonicalAncestor, ...missing));
+                canonicalAncestor = canonicalize(pathForWindowsFilesystem(cursor));
+                break;
             }
             catch (error) {
                 if (!isNotFoundPathError(error))
@@ -336,15 +263,15 @@ function resolveTargetPathViaExistingAncestorSync(targetPath) {
         if (parent === cursor) {
             // Filesystem roots are expected to exist; preserve the underlying
             // not-found diagnosis if a synthetic namespace violates that premise.
-            const canonicalAncestor = canonicalize(pathForWindowsFilesystem(cursor));
-            assertNoWindowsPathAlias(canonicalAncestor, "filesystem", "file-lock target ancestor uses a Windows filesystem namespace alias");
-            return missing.length === 0
-                ? resolvePathPreservingWindowsRoot(canonicalAncestor)
-                : resolvePathPreservingWindowsRoot(path.resolve(canonicalAncestor, ...missing));
+            canonicalAncestor = canonicalize(pathForWindowsFilesystem(cursor));
+            break;
         }
-        missing.unshift(path.basename(cursor));
         cursor = parent;
     }
+    assertNoWindowsPathAlias(canonicalAncestor, "filesystem", "file-lock target ancestor uses a Windows filesystem namespace alias");
+    return resolvePathPreservingWindowsRoot(cursor === normalized
+        ? canonicalAncestor
+        : path.resolve(canonicalAncestor, `.${path.sep}${normalized.slice(cursor.length)}`));
 }
 export function normalizeFileLockSyncTargetWithRoot(authority, resolvedTargetPath) {
     assertNoNulPathInput(resolvedTargetPath, "file-lock target contains a NUL byte");

package/dist/file-lock-sync-stale-admission.d.ts

@@ -1,4 +1,5 @@
 import type { FileLockSyncAcquireOptions } from "./file-lock-sync.js";
+import type { SyncLockAcquisition } from "./file-lock-sync-acquisition.js";
 import type { SidecarLockStaleRecovery } from "./sidecar-lock-types.js";
 export type SyncStaleOptionsState<TPayload extends Record<string, unknown>> = {
     shouldReclaimObserved?: boolean;
@@ -7,18 +8,12 @@ export type SyncStaleOptionsState<TPayload extends Record<string, unknown>> = {
     shouldRemove?: FileLockSyncAcquireOptions<TPayload>["shouldRemoveStaleLock"];
 };
 /** Handle one exclusive-create conflict without surrendering canonical admission. */
-export declare function handleSyncStaleAdmission<TPayload extends Record<string, unknown>>(params: {
-    hasToken(): boolean;
+export declare function handleSyncStaleAdmission<TPayload extends Record<string, unknown>>(acquisition: SyncLockAcquisition, params: {
     currentHeld(): unknown;
-    lockPath: string;
-    normalizedTargetPath: string;
     options: FileLockSyncAcquireOptions<TPayload>;
     parsePayload?: (raw: string) => unknown;
     reclaimGuardPath: string;
-    retryLockFileDenial(error: unknown): boolean;
     staleMs: number;
     staleOptions: SyncStaleOptionsState<TPayload>;
     staleRecovery?: SidecarLockStaleRecovery;
-    waitForRetry(): void;
 }): void;
-//# sourceMappingURL=file-lock-sync-stale-admission.d.ts.map