@openclaw/fs-safe 0.14.0 → 0.15.0

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

@@ -0,0 +1,90 @@
+import { FsSafeError } from "./errors.js";
+import { createSuppressedError } from "./suppressed-error.js";
+const ROOT_SYNC_CLEANUP_REGISTERING_KEY = Symbol.for("fsSafe.syncRootSidecarLockCleanupRegistering.v1");
+const ROOT_SYNC_CLEANUP_REGISTERED_KEY = Symbol.for("fsSafe.syncRootSidecarLockCleanupRegistered.v1");
+const ROOT_SYNC_CLEANUP_FAILED_KEY = Symbol.for("fsSafe.syncRootSidecarLockCleanupRegistrationFailed.v1");
+const ROOT_SYNC_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.syncRootSidecarLockCleanupHandler.v1");
+function unavailable(message) {
+    return new FsSafeError("helper-unavailable", message);
+}
+function exactListenerCount(listener) {
+    return process.listeners("exit").filter((candidate) => candidate === listener).length;
+}
+export function ensureFileLockSyncRootExitCleanupRegistered(cleanupHandler) {
+    const state = globalThis;
+    if (state[ROOT_SYNC_CLEANUP_REGISTERED_KEY]) {
+        if (typeof state[ROOT_SYNC_CLEANUP_HANDLER_KEY] === "function")
+            return;
+        state[ROOT_SYNC_CLEANUP_FAILED_KEY] = true;
+        throw unavailable("Root sidecar exit cleanup registration state is inconsistent");
+    }
+    if (state[ROOT_SYNC_CLEANUP_FAILED_KEY]) {
+        throw unavailable("Root sidecar exit cleanup registration previously failed");
+    }
+    if (state[ROOT_SYNC_CLEANUP_REGISTERING_KEY]) {
+        throw unavailable("Root sidecar exit cleanup registration is already in progress");
+    }
+    if (state[ROOT_SYNC_CLEANUP_HANDLER_KEY] !== undefined) {
+        state[ROOT_SYNC_CLEANUP_FAILED_KEY] = true;
+        throw unavailable("Root sidecar exit cleanup handler exists without registration");
+    }
+    state[ROOT_SYNC_CLEANUP_REGISTERING_KEY] = true;
+    let baselineCount;
+    let registrationAttempted = false;
+    let registrationStateAmbiguous = false;
+    try {
+        baselineCount = exactListenerCount(cleanupHandler);
+        if (baselineCount !== 0) {
+            registrationStateAmbiguous = true;
+            throw unavailable("Root sidecar exit cleanup listener exists without registration");
+        }
+        registrationAttempted = true;
+        process.on("exit", cleanupHandler);
+        if (exactListenerCount(cleanupHandler) !== baselineCount + 1) {
+            throw unavailable("Root sidecar exit cleanup listener was not registered exactly once");
+        }
+        // Do not expose a callable handler or report success until process.on has
+        // returned and the exact listener registration has been observed.
+        state[ROOT_SYNC_CLEANUP_HANDLER_KEY] = cleanupHandler;
+        state[ROOT_SYNC_CLEANUP_REGISTERED_KEY] = true;
+        state[ROOT_SYNC_CLEANUP_FAILED_KEY] = false;
+        state[ROOT_SYNC_CLEANUP_REGISTERING_KEY] = false;
+    }
+    catch (registrationError) {
+        let rollbackFailed = false;
+        let rollbackError;
+        if (registrationAttempted && baselineCount !== undefined) {
+            try {
+                let currentCount = exactListenerCount(cleanupHandler);
+                while (currentCount > baselineCount) {
+                    process.removeListener("exit", cleanupHandler);
+                    const nextCount = exactListenerCount(cleanupHandler);
+                    if (nextCount >= currentCount) {
+                        throw unavailable("Root sidecar exit cleanup listener rollback made no progress");
+                    }
+                    currentCount = nextCount;
+                }
+                if (currentCount !== baselineCount) {
+                    throw unavailable("Root sidecar exit cleanup listener rollback was ambiguous");
+                }
+            }
+            catch (error) {
+                rollbackFailed = true;
+                rollbackError = error;
+            }
+        }
+        state[ROOT_SYNC_CLEANUP_HANDLER_KEY] = undefined;
+        state[ROOT_SYNC_CLEANUP_REGISTERED_KEY] = false;
+        state[ROOT_SYNC_CLEANUP_REGISTERING_KEY] = false;
+        if (registrationStateAmbiguous) {
+            state[ROOT_SYNC_CLEANUP_FAILED_KEY] = true;
+            throw registrationError;
+        }
+        if (rollbackFailed) {
+            state[ROOT_SYNC_CLEANUP_FAILED_KEY] = true;
+            throw createSuppressedError(registrationError, rollbackError, "Root sidecar exit cleanup registration and rollback both failed");
+        }
+        state[ROOT_SYNC_CLEANUP_FAILED_KEY] = false;
+        throw registrationError;
+    }
+}

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

@@ -0,0 +1,36 @@
+import { type RootContext } from "./root-context.js";
+import type { Root, RootDefaults } from "./root-impl.js";
+/** @internal Registers only instances constructed by RootHandle itself. */
+export declare function registerFileLockSyncRootAdapter(handle: object, context: RootContext, defaults: RootDefaults): void;
+export type FileLockSyncRootAuthority = Readonly<{
+    adapter: object;
+    context: RootContext;
+    assertBeforeMutation?: () => void;
+    denyMutations?: Readonly<{
+        paths?: readonly string[];
+        prefixes?: readonly string[];
+    }>;
+    hardlinks?: RootDefaults["hardlinks"];
+    mutationPolicy: RootPathResolutionPolicy;
+    readPolicy: RootPathResolutionPolicy;
+    policiesMatch: boolean;
+}>;
+export type FileLockSyncRootPath = Readonly<{
+    authority: FileLockSyncRootAuthority;
+    path: string;
+    relativePath: string;
+}>;
+export declare function captureFileLockSyncRootAuthority(lockRoot: Root): FileLockSyncRootAuthority;
+export declare function invokeFileLockSyncRootMutationAuthority(authority: FileLockSyncRootAuthority): boolean;
+export declare function assertFileLockSyncRootMutationAllowed(pathname: string, policy: FileLockSyncRootAuthority["denyMutations"], protectAncestors?: boolean): void;
+type RootPathResolutionPolicy = Readonly<{
+    rejectSymlinks?: boolean;
+    rejectFinalSymlink?: boolean;
+    rejectUnresolvedSymlinks: true;
+}>;
+export declare function admitFileLockSyncRootPath(authority: FileLockSyncRootAuthority, requestedPath: string): FileLockSyncRootPath;
+export declare function assertFileLockSyncRootResolvedPathCurrent(pathAuthority: FileLockSyncRootPath): void;
+export declare function assertFileLockSyncRootPathsCurrent(paths: readonly FileLockSyncRootPath[], invokeAuthority?: boolean, pathsAlreadyCurrent?: boolean): void;
+export declare function normalizeFileLockSyncTargetWithRoot(authority: FileLockSyncRootAuthority, resolvedTargetPath: string): string;
+export {};
+//# sourceMappingURL=file-lock-sync-root.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-root.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAgBzD,2EAA2E;AAC3E,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,YAAY,GACrB,IAAI,CAON;AAED,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC;IACrB,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,aAAa,CAAC,EAAE,QAAQ,CAAC;QACvB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC1B,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAC9B,CAAC,CAAC;IACH,SAAS,CAAC,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;IACtC,cAAc,EAAE,wBAAwB,CAAC;IACzC,UAAU,EAAE,wBAAwB,CAAC;IACrC,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,SAAS,EAAE,yBAAyB,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CAAC;AAcH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,IAAI,GACb,yBAAyB,CAkD3B;AAED,wBAAgB,uCAAuC,CACrD,SAAS,EAAE,yBAAyB,GACnC,OAAO,CAOT;AAuDD,wBAAgB,qCAAqC,CACnD,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,yBAAyB,CAAC,eAAe,CAAC,EAClD,gBAAgB,UAAQ,GACvB,IAAI,CAsBN;AAED,KAAK,wBAAwB,GAAG,QAAQ,CAAC;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,wBAAwB,EAAE,IAAI,CAAC;CAChC,CAAC,CAAC;AA6FH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,yBAAyB,EACpC,aAAa,EAAE,MAAM,GACpB,oBAAoB,CAetB;AAED,wBAAgB,yCAAyC,CACvD,aAAa,EAAE,oBAAoB,GAClC,IAAI,CASN;AAwBD,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,SAAS,oBAAoB,EAAE,EACtC,eAAe,UAAQ,EACvB,mBAAmB,UAAQ,GAC1B,IAAI,CAuBN;AAwCD,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,yBAAyB,EACpC,kBAAkB,EAAE,MAAM,GACzB,MAAM,CAeR"}

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