@openclaw/fs-safe 0.13.1 → 0.15.0

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

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import { foreignSyncHeldLock } from "./file-lock-sync-admission.js";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import {} from "./file-lock-sync-root.js";
+import { removeFileLockSyncRootFile } from "./file-lock-sync-root-mutation.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { createRootSyncHeldLockHandle, verifyRootSyncHeldLock, } from "./file-lock-sync-root-held.js";
+export class FileLockSyncRootArbitrationCollision extends FsSafeError {
+    constructor() {
+        super("path-mismatch", "file lock arbitration changed during local creation");
+    }
+}
+function sameRootLockPath(left, right) {
+    return left.relativePath === right.relativePath && path.relative(left.path, right.path) === "";
+}
+export function tryReuseCurrentRootSyncHeldLock(arbitration) {
+    const held = arbitration.heldLocks.get(arbitration.normalizedTargetPath);
+    const reusable = held && !foreignSyncHeldLock("root", arbitration.normalizedTargetPath) &&
+        arbitration.reentrantOwner !== undefined &&
+        held.reentrantOwner !== undefined &&
+        arbitration.reentrantOwner === held.reentrantOwner &&
+        arbitration.authority.adapter === held.rootAuthority.adapter &&
+        sameRootLockPath(arbitration.lockRootPath, held.rootPath) &&
+        held.releaseState !== "released";
+    if (!reusable)
+        return undefined;
+    if (!verifyRootSyncHeldLock(held)) {
+        throw new FsSafeError("path-mismatch", "held sidecar lock changed before reentrant reuse");
+    }
+    // Verification can invoke a custom parser. Re-fetch the exact entry before
+    // granting a reference, while retaining supported releasing/exit states.
+    if (arbitration.heldLocks.get(arbitration.normalizedTargetPath) !== held ||
+        held.releaseState === "released" || foreignSyncHeldLock("root", arbitration.normalizedTargetPath)) {
+        throw new FsSafeError("path-mismatch", "held sidecar lock changed during reentrant reuse");
+    }
+    held.refCount += 1;
+    held.revision += 1;
+    return createRootSyncHeldLockHandle(held);
+}
+export function cleanupCreatedRootSyncLock(lockRootPath, fd, receipt, timer) {
+    let timerCleanupFailed = false;
+    let timerCleanupError;
+    try {
+        if (timer)
+            clearInterval(timer);
+    }
+    catch (error) {
+        timerCleanupFailed = true;
+        timerCleanupError = error;
+    }
+    try {
+        fs.closeSync(fd);
+        if (!removeFileLockSyncRootFile(lockRootPath, receipt)) {
+            throw new FsSafeError("path-mismatch", "created sidecar lock changed before cleanup");
+        }
+    }
+    catch (fileCleanupError) {
+        if (timerCleanupFailed) {
+            throw createSuppressedError(timerCleanupError, fileCleanupError, "unpublished lock timer and file cleanup both failed");
+        }
+        throw fileCleanupError;
+    }
+    if (timerCleanupFailed)
+        throw timerCleanupError;
+}

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

@@ -0,0 +1,34 @@
+import type { FileLockSyncHandle } from "./file-lock-sync.js";
+import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+import { type FileLockSyncRootAuthority, type FileLockSyncRootPath } from "./file-lock-sync-root.js";
+import { type FileLockSyncRootFileReceipt, type FileLockSyncRootSnapshot } from "./file-lock-sync-root-io.js";
+type RootSyncHeldLockReleaseState = "active" | "releasing" | "exit-cleaning" | "released";
+type RootSyncHeldLockHandleDisposition = {
+    held: RootSyncHeldLock;
+    released: boolean;
+};
+export type RootSyncHeldLock = {
+    deferredExitReleases?: Set<RootSyncHeldLockHandleDisposition>;
+    fd: number | undefined;
+    lockPath: string;
+    normalizedTargetPath: string;
+    parsePayload?: (raw: string) => unknown;
+    refCount: number;
+    reentrantOwner?: string;
+    releaseState: RootSyncHeldLockReleaseState;
+    revision: number;
+    rootAuthority: FileLockSyncRootAuthority;
+    rootPath: FileLockSyncRootPath;
+    rootReceipt: FileLockSyncRootFileReceipt;
+    snapshot: SidecarLockSnapshot;
+    timer?: NodeJS.Timeout;
+};
+export declare function readRootSidecarSnapshotSync(rootPath: FileLockSyncRootPath, parsePayload?: (raw: string) => unknown, onOpenFailure?: (error: unknown) => void, expectedReceipt?: FileLockSyncRootFileReceipt): FileLockSyncRootSnapshot | null;
+export declare function getRootSyncHeldLocks(): Map<string, RootSyncHeldLock>;
+export declare function ensureRootSyncExitCleanupRegistered(): void;
+export declare function verifyRootSyncHeldLock(held: RootSyncHeldLock): boolean;
+export declare function createRootSyncHeldLockHandle(held: RootSyncHeldLock): FileLockSyncHandle;
+export declare function isRootSyncHeldLockHandle(handle: FileLockSyncHandle): boolean;
+export declare function withRootSyncHeldLockHandle<T>(lock: FileLockSyncHandle, fn: () => T): T;
+export {};
+//# sourceMappingURL=file-lock-sync-root-held.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-root-held.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-held.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAIL,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC9B,MAAM,6BAA6B,CAAC;AAQrC,KAAK,4BAA4B,GAAG,QAAQ,GAAG,WAAW,GAAG,eAAe,GAAG,UAAU,CAAC;AAE1F,KAAK,iCAAiC,GAAG;IACvC,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAOF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oBAAoB,CAAC,EAAE,GAAG,CAAC,iCAAiC,CAAC,CAAC;IAC9D,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,YAAY,EAAE,4BAA4B,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,yBAAyB,CAAC;IACzC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,WAAW,EAAE,2BAA2B,CAAC;IACzC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CACxB,CAAC;AAQF,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,oBAAoB,EAC9B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,EACvC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EACxC,eAAe,CAAC,EAAE,2BAA2B,GAC5C,wBAAwB,GAAG,IAAI,CAmCjC;AAED,wBAAgB,oBAAoB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAQpE;AA+KD,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAWtE;AAsHD,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,CAqBvF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAE5E;AAED,wBAAgB,0BAA0B,CAAC,CAAC,EAC1C,IAAI,EAAE,kBAAkB,EACxB,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAoBH"}

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

@@ -0,0 +1,393 @@
+import fs from "node:fs";
+import { getSyncLockAdmissions } from "./file-lock-sync-admission.js";
+import { FsSafeError } from "./errors.js";
+import { parseSidecarLockPayload, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import {} from "./file-lock-sync-root.js";
+import { fileLockSyncRootReceiptStillCurrent, fileLockSyncRootSnapshotStillCurrent, readFileLockSyncRootSnapshot, } from "./file-lock-sync-root-io.js";
+import { removeFileLockSyncRootFile } from "./file-lock-sync-root-mutation.js";
+import { ensureFileLockSyncRootExitCleanupRegistered } from "./file-lock-sync-root-registration.js";
+const ROOT_SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncRootSidecarLocks.v1");
+const ROOT_SYNC_CLEANUP_ACTIVE_KEY = Symbol.for("fsSafe.syncRootSidecarLockCleanupActive.v1");
+const MAX_CONTINUITY_CLEANUP_ATTEMPTS = 2;
+const rootSyncHandleDispositions = new WeakMap();
+function readRootSyncHeldReleaseState(held) {
+    return held.releaseState;
+}
+export function readRootSidecarSnapshotSync(rootPath, parsePayload, onOpenFailure, expectedReceipt) {
+    const rawSnapshot = readFileLockSyncRootSnapshot(rootPath, {
+        expectedReceipt,
+        onOpenFailure,
+    });
+    if (!rawSnapshot)
+        return null;
+    let parsedPayload;
+    try {
+        parsedPayload = parseSidecarLockPayload(rawSnapshot.snapshot.raw, parsePayload);
+    }
+    catch (parseError) {
+        if (parsePayload) {
+            try {
+                if (!fileLockSyncRootSnapshotStillCurrent(rootPath, rawSnapshot)) {
+                    throw new FsSafeError("path-mismatch", "sidecar changed during payload parsing");
+                }
+            }
+            catch (admissionError) {
+                throw createSuppressedError(parseError, admissionError, "sidecar parser and post-callback admission both failed");
+            }
+        }
+        throw parseError;
+    }
+    if (parsePayload && !fileLockSyncRootSnapshotStillCurrent(rootPath, rawSnapshot)) {
+        return null;
+    }
+    return {
+        receipt: rawSnapshot.receipt,
+        snapshot: { ...rawSnapshot.snapshot, payload: parsedPayload },
+    };
+}
+export function getRootSyncHeldLocks() {
+    const globalWithState = globalThis;
+    if (!globalWithState[ROOT_SYNC_HELD_LOCKS_KEY]) {
+        globalWithState[ROOT_SYNC_HELD_LOCKS_KEY] = new Map();
+    }
+    return globalWithState[ROOT_SYNC_HELD_LOCKS_KEY];
+}
+function existingRootSyncHeldLocks() {
+    return globalThis[ROOT_SYNC_HELD_LOCKS_KEY];
+}
+function reactivateExactHeldLock(heldLocks, held, restoreConsumedReference) {
+    if (heldLocks.get(held.normalizedTargetPath) !== held || held.releaseState === "released") {
+        return false;
+    }
+    if (restoreConsumedReference)
+        held.refCount += 1;
+    held.releaseState = "active";
+    held.revision += 1;
+    return true;
+}
+function finishDeferredExitReleases(held) {
+    const deferred = held.deferredExitReleases;
+    if (!deferred)
+        return;
+    for (const disposition of deferred)
+        disposition.released = true;
+    deferred.clear();
+    held.deferredExitReleases = undefined;
+}
+function restoreDeferredExitReleases(held) {
+    const deferred = held.deferredExitReleases;
+    if (!deferred)
+        return 0;
+    const restored = deferred.size;
+    deferred.clear();
+    held.deferredExitReleases = undefined;
+    return restored;
+}
+function settleDeferredExitRelease(lock) {
+    const disposition = rootSyncHandleDispositions.get(lock);
+    if (!disposition || disposition.released)
+        return;
+    const deferred = disposition.held.deferredExitReleases;
+    // Scoped disposal may surrender only its own reference, after release has
+    // proven that exact handle token was tentatively consumed by exit cleanup.
+    if (!deferred?.delete(disposition))
+        return;
+    if (deferred.size === 0)
+        disposition.held.deferredExitReleases = undefined;
+    disposition.released = true;
+}
+function restoreExactHeldLockAfterExitCleanup(heldLocks, held) {
+    if (heldLocks.get(held.normalizedTargetPath) !== held || held.releaseState === "released")
+        return;
+    // Restore exactly the handle references tentatively consumed by exit
+    // callbacks. A retained successor is a distinct reference and must not be
+    // borrowed by a pending original handle.
+    held.refCount += restoreDeferredExitReleases(held);
+    if (held.refCount <= 0) {
+        // No tracked handle can retry. Drop only the record; the sidecar itself is
+        // deliberately left in place for policy-governed reclamation.
+        held.releaseState = "released";
+        held.revision += 1;
+        heldLocks.delete(held.normalizedTargetPath);
+        return;
+    }
+    held.releaseState = "active";
+    held.revision += 1;
+}
+function releaseAllRootSyncHeldLocks() {
+    const globalWithCleanup = globalThis;
+    if (globalWithCleanup[ROOT_SYNC_CLEANUP_ACTIVE_KEY])
+        return;
+    globalWithCleanup[ROOT_SYNC_CLEANUP_ACTIVE_KEY] = true;
+    try {
+        // A newListener callback can invoke the candidate handler before
+        // registration succeeds. Do not create acquisition state in that window.
+        const heldLocks = existingRootSyncHeldLocks();
+        if (!heldLocks)
+            return;
+        getSyncLockAdmissions().clear();
+        for (const [normalizedTargetPath, held] of heldLocks) {
+            if (heldLocks.get(normalizedTargetPath) !== held || held.releaseState !== "active")
+                continue;
+            held.releaseState = "exit-cleaning";
+            held.revision += 1;
+            let cleanupRevision = held.revision;
+            const timer = held.timer;
+            const fd = held.fd;
+            // Consume descriptor/timer ownership before either operation can invoke
+            // instrumented callbacks or recursively enter the public cleanup hook.
+            held.timer = undefined;
+            held.fd = undefined;
+            if (timer)
+                clearInterval(timer);
+            try {
+                if (fd !== undefined)
+                    fs.closeSync(fd);
+            }
+            catch {
+                // Best-effort process-exit cleanup.
+            }
+            const entryIsContinuous = () => heldLocks.get(normalizedTargetPath) === held &&
+                held.releaseState === "exit-cleaning" &&
+                held.revision === cleanupRevision;
+            const beginFreshCleanupAttempt = () => {
+                held.releaseState = "exit-cleaning";
+                held.revision += 1;
+                cleanupRevision = held.revision;
+            };
+            if (!entryIsContinuous()) {
+                if (heldLocks.get(normalizedTargetPath) === held &&
+                    readRootSyncHeldReleaseState(held) !== "released" && held.refCount === 0) {
+                    beginFreshCleanupAttempt();
+                }
+                else {
+                    restoreExactHeldLockAfterExitCleanup(heldLocks, held);
+                    continue;
+                }
+            }
+            let cleaned = false;
+            for (let cleanupAttempt = 0; cleanupAttempt < MAX_CONTINUITY_CLEANUP_ATTEMPTS; cleanupAttempt += 1) {
+                let continuityInterrupted = false;
+                let removalFailed = false;
+                let removed = false;
+                try {
+                    removed = removeFileLockSyncRootFile(held.rootPath, held.rootReceipt, held.snapshot, () => {
+                        const current = entryIsContinuous();
+                        if (!current)
+                            continuityInterrupted = true;
+                        return current;
+                    });
+                }
+                catch {
+                    // A surviving sidecar fails closed and can be reclaimed by policy.
+                    removalFailed = true;
+                }
+                if (!removalFailed && removed && !continuityInterrupted && entryIsContinuous()) {
+                    cleaned = true;
+                    break;
+                }
+                const continuousEntry = entryIsContinuous();
+                const exactEntry = heldLocks.get(normalizedTargetPath) === held &&
+                    readRootSyncHeldReleaseState(held) !== "released";
+                if (exactEntry && (continuityInterrupted || !continuousEntry) &&
+                    held.refCount === 0 && cleanupAttempt + 1 < MAX_CONTINUITY_CLEANUP_ATTEMPTS) {
+                    beginFreshCleanupAttempt();
+                    continue;
+                }
+                if (continuousEntry && held.refCount > 0) {
+                    // Preserve established best-effort process-exit behavior: after
+                    // authority-safe removal declines or throws, discard the live record
+                    // without attempting any less-restricted deletion.
+                    cleaned = true;
+                    break;
+                }
+                restoreExactHeldLockAfterExitCleanup(heldLocks, held);
+                break;
+            }
+            if (!cleaned)
+                continue;
+            finishDeferredExitReleases(held);
+            held.releaseState = "released";
+            held.revision += 1;
+            if (heldLocks.get(normalizedTargetPath) === held) {
+                heldLocks.delete(normalizedTargetPath);
+            }
+        }
+    }
+    finally {
+        globalWithCleanup[ROOT_SYNC_CLEANUP_ACTIVE_KEY] = false;
+    }
+}
+export function ensureRootSyncExitCleanupRegistered() {
+    ensureFileLockSyncRootExitCleanupRegistered(releaseAllRootSyncHeldLocks);
+}
+export function verifyRootSyncHeldLock(held) {
+    const current = readRootSidecarSnapshotSync(held.rootPath, held.parsePayload, undefined, held.rootReceipt);
+    if (!current)
+        return false;
+    return current.receipt.identity.dev === held.rootReceipt.identity.dev &&
+        current.receipt.identity.ino === held.rootReceipt.identity.ino &&
+        sidecarLockSnapshotMatches(current.snapshot, held.snapshot);
+}
+function releaseRootSyncHeldLock(held, disposition) {
+    const heldLocks = getRootSyncHeldLocks();
+    if (heldLocks.get(held.normalizedTargetPath) !== held || held.releaseState === "released")
+        return true;
+    if (held.releaseState !== "active") {
+        if (held.deferredExitReleases?.has(disposition))
+            return false;
+        if (held.refCount <= 0)
+            return false;
+        if (!fileLockSyncRootReceiptStillCurrent(held.rootPath, held.rootReceipt)) {
+            throw new FsSafeError("path-mismatch", "held sidecar lock changed before release");
+        }
+        held.refCount -= 1;
+        held.revision += 1;
+        // Exit cleanup, unlike an ordinary final release, has not consumed a
+        // handle reference of its own. Keep the last callback-entered handle
+        // retryable until cleanup either succeeds or restores it.
+        if (held.releaseState !== "exit-cleaning" || held.refCount > 0)
+            return true;
+        (held.deferredExitReleases ??= new Set()).add(disposition);
+        return false;
+    }
+    if (held.refCount > 1) {
+        if (!fileLockSyncRootReceiptStillCurrent(held.rootPath, held.rootReceipt)) {
+            throw new FsSafeError("path-mismatch", "held sidecar lock changed before release");
+        }
+        held.refCount -= 1;
+        held.revision += 1;
+        return true;
+    }
+    if (held.refCount !== 1)
+        return false;
+    held.refCount = 0;
+    held.releaseState = "releasing";
+    held.revision += 1;
+    let releaseRevision = held.revision;
+    const entryIsContinuous = () => heldLocks.get(held.normalizedTargetPath) === held &&
+        held.releaseState === "releasing" &&
+        held.revision === releaseRevision &&
+        held.refCount === 0;
+    const beginFreshReleaseAttempt = () => {
+        held.releaseState = "releasing";
+        held.revision += 1;
+        releaseRevision = held.revision;
+    };
+    const fd = held.fd;
+    held.fd = undefined;
+    try {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+    catch (error) {
+        reactivateExactHeldLock(heldLocks, held, true);
+        throw error;
+    }
+    if (!entryIsContinuous()) {
+        if (heldLocks.get(held.normalizedTargetPath) !== held ||
+            readRootSyncHeldReleaseState(held) === "released") {
+            return true;
+        }
+        if (held.refCount > 0) {
+            reactivateExactHeldLock(heldLocks, held, false);
+            return true;
+        }
+        beginFreshReleaseAttempt();
+    }
+    for (let releaseAttempt = 0; releaseAttempt < MAX_CONTINUITY_CLEANUP_ATTEMPTS; releaseAttempt += 1) {
+        let continuityInterrupted = false;
+        let removed;
+        try {
+            removed = removeFileLockSyncRootFile(held.rootPath, held.rootReceipt, held.snapshot, () => {
+                const current = entryIsContinuous();
+                if (!current)
+                    continuityInterrupted = true;
+                return current;
+            });
+        }
+        catch (error) {
+            reactivateExactHeldLock(heldLocks, held, true);
+            throw error;
+        }
+        if (!continuityInterrupted && entryIsContinuous()) {
+            if (!removed) {
+                reactivateExactHeldLock(heldLocks, held, true);
+                throw new FsSafeError("path-mismatch", "owned sidecar lock changed before release");
+            }
+            const timer = held.timer;
+            held.timer = undefined;
+            held.releaseState = "released";
+            held.revision += 1;
+            if (heldLocks.get(held.normalizedTargetPath) === held) {
+                heldLocks.delete(held.normalizedTargetPath);
+            }
+            if (timer)
+                clearInterval(timer);
+            return true;
+        }
+        if (heldLocks.get(held.normalizedTargetPath) !== held ||
+            readRootSyncHeldReleaseState(held) === "released") {
+            return true;
+        }
+        if (held.refCount > 0) {
+            reactivateExactHeldLock(heldLocks, held, false);
+            return true;
+        }
+        if (held.refCount === 0 && releaseAttempt + 1 < MAX_CONTINUITY_CLEANUP_ATTEMPTS) {
+            beginFreshReleaseAttempt();
+            continue;
+        }
+        reactivateExactHeldLock(heldLocks, held, true);
+        throw new FsSafeError("path-mismatch", "held sidecar release continuity changed repeatedly");
+    }
+    throw new FsSafeError("path-mismatch", "held sidecar release could not complete");
+}
+export function createRootSyncHeldLockHandle(held) {
+    const disposition = { held, released: false };
+    let releaseInProgress = false;
+    const release = () => {
+        if (disposition.released || releaseInProgress)
+            return;
+        releaseInProgress = true;
+        try {
+            if (releaseRootSyncHeldLock(held, disposition))
+                disposition.released = true;
+        }
+        finally {
+            releaseInProgress = false;
+        }
+    };
+    const handle = {
+        lockPath: held.lockPath,
+        normalizedTargetPath: held.normalizedTargetPath,
+        verifyStillHeld: () => verifyRootSyncHeldLock(held),
+        release,
+        [Symbol.dispose]: release,
+    };
+    rootSyncHandleDispositions.set(handle, disposition);
+    return handle;
+}
+export function isRootSyncHeldLockHandle(handle) {
+    return rootSyncHandleDispositions.has(handle);
+}
+export function withRootSyncHeldLockHandle(lock, fn) {
+    let result;
+    try {
+        result = fn();
+    }
+    catch (callbackError) {
+        try {
+            lock.release();
+            settleDeferredExitRelease(lock);
+        }
+        catch (releaseError) {
+            throw createSuppressedError(releaseError, callbackError, "file lock release and protected callback both failed");
+        }
+        throw callbackError;
+    }
+    lock.release();
+    settleDeferredExitRelease(lock);
+    return result;
+}

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

@@ -0,0 +1,44 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { RootDefaults } from "./root-options.js";
+import { type FileLockSyncRootPath } from "./file-lock-sync-root.js";
+export type ExactIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type DirectoryReceipt = Readonly<{
+    identity: ExactIdentity;
+    path: string;
+    realPath: string;
+}>;
+export type FileLockSyncRootFileReceipt = Readonly<{
+    identity: ExactIdentity;
+    parent: DirectoryReceipt;
+}>;
+export type FileLockSyncRootDirectoryReceipt = Readonly<{
+    identity: ExactIdentity;
+    parent: DirectoryReceipt;
+}>;
+export type FileLockSyncRootDiskSnapshot = {
+    ownershipToken?: never;
+    payload: unknown;
+    raw: string;
+    stat: Stats;
+};
+export type FileLockSyncRootSnapshot = Readonly<{
+    receipt: FileLockSyncRootFileReceipt;
+    snapshot: FileLockSyncRootDiskSnapshot;
+}>;
+export declare function observeDirectory(pathname: string, initial?: BigIntStats): DirectoryReceipt;
+export declare function assertDirectoryCurrent(receipt: DirectoryReceipt, initial?: BigIntStats): void;
+export declare function assertRetainedParentCurrent(pathAuthority: FileLockSyncRootPath, parent: DirectoryReceipt): void;
+export declare function exactFileIdentity(stat: BigIntStats): ExactIdentity;
+export declare function assertRegularFile(stat: BigIntStats, hardlinks: RootDefaults["hardlinks"]): void;
+export declare function sameExactIdentity(left: ExactIdentity, right: ExactIdentity): boolean;
+export declare function readFileLockSyncRootSnapshot(pathAuthority: FileLockSyncRootPath, options?: {
+    expectedReceipt?: FileLockSyncRootFileReceipt;
+    onOpenFailure?: (error: unknown) => void;
+}): FileLockSyncRootSnapshot | null;
+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-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-root-io.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-io.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAQ3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAQtD,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAKlC,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAEH,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IACjD,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,gBAAgB,CAAC;CAC1B,CAAC,CAAC;AAEH,MAAM,MAAM,gCAAgC,GAAG,QAAQ,CAAC;IACtD,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,gBAAgB,CAAC;CAC1B,CAAC,CAAC;AAEH,MAAM,MAAM,4BAA4B,GAAG;IACzC,cAAc,CAAC,EAAE,KAAK,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,OAAO,EAAE,2BAA2B,CAAC;IACrC,QAAQ,EAAE,4BAA4B,CAAC;CACxC,CAAC,CAAC;AAKH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,gBAAgB,CAY1F;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAO7F;AAED,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,oBAAoB,EACnC,MAAM,EAAE,gBAAgB,GACvB,IAAI,CAQN;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,aAAa,CAElE;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,YAAY,CAAC,WAAW,CAAC,GACnC,IAAI,CAKN;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAEpF;AAqBD,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,oBAAoB,EACnC,OAAO,GAAE;IACP,eAAe,CAAC,EAAE,2BAA2B,CAAC;IAC9C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC,GACL,wBAAwB,GAAG,IAAI,CA4GjC;AAED,wBAAgB,oCAAoC,CAClD,aAAa,EAAE,oBAAoB,EACnC,QAAQ,EAAE,wBAAwB,GACjC,OAAO,CAOT;AAED,wBAAgB,kCAAkC,CAChD,aAAa,EAAE,oBAAoB,EACnC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAeT;AAED,wBAAgB,mCAAmC,CACjD,aAAa,EAAE,oBAAoB,EACnC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAGT"}