@openclaw/fs-safe 0.14.0 → 0.16.0

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

@@ -0,0 +1,277 @@
+import fs, {} from "node:fs";
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { assertRootIdentityCurrentSync } from "./root-context.js";
+import { directoryComponentNotDirectoryError, outsideWorkspaceError, } from "./root-errors.js";
+import { sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { assertFileLockSyncRootMutationAllowed, assertFileLockSyncRootResolvedPathCurrent, invokeFileLockSyncRootMutationAuthority, } from "./file-lock-sync-root.js";
+import { assertDirectoryCurrent, assertRegularFile, assertRetainedParentCurrent, exactFileIdentity, fileLockSyncRootReceiptStillCurrent, fileReceiptCurrentAfterParentCheck, observeDirectory, readFileLockSyncRootSnapshot, sameExactIdentity, } from "./file-lock-sync-root-io.js";
+import { pathForWindowsFilesystem } from "./windows-path-alias.js";
+function ensureParent(pathAuthority) {
+    const authority = pathAuthority.authority;
+    const context = authority.context;
+    assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+    const targetParent = path.dirname(pathAuthority.path);
+    const admitted = admitPathInsideRoot({
+        rootPath: context.rootReal,
+        candidatePath: targetParent,
+        rootIdentity: context.rootIdentity,
+    });
+    if (!admitted)
+        throw outsideWorkspaceError();
+    const relative = admitted.relativePath;
+    let current = context.rootReal;
+    let currentReceipt = observeDirectory(current);
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        const next = path.join(current, segment);
+        assertRootIdentityCurrentSync(context);
+        assertDirectoryCurrent(currentReceipt);
+        let missing = false;
+        let existing;
+        try {
+            existing = fs.lstatSync(pathForWindowsFilesystem(next), { bigint: true });
+            if (existing.isSymbolicLink() || !existing.isDirectory()) {
+                throw directoryComponentNotDirectoryError();
+            }
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error))
+                throw error;
+            missing = true;
+        }
+        if (missing) {
+            assertFileLockSyncRootMutationAllowed(next, authority.denyMutations);
+            const mutationAuthorityInvoked = invokeFileLockSyncRootMutationAuthority(authority);
+            if (mutationAuthorityInvoked) {
+                assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+            }
+            assertDirectoryCurrent(currentReceipt);
+            assertRootIdentityCurrentSync(context);
+            // The callback may retarget a deny-policy alias at this particular
+            // intermediate component without changing the admitted final sidecar.
+            // Refresh the actual mkdir target after the callback and immediately
+            // before mutation.
+            if (mutationAuthorityInvoked) {
+                assertFileLockSyncRootMutationAllowed(next, authority.denyMutations);
+            }
+            try {
+                fs.mkdirSync(pathForWindowsFilesystem(next));
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        const nextReceipt = observeDirectory(next, existing);
+        assertDirectoryCurrent(currentReceipt);
+        current = nextReceipt.realPath;
+        currentReceipt = nextReceipt;
+    }
+    assertRootIdentityCurrentSync(context);
+    assertDirectoryCurrent(currentReceipt);
+    return currentReceipt;
+}
+export function createFileLockSyncRootFile(pathAuthority, mode, options = {}) {
+    const parent = ensureParent(pathAuthority);
+    if (invokeFileLockSyncRootMutationAuthority(pathAuthority.authority)) {
+        assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+        assertRetainedParentCurrent(pathAuthority, parent);
+    }
+    const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number"
+        ? fs.constants.O_NOFOLLOW
+        : 0;
+    let fd;
+    let receipt;
+    try {
+        options.assertBeforeOpen?.();
+        try {
+            fd = fs.openSync(pathForWindowsFilesystem(pathAuthority.path), fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, mode);
+        }
+        catch (error) {
+            options.onOpenFailure?.(error);
+            throw error;
+        }
+        const opened = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }));
+        assertRegularFile(opened, pathAuthority.authority.hardlinks);
+        receipt = Object.freeze({ identity: exactFileIdentity(opened), parent });
+        if (!fileReceiptCurrentAfterParentCheck(pathAuthority, receipt)) {
+            throw new FsSafeError("path-mismatch", "created sidecar lock changed before admission");
+        }
+        return { fd, receipt };
+    }
+    catch (error) {
+        if (fd === undefined)
+            throw error;
+        const failedFd = fd;
+        fd = undefined;
+        try {
+            fs.closeSync(failedFd);
+            if (receipt && !removeFileLockSyncRootFile(pathAuthority, receipt)) {
+                throw new FsSafeError("path-mismatch", "created sidecar lock changed before cleanup");
+            }
+        }
+        catch (cleanupError) {
+            throw createSuppressedError(error, cleanupError, "file lock create admission and cleanup both failed");
+        }
+        throw error;
+    }
+}
+export function refreshFileLockSyncRootFileReceipt(pathAuthority, receipt) {
+    if (!fileReceiptCurrentAfterParentCheck(pathAuthority, receipt)) {
+        throw new FsSafeError("path-mismatch", "created sidecar lock changed before admission");
+    }
+    return receipt;
+}
+export function removeFileLockSyncRootFile(pathAuthority, receipt, expected, assertBeforeRemove) {
+    assertFileLockSyncRootMutationAllowed(pathAuthority.path, pathAuthority.authority.denyMutations);
+    const matches = () => {
+        if (!expected)
+            return fileLockSyncRootReceiptStillCurrent(pathAuthority, receipt);
+        const current = readFileLockSyncRootSnapshot(pathAuthority, {
+            expectedReceipt: receipt,
+        });
+        const matched = !!current &&
+            sameExactIdentity(current.receipt.identity, receipt.identity) &&
+            sidecarLockSnapshotMatches(current.snapshot, expected);
+        return matched;
+    };
+    if (!matches())
+        return false;
+    if (invokeFileLockSyncRootMutationAuthority(pathAuthority.authority) && !matches())
+        return false;
+    if (assertBeforeRemove?.() === false)
+        return false;
+    assertFileLockSyncRootMutationAllowed(pathAuthority.path, pathAuthority.authority.denyMutations);
+    fs.unlinkSync(pathForWindowsFilesystem(pathAuthority.path));
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    let successorStat;
+    try {
+        successorStat = inspectFileIdentitySync(() => fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true }));
+    }
+    catch (error) {
+        if (isNotFoundPathError(error))
+            return true;
+        throw error;
+    }
+    assertRegularFile(successorStat, pathAuthority.authority.hardlinks);
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    if (!sameExactIdentity(exactFileIdentity(successorStat), receipt.identity))
+        return true;
+    if (expected) {
+        const successor = readFileLockSyncRootSnapshot(pathAuthority);
+        assertRetainedParentCurrent(pathAuthority, receipt.parent);
+        if (successor) {
+            if (!sameExactIdentity(successor.receipt.identity, receipt.identity) ||
+                !sidecarLockSnapshotMatches(successor.snapshot, expected))
+                return true;
+        }
+        else {
+            // A null descriptor-bound snapshot can mean confirmed absence, a distinct
+            // replacement, or unverifiable identity. Re-observe once and accept only
+            // the first two states; ambiguity about the removed generation fails closed.
+            let current;
+            try {
+                current = inspectFileIdentitySync(() => fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true }));
+            }
+            catch (error) {
+                if (isNotFoundPathError(error)) {
+                    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+                    return true;
+                }
+                throw error;
+            }
+            assertRegularFile(current, pathAuthority.authority.hardlinks);
+            assertRetainedParentCurrent(pathAuthority, receipt.parent);
+            if (!sameExactIdentity(exactFileIdentity(current), receipt.identity))
+                return true;
+        }
+    }
+    throw new FsSafeError("path-mismatch", "sidecar lock was replaced during removal");
+}
+export function fileLockSyncRootGuardExists(pathAuthority, pathAlreadyCurrent = false) {
+    if (!pathAlreadyCurrent)
+        assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+    // A shared path admission may skip only duplicate resolution, never this
+    // operation-local Root identity fence before fresh directory inspection.
+    assertRootIdentityCurrentSync(pathAuthority.authority.context);
+    let stat;
+    try {
+        stat = fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true });
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+            assertRootIdentityCurrentSync(pathAuthority.authority.context);
+            return false;
+        }
+        throw error;
+    }
+    if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) {
+        throw directoryComponentNotDirectoryError();
+    }
+    if (stat.isFile())
+        assertRegularFile(stat, pathAuthority.authority.hardlinks);
+    const parent = observeDirectory(path.dirname(pathAuthority.path));
+    if (stat.isFile()) {
+        const current = inspectFileIdentitySync(() => fs.lstatSync(pathForWindowsFilesystem(pathAuthority.path), { bigint: true }), exactFileIdentity(stat));
+        assertRegularFile(current, pathAuthority.authority.hardlinks);
+    }
+    else {
+        inspectDirectoryIdentitySync(pathAuthority.path, exactFileIdentity(stat));
+    }
+    assertDirectoryCurrent(parent);
+    assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+    assertRootIdentityCurrentSync(pathAuthority.authority.context);
+    return true;
+}
+export function createFileLockSyncRootDirectory(pathAuthority) {
+    const parent = ensureParent(pathAuthority);
+    if (invokeFileLockSyncRootMutationAuthority(pathAuthority.authority)) {
+        assertFileLockSyncRootResolvedPathCurrent(pathAuthority);
+        assertRetainedParentCurrent(pathAuthority, parent);
+    }
+    try {
+        fs.mkdirSync(pathForWindowsFilesystem(pathAuthority.path));
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return null;
+        throw error;
+    }
+    const stat = inspectDirectoryIdentitySync(pathAuthority.path);
+    const receipt = Object.freeze({ identity: exactFileIdentity(stat), parent });
+    assertRetainedParentCurrent(pathAuthority, parent);
+    inspectDirectoryIdentitySync(pathAuthority.path, receipt.identity);
+    return receipt;
+}
+export function removeFileLockSyncRootDirectory(pathAuthority, receipt) {
+    if (!fileLockSyncRootDirectoryReceiptStillCurrent(pathAuthority, receipt))
+        return false;
+    assertFileLockSyncRootMutationAllowed(pathAuthority.path, pathAuthority.authority.denyMutations, true);
+    if (invokeFileLockSyncRootMutationAuthority(pathAuthority.authority) &&
+        !fileLockSyncRootDirectoryReceiptStillCurrent(pathAuthority, receipt))
+        return false;
+    assertFileLockSyncRootMutationAllowed(pathAuthority.path, pathAuthority.authority.denyMutations, true);
+    fs.rmdirSync(pathForWindowsFilesystem(pathAuthority.path));
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    return true;
+}
+export function fileLockSyncRootDirectoryReceiptStillCurrent(pathAuthority, receipt) {
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    try {
+        inspectDirectoryIdentitySync(pathAuthority.path, receipt.identity);
+    }
+    catch (error) {
+        if (isNotFoundPathError(error) ||
+            (error instanceof FsSafeError && error.code === "path-mismatch"))
+            return false;
+        throw error;
+    }
+    assertRetainedParentCurrent(pathAuthority, receipt.parent);
+    return true;
+}

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

@@ -0,0 +1,20 @@
+import type { FileLockSyncAcquireOptions } from "./file-lock-sync.js";
+import type { SidecarLockCompromisedInfo, SidecarLockRetryOptions, SidecarLockStaleRecovery } from "./sidecar-lock-types.js";
+type CapturedRootSyncAcquireOptions<TPayload extends Record<string, unknown>> = Readonly<{
+    compromiseCheckIntervalMs?: number;
+    lockPath?: string;
+    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
+    optionsReceiver: FileLockSyncAcquireOptions<TPayload>;
+    parsePayload?: (raw: string) => unknown;
+    payload: () => TPayload;
+    reentrantOwner?: string;
+    retry: Readonly<SidecarLockRetryOptions>;
+    shouldReclaim?: FileLockSyncAcquireOptions<TPayload>["shouldReclaim"];
+    shouldRemoveStaleLock?: FileLockSyncAcquireOptions<TPayload>["shouldRemoveStaleLock"];
+    staleMs: number;
+    staleRecovery?: SidecarLockStaleRecovery;
+    timeoutMs?: number;
+}>;
+export declare function captureRootSyncAcquireOptions<TPayload extends Record<string, unknown>>(options: FileLockSyncAcquireOptions<TPayload>): CapturedRootSyncAcquireOptions<TPayload>;
+export {};
+//# sourceMappingURL=file-lock-sync-root-options.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-root-options.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAItE,OAAO,KAAK,EAAE,0BAA0B,EAAE,uBAAuB,EAC/D,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,KAAK,8BAA8B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC;IACvF,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC3D,eAAe,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IACtD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,OAAO,EAAE,MAAM,QAAQ,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,QAAQ,CAAC,uBAAuB,CAAC,CAAC;IACzC,aAAa,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,CAAC;IACtE,qBAAqB,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC,uBAAuB,CAAC,CAAC;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,wBAAgB,6BAA6B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpF,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,8BAA8B,CAAC,QAAQ,CAAC,CAuD1C"}

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

@@ -0,0 +1,58 @@
+import { getFsSafeLockConfig } from "./lock-config.js";
+import { validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockRetryOptions, validateSidecarLockStaleMs, validateSidecarLockTimeoutMs } from "./sidecar-lock-policy.js";
+export function captureRootSyncAcquireOptions(options) {
+    // Root authority is already validated and snapshotted before entering this
+    // helper. Snapshot every remaining caller-owned property before validating
+    // options; nested retry accessors must not be revisited by backoff or a
+    // callback that mutates the original options object.
+    const lockPath = options.lockPath;
+    const staleMsInput = options.staleMs;
+    const timeoutMsInput = options.timeoutMs;
+    const retryInput = options.retry;
+    const staleRecoveryInput = options.staleRecovery;
+    const reentrantOwner = options.reentrantOwner;
+    const payload = options.payload;
+    const shouldReclaim = options.shouldReclaim;
+    const shouldRemoveStaleLock = options.shouldRemoveStaleLock;
+    const parsePayload = options.parsePayload;
+    const onCompromised = options.onCompromised;
+    const compromiseCheckIntervalMs = options.compromiseCheckIntervalMs;
+    const retrySnapshot = retryInput === undefined ? undefined : Object.freeze({
+        retries: retryInput.retries,
+        factor: retryInput.factor,
+        minTimeout: retryInput.minTimeout,
+        maxTimeout: retryInput.maxTimeout,
+        randomize: retryInput.randomize,
+    });
+    const defaults = getFsSafeLockConfig();
+    const defaultRetry = defaults.retry;
+    const retry = retrySnapshot ?? Object.freeze({
+        retries: defaultRetry?.retries,
+        factor: defaultRetry?.factor,
+        minTimeout: defaultRetry?.minTimeout,
+        maxTimeout: defaultRetry?.maxTimeout,
+        randomize: defaultRetry?.randomize,
+    });
+    const timeoutMs = timeoutMsInput ?? defaults.timeoutMs;
+    const staleMs = staleMsInput ?? defaults.staleMs ?? 30_000;
+    const staleRecovery = staleRecoveryInput ?? defaults.staleRecovery;
+    validateSidecarLockRetryOptions(retry);
+    validateSidecarLockTimeoutMs(timeoutMs);
+    validateSidecarLockStaleMs(staleMs);
+    validateSidecarLockCompromiseCheckIntervalMs(compromiseCheckIntervalMs);
+    return Object.freeze({
+        compromiseCheckIntervalMs,
+        lockPath,
+        onCompromised,
+        optionsReceiver: options,
+        parsePayload,
+        payload,
+        reentrantOwner,
+        retry,
+        shouldReclaim,
+        shouldRemoveStaleLock,
+        staleMs,
+        staleRecovery,
+        timeoutMs,
+    });
+}

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

@@ -0,0 +1,2 @@
+export declare function ensureFileLockSyncRootExitCleanupRegistered(cleanupHandler: () => void): void;
+//# sourceMappingURL=file-lock-sync-root-registration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-root-registration.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-registration.ts"],"names":[],"mappings":"AA+BA,wBAAgB,2CAA2C,CACzD,cAAc,EAAE,MAAM,IAAI,GACzB,IAAI,CAgFN"}

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