@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/directory-guard.js

@@ -30,6 +30,12 @@ export function assertDirectoryIdentitySync(observedPath, expected) {
     }
 }
 export async function createAsyncDirectoryGuard(dir, options) {
+    return captureDirectoryGuard(dir, "native", options);
+}
+export function createSyncDirectoryGuard(dir) {
+    return captureDirectoryGuard(dir, "normalized");
+}
+function captureDirectoryGuard(dir, mode, options) {
     const operationPath = directoryOperationPath(dir);
     const stat = options?.bigint
         ? inspectDirectoryIdentityAtPathSync(operationPath, undefined, options.initial)
@@ -37,11 +43,17 @@ export async function createAsyncDirectoryGuard(dir, options) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    const realPath = realpathSync.native(operationPath);
+    const realPath = mode === "native" ? realpathSync.native(operationPath) : realpathSync(operationPath);
     assertNoWindowsPathAlias(realPath, "filesystem");
     return { dir, realPath, stat };
 }
 export async function assertAsyncDirectoryGuard(guard) {
+    assertDirectoryGuard(guard, "native");
+}
+export function assertSyncDirectoryGuard(guard) {
+    assertDirectoryGuard(guard, "normalized");
+}
+function assertDirectoryGuard(guard, mode) {
     const dir = guard.dir;
     const operationPath = directoryOperationPath(dir);
     const expectedRealPath = guard.realPath;
@@ -57,71 +69,32 @@ export async function assertAsyncDirectoryGuard(guard) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    if (!sameFileIdentity(stat, expectedIdentity)) {
+    // Native guards check identity first; normalized numeric guards preserve
+    // canonicalization errors before their final identity comparison.
+    if (mode === "native" && !sameFileIdentity(stat, expectedIdentity)) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
-    const realPath = realpathSync.native(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem");
-    if (realPath !== expectedRealPath) {
-        throw new FsSafeError("path-mismatch", "directory changed during operation");
-    }
-}
-export function createSyncDirectoryGuard(dir) {
-    const operationPath = directoryOperationPath(dir);
-    const stat = fsSync.lstatSync(operationPath);
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw directoryComponentNotDirectoryError();
-    }
-    const realPath = realpathSync(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem");
-    return { dir, realPath, stat };
-}
-export function assertSyncDirectoryGuard(guard) {
-    const dir = guard.dir;
-    const operationPath = directoryOperationPath(dir);
-    const expectedRealPath = guard.realPath;
-    assertNoWindowsPathAlias(expectedRealPath, "filesystem");
-    const expectedStat = guard.stat;
-    const expectedIdentity = { dev: expectedStat.dev, ino: expectedStat.ino };
-    const stat = typeof expectedIdentity.dev === "bigint" && typeof expectedIdentity.ino === "bigint"
-        ? inspectDirectoryIdentityAtPathSync(operationPath, { dev: expectedIdentity.dev, ino: expectedIdentity.ino })
-        : fsSync.lstatSync(operationPath);
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-        throw directoryComponentNotDirectoryError();
-    }
-    const realPath = typeof expectedIdentity.ino === "bigint"
+    const realPath = mode === "native" || typeof expectedIdentity.ino === "bigint"
         ? realpathSync.native(operationPath) : realpathSync(operationPath);
     assertNoWindowsPathAlias(realPath, "filesystem");
-    if (!sameFileIdentity(stat, expectedIdentity) || realPath !== expectedRealPath) {
+    if ((mode === "normalized" && !sameFileIdentity(stat, expectedIdentity)) || realPath !== expectedRealPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
 }
 export async function createNearestExistingDirectoryGuard(rootReal, targetPath, options = { bigint: false }) {
-    assertNoWindowsPathAlias(rootReal, "filesystem");
-    assertNoWindowsPathAlias(targetPath, "filesystem");
-    let current = resolvePathPreservingWindowsRoot(targetPath);
-    const root = resolvePathPreservingWindowsRoot(rootReal);
-    while (current !== root) {
-        try {
-            return await createAsyncDirectoryGuard(current, options);
-        }
-        catch (error) {
-            if (!isNotFoundPathError(error)) {
-                throw error;
-            }
-            current = path.dirname(current);
-        }
-    }
-    return await createAsyncDirectoryGuard(root, options);
+    return nearestExistingDirectoryGuard(rootReal, targetPath, "native", options);
 }
 export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
+    return nearestExistingDirectoryGuard(rootReal, targetPath, "normalized");
+}
+function nearestExistingDirectoryGuard(rootReal, targetPath, mode, options) {
     assertNoWindowsPathAlias(rootReal, "filesystem");
     assertNoWindowsPathAlias(targetPath, "filesystem");
     let current = resolvePathPreservingWindowsRoot(targetPath);
     const root = resolvePathPreservingWindowsRoot(rootReal);
     while (current !== root) {
         try {
-            return createSyncDirectoryGuard(current);
+            return captureDirectoryGuard(current, mode, options);
         }
         catch (error) {
             if (!isNotFoundPathError(error)) {
@@ -130,15 +103,11 @@ export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
             current = path.dirname(current);
         }
     }
-    return createSyncDirectoryGuard(root);
+    return captureDirectoryGuard(root, mode, options);
 }
 // Recovery receipts must retain every identity bit, including on Windows.
 export async function inspectDirectoryIdentity(dir, expected) {
-    const operationPath = directoryOperationPath(dir);
-    const expectedIdentity = expected === undefined
-        ? undefined
-        : { dev: expected.dev, ino: expected.ino };
-    return inspectDirectoryIdentityAtPathSync(operationPath, expectedIdentity);
+    return inspectDirectoryIdentitySync(dir, expected);
 }
 function directoryOperationPath(dir) {
     assertNoWindowsPathAlias(dir, "filesystem");

package/dist/directory-mode-node.d.ts

@@ -19,4 +19,3 @@ export declare function pinNodeDirectoryForModeSync(dirPath: string, options?: {
     apply(mode: number, check?: () => void): void;
     close(): void;
 };
-//# sourceMappingURL=directory-mode-node.d.ts.map

package/dist/directory-mode-node.js

@@ -95,7 +95,12 @@ export async function pinNodeDirectoryForMode(dirPath, options = {}) {
         return owner;
     }
     catch (error) {
-        await handle.close();
+        try {
+            await handle.close();
+        }
+        catch {
+            // Preserve the initial admission failure before ownership transfers.
+        }
         throw error;
     }
 }
@@ -193,7 +198,12 @@ export function pinNodeDirectoryForModeSync(dirPath, options = {}) {
         };
     }
     catch (error) {
-        fsSync.closeSync(fd);
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch {
+            // Preserve the initial admission failure before ownership transfers.
+        }
         throw error;
     }
 }

package/dist/directory-mode-owner.d.ts

@@ -18,4 +18,3 @@ export declare function ownDirectoryMode(params: {
     close: () => Promise<void>;
     ignoreChmodError?: boolean;
 }): DirectoryModeOwner;
-//# sourceMappingURL=directory-mode-owner.d.ts.map

package/dist/directory-receipt.d.ts

@@ -21,4 +21,3 @@ export declare function createDirectoryReceiptFromIdentity(pathname: string, rea
 export declare function createDirectoryReceiptSync(directoryPath: string, label: string, canonicalize?: (pathname: string) => string): DirectoryReceipt;
 export declare function assertDirectoryReceiptCurrentSync(receipt: DirectoryReceipt, label: string, canonicalize?: (pathname: string) => string): void;
 export {};
-//# sourceMappingURL=directory-receipt.d.ts.map

package/dist/durability.d.ts

@@ -1,4 +1,4 @@
 export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
-export { isHardlinkFallbackError, publishFileExclusive, type PublishFileExclusiveResult, type PublishFileExclusiveStrategy, type PublishFileExclusiveCleanup, type PublishFileExclusiveDirectorySyncFailure, type PublishFileExclusiveFailureDetails, type PublishFileExclusiveFailurePhase, type PublishFileExclusiveSyncFailurePolicy, } from "./publish-file.js";
+export { isHardlinkFallbackError, publishFileExclusive, type PublishFileExclusiveResult, type PublishFileExclusiveStrategy, } from "./publish-file.js";
+export type { PublishFileExclusiveCleanup, PublishFileExclusiveDirectorySyncFailure, PublishFileExclusiveFailureDetails, PublishFileExclusiveFailurePhase, PublishFileExclusiveSyncFailurePolicy, } from "./publish-file-failure.js";
 export { sha256File, sha256FileSync, type Sha256FileInput, type Sha256FileSyncInput, type Sha256FileOptions, type Sha256FileResult, } from "./file-hash.js";
-//# sourceMappingURL=durability.d.ts.map

package/dist/effective-uid.d.ts

@@ -1,2 +1 @@
 export declare function resolveEffectiveUid(): number;
-//# sourceMappingURL=effective-uid.d.ts.map

package/dist/error-detail.d.ts

@@ -1,3 +1,2 @@
 export declare function formatErrorDetail(value: string): string;
 export declare function shortPath(value: string): string;
-//# sourceMappingURL=error-detail.d.ts.map

package/dist/errors.d.ts

@@ -11,4 +11,3 @@ export declare class FsSafeError extends Error {
         details?: FsSafeErrorDetails;
     });
 }
-//# sourceMappingURL=errors.d.ts.map

package/dist/file-cleanup.d.ts

@@ -17,4 +17,3 @@ export declare function cleanupPinnedFilePath(params: {
     throwOnCleanupError?: boolean;
 }): Promise<OwnedPathCleanupStatus>;
 export {};
-//# sourceMappingURL=file-cleanup.d.ts.map

package/dist/file-contents.d.ts

@@ -3,4 +3,3 @@ export type SameFileContentsOptions = {
 };
 /** Compares borrowed regular files from offset zero without moving or closing either descriptor. */
 export declare function sameFileContentsSync(leftFd: number, rightFd: number, options?: SameFileContentsOptions): boolean;
-//# sourceMappingURL=file-contents.d.ts.map

package/dist/file-handle-transfer.d.ts

@@ -13,4 +13,3 @@ export declare function transferFileHandle(source: FileHandle, target: FileHandl
     sizeHint: number;
     targetPosition?: number;
 }): Promise<number>;
-//# sourceMappingURL=file-handle-transfer.d.ts.map

package/dist/file-hash.d.ts

@@ -14,4 +14,3 @@ export declare function hashFileHandle(handle: FileHandle, native?: NativeBindin
 export declare function sha256File(input: Sha256FileInput, options?: Sha256FileOptions): Promise<Sha256FileResult>;
 /** Hash synchronously from offset zero, retaining ownership and position of a borrowed fd. */
 export declare function sha256FileSync(input: Sha256FileSyncInput, options?: Sha256FileOptions): Sha256FileResult;
-//# sourceMappingURL=file-hash.d.ts.map

package/dist/file-hash.js

@@ -1,3 +1,55 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { createHash } from "node:crypto";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
@@ -7,58 +59,99 @@ import { getNativeBinding } from "./native.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
-export async function hashFileHandle(handle, native = getNativeBinding(), { maxBytes = Infinity, signal } = {}) {
-    signal?.throwIfAborted();
-    const stat = fsSync.fstatSync(handle.fd);
-    if (!stat.isFile()) {
-        throw new FsSafeError("not-file", "SHA-256 input is not a regular file");
+// Idle storage is bounded independently of caller concurrency. A pending read
+// retains its exclusive borrow until the async hasher settles.
+const hashScratchBuffers = [];
+function takeHashScratch(size) {
+    const index = hashScratchBuffers.findIndex((buffer) => buffer.length >= size);
+    return index < 0 ? Buffer.allocUnsafe(size) : hashScratchBuffers.splice(index, 1)[0];
+}
+class HashScratch {
+    #storage;
+    buffer;
+    constructor(size) {
+        this.#storage = takeHashScratch(size);
+        this.buffer = this.#storage.subarray(0, size);
     }
-    if (stat.size > maxBytes) {
-        throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
+    grow(size) {
+        const storage = takeHashScratch(size);
+        this[Symbol.dispose]();
+        this.#storage = storage;
+        return this.buffer = storage.subarray(0, size);
     }
-    if (native) {
-        // A completed N-API task can mask later aborts on the same signal.
-        const nativeSignal = signal ? AbortSignal.any([signal]) : undefined;
-        try {
-            const result = await native.sha256File(handle.fd, Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal);
-            signal?.throwIfAborted();
-            return result;
-        }
-        catch (error) {
-            // N-API settles only after compute stops; never race descriptor cleanup.
-            signal?.throwIfAborted();
-            if (error?.code === "too-large") {
-                throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`, { cause: error });
-            }
-            throw error;
-        }
-        finally {
-            // Node retains composite signals while N-API's abort listener is attached.
-            if (nativeSignal)
-                nativeSignal.onabort = null;
-        }
+    [Symbol.dispose]() {
+        // Clear the used view before retention; a larger unused tail was cleared
+        // by its previous borrower, without making tiny hashes clear large buffers.
+        this.buffer.fill(0);
+        hashScratchBuffers.push(this.#storage);
+        hashScratchBuffers.sort((left, right) => left.length - right.length);
+        if (hashScratchBuffers.length > 4)
+            hashScratchBuffers.shift();
     }
-    const hash = createHash("sha256");
-    let buffer = Buffer.allocUnsafe(Math.min(256 * 1024, Math.max(1, stat.size + 1), maxBytes + 1));
-    let position = 0;
-    while (true) {
-        signal?.throwIfAborted();
-        const length = Math.min(buffer.length, maxBytes - position + 1);
-        const { bytesRead } = await handle.read(buffer, 0, length, position);
+}
+export async function hashFileHandle(handle, native = getNativeBinding(), { maxBytes = Infinity, signal } = {}) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
         signal?.throwIfAborted();
-        if (bytesRead > maxBytes - position) {
+        const stat = fsSync.fstatSync(handle.fd);
+        if (!stat.isFile()) {
+            throw new FsSafeError("not-file", "SHA-256 input is not a regular file");
+        }
+        if (stat.size > maxBytes) {
             throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
         }
-        if (bytesRead === 0) {
-            return { bytes: position, digest: hash.digest("hex") };
+        if (native) {
+            // A completed N-API task can mask later aborts on the same signal.
+            const nativeSignal = signal ? AbortSignal.any([signal]) : undefined;
+            try {
+                const result = await native.sha256File(handle.fd, Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal);
+                signal?.throwIfAborted();
+                return result;
+            }
+            catch (error) {
+                // N-API settles only after compute stops; never race descriptor cleanup.
+                signal?.throwIfAborted();
+                if (error?.code === "too-large") {
+                    throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`, { cause: error });
+                }
+                throw error;
+            }
+            finally {
+                // Node retains composite signals while N-API's abort listener is attached.
+                if (nativeSignal)
+                    nativeSignal.onabort = null;
+            }
         }
-        hash.update(buffer.subarray(0, bytesRead));
-        position += bytesRead;
-        // A full small buffer can mean growth or a virtual file with an unhelpful size.
-        if (bytesRead === buffer.length && buffer.length < 64 * 1024) {
-            buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1));
+        const hash = createHash("sha256");
+        const scratch = __addDisposableResource(env_1, new HashScratch(Math.min(256 * 1024, Math.max(1, stat.size + 1), maxBytes + 1)), false);
+        let buffer = scratch.buffer;
+        let position = 0;
+        while (true) {
+            signal?.throwIfAborted();
+            const length = Math.min(buffer.length, maxBytes - position + 1);
+            const { bytesRead } = await handle.read(buffer, 0, length, position);
+            signal?.throwIfAborted();
+            if (bytesRead > maxBytes - position) {
+                throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
+            }
+            if (bytesRead === 0) {
+                return { bytes: position, digest: hash.digest("hex") };
+            }
+            hash.update(buffer.subarray(0, bytesRead));
+            position += bytesRead;
+            // A full small buffer can mean growth or a virtual file with an unhelpful size.
+            if (bytesRead === buffer.length && buffer.length < 64 * 1024) {
+                buffer = scratch.grow(Math.min(64 * 1024, maxBytes + 1));
+            }
         }
     }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
 }
 function hashPathIdentity(filePath, afterOpen = false) {
     const stat = fsSync.lstatSync(filePath, { bigint: true });
@@ -123,34 +216,45 @@ export async function sha256File(input, options = {}) {
         : await hashFileHandle(input, getNativeBinding(), normalized);
 }
 function hashDescriptorSync(fd, { maxBytes = Infinity, signal }) {
-    signal?.throwIfAborted();
-    const stat = fsSync.fstatSync(fd);
-    if (!stat.isFile()) {
-        throw new FsSafeError("not-file", "SHA-256 input is not a regular file");
-    }
-    if (stat.size > maxBytes) {
-        throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
-    }
-    const hash = createHash("sha256");
-    let buffer = Buffer.allocUnsafe(Math.min(256 * 1024, Math.max(1, stat.size + 1), maxBytes + 1));
-    let position = 0;
-    while (true) {
-        signal?.throwIfAborted();
-        const length = Math.min(buffer.length, maxBytes - position + 1);
-        const bytesRead = fsSync.readSync(fd, buffer, 0, length, position);
+    const env_2 = { stack: [], error: void 0, hasError: false };
+    try {
         signal?.throwIfAborted();
-        if (bytesRead > maxBytes - position) {
-            throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
+        const stat = fsSync.fstatSync(fd);
+        if (!stat.isFile()) {
+            throw new FsSafeError("not-file", "SHA-256 input is not a regular file");
         }
-        if (bytesRead === 0) {
-            return { bytes: position, digest: hash.digest("hex") };
+        if (stat.size > maxBytes) {
+            throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
         }
-        hash.update(buffer.subarray(0, bytesRead));
-        position += bytesRead;
-        if (bytesRead === buffer.length && buffer.length < 64 * 1024) {
-            buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1));
+        const hash = createHash("sha256");
+        const scratch = __addDisposableResource(env_2, new HashScratch(Math.min(256 * 1024, Math.max(1, stat.size + 1), maxBytes + 1)), false);
+        let buffer = scratch.buffer;
+        let position = 0;
+        while (true) {
+            signal?.throwIfAborted();
+            const length = Math.min(buffer.length, maxBytes - position + 1);
+            const bytesRead = fsSync.readSync(fd, buffer, 0, length, position);
+            signal?.throwIfAborted();
+            if (bytesRead > maxBytes - position) {
+                throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
+            }
+            if (bytesRead === 0) {
+                return { bytes: position, digest: hash.digest("hex") };
+            }
+            hash.update(buffer.subarray(0, bytesRead));
+            position += bytesRead;
+            if (bytesRead === buffer.length && buffer.length < 64 * 1024) {
+                buffer = scratch.grow(Math.min(64 * 1024, maxBytes + 1));
+            }
         }
     }
+    catch (e_2) {
+        env_2.error = e_2;
+        env_2.hasError = true;
+    }
+    finally {
+        __disposeResources(env_2);
+    }
 }
 function hashPathSync(filePath, options) {
     assertNoWindowsPathAlias(filePath, "filesystem", "SHA-256 path uses a Windows filesystem namespace alias");

package/dist/file-identity.d.ts

@@ -5,4 +5,3 @@ export type FileIdentityStat = {
 export declare function sha256Hex(data: string | Buffer, encoding?: BufferEncoding): string;
 export declare function sameFileIdentity(left: FileIdentityStat, right: FileIdentityStat, platform?: NodeJS.Platform): boolean;
 export declare function sameFileIdentityForCleanup(left: FileIdentityStat, right: FileIdentityStat, platform?: NodeJS.Platform): boolean;
-//# sourceMappingURL=file-identity.d.ts.map

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

@@ -0,0 +1,22 @@
+import type { FileLockSyncHandle } from "./file-lock-sync.js";
+import type { SidecarLockCompromisedInfo, SidecarLockRetryOptions } from "./sidecar-lock-types.js";
+/** Owns local arbitration and retry state, independently of filesystem authority. */
+export declare class SyncLockAcquisition {
+    #private;
+    readonly lockPath: string;
+    readonly normalizedTargetPath: string;
+    private readonly retry;
+    private readonly timeoutMs;
+    constructor(lockPath: string, normalizedTargetPath: string, retry: SidecarLockRetryOptions, timeoutMs: number | undefined);
+    get owns(): boolean;
+    hasToken(): boolean;
+    assert(): void;
+    reserve(): void;
+    release(): void;
+    run<T>(callback: () => T): T;
+    waitForRetry(): void;
+    retryDenial(error: unknown): boolean;
+    monitor(held: {
+        timer?: NodeJS.Timeout;
+    }, handle: FileLockSyncHandle, callback: ((info: SidecarLockCompromisedInfo) => void) | undefined, interval: number | undefined, receiver: object, recordTimer?: (timer: NodeJS.Timeout) => void): void;
+}

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

@@ -0,0 +1,98 @@
+import { getSyncLockAdmissions } from "./file-lock-sync-admission.js";
+import { isTransientLockFileDenial, maxTransientLockDenials, sidecarLockRetryDelay, sidecarLockTimeout, } from "./sidecar-lock-policy.js";
+import { sleepSync } from "./timing.js";
+/** Owns local arbitration and retry state, independently of filesystem authority. */
+export class SyncLockAcquisition {
+    lockPath;
+    normalizedTargetPath;
+    retry;
+    timeoutMs;
+    #admissions = getSyncLockAdmissions();
+    #token = {};
+    #owns = false;
+    #startedAt = performance.now();
+    #attempt = 0;
+    #transientDenials = 0;
+    constructor(lockPath, normalizedTargetPath, retry, timeoutMs) {
+        this.lockPath = lockPath;
+        this.normalizedTargetPath = normalizedTargetPath;
+        this.retry = retry;
+        this.timeoutMs = timeoutMs;
+    }
+    get owns() { return this.#owns; }
+    hasToken() { return this.#admissions.get(this.normalizedTargetPath) === this.#token; }
+    assert() {
+        if (!this.hasToken())
+            throw sidecarLockTimeout(this.lockPath, this.normalizedTargetPath);
+    }
+    reserve() {
+        if (this.#owns)
+            return;
+        // An existing synchronous owner can finish only after this stack unwinds.
+        if (this.#admissions.has(this.normalizedTargetPath)) {
+            throw sidecarLockTimeout(this.lockPath, this.normalizedTargetPath);
+        }
+        this.#admissions.set(this.normalizedTargetPath, this.#token);
+        this.#owns = true;
+    }
+    release() {
+        if (this.#owns && this.hasToken())
+            this.#admissions.delete(this.normalizedTargetPath);
+        this.#owns = false;
+    }
+    run(callback) {
+        this.assert();
+        try {
+            return callback();
+        }
+        finally {
+            this.assert();
+        }
+    }
+    waitForRetry() {
+        this.release();
+        const delay = sidecarLockRetryDelay(this.retry, this.timeoutMs, performance.now() - this.#startedAt, this.#attempt);
+        if (delay === undefined)
+            throw sidecarLockTimeout(this.lockPath, this.normalizedTargetPath);
+        sleepSync(delay);
+        this.#attempt += 1;
+    }
+    retryDenial(error) {
+        if (!isTransientLockFileDenial(error, this.lockPath) ||
+            ++this.#transientDenials > maxTransientLockDenials)
+            return false;
+        try {
+            this.waitForRetry();
+        }
+        catch (waitError) {
+            // Exhausted backoff must preserve the filesystem denial diagnosis.
+            if (waitError.code === "file_lock_timeout")
+                throw error;
+            throw waitError;
+        }
+        return true;
+    }
+    monitor(held, handle, callback, interval, receiver, recordTimer) {
+        if (!callback || (interval ?? 0) <= 0)
+            return;
+        const { lockPath, normalizedTargetPath } = this;
+        const timer = setInterval(() => {
+            let stillHeld;
+            try {
+                stillHeld = handle.verifyStillHeld();
+            }
+            catch {
+                stillHeld = false;
+            }
+            if (!stillHeld && held.timer) {
+                clearInterval(held.timer);
+                held.timer = undefined;
+                Reflect.apply(callback, receiver, [{ lockPath, normalizedTargetPath }]);
+            }
+        }, interval);
+        // Root cleanup retains a separate provisional receipt before unref can fail.
+        recordTimer?.(timer);
+        held.timer = timer;
+        timer.unref();
+    }
+}

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

@@ -12,8 +12,6 @@ export type SyncHeldLock = {
 export declare function foreignSyncHeldLock(route: "raw" | "root", target: string): object | undefined;
 export declare function getSyncHeldLocks(): Map<string, SyncHeldLock>;
 export declare function getSyncLockAdmissions(): Map<string, object>;
-export declare function syncLockTimeout(lockPath: string, normalizedTargetPath: string): Error;
 export declare function defaultSyncShouldReclaim(snapshot: SidecarLockSnapshot, staleMs: number, nowMs: number): boolean;
 export declare function syncReclaimGuardExists(reclaimGuardPath: string): boolean;
 export declare function ensureSyncLockExitCleanupRegistered(cleanup: () => void, lockPath: string, normalizedTargetPath: string): void;
-//# sourceMappingURL=file-lock-sync-admission.d.ts.map