@openclaw/fs-safe 0.14.0 → 0.16.0

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

@@ -0,0 +1,361 @@
+import fs from "node:fs";
+import path from "node:path";
+import {} from "./deny-mutations.js";
+import { FsSafeError } from "./errors.js";
+import { assertNoNulPathInput, isNotFoundPathError, isPathInside } from "./path.js";
+import { resolveRootPathSync } from "./root-path.js";
+import { isRootPathEscapeError } from "./root-path-errors.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { assertRootIdentityCurrentSync, } from "./root-context.js";
+import { directoryComponentNotDirectoryError, outsideWorkspaceError, } from "./root-errors.js";
+import { mutationSymlinkResolution, readSymlinkResolution, } from "./root-symlink-policy.js";
+import { realpathSync } from "./realpath.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const retainedRootContexts = new WeakMap();
+const retainedRootDefaults = new WeakMap();
+/** @internal Registers only instances constructed by RootHandle itself. */
+export function registerFileLockSyncRootAdapter(handle, context, defaults) {
+    const identity = context.rootIdentity;
+    if (typeof identity.dev !== "bigint" || typeof identity.ino !== "bigint")
+        return;
+    // Retain the already-created Root inputs directly. Registration adds no
+    // per-Root wrapper/context allocations for callers that never use sync locks.
+    retainedRootContexts.set(handle, context);
+    retainedRootDefaults.set(handle, defaults);
+}
+function snapshotPolicy(policy) {
+    if (policy === undefined)
+        return undefined;
+    const paths = policy.paths;
+    const prefixes = policy.prefixes;
+    return Object.freeze({
+        paths: paths === undefined ? undefined : Object.freeze([...paths]),
+        prefixes: prefixes === undefined ? undefined : Object.freeze([...prefixes]),
+    });
+}
+export function captureFileLockSyncRootAuthority(lockRoot) {
+    const adapter = lockRoot;
+    const retainedContext = retainedRootContexts.get(adapter);
+    const retainedDefaults = retainedRootDefaults.get(adapter);
+    if (!retainedContext || !retainedDefaults) {
+        throw new FsSafeError("helper-unavailable", "synchronous Root-backed file locks require a genuine fs-safe Root handle");
+    }
+    const identity = retainedContext.rootIdentity;
+    if (typeof identity.dev !== "bigint" || typeof identity.ino !== "bigint") {
+        throw new FsSafeError("helper-unavailable", "synchronous Root identity is unavailable");
+    }
+    const context = Object.freeze({
+        rootDir: retainedContext.rootDir,
+        rootGuard: retainedContext.rootGuard,
+        rootIdentity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
+        rootReal: retainedContext.rootReal,
+        rootWithSep: retainedContext.rootWithSep,
+    });
+    const defaults = retainedDefaults;
+    const assertBeforeMutation = defaults.assertBeforeMutation;
+    const denyMutations = snapshotPolicy(defaults.denyMutations);
+    const hardlinks = defaults.hardlinks;
+    const mutationSymlinks = defaults.mutationSymlinks;
+    const symlinks = defaults.symlinks;
+    // Snapshot all defaults before the Root check and mutation-policy validation.
+    assertRootIdentityCurrentSync(context);
+    const mutation = mutationSymlinkResolution(mutationSymlinks);
+    const mutationPolicy = Object.freeze({
+        rejectSymlinks: mutation.rejectSymlinks,
+        rejectFinalSymlink: mutation.rejectFinalSymlink,
+        rejectUnresolvedSymlinks: true,
+    });
+    const readPolicy = Object.freeze({
+        ...readSymlinkResolution(symlinks),
+        rejectUnresolvedSymlinks: true,
+    });
+    return Object.freeze({
+        adapter,
+        context,
+        assertBeforeMutation,
+        denyMutations,
+        hardlinks,
+        mutationPolicy,
+        readPolicy,
+        policiesMatch: mutationPolicy.rejectSymlinks === readPolicy.rejectSymlinks &&
+            mutationPolicy.rejectFinalSymlink === readPolicy.rejectFinalSymlink,
+    });
+}
+export function invokeFileLockSyncRootMutationAuthority(authority) {
+    const assertion = authority.assertBeforeMutation;
+    if (!assertion)
+        return false;
+    // Match Root mutation semantics: callbacks are invoked unbound and a
+    // thenable result cannot authorize a synchronous filesystem mutation.
+    assertSynchronousCallbackResult(assertion(), "assertBeforeMutation");
+    return true;
+}
+function samePath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === "";
+}
+function absoluteRootPath(authority, relativePath) {
+    const segments = relativePath.split(path.posix.sep);
+    const absolute = path.join(authority.context.rootReal, ...segments);
+    assertNoWindowsPathAlias(absolute, "filesystem", "sidecar lock path uses a Windows filesystem namespace alias");
+    return absolute;
+}
+function assertValidPolicyEntries(entries) {
+    const captured = [];
+    for (const entry of entries ?? []) {
+        if (!entry || !path.isAbsolute(entry)) {
+            throw new FsSafeError("invalid-path", "deny mutation paths must be non-empty absolute paths");
+        }
+        assertNoNulPathInput(entry, "deny mutation path contains a NUL byte");
+        assertNoWindowsPathAlias(entry, "filesystem", "deny mutation path uses a Windows filesystem namespace alias");
+        captured.push(resolvePathPreservingWindowsRoot(entry));
+    }
+    return captured;
+}
+function mutationComparablePaths(pathname) {
+    const resolved = resolvePathPreservingWindowsRoot(pathname);
+    assertNoWindowsPathAlias(resolved, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    let cursor = resolved;
+    const missing = [];
+    while (path.parse(cursor).root !== cursor) {
+        try {
+            fs.lstatSync(pathForWindowsFilesystem(cursor));
+            break;
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error))
+                throw error;
+            missing.unshift(path.basename(cursor));
+            cursor = path.dirname(cursor);
+        }
+    }
+    // Deny policy is an authority boundary: unlike advisory key normalization,
+    // an ambiguous existing ancestor must not silently fall back to lexical form.
+    const canonicalAncestor = realpathSync.native(pathForWindowsFilesystem(cursor));
+    assertNoWindowsPathAlias(canonicalAncestor, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    const canonical = missing.length === 0
+        ? canonicalAncestor
+        : path.resolve(canonicalAncestor, ...missing);
+    assertNoWindowsPathAlias(canonical, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    return samePath(resolved, canonical) ? [resolved] : [resolved, canonical];
+}
+export function assertFileLockSyncRootMutationAllowed(pathname, policy, protectAncestors = false) {
+    if (!policy?.paths?.length && !policy?.prefixes?.length)
+        return;
+    const targets = mutationComparablePaths(pathname);
+    for (const entry of assertValidPolicyEntries(policy.paths)) {
+        for (const denied of mutationComparablePaths(entry)) {
+            for (const target of targets) {
+                if ((isPathInside(denied, target) && isPathInside(target, denied)) ||
+                    (protectAncestors && isPathInside(target, denied))) {
+                    throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
+                }
+            }
+        }
+    }
+    for (const entry of assertValidPolicyEntries(policy.prefixes)) {
+        for (const denied of mutationComparablePaths(entry)) {
+            for (const target of targets) {
+                if (isPathInside(denied, target) || (protectAncestors && isPathInside(target, denied))) {
+                    throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
+                }
+            }
+        }
+    }
+}
+function resolveAdmittedPath(authority, absolutePath, policy, rootPath) {
+    const context = authority.context;
+    let resolved;
+    try {
+        resolved = resolveRootPathSync({
+            absolutePath,
+            // The shared resolver identity-gates ambiguous Windows matches against the
+            // original Root spelling before rebasing them to the retained canonical root.
+            rootPath,
+            rootCanonicalPath: context.rootReal,
+            rootIdentity: context.rootIdentity,
+            boundaryLabel: "sidecar lock root",
+            ...policy,
+        });
+    }
+    catch (error) {
+        if (isRootPathEscapeError(error)) {
+            throw new FsSafeError("outside-workspace", "sidecar lock path is outside lockRoot", { cause: error });
+        }
+        throw error;
+    }
+    const admitted = admitPathInsideRoot({
+        rootPath: context.rootReal,
+        candidatePath: resolved.canonicalPath,
+        rootIdentity: context.rootIdentity,
+    });
+    if (!admitted || admitted.relativePath === "" || samePath(admitted.path, context.rootReal)) {
+        throw outsideWorkspaceError();
+    }
+    return {
+        path: admitted.path,
+        relativePath: admitted.relativePath.split(path.sep).join(path.posix.sep),
+    };
+}
+function resolveBothPolicies(authority, absolutePath, rootPath) {
+    const { mutationPolicy, readPolicy, policiesMatch } = authority;
+    const mutation = resolveAdmittedPath(authority, absolutePath, mutationPolicy, rootPath);
+    const readable = policiesMatch
+        ? mutation
+        : resolveAdmittedPath(authority, absolutePath, readPolicy, rootPath);
+    if (!samePath(mutation.path, readable.path)) {
+        throw new FsSafeError("path-mismatch", "sidecar read and mutation paths resolve differently");
+    }
+    assertFileLockSyncRootMutationAllowed(mutation.path, authority.denyMutations);
+    return mutation;
+}
+function admitRequestedRootPrefix(authority, requestedPath) {
+    const context = authority.context;
+    const identityCache = process.platform === "win32" ? new Map() : undefined;
+    const original = admitPathInsideRoot({
+        rootPath: context.rootDir,
+        candidatePath: requestedPath,
+        rootIdentity: context.rootIdentity,
+        resolveCandidateRoot: context.rootDir !== context.rootReal,
+        identityCache,
+    });
+    if (original && original.relativePath !== "") {
+        return { path: original.path, rootPath: context.rootDir };
+    }
+    const canonical = context.rootDir === context.rootReal ? undefined : admitPathInsideRoot({
+        rootPath: context.rootReal,
+        candidatePath: requestedPath,
+        rootIdentity: context.rootIdentity,
+        identityCache,
+    });
+    if (!canonical || canonical.relativePath === "")
+        throw outsideWorkspaceError();
+    return { path: canonical.path, rootPath: context.rootReal };
+}
+export function admitFileLockSyncRootPath(authority, requestedPath) {
+    assertNoNulPathInput(requestedPath, "sidecar lock path contains a NUL byte");
+    const resolved = resolvePathPreservingWindowsRoot(requestedPath);
+    assertNoWindowsPathAlias(resolved, "filesystem", "sidecar lock path uses a Windows filesystem namespace alias");
+    assertRootIdentityCurrentSync(authority.context);
+    const prefixed = admitRequestedRootPrefix(authority, resolved);
+    const selected = resolveBothPolicies(authority, prefixed.path, prefixed.rootPath);
+    assertRootIdentityCurrentSync(authority.context);
+    const admitted = Object.freeze({
+        authority,
+        path: selected.path,
+        relativePath: selected.relativePath,
+    });
+    assertMissingParentMutationsAllowed(admitted);
+    return admitted;
+}
+export function assertFileLockSyncRootResolvedPathCurrent(pathAuthority) {
+    const resolved = resolveBothPolicies(pathAuthority.authority, absoluteRootPath(pathAuthority.authority, pathAuthority.relativePath), pathAuthority.authority.context.rootReal);
+    if (!samePath(resolved.path, pathAuthority.path)) {
+        throw new FsSafeError("path-mismatch", "sidecar lock path changed during operation");
+    }
+}
+function assertMissingParentMutationsAllowed(pathAuthority) {
+    const authority = pathAuthority.authority;
+    const context = authority.context;
+    const relativeParent = path.posix.dirname(pathAuthority.relativePath);
+    const relative = relativeParent === "." ? "" : relativeParent;
+    let current = context.rootReal;
+    let missing = false;
+    for (const segment of relative.split(path.posix.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        if (!missing) {
+            try {
+                const stat = fs.lstatSync(pathForWindowsFilesystem(current), { bigint: true });
+                if (stat.isSymbolicLink() || !stat.isDirectory())
+                    throw directoryComponentNotDirectoryError();
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error))
+                    throw error;
+                missing = true;
+            }
+        }
+        if (missing)
+            assertFileLockSyncRootMutationAllowed(current, authority.denyMutations);
+    }
+}
+export function assertFileLockSyncRootPathsCurrent(paths, invokeAuthority = false, pathsAlreadyCurrent = false) {
+    const authority = paths[0]?.authority;
+    for (const pathAuthority of paths) {
+        if (authority && pathAuthority.authority !== authority) {
+            throw new FsSafeError("path-mismatch", "sidecar paths use different Root authority");
+        }
+    }
+    if (!pathsAlreadyCurrent) {
+        if (authority)
+            assertRootIdentityCurrentSync(authority.context);
+        for (const pathAuthority of paths) {
+            assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+            assertMissingParentMutationsAllowed(pathAuthority);
+        }
+        if (authority)
+            assertRootIdentityCurrentSync(authority.context);
+    }
+    if (invokeAuthority && authority && invokeFileLockSyncRootMutationAuthority(authority)) {
+        assertRootIdentityCurrentSync(authority.context);
+        for (const pathAuthority of paths) {
+            assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+            assertMissingParentMutationsAllowed(pathAuthority);
+        }
+        assertRootIdentityCurrentSync(authority.context);
+    }
+}
+function resolveTargetPathViaExistingAncestorSync(targetPath) {
+    const normalized = resolvePathPreservingWindowsRoot(targetPath);
+    const canonicalize = process.platform === "win32" ? realpathSync.native : realpathSync;
+    let cursor = normalized;
+    const missing = [];
+    while (true) {
+        try {
+            fs.lstatSync(pathForWindowsFilesystem(cursor));
+            try {
+                const canonicalAncestor = canonicalize(pathForWindowsFilesystem(cursor));
+                assertNoWindowsPathAlias(canonicalAncestor, "filesystem", "file-lock target ancestor uses a Windows filesystem namespace alias");
+                return missing.length === 0
+                    ? resolvePathPreservingWindowsRoot(canonicalAncestor)
+                    : resolvePathPreservingWindowsRoot(path.resolve(canonicalAncestor, ...missing));
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error))
+                    throw error;
+                // A dangling link is an existing lexical entry but not a canonical
+                // ancestor. Continue at its parent instead of abandoning native
+                // long/short-name normalization for the rest of the target path.
+            }
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error))
+                throw error;
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor) {
+            // Filesystem roots are expected to exist; preserve the underlying
+            // not-found diagnosis if a synthetic namespace violates that premise.
+            const canonicalAncestor = canonicalize(pathForWindowsFilesystem(cursor));
+            assertNoWindowsPathAlias(canonicalAncestor, "filesystem", "file-lock target ancestor uses a Windows filesystem namespace alias");
+            return missing.length === 0
+                ? resolvePathPreservingWindowsRoot(canonicalAncestor)
+                : resolvePathPreservingWindowsRoot(path.resolve(canonicalAncestor, ...missing));
+        }
+        missing.unshift(path.basename(cursor));
+        cursor = parent;
+    }
+}
+export function normalizeFileLockSyncTargetWithRoot(authority, resolvedTargetPath) {
+    assertNoNulPathInput(resolvedTargetPath, "file-lock target contains a NUL byte");
+    assertNoWindowsPathAlias(resolvedTargetPath, "filesystem", "file-lock target uses a Windows filesystem namespace alias");
+    assertRootIdentityCurrentSync(authority.context);
+    // Preserve POSIX's pathname-key behavior while making Windows resolve the
+    // complete existing prefix (including an existing 8.3-spelled filename).
+    const normalized = process.platform === "win32"
+        ? resolveTargetPathViaExistingAncestorSync(resolvedTargetPath)
+        : path.join(resolveTargetPathViaExistingAncestorSync(path.dirname(resolvedTargetPath)), path.basename(resolvedTargetPath));
+    assertNoWindowsPathAlias(normalized, "filesystem", "file-lock target uses a Windows filesystem namespace alias");
+    assertRootIdentityCurrentSync(authority.context);
+    return normalized;
+}

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

@@ -0,0 +1,24 @@
+import type { FileLockSyncAcquireOptions } from "./file-lock-sync.js";
+import type { SidecarLockStaleRecovery } from "./sidecar-lock-types.js";
+export type SyncStaleOptionsState<TPayload extends Record<string, unknown>> = {
+    shouldReclaimObserved?: boolean;
+    shouldReclaim?: FileLockSyncAcquireOptions<TPayload>["shouldReclaim"];
+    shouldRemoveObserved?: boolean;
+    shouldRemove?: FileLockSyncAcquireOptions<TPayload>["shouldRemoveStaleLock"];
+};
+/** Handle one exclusive-create conflict without surrendering canonical admission. */
+export declare function handleSyncStaleAdmission<TPayload extends Record<string, unknown>>(params: {
+    hasToken(): boolean;
+    currentHeld(): unknown;
+    lockPath: string;
+    normalizedTargetPath: string;
+    options: FileLockSyncAcquireOptions<TPayload>;
+    parsePayload?: (raw: string) => unknown;
+    reclaimGuardPath: string;
+    retryLockFileDenial(error: unknown): boolean;
+    staleMs: number;
+    staleOptions: SyncStaleOptionsState<TPayload>;
+    staleRecovery?: SidecarLockStaleRecovery;
+    waitForRetry(): void;
+}): void;
+//# sourceMappingURL=file-lock-sync-stale-admission.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-stale-admission.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-stale-admission.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAQtE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAExE,MAAM,MAAM,qBAAqB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC5E,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,aAAa,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,CAAC;IACtE,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,YAAY,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC,uBAAuB,CAAC,CAAC;CAC9E,CAAC;AAEF,qFAAqF;AACrF,wBAAgB,wBAAwB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE;IACzF,QAAQ,IAAI,OAAO,CAAC;IACpB,WAAW,IAAI,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IAC9C,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAC9C,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,YAAY,IAAI,IAAI,CAAC;CACtB,GAAG,IAAI,CAiLP"}

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

@@ -0,0 +1,205 @@
+import fs from "node:fs";
+import { defaultSyncShouldReclaim, syncLockTimeout } from "./file-lock-sync-admission.js";
+import { parseSidecarLockSnapshot, readSidecarLockRawSnapshotSync, removeSidecarLockIfUnchangedSync, } from "./sidecar-lock-reclaim.js";
+/** Handle one exclusive-create conflict without surrendering canonical admission. */
+export function handleSyncStaleAdmission(params) {
+    const holderChanged = {};
+    const assertUnheld = () => {
+        if (!params.hasToken()) {
+            throw syncLockTimeout(params.lockPath, params.normalizedTargetPath);
+        }
+        if (params.currentHeld())
+            throw holderChanged;
+    };
+    const retryHolderChange = (error) => {
+        if (error !== holderChanged)
+            return false;
+        params.waitForRetry();
+        return true;
+    };
+    let rawSnapshot;
+    let lockFileOpenDenied = false;
+    try {
+        rawSnapshot = readSidecarLockRawSnapshotSync(params.lockPath, {
+            rejectNonFile: true,
+            onOpenFailure: (error) => {
+                lockFileOpenDenied = true;
+                assertUnheld();
+            },
+        });
+        assertUnheld();
+    }
+    catch (error) {
+        if (retryHolderChange(error))
+            return;
+        try {
+            assertUnheld();
+        }
+        catch (boundaryError) {
+            if (retryHolderChange(boundaryError))
+                return;
+            throw boundaryError;
+        }
+        if (lockFileOpenDenied && params.retryLockFileDenial(error))
+            return;
+        throw error;
+    }
+    const stale = params.staleOptions;
+    try {
+        if (!stale.shouldReclaimObserved) {
+            assertUnheld();
+            stale.shouldReclaim = params.options.shouldReclaim;
+            stale.shouldReclaimObserved = true;
+            assertUnheld();
+        }
+        if (!stale.shouldRemoveObserved) {
+            assertUnheld();
+            stale.shouldRemove = params.options.shouldRemoveStaleLock;
+            stale.shouldRemoveObserved = true;
+            assertUnheld();
+        }
+    }
+    catch (error) {
+        if (retryHolderChange(error))
+            return;
+        try {
+            assertUnheld();
+        }
+        catch (boundaryError) {
+            if (retryHolderChange(boundaryError))
+                return;
+            throw boundaryError;
+        }
+        throw error;
+    }
+    const guardedParser = params.parsePayload && ((raw) => {
+        assertUnheld();
+        try {
+            return Reflect.apply(params.parsePayload, undefined, [raw]);
+        }
+        finally {
+            assertUnheld();
+        }
+    });
+    let snapshot;
+    try {
+        snapshot = parseSidecarLockSnapshot(rawSnapshot, guardedParser);
+        assertUnheld();
+    }
+    catch (error) {
+        if (retryHolderChange(error))
+            return;
+        throw error;
+    }
+    if (!snapshot) {
+        params.waitForRetry();
+        return;
+    }
+    const nowMs = Date.now();
+    let reclaim;
+    try {
+        assertUnheld();
+        try {
+            reclaim = stale.shouldReclaim
+                ? Reflect.apply(stale.shouldReclaim, params.options, [{
+                        lockPath: params.lockPath,
+                        normalizedTargetPath: params.normalizedTargetPath,
+                        payload: snapshot.payload,
+                        staleMs: params.staleMs,
+                        nowMs,
+                        heldByThisProcess: false,
+                    }])
+                : defaultSyncShouldReclaim(snapshot, params.staleMs, nowMs);
+        }
+        finally {
+            assertUnheld();
+        }
+    }
+    catch (error) {
+        if (retryHolderChange(error))
+            return;
+        throw error;
+    }
+    if (!reclaim) {
+        params.waitForRetry();
+        return;
+    }
+    if (params.staleRecovery === "remove-if-unchanged" &&
+        snapshot.raw !== undefined &&
+        stale.shouldRemove !== undefined) {
+        let approved;
+        try {
+            assertUnheld();
+            try {
+                approved = Reflect.apply(stale.shouldRemove, params.options, [{
+                        lockPath: params.lockPath,
+                        normalizedTargetPath: params.normalizedTargetPath,
+                        raw: snapshot.raw,
+                        payload: snapshot.payload,
+                    }]);
+            }
+            finally {
+                assertUnheld();
+            }
+        }
+        catch (error) {
+            if (retryHolderChange(error))
+                return;
+            throw error;
+        }
+        if (!approved) {
+            throw Object.assign(new Error(`file lock stale for ${params.normalizedTargetPath}`), {
+                code: "file_lock_stale",
+                lockPath: params.lockPath,
+                normalizedTargetPath: params.normalizedTargetPath,
+            });
+        }
+        try {
+            fs.mkdirSync(params.reclaimGuardPath);
+        }
+        catch (error) {
+            try {
+                assertUnheld();
+            }
+            catch (boundaryError) {
+                if (retryHolderChange(boundaryError))
+                    return;
+                throw boundaryError;
+            }
+            if (error.code === "EEXIST") {
+                params.waitForRetry();
+                return;
+            }
+            throw error;
+        }
+        let holderInterrupted = false;
+        try {
+            assertUnheld();
+            if (removeSidecarLockIfUnchangedSync(params.lockPath, snapshot, assertUnheld))
+                return;
+        }
+        catch (error) {
+            if (error === holderChanged)
+                holderInterrupted = true;
+            else
+                throw error;
+        }
+        finally {
+            try {
+                fs.rmdirSync(params.reclaimGuardPath);
+            }
+            catch {
+                // A surviving reclaim guard fails closed.
+            }
+        }
+        if (holderInterrupted) {
+            params.waitForRetry();
+            return;
+        }
+    }
+    throw Object.assign(new Error(`file lock stale for ${params.normalizedTargetPath}`), {
+        code: "file_lock_stale",
+        lockPath: params.lockPath,
+        normalizedTargetPath: params.normalizedTargetPath,
+    });
+}

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

@@ -1 +1 @@
-{"version":3,"file":"file-lock-sync.d.ts","sourceRoot":"","sources":["../src/file-lock-sync.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EASL,KAAK,wBAAwB,EAC9B,MAAM,2BAA2B,CAAC;AAWnC,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAQjC,MAAM,MAAM,0BAA0B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,QAAQ,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,KAAK,CAAC;KAC1B,KAAK,OAAO,CAAC;IACd,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,OAAO,CAAC;IACxE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC3D,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,IAAI,OAAO,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AA8JF,wBAAgB,mBAAmB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,kBAAkB,CA4NpB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,EAC7C,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAOH"}
+{"version":3,"file":"file-lock-sync.d.ts","sourceRoot":"","sources":["../src/file-lock-sync.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAML,KAAK,wBAAwB,EAC9B,MAAM,2BAA2B,CAAC;AAUnC,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAqBjC,MAAM,MAAM,0BAA0B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,QAAQ,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,KAAK,CAAC;KAC1B,KAAK,OAAO,CAAC;IACd,qBAAqB,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,OAAO,CAAC;IACxE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC3D,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,IAAI,OAAO,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AAyFF,wBAAgB,mBAAmB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,kBAAkB,CAyRpB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,EAC7C,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAQH"}