@openclaw/fs-safe 0.15.0 → 0.17.0

package/dist/directory-durability.js

@@ -3,7 +3,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { ensureAbsoluteDirectory } from "./absolute-path.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { assertDirectoryReceiptCurrentSync, copyRetainedDirectoryReceipt, createDirectoryReceiptSync, directoryReceiptAuthority, directoryReceiptIdentity, ownDirectoryReceipt, } from "./directory-receipt.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
 import { realpathSync } from "./realpath.js";
 function directoryOpenFlags() {
@@ -38,81 +39,23 @@ function unsupportedOutcome(error) {
     const code = error.code;
     return code ? { status: "unsupported", code } : { status: "unsupported" };
 }
-function assertDirectory(identity, pathname, label) {
-    if (identity.isSymbolicLink() || !identity.isDirectory()) {
-        throw new FsSafeError("not-file", `${label} must be a real directory: ${pathname}`);
-    }
-}
-function ownDirectoryReceipt(receipt) {
-    const pathname = receipt.path;
-    const realPath = receipt.realPath;
-    const identity = receipt.identity;
-    return { path: pathname, realPath, identity };
-}
-function assertDirectoryReceiptPaths(receipt, label) {
-    assertNoWindowsPathAlias(receipt.path, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
-    assertNoWindowsPathAlias(receipt.realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
-}
 async function createDirectoryReceipt(directoryPath, label) {
-    assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
-    const resolvedPath = resolvePathPreservingWindowsRoot(directoryPath);
-    assertNoWindowsPathAlias(resolvedPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
-    const operationPath = pathForWindowsFilesystem(resolvedPath);
-    const identity = fsSync.lstatSync(operationPath);
-    assertDirectory(identity, resolvedPath, label);
-    const realPath = realpathSync.native(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
-    return {
-        path: resolvedPath,
-        realPath,
-        identity,
-    };
-}
-function createDirectoryReceiptSync(directoryPath, label) {
-    assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
-    const resolvedPath = resolvePathPreservingWindowsRoot(directoryPath);
-    assertNoWindowsPathAlias(resolvedPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
-    const operationPath = pathForWindowsFilesystem(resolvedPath);
-    const identity = fsSync.lstatSync(operationPath);
-    assertDirectory(identity, resolvedPath, label);
-    const realPath = realpathSync(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
-    return {
-        path: resolvedPath,
-        realPath,
-        identity,
-    };
+    return createDirectoryReceiptSync(directoryPath, label, realpathSync.native);
 }
 async function assertDirectoryReceiptCurrent(receipt, label) {
-    assertDirectoryReceiptPaths(receipt, label);
-    const operationPath = pathForWindowsFilesystem(receipt.path);
-    const currentIdentity = fsSync.lstatSync(operationPath);
-    assertDirectory(currentIdentity, receipt.path, label);
-    const realPath = realpathSync.native(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
-    if (!sameFileIdentity(receipt.identity, currentIdentity) ||
-        realPath !== receipt.realPath) {
-        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
-    }
+    assertDirectoryReceiptCurrentSync(receipt, label, realpathSync.native);
 }
-function assertDirectoryReceiptCurrentSync(receipt, label) {
-    assertDirectoryReceiptPaths(receipt, label);
-    const operationPath = pathForWindowsFilesystem(receipt.path);
-    const currentIdentity = fsSync.lstatSync(operationPath);
-    assertDirectory(currentIdentity, receipt.path, label);
-    const realPath = realpathSync(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
-    if (!sameFileIdentity(receipt.identity, currentIdentity) ||
-        realPath !== receipt.realPath) {
-        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
-    }
+function assertOpenDirectoryIdentity(descriptor, receipt, label) {
+    inspectFileIdentitySync(() => {
+        const opened = fsSync.fstatSync(descriptor, { bigint: true });
+        if (!opened.isDirectory()) {
+            throw new FsSafeError("not-file", `${label} must be a real directory: ${receipt.path}`);
+        }
+        return opened;
+    }, directoryReceiptAuthority(receipt).identity);
 }
 async function assertOpenDirectoryCurrent(handle, receipt, label) {
-    const openedIdentity = fsSync.fstatSync(handle.fd);
-    assertDirectory(openedIdentity, receipt.path, label);
-    if (!sameFileIdentity(receipt.identity, openedIdentity)) {
-        throw new FsSafeError("path-mismatch", `${label} handle changed during directory sync: ${receipt.path}`);
-    }
+    assertOpenDirectoryIdentity(handle.fd, receipt, label);
     await assertDirectoryReceiptCurrent(receipt, label);
 }
 class PinnedDirectoryImpl {
@@ -124,7 +67,7 @@ class PinnedDirectoryImpl {
     constructor(handle, receipt, label) {
         this.#handle = handle;
         this.#authority = receipt;
-        this.receipt = ownDirectoryReceipt(receipt);
+        this.receipt = copyRetainedDirectoryReceipt(receipt);
         this.#label = label;
     }
     async assertCurrent() {
@@ -213,11 +156,7 @@ export function syncDirectorySync(directory, options = {}) {
         return unsupportedOutcome(error);
     }
     try {
-        const openedIdentity = fsSync.fstatSync(descriptor);
-        assertDirectory(openedIdentity, receipt.path, label);
-        if (!sameFileIdentity(receipt.identity, openedIdentity)) {
-            throw new FsSafeError("path-mismatch", `${label} handle changed during directory sync: ${receipt.path}`);
-        }
+        assertOpenDirectoryIdentity(descriptor, receipt, label);
         assertDirectoryReceiptCurrentSync(receipt, label);
         try {
             fsSync.fsyncSync(descriptor);
@@ -273,13 +212,16 @@ export async function ensureDurableDirectory(options) {
     assertNoWindowsPathAlias(requestedDirectoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
     const directoryPath = resolvePathPreservingWindowsRoot(requestedDirectoryPath);
     assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const expectedInput = options.expectedExistingIdentity;
+    const expectedIdentity = expectedInput && directoryReceiptIdentity(expectedInput);
     const ancestorReceipt = await findExistingAncestorReceipt(directoryPath, label);
     const targetExists = ancestorReceipt.path === directoryPath;
-    const expectedExistingIdentity = options.expectedExistingIdentity;
-    if (expectedExistingIdentity &&
-        (!targetExists || !sameFileIdentity(expectedExistingIdentity, ancestorReceipt.identity))) {
+    if (expectedIdentity && !targetExists) {
         throw new FsSafeError("path-mismatch", `${label} changed before durable directory pinning: ${directoryPath}`);
     }
+    if (expectedIdentity) {
+        inspectFileIdentitySync(() => directoryReceiptAuthority(ancestorReceipt).identity, expectedIdentity);
+    }
     const ancestor = await pinDirectory(ancestorReceipt, { label });
     const pinnedDirectories = [ancestor];
     try {
@@ -336,7 +278,7 @@ export async function ensureDurableDirectory(options) {
         }
         await ancestor.assertCurrent();
         await assertDirectoryReceiptCurrent(finalReceipt, label);
-        return { ...finalReceipt, parentSync };
+        return Object.assign(copyRetainedDirectoryReceipt(finalReceipt), { parentSync });
     }
     finally {
         await Promise.all(pinnedDirectories.toReversed().map(async (directory) => directory.close()));

package/dist/directory-guard.d.ts

@@ -34,6 +34,9 @@ export declare function assertAsyncDirectoryGuard(guard: AnyAsyncDirectoryGuard)
 export declare function createSyncDirectoryGuard(dir: string): SyncDirectoryGuard;
 export declare function assertSyncDirectoryGuard(guard: SyncDirectoryGuard | AnyAsyncDirectoryGuard): void;
 export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string): Promise<AsyncDirectoryGuard>;
+export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
+    bigint: true;
+}): Promise<AsyncDirectoryGuard<BigIntStats>>;
 export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
     bigint: boolean;
 }): Promise<AnyAsyncDirectoryGuard>;

package/dist/directory-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"directory-guard.d.ts","sourceRoot":"","sources":["../src/directory-guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"directory-guard.d.ts","sourceRoot":"","sources":["../src/directory-guard.ts"],"names":[],"mappings":"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"}

package/dist/directory-mode-node.d.ts

@@ -1,5 +1,7 @@
 import { type BigIntStats } from "node:fs";
 import { type DirectoryModeOwner } from "./directory-mode-owner.js";
+/** Darwin descriptor inspection avoids requesting directory-content reads. */
+export declare function nodeDarwinDirectoryMetadataFlags(): number;
 export declare function nodeDirectorySearchOnlyFlags(): {
     flags: number;
     proc: boolean;

package/dist/directory-mode-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"directory-mode-node.d.ts","sourceRoot":"","sources":["../src/directory-mode-node.ts"],"names":[],"mappings":"AAAA,OAAe,EAAa,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAK9D,OAAO,EAA0C,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE5G,wBAAgB,4BAA4B,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAO3F;AAED,2FAA2F;AAC3F,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,OAAO,CAAC,kBAAkB,CAAC,CAsE7B;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE;IAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE,CAsFlE"}
+{"version":3,"file":"directory-mode-node.d.ts","sourceRoot":"","sources":["../src/directory-mode-node.ts"],"names":[],"mappings":"AAAA,OAAe,EAAa,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAK9D,OAAO,EAA0C,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE5G,8EAA8E;AAC9E,wBAAgB,gCAAgC,IAAI,MAAM,CAMzD;AAED,wBAAgB,4BAA4B,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAO3F;AAED,2FAA2F;AAC3F,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,OAAO,CAAC,kBAAkB,CAAC,CAsE7B;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE;IAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE,CAsFlE"}

package/dist/directory-mode-node.js

@@ -4,6 +4,14 @@ import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertOwnedDirectory, ownDirectoryMode } from "./directory-mode-owner.js";
+/** Darwin descriptor inspection avoids requesting directory-content reads. */
+export function nodeDarwinDirectoryMetadataFlags() {
+    if (process.platform !== "darwin" || (process.arch !== "x64" && process.arch !== "arm64")) {
+        throw new FsSafeError("helper-unavailable", "Darwin directory metadata descriptors are unavailable");
+    }
+    // Darwin SDK O_EVTONLY; Node omits this flag from its exported constants.
+    return 0x8000 | constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+}
 export function nodeDirectorySearchOnlyFlags() {
     if (process.arch !== "x64" && process.arch !== "arm64")
         return undefined;

package/dist/directory-receipt.d.ts

@@ -0,0 +1,24 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { FileIdentityStat } from "./file-identity.js";
+type ExactIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
+declare const numericFields: readonly ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"];
+declare const timeFields: readonly ["atime", "mtime", "ctime", "birthtime"];
+type DirectoryMetadata = Pick<Stats, typeof numericFields[number] | `${typeof timeFields[number]}Ms`>;
+type DirectoryProvenance = Readonly<{
+    identity: ExactIdentity;
+    metadata: Readonly<DirectoryMetadata>;
+}>;
+type DirectoryAuthority = DirectoryProvenance & Readonly<{
+    path: string;
+    realPath: string;
+}>;
+export declare function directoryReceiptIdentity(identity: FileIdentityStat): ExactIdentity;
+export declare function directoryReceiptAuthority(receipt: DirectoryReceipt<Stats | BigIntStats>): DirectoryAuthority;
+export declare function ownDirectoryReceipt(receipt: DirectoryReceipt<Stats | BigIntStats>): DirectoryReceipt;
+export declare function copyRetainedDirectoryReceipt(receipt: DirectoryReceipt): DirectoryReceipt;
+export declare function createDirectoryReceiptFromIdentity(pathname: string, realPath: string, exactStat: BigIntStats): DirectoryReceipt;
+export declare function createDirectoryReceiptSync(directoryPath: string, label: string, canonicalize?: (pathname: string) => string): DirectoryReceipt;
+export declare function assertDirectoryReceiptCurrentSync(receipt: DirectoryReceipt, label: string, canonicalize?: (pathname: string) => string): void;
+export {};
+//# sourceMappingURL=directory-receipt.d.ts.map

package/dist/directory-receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-receipt.d.ts","sourceRoot":"","sources":["../src/directory-receipt.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAQ3D,KAAK,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;AAChE,QAAA,MAAM,aAAa,YAAI,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAClH,QAAA,MAAM,UAAU,YAAI,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,CAAU,CAAC;AACrE,KAAK,iBAAiB,GAAG,IAAI,CAAC,KAAK,EAAE,OAAO,aAAa,CAAC,MAAM,CAAC,GAAG,GAAG,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACtG,KAAK,mBAAmB,GAAG,QAAQ,CAAC;IAClC,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;CACvC,CAAC,CAAC;AACH,KAAK,kBAAkB,GAAG,mBAAmB,GAAG,QAAQ,CAAC;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAOH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,aAAa,CAuBlF;AAsCD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,kBAAkB,CAE5G;AAQD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,gBAAgB,CAEpG;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAGxF;AAWD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,WAAW,GACrB,gBAAgB,CASlB;AAED,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,YAAY,GAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAqB,GACxD,gBAAgB,CASlB;AAED,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,MAAM,EACb,YAAY,GAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAqB,GACxD,IAAI,CAUN"}

package/dist/directory-receipt.js

@@ -0,0 +1,123 @@
+import fs, {} from "node:fs";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const numericFields = ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"];
+const timeFields = ["atime", "mtime", "ctime", "birthtime"];
+// Live pins retain private authority. New admissions snapshot the supplied
+// fields and accept exact provenance only while its public identity is intact.
+const authorities = new WeakMap();
+const identities = new WeakMap();
+export function directoryReceiptIdentity(identity) {
+    if (!identity) {
+        throw new FsSafeError("path-mismatch", "directory receipt identity is missing");
+    }
+    const known = identities.get(identity);
+    const dev = identity.dev;
+    const ino = identity.ino;
+    if (known) {
+        const matches = (value, expected) => typeof value === "bigint" ? value === expected : value === Number(expected);
+        if (!matches(dev, known.identity.dev) || !matches(ino, known.identity.ino)) {
+            throw new FsSafeError("path-mismatch", "directory receipt identity changed");
+        }
+        return known.identity;
+    }
+    const exact = (value) => {
+        if ((typeof value !== "bigint" && !Number.isSafeInteger(value)) ||
+            (process.platform === "win32" && (value === 0 || value === 0n))) {
+            throw new FsSafeError("path-mismatch", "directory receipt identity could not be verified");
+        }
+        return BigInt(value);
+    };
+    return Object.freeze({ dev: exact(dev), ino: exact(ino) });
+}
+function snapshotDirectoryReceipt(receipt) {
+    const pathname = receipt?.path;
+    const realPath = receipt?.realPath;
+    const stat = receipt?.identity;
+    if (typeof pathname !== "string" || typeof realPath !== "string" || stat == null) {
+        throw new FsSafeError("path-mismatch", "directory receipt is incomplete");
+    }
+    assertNoWindowsPathAlias(pathname, "filesystem");
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    const identity = directoryReceiptIdentity(stat);
+    const known = authorities.get(receipt);
+    if (known && (pathname !== known.path || realPath !== known.realPath ||
+        identity.dev !== known.identity.dev || identity.ino !== known.identity.ino)) {
+        throw new FsSafeError("path-mismatch", "directory receipt changed before admission");
+    }
+    const metadata = known?.metadata ?? identities.get(stat)?.metadata ?? snapshotDirectoryMetadata(stat, identity);
+    return Object.freeze({ path: pathname, realPath, identity, metadata });
+}
+function snapshotDirectoryMetadata(stat, identity) {
+    const metadata = {};
+    for (const field of numericFields) {
+        metadata[field] = Number(field === "dev" || field === "ino" ? identity[field] : stat[field]);
+    }
+    for (const field of timeFields) {
+        if ("atimeNs" in stat) {
+            const nanoseconds = stat[`${field}Ns`];
+            const remainder = ((nanoseconds % 1000000000n) + 1000000000n) % 1000000000n;
+            metadata[`${field}Ms`] = Number((nanoseconds - remainder) / 1000000000n) * 1_000 + Number(remainder) / 1_000_000;
+        }
+        else {
+            metadata[`${field}Ms`] = stat[`${field}Ms`];
+        }
+    }
+    return Object.freeze(metadata);
+}
+export function directoryReceiptAuthority(receipt) {
+    return authorities.get(receipt) ?? snapshotDirectoryReceipt(receipt);
+}
+function rememberReceipt(receipt, authority) {
+    authorities.set(receipt, authority);
+    identities.set(receipt.identity, authority);
+    return receipt;
+}
+export function ownDirectoryReceipt(receipt) {
+    return receiptFromAuthority(snapshotDirectoryReceipt(receipt));
+}
+export function copyRetainedDirectoryReceipt(receipt) {
+    const authority = directoryReceiptAuthority(receipt);
+    return receiptFromAuthority(authority);
+}
+function receiptFromAuthority(authority) {
+    return rememberReceipt({
+        path: authority.path,
+        realPath: authority.realPath,
+        identity: Object.assign(Object.create(fs.Stats.prototype), authority.metadata),
+    }, authority);
+}
+// The caller already admitted the exact observation and its paths.
+export function createDirectoryReceiptFromIdentity(pathname, realPath, exactStat) {
+    const identity = Object.freeze({ dev: exactStat.dev, ino: exactStat.ino });
+    return receiptFromAuthority(Object.freeze({
+        path: pathname,
+        realPath,
+        identity,
+        // Project metadata from the admitted observation, never a fresh pathname stat.
+        metadata: snapshotDirectoryMetadata(exactStat, identity),
+    }));
+}
+export function createDirectoryReceiptSync(directoryPath, label, canonicalize = realpathSync) {
+    assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const pathname = resolvePathPreservingWindowsRoot(directoryPath);
+    assertNoWindowsPathAlias(pathname, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const exact = inspectDirectoryIdentitySync(pathname);
+    const operationPath = pathForWindowsFilesystem(pathname);
+    const realPath = canonicalize(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    return createDirectoryReceiptFromIdentity(pathname, realPath, exact);
+}
+export function assertDirectoryReceiptCurrentSync(receipt, label, canonicalize = realpathSync) {
+    const authority = directoryReceiptAuthority(receipt);
+    assertNoWindowsPathAlias(authority.path, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    assertNoWindowsPathAlias(authority.realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    inspectDirectoryIdentitySync(authority.path, authority.identity);
+    const realPath = canonicalize(pathForWindowsFilesystem(authority.path));
+    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    if (realPath !== authority.realPath) {
+        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${authority.path}`);
+    }
+}

package/dist/file-cleanup.d.ts

@@ -0,0 +1,20 @@
+import { type BigIntStats } from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+export declare function readErrorCode(error: unknown): unknown;
+export declare function hasErrorCode(error: unknown, expected: string): boolean;
+type OwnedPathCleanupStatus = "removed" | "name-absent" | "preserved";
+export declare function removeOwnedPath(params: {
+    fsModule: Pick<typeof fs, "lstat" | "unlink">;
+    pathname: string;
+    identity?: BigIntStats;
+}): Promise<OwnedPathCleanupStatus>;
+export declare function cleanupPinnedFilePath(params: {
+    pathname: string;
+    handle: Pick<FileHandle, "fd">;
+    identity?: BigIntStats;
+    parentGuard: AnyAsyncDirectoryGuard;
+    throwOnCleanupError?: boolean;
+}): Promise<OwnedPathCleanupStatus>;
+export {};
+//# sourceMappingURL=file-cleanup.d.ts.map

package/dist/file-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cleanup.d.ts","sourceRoot":"","sources":["../src/file-cleanup.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAA6B,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAI9F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASrD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,KAAK,sBAAsB,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;AAEtE,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,QAAQ,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAoBlC;AAGD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,WAAW,EAAE,sBAAsB,CAAC;IACpC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAgClC"}

package/dist/file-cleanup.js

@@ -0,0 +1,81 @@
+import syncFs, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { assertAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+export function readErrorCode(error) {
+    if ((typeof error !== "object" || error === null) && typeof error !== "function") {
+        return undefined;
+    }
+    try {
+        return Reflect.get(error, "code");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function hasErrorCode(error, expected) {
+    return readErrorCode(error) === expected;
+}
+export async function removeOwnedPath(params) {
+    if (!params.identity)
+        return "preserved";
+    try {
+        const current = params.fsModule === fs
+            ? syncFs.lstatSync(params.pathname, { bigint: true })
+            : await params.fsModule.lstat(params.pathname, { bigint: true });
+        if (current.isSymbolicLink() ||
+            !current.isFile() ||
+            current.nlink !== 1n ||
+            !sameFileIdentityForCleanup(current, params.identity)) {
+            return "preserved";
+        }
+        await params.fsModule.unlink(params.pathname);
+        return "removed";
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT"))
+            return "name-absent";
+        throw error;
+    }
+}
+// Borrowed handle: the caller retains it until guarded cleanup finishes.
+export async function cleanupPinnedFilePath(params) {
+    if (!params.identity)
+        return "preserved";
+    try {
+        const guard = params.parentGuard;
+        if ([guard.stat.dev, guard.stat.ino].some((value) => typeof value === "number" && !Number.isSafeInteger(value)))
+            return "preserved";
+        await assertAsyncDirectoryGuard(guard);
+        const parent = syncFs.lstatSync(guard.dir, { bigint: true });
+        if (parent.isSymbolicLink() || !parent.isDirectory() ||
+            !sameFileIdentityForCleanup(parent, guard.stat))
+            return "preserved";
+        const opened = syncFs.fstatSync(params.handle.fd, { bigint: true });
+        if (!opened.isFile() || opened.nlink !== 1n ||
+            !sameFileIdentityForCleanup(opened, params.identity))
+            return "preserved";
+    }
+    catch (error) {
+        // Unverifiable authority must preserve the path and the original write failure.
+        if (params.throwOnCleanupError &&
+            !(error instanceof FsSafeError && error.category === "policy") &&
+            !hasErrorCode(error, "ENOENT") && !hasErrorCode(error, "ENOTDIR") &&
+            !hasErrorCode(error, "ELOOP"))
+            throw error;
+        return "preserved";
+    }
+    try {
+        return await removeOwnedPath({
+            fsModule: fs,
+            pathname: params.pathname,
+            identity: params.identity,
+        });
+    }
+    catch (error) {
+        if (params.throwOnCleanupError)
+            throw error;
+        return "preserved";
+    }
+}

package/dist/file-contents.d.ts

@@ -0,0 +1,6 @@
+export type SameFileContentsOptions = {
+    maxBytes?: number;
+};
+/** Compares borrowed regular files from offset zero without moving or closing either descriptor. */
+export declare function sameFileContentsSync(leftFd: number, rightFd: number, options?: SameFileContentsOptions): boolean;
+//# sourceMappingURL=file-contents.d.ts.map

package/dist/file-contents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-contents.d.ts","sourceRoot":"","sources":["../src/file-contents.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,oGAAoG;AACpG,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAgCT"}

package/dist/file-contents.js

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { readFileWindowFullySync } from "./positional-read.js";
+/** Compares borrowed regular files from offset zero without moving or closing either descriptor. */
+export function sameFileContentsSync(leftFd, rightFd, options = {}) {
+    const maxBytes = normalizeMaxBytes(options.maxBytes) ?? Infinity;
+    const limit = Math.min(maxBytes, Number.MAX_SAFE_INTEGER);
+    const tooLarge = () => new FsSafeError("too-large", `file comparison exceeds ${limit} bytes`);
+    for (const fd of [leftFd, rightFd]) {
+        const stat = fs.fstatSync(fd, { bigint: true });
+        if (!stat.isFile()) {
+            throw new FsSafeError("not-file", "file comparison requires regular-file descriptors");
+        }
+        if (stat.size > BigInt(limit))
+            throw tooLarge();
+    }
+    const left = Buffer.allocUnsafe(Math.min(1024 * 1024, Math.max(1, limit)));
+    const right = Buffer.allocUnsafe(left.length);
+    let position = 0;
+    while (true) {
+        const length = Math.min(left.length, limit - position);
+        if (length === 0) {
+            // Probe EOF at the limit without forming an unsafe exclusive window end.
+            const leftExtra = fs.readSync(leftFd, left, 0, 1, position);
+            const rightExtra = fs.readSync(rightFd, right, 0, 1, position);
+            if (leftExtra !== 0 || rightExtra !== 0)
+                throw tooLarge();
+            return true;
+        }
+        const leftRead = readFileWindowFullySync(leftFd, left.subarray(0, length), position);
+        const rightRead = readFileWindowFullySync(rightFd, right.subarray(0, length), position);
+        if (leftRead !== rightRead || !left.subarray(0, leftRead).equals(right.subarray(0, rightRead))) {
+            return false;
+        }
+        if (leftRead < length)
+            return true;
+        position += leftRead;
+    }
+}

package/dist/file-hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-hash.d.ts","sourceRoot":"","sources":["../src/file-hash.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAKnE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;AAClD,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,CAAC;AAElD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,aAAa,GAAG,SAA8B,EACtD,EAAE,QAAmB,EAAE,MAAM,EAAE,GAAE,iBAAsB,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAwD3B;AA0DD,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAwDD,8FAA8F;AAC9F,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAMlB"}
+{"version":3,"file":"file-hash.d.ts","sourceRoot":"","sources":["../src/file-hash.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAKnE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;AAClD,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,CAAC;AAElD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,aAAa,GAAG,SAA8B,EACtD,EAAE,QAAmB,EAAE,MAAM,EAAE,GAAE,iBAAsB,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAwD3B;AA8DD,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AA2DD,8FAA8F;AAC9F,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAMlB"}

package/dist/file-hash.js

@@ -99,14 +99,20 @@ async function hashPath(filePath, options) {
     catch (error) {
         rethrowHashOpenError(error);
     }
+    let completed = false;
     try {
         options.signal?.throwIfAborted();
         const opened = await inspectFileIdentity(() => hashDescriptorIdentity(handle.fd), before);
         await inspectFileIdentity(() => hashPathIdentity(filePath, true), opened);
-        return await hashFileHandle(handle, getNativeBinding(), options);
+        const result = await hashFileHandle(handle, getNativeBinding(), options);
+        completed = true;
+        return result;
     }
     finally {
-        await handle.close().catch(() => undefined);
+        if (completed)
+            await handle.close();
+        else
+            await handle.close().catch(() => undefined);
     }
 }
 export async function sha256File(input, options = {}) {
@@ -157,17 +163,23 @@ function hashPathSync(filePath, options) {
     catch (error) {
         rethrowHashOpenError(error);
     }
+    let completed = false;
     try {
         options.signal?.throwIfAborted();
         const opened = inspectFileIdentitySync(() => hashDescriptorIdentity(fd), before);
         inspectFileIdentitySync(() => hashPathIdentity(filePath, true), opened);
-        return hashDescriptorSync(fd, options);
+        const result = hashDescriptorSync(fd, options);
+        completed = true;
+        return result;
     }
     finally {
         try {
             fsSync.closeSync(fd);
         }
-        catch { /* Preserve the hashing outcome. */ }
+        catch (error) {
+            if (completed)
+                throw error;
+        }
     }
 }
 /** Hash synchronously from offset zero, retaining ownership and position of a borrowed fd. */

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

@@ -1 +1 @@
-{"version":3,"file":"file-lock-sync-root-acquire.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-acquire.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAgD3C,wBAAgB,2BAA2B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClF,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,0BAA0B,CAAC,QAAQ,CAAC,EAClD,QAAQ,EAAE,IAAI,GACb,kBAAkB,CA8VpB"}
+{"version":3,"file":"file-lock-sync-root-acquire.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-acquire.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAiD3C,wBAAgB,2BAA2B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClF,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,0BAA0B,CAAC,QAAQ,CAAC,EAClD,QAAQ,EAAE,IAAI,GACb,kBAAkB,CAgWpB"}

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

@@ -7,6 +7,7 @@ import { computeSidecarLockDelayMs, isTransientLockFileDenial, maxTransientLockD
 import { serializeSidecarLockPayload, } from "./sidecar-lock-reclaim.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { sleepSync } from "./timing.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { admitFileLockSyncRootPath, assertFileLockSyncRootPathsCurrent, captureFileLockSyncRootAuthority, normalizeFileLockSyncTargetWithRoot, } from "./file-lock-sync-root.js";
 import { cleanupCreatedRootSyncLock, FileLockSyncRootArbitrationCollision, tryReuseCurrentRootSyncHeldLock, } from "./file-lock-sync-root-arbitration.js";
@@ -299,6 +300,7 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                             nowMs,
                             heldByThisProcess: false,
                         }]);
+                    assertSynchronousCallbackResult(reclaim, "shouldReclaim");
                     assertAdmission();
                     if (!fileLockSyncRootSnapshotStillCurrent(lockRootPath, current)) {
                         throw new FsSafeError("path-mismatch", "sidecar changed during reclaim policy callback");
@@ -324,6 +326,7 @@ export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot)
                                 raw: snapshot.raw,
                                 payload: snapshot.payload,
                             }]);
+                        assertSynchronousCallbackResult(approved, "shouldRemoveStaleLock");
                         assertAdmission();
                         assertOwnedReclaimGuardCurrent();
                         if (approved) {

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

@@ -28,7 +28,6 @@ export declare function getRootSyncHeldLocks(): Map<string, RootSyncHeldLock>;
 export declare function ensureRootSyncExitCleanupRegistered(): void;
 export declare function verifyRootSyncHeldLock(held: RootSyncHeldLock): boolean;
 export declare function createRootSyncHeldLockHandle(held: RootSyncHeldLock): FileLockSyncHandle;
-export declare function isRootSyncHeldLockHandle(handle: FileLockSyncHandle): boolean;
-export declare function withRootSyncHeldLockHandle<T>(lock: FileLockSyncHandle, fn: () => T): T;
+export declare function withSyncHeldLockHandle<T>(lock: FileLockSyncHandle, fn: () => T): T;
 export {};
 //# sourceMappingURL=file-lock-sync-root-held.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"file-lock-sync-root-held.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-held.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAIL,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC9B,MAAM,6BAA6B,CAAC;AAQrC,KAAK,4BAA4B,GAAG,QAAQ,GAAG,WAAW,GAAG,eAAe,GAAG,UAAU,CAAC;AAE1F,KAAK,iCAAiC,GAAG;IACvC,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAOF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oBAAoB,CAAC,EAAE,GAAG,CAAC,iCAAiC,CAAC,CAAC;IAC9D,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,4BAA4B,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,yBAAyB,CAAC;IACzC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,WAAW,EAAE,2BAA2B,CAAC;IACzC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CACxB,CAAC;AAQF,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,oBAAoB,EAC9B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,EACvC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EACxC,eAAe,CAAC,EAAE,2BAA2B,GAC5C,wBAAwB,GAAG,IAAI,CAmCjC;AAED,wBAAgB,oBAAoB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAQpE;AA+KD,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAWtE;AAsHD,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,CAqBvF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAE5E;AAED,wBAAgB,0BAA0B,CAAC,CAAC,EAC1C,IAAI,EAAE,kBAAkB,EACxB,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAoBH"}
+{"version":3,"file":"file-lock-sync-root-held.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-root-held.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAIL,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC9B,MAAM,6BAA6B,CAAC;AAQrC,KAAK,4BAA4B,GAAG,QAAQ,GAAG,WAAW,GAAG,eAAe,GAAG,UAAU,CAAC;AAE1F,KAAK,iCAAiC,GAAG;IACvC,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAOF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oBAAoB,CAAC,EAAE,GAAG,CAAC,iCAAiC,CAAC,CAAC;IAC9D,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,4BAA4B,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,yBAAyB,CAAC;IACzC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,WAAW,EAAE,2BAA2B,CAAC;IACzC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CACxB,CAAC;AAQF,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,oBAAoB,EAC9B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,EACvC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EACxC,eAAe,CAAC,EAAE,2BAA2B,GAC5C,wBAAwB,GAAG,IAAI,CAmCjC;AAED,wBAAgB,oBAAoB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAQpE;AA+KD,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAWtE;AAsHD,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,CAqBvF;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,IAAI,EAAE,kBAAkB,EACxB,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAoBH"}