@openclaw/fs-safe 0.14.0 → 0.16.0

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"}

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

@@ -0,0 +1,209 @@
+import fs, {} from "node:fs";
+import path from "node:path";
+import { readFileDescriptorBoundedSync } from "./bounded-read.js";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { assertRootIdentityCurrentSync } from "./root-context.js";
+import { hardlinkedPathNotAllowedError } from "./root-errors.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
+import { sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { assertFileLockSyncRootResolvedPathCurrent, } from "./file-lock-sync-root.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
+const MAX_SIDECAR_LOCK_PAYLOAD_BYTES = 1024 * 1024;
+const samePath = (left, right) => path.relative(path.resolve(left), path.resolve(right)) === "";
+export function observeDirectory(pathname, initial) {
+    const stat = inspectDirectoryIdentitySync(pathname, undefined, initial);
+    const realPath = realpathSync.native(pathForWindowsFilesystem(pathname));
+    assertNoWindowsPathAlias(realPath, "filesystem", "sidecar lock parent uses a Windows filesystem namespace alias");
+    if (!samePath(realPath, pathname)) {
+        throw new FsSafeError("path-mismatch", "sidecar lock parent changed during operation");
+    }
+    return Object.freeze({
+        identity: Object.freeze({ dev: stat.dev, ino: stat.ino }),
+        path: pathname,
+        realPath,
+    });
+}
+export function assertDirectoryCurrent(receipt, initial) {
+    inspectDirectoryIdentitySync(receipt.path, receipt.identity, initial);
+    const currentReal = realpathSync.native(pathForWindowsFilesystem(receipt.path));
+    assertNoWindowsPathAlias(currentReal, "filesystem", "sidecar lock parent uses a Windows filesystem namespace alias");
+    if (currentReal !== receipt.realPath) {
+        throw new FsSafeError("path-mismatch", "sidecar lock parent changed during operation");
+    }
+}
+export function assertRetainedParentCurrent(pathAuthority, parent) {
+    const context = pathAuthority.authority.context;
+    const sharedIdentity = parent.path === context.rootReal &&
+        parent.identity.dev === context.rootIdentity.dev && parent.identity.ino === context.rootIdentity.ino;
+    let rootStat;
+    assertRootIdentityCurrentSync(context, sharedIdentity ? stat => { rootStat = stat; } : undefined);
+    assertDirectoryCurrent(parent, rootStat);
+    assertRootIdentityCurrentSync(context);
+}
+export function exactFileIdentity(stat) {
+    return Object.freeze({ dev: stat.dev, ino: stat.ino });
+}
+export function assertRegularFile(stat, hardlinks) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new FsSafeError("not-file", "sidecar lock is not a regular file");
+    }
+    if (hardlinks !== "allow" && stat.nlink > 1n)
+        throw hardlinkedPathNotAllowedError();
+}
+export function sameExactIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function assertFreshPathCurrent(pathAuthority) {
+    // The exact Root observation is deliberately last: this helper is used both
+    // immediately before fresh pathname I/O and immediately before returning it.
+    assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+    assertRootIdentityCurrentSync(pathAuthority.authority.context);
+}
+function missingAfterCurrentRead(pathAuthority, expectedReceipt) {
+    if (expectedReceipt) {
+        assertRetainedParentCurrent(pathAuthority, expectedReceipt.parent);
+    }
+    else {
+        assertFreshPathCurrent(pathAuthority);
+    }
+    return null;
+}
+export function readFileLockSyncRootSnapshot(pathAuthority, options = {}) {
+    const expectedReceipt = options.expectedReceipt;
+    if (expectedReceipt) {
+        assertRetainedParentCurrent(pathAuthority, expectedReceipt.parent);
+    }
+    else {
+        assertFreshPathCurrent(pathAuthority);
+    }
+    let before;
+    try {
+        before = inspectFileIdentitySync(() => fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true }), expectedReceipt?.identity);
+    }
+    catch (error) {
+        if (isNotFoundPathError(error) || (expectedReceipt && error instanceof FsSafeError && error.code === "path-mismatch"))
+            return missingAfterCurrentRead(pathAuthority, expectedReceipt);
+        throw error;
+    }
+    assertRegularFile(before, pathAuthority.authority.hardlinks);
+    const parent = expectedReceipt?.parent ?? observeDirectory(path.dirname(pathAuthority.path));
+    let fd;
+    let operationError;
+    let operationFailed = false;
+    try {
+        try {
+            fd = fs.openSync(pathForWindowsFilesystem(pathAuthority.path), resolveReadOpenFlags());
+        }
+        catch (error) {
+            if (isNotFoundPathError(error))
+                return missingAfterCurrentRead(pathAuthority, expectedReceipt);
+            options.onOpenFailure?.(error);
+            throw error;
+        }
+        let opened;
+        try {
+            opened = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }), exactFileIdentity(before));
+        }
+        catch (error) {
+            if (error instanceof FsSafeError && error.code === "path-mismatch") {
+                if (expectedReceipt) {
+                    assertRetainedParentCurrent(pathAuthority, parent);
+                }
+                else {
+                    assertDirectoryCurrent(parent);
+                    assertFreshPathCurrent(pathAuthority);
+                }
+                return null;
+            }
+            throw error;
+        }
+        assertRegularFile(opened, pathAuthority.authority.hardlinks);
+        const raw = readFileDescriptorBoundedSync(fd, MAX_SIDECAR_LOCK_PAYLOAD_BYTES).toString("utf8");
+        let after;
+        try {
+            after = inspectFileIdentitySync(() => fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true }), exactFileIdentity(opened));
+        }
+        catch (error) {
+            if (isNotFoundPathError(error) ||
+                (error instanceof FsSafeError && error.code === "path-mismatch")) {
+                if (expectedReceipt) {
+                    assertRetainedParentCurrent(pathAuthority, parent);
+                }
+                else {
+                    assertDirectoryCurrent(parent);
+                    assertFreshPathCurrent(pathAuthority);
+                }
+                return null;
+            }
+            throw error;
+        }
+        assertRegularFile(after, pathAuthority.authority.hardlinks);
+        const stat = fs.fstatSync(fd);
+        if (expectedReceipt) {
+            assertRetainedParentCurrent(pathAuthority, parent);
+        }
+        else {
+            assertDirectoryCurrent(parent);
+            assertFreshPathCurrent(pathAuthority);
+        }
+        const snapshot = {
+            raw,
+            payload: null,
+            stat,
+        };
+        return Object.freeze({
+            receipt: Object.freeze({ identity: exactFileIdentity(opened), parent }),
+            snapshot,
+        });
+    }
+    catch (error) {
+        operationFailed = true;
+        operationError = error;
+        throw error;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch (closeError) {
+                if (operationFailed) {
+                    throw createSuppressedError(closeError, operationError, "sidecar snapshot admission and descriptor close both failed");
+                }
+                throw closeError;
+            }
+        }
+    }
+}
+export function fileLockSyncRootSnapshotStillCurrent(pathAuthority, observed) {
+    const current = readFileLockSyncRootSnapshot(pathAuthority, {
+        expectedReceipt: observed.receipt,
+    });
+    return !!current &&
+        sameExactIdentity(current.receipt.identity, observed.receipt.identity) &&
+        sidecarLockSnapshotMatches(current.snapshot, observed.snapshot);
+}
+export function fileReceiptCurrentAfterParentCheck(pathAuthority, receipt) {
+    let current;
+    try {
+        current = inspectFileIdentitySync(() => fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true }), receipt.identity);
+    }
+    catch (error) {
+        if (isNotFoundPathError(error) ||
+            (error instanceof FsSafeError && error.code === "path-mismatch"))
+            return false;
+        throw error;
+    }
+    assertRegularFile(current, pathAuthority.authority.hardlinks);
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    return true;
+}
+export function fileLockSyncRootReceiptStillCurrent(pathAuthority, receipt) {
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    return fileReceiptCurrentAfterParentCheck(pathAuthority, receipt);
+}

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

@@ -0,0 +1,17 @@
+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;
+}): {
+    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 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-root-mutation.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-mutation.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAWL,KAAK,gCAAgC,EACrC,KAAK,2BAA2B,EACjC,MAAM,6BAA6B,CAAC;AA+DrC,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,oBAAoB,EACnC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC,GACL;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,2BAA2B,CAAA;CAAE,CA4CtD;AAED,wBAAgB,kCAAkC,CAChD,aAAa,EAAE,oBAAoB,EACnC,OAAO,EAAE,2BAA2B,GACnC,2BAA2B,CAK7B;AAED,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,oBAAoB,EACnC,OAAO,EAAE,2BAA2B,EACpC,QAAQ,CAAC,EAAE,mBAAmB,EAC9B,kBAAkB,CAAC,EAAE,MAAM,OAAO,GAAG,IAAI,GACxC,OAAO,CA0DT;AAED,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,oBAAoB,EACnC,kBAAkB,UAAQ,GACzB,OAAO,CAkCT;AAED,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,oBAAoB,GAClC,gCAAgC,GAAG,IAAI,CAiBzC;AAED,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,oBAAoB,EACnC,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAST;AAED,wBAAgB,4CAA4C,CAC1D,aAAa,EAAE,oBAAoB,EACnC,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAWT"}