@openclaw/fs-safe 0.14.0 → 0.15.0

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

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