@openclaw/fs-safe 0.17.0 → 0.18.1

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

@@ -1,5 +1,6 @@
 import fs from "node:fs";
-import { sidecarLockPayloadCreatedAtMs } from "./sidecar-lock-policy.js";
+import { sidecarLockPayloadCreatedAtMs, sidecarLockTimeout } from "./sidecar-lock-policy.js";
+import { ensureSidecarLockCleanupRegistered } from "./sidecar-lock-registration.js";
 const SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncSidecarLocks");
 const SYNC_ADMISSIONS_KEY = Symbol.for("fsSafe.syncSidecarLockAdmissions");
 const SYNC_CLEANUP_REGISTERED_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistered");
@@ -25,13 +26,6 @@ export function getSyncLockAdmissions() {
     }
     return globalWithState[SYNC_ADMISSIONS_KEY];
 }
-export function syncLockTimeout(lockPath, normalizedTargetPath) {
-    return Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
-        code: "file_lock_timeout",
-        lockPath,
-        normalizedTargetPath,
-    });
-}
 export function defaultSyncShouldReclaim(snapshot, staleMs, nowMs) {
     const createdAtMs = sidecarLockPayloadCreatedAtMs(snapshot.payload);
     if (createdAtMs !== null)
@@ -50,44 +44,11 @@ export function syncReclaimGuardExists(reclaimGuardPath) {
     }
 }
 export function ensureSyncLockExitCleanupRegistered(cleanup, lockPath, normalizedTargetPath) {
-    const globalWithCleanup = globalThis;
-    if (globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY])
-        return;
-    if (globalWithCleanup[SYNC_CLEANUP_REGISTRATION_KEY]) {
-        // process.on() emits newListener synchronously. A nested synchronous
-        // acquisition cannot wait for this stack to finish registering.
-        throw syncLockTimeout(lockPath, normalizedTargetPath);
-    }
-    const registration = {};
-    globalWithCleanup[SYNC_CLEANUP_REGISTRATION_KEY] = registration;
-    try {
-        process.on("exit", cleanup);
-        globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY] = cleanup;
-        globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY] = true;
-    }
-    catch (error) {
-        if (process.listeners("exit").includes(cleanup)) {
-            try {
-                process.off("exit", cleanup);
-            }
-            catch {
-                // Reconcile the marker with the actual listener below.
-            }
-        }
-        if (process.listeners("exit").includes(cleanup)) {
-            globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY] = cleanup;
-            globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY] = true;
-        }
-        else {
-            if (globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY] === cleanup) {
-                delete globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY];
-            }
-        }
-        throw error;
-    }
-    finally {
-        if (globalWithCleanup[SYNC_CLEANUP_REGISTRATION_KEY] === registration) {
-            delete globalWithCleanup[SYNC_CLEANUP_REGISTRATION_KEY];
-        }
-    }
+    ensureSidecarLockCleanupRegistered({
+        event: "exit",
+        registered: SYNC_CLEANUP_REGISTERED_KEY,
+        registering: SYNC_CLEANUP_REGISTRATION_KEY,
+        handler: SYNC_CLEANUP_HANDLER_KEY,
+        reentryError: () => sidecarLockTimeout(lockPath, normalizedTargetPath),
+    }, cleanup, true);
 }

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

@@ -1,4 +1,3 @@
 import type { FileLockSyncAcquireOptions, FileLockSyncHandle } from "./file-lock-sync.js";
 import type { Root } from "./root-impl.js";
 export declare function acquireFileLockSyncWithRoot<TPayload extends Record<string, unknown>>(targetPath: string, inputOptions: FileLockSyncAcquireOptions<TPayload>, lockRoot: Root): FileLockSyncHandle;
-//# sourceMappingURL=file-lock-sync-root-acquire.d.ts.map

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

@@ -2,11 +2,11 @@ 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, sidecarLockStale } 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";
@@ -37,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,
@@ -59,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)
@@ -116,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) {
@@ -137,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;
@@ -154,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)
@@ -193,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;
@@ -240,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;
@@ -254,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;
@@ -272,7 +206,7 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                     });
                 }
                 catch (readError) {
-                    if (lockFileOpenDenied && retryLockFileDenial(readError))
+                    if (lockFileOpenDenied && acquisition.retryDenial(readError))
                         continue;
                     throw readError;
                 }
@@ -280,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;
@@ -301,7 +235,7 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                             heldByThisProcess: false,
                         }]);
                     assertSynchronousCallbackResult(reclaim, "shouldReclaim");
-                    assertAdmission();
+                    acquisition.assert();
                     if (!fileLockSyncRootSnapshotStillCurrent(lockRootPath, current)) {
                         throw new FsSafeError("path-mismatch", "sidecar changed during reclaim policy callback");
                     }
@@ -315,7 +249,7 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                         options.shouldRemoveStaleLock) {
                         const guard = createFileLockSyncRootDirectory(reclaimRootPath);
                         if (!guard) {
-                            waitForRetry();
+                            acquisition.waitForRetry();
                             continue;
                         }
                         ownedReclaimGuard = guard;
@@ -327,11 +261,11 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                                 payload: snapshot.payload,
                             }]);
                         assertSynchronousCallbackResult(approved, "shouldRemoveStaleLock");
-                        assertAdmission();
+                        acquisition.assert();
                         assertOwnedReclaimGuardCurrent();
                         if (approved) {
                             const removed = removeFileLockSyncRootFile(lockRootPath, current.receipt, snapshot, () => {
-                                assertAdmission();
+                                acquisition.assert();
                                 assertOwnedReclaimGuardCurrent();
                                 if (currentTargetHolder() !== undefined)
                                     throw new FileLockSyncRootArbitrationCollision();
@@ -346,13 +280,9 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                         }
                         releaseReclaimGuard();
                     }
-                    throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-                        code: "file_lock_stale",
-                        lockPath,
-                        normalizedTargetPath,
-                    });
+                    throw sidecarLockStale(lockPath, normalizedTargetPath);
                 }
-                waitForRetry();
+                acquisition.waitForRetry();
             }
         }
     }
@@ -368,6 +298,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

@@ -30,4 +30,3 @@ export declare function verifyRootSyncHeldLock(held: RootSyncHeldLock): boolean;
 export declare function createRootSyncHeldLockHandle(held: RootSyncHeldLock): FileLockSyncHandle;
 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-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

@@ -1,5 +1,6 @@
 import { type RootContext } from "./root-context.js";
-import type { Root, RootDefaults } from "./root-impl.js";
+import type { Root } from "./root-impl.js";
+import type { RootDefaults } from "./root-options.js";
 /** @internal Registers only instances constructed by RootHandle itself. */
 export declare function registerFileLockSyncRootAdapter(handle: object, context: RootContext, defaults: RootDefaults): void;
 export type FileLockSyncRootAuthority = Readonly<{
@@ -30,7 +31,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