@openclaw/fs-safe 0.14.0 → 0.15.0

package/dist/file-handle-transfer.js

@@ -1,9 +1,64 @@
+import fs from "node:fs";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult, composeMutationAssertions, rethrowMutationAuthorityError, } from "./mutation-authority.js";
 import { writeAllToFile } from "./write-file-handle.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 const NO_CALLBACK_ARGUMENTS = Object.freeze([]);
+function createTransferBuffer(sizeHint, limit) {
+    return Buffer.allocUnsafe(Math.min(512 * 1024, Math.max(64 * 1024, sizeHint), limit + 1));
+}
+/** Copies caller-owned regular-file descriptors without moving either cursor. */
+export function copyFileDescriptorSync(sourceFd, targetFd, options = {}) {
+    const signal = options.signal;
+    signal?.throwIfAborted();
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const onChunk = options.onChunk;
+    const assertBeforeMutation = options.assertBeforeMutation;
+    const sourceStat = inspectFileIdentitySync(() => {
+        signal?.throwIfAborted();
+        return fs.fstatSync(sourceFd, { bigint: true });
+    });
+    if (!sourceStat.isFile())
+        throw new FsSafeError("not-file", "copy source descriptor must be a regular file");
+    if (maxBytes !== undefined && Number.isFinite(maxBytes) && sourceStat.size > BigInt(maxBytes)) {
+        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`);
+    }
+    const targetStat = inspectFileIdentitySync(() => {
+        signal?.throwIfAborted();
+        return fs.fstatSync(targetFd, { bigint: true });
+    });
+    if (!targetStat.isFile())
+        throw new FsSafeError("not-file", "copy target descriptor must be a regular file");
+    if (sourceStat.dev === targetStat.dev && sourceStat.ino === targetStat.ino) {
+        throw new FsSafeError("path-alias", "copy source and target descriptors refer to the same file");
+    }
+    const limit = maxBytes ?? Infinity;
+    const buffer = createTransferBuffer(Number(sourceStat.size), limit);
+    let position = 0;
+    while (true) {
+        signal?.throwIfAborted();
+        const bytesRead = fs.readSync(sourceFd, buffer, 0, Math.min(buffer.length, limit - position + 1), position);
+        if (bytesRead > limit - position) {
+            throw new FsSafeError("too-large", `file exceeds limit of ${limit} bytes`);
+        }
+        if (bytesRead === 0)
+            return position;
+        const chunk = buffer.subarray(0, bytesRead);
+        assertSynchronousCallbackResult(onChunk?.(chunk), "onChunk");
+        let offset = 0;
+        while (offset < bytesRead) {
+            signal?.throwIfAborted();
+            assertSynchronousCallbackResult(assertBeforeMutation?.(), "assertBeforeMutation");
+            signal?.throwIfAborted();
+            const written = fs.writeSync(targetFd, chunk, offset, bytesRead - offset, position + offset);
+            if (written <= 0)
+                throw new FsSafeError("helper-failed", "file write made no progress");
+            offset += written;
+        }
+        position += bytesRead;
+    }
+}
 function defineReceiverValue(receiver, key, value) {
     Object.defineProperty(receiver, key, {
         value, enumerable: true, writable: true, configurable: true,
@@ -110,7 +165,7 @@ export function transferFileHandle(source, target, options) {
 }
 async function transferFileHandleCore(source, target, sizeHint, maxBytes, targetPosition, signal, onChunk, beforeWrite, callbackThis) {
     const limit = maxBytes ?? Infinity;
-    const buffer = Buffer.allocUnsafe(Math.min(512 * 1024, Math.max(64 * 1024, sizeHint), limit + 1));
+    const buffer = createTransferBuffer(sizeHint, limit);
     let position = 0;
     while (true) {
         signal?.throwIfAborted();

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

@@ -1 +1 @@
-{"version":3,"file":"file-identity.d.ts","sourceRoot":"","sources":["../src/file-identity.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB,CAAC;AAsBF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,MAAM,CAGlF;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAQT;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAWT"}
+{"version":3,"file":"file-identity.d.ts","sourceRoot":"","sources":["../src/file-identity.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB,CAAC;AAsBF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,MAAM,CAGlF;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAQT;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAqBT"}

package/dist/file-identity.js

@@ -23,12 +23,26 @@ export function sameFileIdentity(left, right, platform = process.platform) {
         !isStatValueProvablyDifferent(left.ino, right.ino, platform));
 }
 export function sameFileIdentityForCleanup(left, right, platform = process.platform) {
+    if (platform !== "win32") {
+        return sameStatValue(left.dev, right.dev) && sameStatValue(left.ino, right.ino);
+    }
     // A zero Windows device or inode is unknown, not proof that a pathname still
     // names the object we created. Cleanup must fail closed rather than delete a
     // replacement that happens to share the known half of the identity.
-    if (platform === "win32" &&
-        (isZero(left.dev) || isZero(left.ino) || isZero(right.dev) || isZero(right.ino))) {
+    // Capture each potentially adapter-backed observation once. This strengthens
+    // the fence against changing accessors; exact legacy getter traces are not a
+    // compatibility contract.
+    const leftDev = left.dev;
+    if (isZero(leftDev))
         return false;
-    }
-    return sameStatValue(left.dev, right.dev) && sameStatValue(left.ino, right.ino);
+    const leftIno = left.ino;
+    if (isZero(leftIno))
+        return false;
+    const rightDev = right.dev;
+    if (isZero(rightDev))
+        return false;
+    const rightIno = right.ino;
+    if (isZero(rightIno))
+        return false;
+    return sameStatValue(leftDev, rightDev) && sameStatValue(leftIno, rightIno);
 }

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

@@ -0,0 +1,19 @@
+import type { SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+export type SyncHeldLock = {
+    fd: number | undefined;
+    lockPath: string;
+    normalizedTargetPath: string;
+    parsePayload?: (raw: string) => unknown;
+    refCount: number;
+    reentrantOwner?: string;
+    snapshot: SidecarLockSnapshot;
+    timer?: NodeJS.Timeout;
+};
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-admission.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-admission.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CACxB,CAAC;AAUF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO7F;AAED,wBAAgB,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAQ5D;AAED,wBAAgB,qBAAqB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ3D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,KAAK,CAMrF;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAIT;AAED,wBAAgB,sBAAsB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAQxE;AAED,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,MAAM,IAAI,EACnB,QAAQ,EAAE,MAAM,EAChB,oBAAoB,EAAE,MAAM,GAC3B,IAAI,CAwCN"}

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

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import { sidecarLockPayloadCreatedAtMs } from "./sidecar-lock-policy.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");
+const SYNC_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupHandler");
+const SYNC_CLEANUP_REGISTRATION_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistration");
+const ROOT_SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncRootSidecarLocks.v1");
+export function foreignSyncHeldLock(route, target) {
+    const key = route === "raw" ? ROOT_SYNC_HELD_LOCKS_KEY : SYNC_HELD_LOCKS_KEY;
+    const state = globalThis;
+    return state[key]?.get(target);
+}
+export function getSyncHeldLocks() {
+    const globalWithState = globalThis;
+    if (!globalWithState[SYNC_HELD_LOCKS_KEY]) {
+        globalWithState[SYNC_HELD_LOCKS_KEY] = new Map();
+    }
+    return globalWithState[SYNC_HELD_LOCKS_KEY];
+}
+export function getSyncLockAdmissions() {
+    const globalWithState = globalThis;
+    if (!globalWithState[SYNC_ADMISSIONS_KEY]) {
+        globalWithState[SYNC_ADMISSIONS_KEY] = new Map();
+    }
+    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)
+        return nowMs - createdAtMs > staleMs;
+    return !snapshot.stat || nowMs - snapshot.stat.mtimeMs > staleMs;
+}
+export function syncReclaimGuardExists(reclaimGuardPath) {
+    try {
+        fs.lstatSync(reclaimGuardPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+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];
+        }
+    }
+}

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

@@ -0,0 +1,4 @@
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-root-acquire.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-acquire.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAgD3C,wBAAgB,2BAA2B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClF,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,0BAA0B,CAAC,QAAQ,CAAC,EAClD,QAAQ,EAAE,IAAI,GACb,kBAAkB,CA8VpB"}

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

@@ -0,0 +1,370 @@
+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 { serializeSidecarLockPayload, } from "./sidecar-lock-reclaim.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { sleepSync } from "./timing.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";
+import { fileLockSyncRootSnapshotStillCurrent, } from "./file-lock-sync-root-io.js";
+import { createFileLockSyncRootDirectory, createFileLockSyncRootFile, fileLockSyncRootGuardExists, fileLockSyncRootDirectoryReceiptStillCurrent, refreshFileLockSyncRootFileReceipt, removeFileLockSyncRootDirectory, removeFileLockSyncRootFile, } from "./file-lock-sync-root-mutation.js";
+import { createRootSyncHeldLockHandle, ensureRootSyncExitCleanupRegistered, getRootSyncHeldLocks, readRootSidecarSnapshotSync, } from "./file-lock-sync-root-held.js";
+export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot) {
+    // The public dispatcher already read lockRoot exactly once. Validate and
+    // snapshot that genuine Root before any remaining option or retry getter can
+    // mutate its defaults or retained policy inputs.
+    const authority = captureFileLockSyncRootAuthority(lockRoot);
+    const options = captureRootSyncAcquireOptions(inputOptions);
+    ensureRootSyncExitCleanupRegistered();
+    assertNoWindowsPathAlias(targetPath);
+    if (options.lockPath !== undefined)
+        assertNoWindowsPathAlias(options.lockPath);
+    const resolvedTargetPath = path.resolve(targetPath);
+    const normalizedTargetPath = normalizeFileLockSyncTargetWithRoot(authority, resolvedTargetPath);
+    const requestedLockPath = path.resolve(options.lockPath ?? `${normalizedTargetPath}.lock`);
+    const lockRootPath = admitFileLockSyncRootPath(authority, requestedLockPath);
+    // A followed final alias and its admitted canonical spelling name the same
+    // sidecar. Derive their arbitration guard from that shared admitted path,
+    // then independently admit the derived mutation target under Root policy.
+    const reclaimRootPath = admitFileLockSyncRootPath(authority, `${lockRootPath.path}.reclaim`);
+    const guardedPaths = Object.freeze([lockRootPath, reclaimRootPath]);
+    const lockPath = lockRootPath.path;
+    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,
+        lockRootPath,
+        normalizedTargetPath,
+        reentrantOwner: options.reentrantOwner,
+    });
+    if (heldLocks.has(normalizedTargetPath) && !foreignSyncHeldLock("root", normalizedTargetPath)) {
+        assertFileLockSyncRootPathsCurrent(guardedPaths, true, true);
+        const initiallyReusable = tryReuseCurrentRootSyncHeldLock(arbitration);
+        if (initiallyReusable)
+            return initiallyReusable;
+    }
+    const startedAt = Date.now();
+    let attempt = 0;
+    let transientDenials = 0;
+    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)
+            return;
+        reclaimCleanupAttempted = true;
+        if (!removeFileLockSyncRootDirectory(reclaimRootPath, receipt)) {
+            throw new FsSafeError("path-mismatch", "owned sidecar reclaim guard changed before release");
+        }
+        ownedReclaimGuard = undefined;
+        reclaimCleanupAttempted = false;
+    };
+    const assertOwnedReclaimGuardCurrent = () => {
+        const receipt = ownedReclaimGuard;
+        if (!receipt || !fileLockSyncRootDirectoryReceiptStillCurrent(reclaimRootPath, receipt)) {
+            throw new FsSafeError("path-mismatch", "owned sidecar reclaim guard changed during acquisition");
+        }
+    };
+    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();
+            if (ownedReclaimGuard)
+                assertOwnedReclaimGuardCurrent();
+            if (!ownedReclaimGuard && fileLockSyncRootGuardExists(reclaimRootPath, true)) {
+                waitForRetry();
+                continue;
+            }
+            if (currentTargetHolder() !== undefined) {
+                const reused = reuseCurrentHeld();
+                if (reused)
+                    return reused;
+            }
+            const payload = Reflect.apply(options.payload, options.optionsReceiver, []);
+            assertAdmission();
+            const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
+            assertAdmission();
+            if (ownedReclaimGuard)
+                assertOwnedReclaimGuardCurrent();
+            if (currentTargetHolder() !== undefined) {
+                const reused = reuseCurrentHeld();
+                if (reused)
+                    return reused;
+                waitForRetry();
+                continue;
+            }
+            let fd;
+            let rootReceipt;
+            let unpublishedTimer;
+            let lockFileCreateOpenFailure;
+            try {
+                const created = createFileLockSyncRootFile(lockRootPath, 0o600, {
+                    assertBeforeOpen: () => {
+                        assertAdmission();
+                        if (ownedReclaimGuard)
+                            assertOwnedReclaimGuardCurrent();
+                        if (currentTargetHolder() !== undefined)
+                            throw new FileLockSyncRootArbitrationCollision();
+                    },
+                    onOpenFailure: (error) => {
+                        lockFileCreateOpenFailure = { error };
+                    },
+                });
+                fd = created.fd;
+                rootReceipt = created.receipt;
+                fs.writeFileSync(fd, raw, "utf8");
+                fs.fsyncSync(fd);
+                const snapshot = {
+                    raw,
+                    payload,
+                    ownershipToken,
+                };
+                if (ownedReclaimGuard)
+                    releaseReclaimGuard();
+                rootReceipt = refreshFileLockSyncRootFileReceipt(lockRootPath, rootReceipt);
+                const createdHeld = {
+                    fd,
+                    lockPath,
+                    normalizedTargetPath,
+                    parsePayload: options.parsePayload,
+                    refCount: 1,
+                    reentrantOwner: options.reentrantOwner,
+                    releaseState: "active",
+                    revision: 0,
+                    rootAuthority: authority,
+                    rootPath: lockRootPath,
+                    rootReceipt,
+                    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();
+                }
+                if (currentTargetHolder() !== undefined) {
+                    throw new FileLockSyncRootArbitrationCollision();
+                }
+                assertAdmission();
+                heldLocks.set(normalizedTargetPath, createdHeld);
+                fd = undefined;
+                unpublishedTimer = undefined;
+                return returnedHandle;
+            }
+            catch (error) {
+                if (fd !== undefined && rootReceipt) {
+                    const cleanupFd = fd;
+                    const cleanupReceipt = rootReceipt;
+                    const cleanupTimer = unpublishedTimer;
+                    fd = undefined;
+                    rootReceipt = undefined;
+                    unpublishedTimer = undefined;
+                    try {
+                        cleanupCreatedRootSyncLock(lockRootPath, cleanupFd, cleanupReceipt, cleanupTimer);
+                    }
+                    catch (cleanupError) {
+                        throw createSuppressedError(error, cleanupError, "file lock acquisition and Root cleanup both failed");
+                    }
+                }
+                if (error instanceof FileLockSyncRootArbitrationCollision) {
+                    const reused = reuseCurrentHeld();
+                    if (reused)
+                        return reused;
+                    waitForRetry();
+                    continue;
+                }
+                const fromLockFileOpen = lockFileCreateOpenFailure !== undefined &&
+                    lockFileCreateOpenFailure.error === error;
+                if (fromLockFileOpen && retryLockFileDenial(error))
+                    continue;
+                if (!fromLockFileOpen || error.code !== "EEXIST")
+                    throw error;
+                if (ownedReclaimGuard) {
+                    releaseReclaimGuard();
+                    const reused = reuseCurrentHeld();
+                    if (reused)
+                        return reused;
+                    waitForRetry();
+                    continue;
+                }
+                if (currentTargetHolder() !== undefined) {
+                    const reused = reuseCurrentHeld();
+                    if (reused)
+                        return reused;
+                    waitForRetry();
+                    continue;
+                }
+                let lockFileOpenDenied = false;
+                let current;
+                try {
+                    current = readRootSidecarSnapshotSync(lockRootPath, options.parsePayload, (openError) => {
+                        lockFileOpenDenied = isTransientLockFileDenial(openError, lockPath);
+                    });
+                }
+                catch (readError) {
+                    if (lockFileOpenDenied && retryLockFileDenial(readError))
+                        continue;
+                    throw readError;
+                }
+                if (currentTargetHolder() !== undefined) {
+                    const reused = reuseCurrentHeld();
+                    if (reused)
+                        return reused;
+                    waitForRetry();
+                    continue;
+                }
+                assertAdmission();
+                if (!current) {
+                    waitForRetry();
+                    continue;
+                }
+                const snapshot = current.snapshot;
+                const nowMs = Date.now();
+                let reclaim;
+                if (options.shouldReclaim) {
+                    reclaim = Reflect.apply(options.shouldReclaim, options.optionsReceiver, [{
+                            lockPath,
+                            normalizedTargetPath,
+                            payload: snapshot.payload,
+                            staleMs: options.staleMs,
+                            nowMs,
+                            heldByThisProcess: false,
+                        }]);
+                    assertAdmission();
+                    if (!fileLockSyncRootSnapshotStillCurrent(lockRootPath, current)) {
+                        throw new FsSafeError("path-mismatch", "sidecar changed during reclaim policy callback");
+                    }
+                }
+                else {
+                    reclaim = defaultSyncShouldReclaim(snapshot, options.staleMs, nowMs);
+                }
+                if (reclaim) {
+                    if (options.staleRecovery === "remove-if-unchanged" &&
+                        snapshot.raw !== undefined &&
+                        options.shouldRemoveStaleLock) {
+                        const guard = createFileLockSyncRootDirectory(reclaimRootPath);
+                        if (!guard) {
+                            waitForRetry();
+                            continue;
+                        }
+                        ownedReclaimGuard = guard;
+                        reclaimCleanupAttempted = false;
+                        const approved = Reflect.apply(options.shouldRemoveStaleLock, options.optionsReceiver, [{
+                                lockPath,
+                                normalizedTargetPath,
+                                raw: snapshot.raw,
+                                payload: snapshot.payload,
+                            }]);
+                        assertAdmission();
+                        assertOwnedReclaimGuardCurrent();
+                        if (approved) {
+                            const removed = removeFileLockSyncRootFile(lockRootPath, current.receipt, snapshot, () => {
+                                assertAdmission();
+                                assertOwnedReclaimGuardCurrent();
+                                if (currentTargetHolder() !== undefined)
+                                    throw new FileLockSyncRootArbitrationCollision();
+                            });
+                            if (!removed) {
+                                throw new FsSafeError("path-mismatch", "stale sidecar changed before removal");
+                            }
+                            continue;
+                        }
+                        if (!fileLockSyncRootSnapshotStillCurrent(lockRootPath, current)) {
+                            throw new FsSafeError("path-mismatch", "sidecar changed during stale-removal policy callback");
+                        }
+                        releaseReclaimGuard();
+                    }
+                    throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+                        code: "file_lock_stale",
+                        lockPath,
+                        normalizedTargetPath,
+                    });
+                }
+                waitForRetry();
+            }
+        }
+    }
+    catch (error) {
+        if (ownedReclaimGuard && !reclaimCleanupAttempted) {
+            try {
+                releaseReclaimGuard();
+            }
+            catch (cleanupError) {
+                throw createSuppressedError(error, cleanupError, "file lock acquisition and reclaim cleanup both failed");
+            }
+        }
+        throw error;
+    }
+    finally {
+        releaseAdmission();
+    }
+}

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

@@ -0,0 +1,18 @@
+import { FsSafeError } from "./errors.js";
+import type { FileLockSyncHandle } from "./file-lock-sync.js";
+import { type FileLockSyncRootAuthority, type FileLockSyncRootPath } from "./file-lock-sync-root.js";
+import type { FileLockSyncRootFileReceipt } from "./file-lock-sync-root-io.js";
+import { type RootSyncHeldLock } from "./file-lock-sync-root-held.js";
+export declare class FileLockSyncRootArbitrationCollision extends FsSafeError {
+    constructor();
+}
+export type FileLockSyncRootArbitration = Readonly<{
+    authority: FileLockSyncRootAuthority;
+    heldLocks: Map<string, RootSyncHeldLock>;
+    lockRootPath: FileLockSyncRootPath;
+    normalizedTargetPath: string;
+    reentrantOwner?: string;
+}>;
+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-arbitration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-root-arbitration.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-arbitration.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAG/E,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,+BAA+B,CAAC;AAEvC,qBAAa,oCAAqC,SAAQ,WAAW;IACnE,cAEC;CACF;AAED,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IACjD,SAAS,EAAE,yBAAyB,CAAC;IACrC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACzC,YAAY,EAAE,oBAAoB,CAAC;IACnC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC,CAAC;AAMH,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,2BAA2B,GACvC,kBAAkB,GAAG,SAAS,CAsBhC;AAED,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,oBAAoB,EAClC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,2BAA2B,EACpC,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,GACrB,IAAI,CAyBN"}