@openclaw/fs-safe 0.10.0 → 0.12.0

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

@@ -1 +1 @@
-{"version":3,"file":"directory-durability.d.ts","sourceRoot":"","sources":["../src/directory-durability.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAM7C,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE7E,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACvD,UAAU,EAAE,oBAAoB,GAAG;QAAE,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;IAC5C,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD,CAAC;AAgKF,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,CAa1B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAmB/B;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,oBAAoB,CAuCtB;AAED,wBAAsB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;AAED,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAMvE;AAuBD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CA8ElC"}
+{"version":3,"file":"directory-durability.d.ts","sourceRoot":"","sources":["../src/directory-durability.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAM7C,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG7E,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACvD,UAAU,EAAE,oBAAoB,GAAG;QAAE,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;IAC5C,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD,CAAC;AAgKF,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,CAa1B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAmB/B;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,oBAAoB,CAuCtB;AAED,wBAAsB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;AAED,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAMvE;AAuBD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CA8ElC"}

package/dist/directory-durability.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { ensureAbsoluteDirectory } from "./absolute-path.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
+import { realpathSync } from "./realpath.js";
 function directoryOpenFlags() {
     if (process.platform === "win32") {
         return "r";
@@ -47,7 +48,7 @@ async function createDirectoryReceipt(directoryPath, label) {
     assertDirectory(identity, resolvedPath, label);
     return {
         path: resolvedPath,
-        realPath: fsSync.realpathSync.native(resolvedPath),
+        realPath: realpathSync.native(resolvedPath),
         identity,
     };
 }
@@ -57,7 +58,7 @@ function createDirectoryReceiptSync(directoryPath, label) {
     assertDirectory(identity, resolvedPath, label);
     return {
         path: resolvedPath,
-        realPath: fsSync.realpathSync(resolvedPath),
+        realPath: realpathSync(resolvedPath),
         identity,
     };
 }
@@ -65,7 +66,7 @@ async function assertDirectoryReceiptCurrent(receipt, label) {
     const currentIdentity = fsSync.lstatSync(receipt.path);
     assertDirectory(currentIdentity, receipt.path, label);
     if (!sameFileIdentity(receipt.identity, currentIdentity) ||
-        (fsSync.realpathSync.native(receipt.path)) !== receipt.realPath) {
+        (realpathSync.native(receipt.path)) !== receipt.realPath) {
         throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
     }
 }
@@ -73,7 +74,7 @@ function assertDirectoryReceiptCurrentSync(receipt, label) {
     const currentIdentity = fsSync.lstatSync(receipt.path);
     assertDirectory(currentIdentity, receipt.path, label);
     if (!sameFileIdentity(receipt.identity, currentIdentity) ||
-        fsSync.realpathSync(receipt.path) !== receipt.realPath) {
+        realpathSync(receipt.path) !== receipt.realPath) {
         throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
     }
 }

package/dist/directory-guard.d.ts

@@ -10,6 +10,15 @@ export type SyncDirectoryGuard = {
     realPath: string;
     stat: Stats;
 };
+export type DirectoryIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+    realPath: string;
+}>;
+export declare function readDirectoryIdentity(dir: string): Promise<DirectoryIdentity>;
+export declare function assertDirectoryIdentitySync(observedPath: string, expected: Pick<DirectoryIdentity, "dev" | "ino"> & {
+    realPath?: string;
+}): void;
 export declare function createAsyncDirectoryGuard(dir: string, options: {
     bigint: true;
 }): Promise<AsyncDirectoryGuard<BigIntStats>>;
@@ -21,11 +30,12 @@ export declare function createAsyncDirectoryGuard(dir: string, options: {
 }): Promise<AnyAsyncDirectoryGuard>;
 export declare function assertAsyncDirectoryGuard(guard: AnyAsyncDirectoryGuard): Promise<void>;
 export declare function createSyncDirectoryGuard(dir: string): SyncDirectoryGuard;
-export declare function assertSyncDirectoryGuard(guard: SyncDirectoryGuard): void;
+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: boolean;
 }): Promise<AnyAsyncDirectoryGuard>;
 export declare function createNearestExistingSyncDirectoryGuard(rootReal: string, targetPath: string): SyncDirectoryGuard;
 export declare function inspectDirectoryIdentity(dir: string, expected?: Pick<BigIntStats, "dev" | "ino">): Promise<BigIntStats>;
+export declare function inspectDirectoryIdentitySync(dir: string, expected?: Pick<BigIntStats, "dev" | "ino">): BigIntStats;
 //# sourceMappingURL=directory-guard.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"directory-guard.d.ts","sourceRoot":"","sources":["../src/directory-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AASlD,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,KAAK,GAAG,WAAW,GAAG,KAAK,IAAI;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,CAAC,CAAC;CACT,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,CAAC,KAAK,GAAG,WAAW,CAAC,CAAC;AAE9E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC,CAAC;AAC7H,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACnH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAStH,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5F;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAMxE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAQxE;AAED,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACxH,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAqBzJ,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,kBAAkB,CAcpB;AAGD,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAM7H"}
+{"version":3,"file":"directory-guard.d.ts","sourceRoot":"","sources":["../src/directory-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAUlD,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,KAAK,GAAG,WAAW,GAAG,KAAK,IAAI;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,CAAC,CAAC;CACT,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,CAAC,KAAK,GAAG,WAAW,CAAC,CAAC;AAE9E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAEH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAGnF;AAED,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,KAAK,GAAG,KAAK,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE,IAAI,CAKN;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC,CAAC;AAC7H,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACnH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAStH,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5F;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAMxE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,kBAAkB,GAAG,sBAAsB,GAAG,IAAI,CAajG;AAED,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACxH,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAqBzJ,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,kBAAkB,CAcpB;AAGD,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAE7H;AAmBD,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GAC1C,WAAW,CAQb"}

package/dist/directory-guard.js

@@ -2,24 +2,37 @@ import fsSync from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { isNotFoundPathError } from "./path.js";
 import { directoryComponentNotDirectoryError } from "./root-errors.js";
+import { realpathSync } from "./realpath.js";
+export async function readDirectoryIdentity(dir) {
+    const guard = await createAsyncDirectoryGuard(dir, { bigint: true });
+    return Object.freeze({ dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath });
+}
+export function assertDirectoryIdentitySync(observedPath, expected) {
+    inspectDirectoryIdentitySync(observedPath, expected);
+    if (expected.realPath !== undefined && realpathSync.native(observedPath) !== expected.realPath) {
+        throw new FsSafeError("path-mismatch", "directory changed during operation");
+    }
+}
 export async function createAsyncDirectoryGuard(dir, options) {
-    const stat = options?.bigint ? await inspectDirectoryIdentity(dir) : fsSync.lstatSync(dir);
+    const stat = options?.bigint ? inspectDirectoryIdentitySync(dir) : fsSync.lstatSync(dir);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    return { dir, realPath: fsSync.realpathSync.native(dir), stat };
+    return { dir, realPath: realpathSync.native(dir), stat };
 }
 export async function assertAsyncDirectoryGuard(guard) {
-    const stat = typeof guard.stat.dev === "bigint" && typeof guard.stat.ino === "bigint"
-        ? await inspectDirectoryIdentity(guard.dir, { dev: guard.stat.dev, ino: guard.stat.ino })
-        : fsSync.lstatSync(guard.dir);
+    if (typeof guard.stat.dev === "bigint" && typeof guard.stat.ino === "bigint") {
+        assertDirectoryIdentitySync(guard.dir, { dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath });
+        return;
+    }
+    const stat = fsSync.lstatSync(guard.dir);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    if (!sameFileIdentity(stat, guard.stat) || fsSync.realpathSync.native(guard.dir) !== guard.realPath) {
+    if (!sameFileIdentity(stat, guard.stat) || realpathSync.native(guard.dir) !== guard.realPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
 }
@@ -28,14 +41,19 @@ export function createSyncDirectoryGuard(dir) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    return { dir, realPath: fsSync.realpathSync(dir), stat };
+    return { dir, realPath: realpathSync(dir), stat };
 }
 export function assertSyncDirectoryGuard(guard) {
+    if (typeof guard.stat.dev === "bigint" && typeof guard.stat.ino === "bigint") {
+        assertDirectoryIdentitySync(guard.dir, { dev: guard.stat.dev, ino: guard.stat.ino, realPath: guard.realPath });
+        return;
+    }
     const stat = fsSync.lstatSync(guard.dir);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw directoryComponentNotDirectoryError();
     }
-    if (!sameFileIdentity(stat, guard.stat) || fsSync.realpathSync(guard.dir) !== guard.realPath) {
+    const realPath = realpathSync(guard.dir);
+    if (!sameFileIdentity(stat, guard.stat) || realPath !== guard.realPath) {
         throw new FsSafeError("path-mismatch", "directory changed during operation");
     }
 }
@@ -73,8 +91,32 @@ export function createNearestExistingSyncDirectoryGuard(rootReal, targetPath) {
 }
 // Recovery receipts must retain every identity bit, including on Windows.
 export async function inspectDirectoryIdentity(dir, expected) {
-    return await inspectFileIdentity(async () => {
-        const stat = fsSync.lstatSync(dir, { bigint: true });
+    return inspectDirectoryIdentitySync(dir, expected);
+}
+function directoryEntryPath(dir) {
+    const windows = process.platform === "win32";
+    if (typeof dir === "string") {
+        const last = dir[dir.length - 1];
+        if (last !== "/" && (!windows || last !== "\\"))
+            return dir;
+    }
+    let rootLength = (windows ? path.win32 : path.posix).parse(dir).root.length;
+    if (windows && /^[\\/]{2}[?.][\\/]UNC[\\/]/i.test(dir)) {
+        // Node parses the namespace prefix as the root; retain the complete UNC share instead.
+        const uncRoot = path.win32.parse(`\\\\${dir.slice(8)}`).root;
+        if (uncRoot.length > 1)
+            rootLength = Math.max(rootLength, uncRoot.length + 6);
+    }
+    let end = dir.length;
+    while (end > rootLength && (dir[end - 1] === "/" || (windows && dir[end - 1] === "\\")))
+        end--;
+    return end === rootLength || end === dir.length ? dir : dir.slice(0, end);
+}
+export function inspectDirectoryIdentitySync(dir, expected) {
+    // A trailing separator makes lstat follow a final directory symlink.
+    const entryPath = directoryEntryPath(dir);
+    return inspectFileIdentitySync(() => {
+        const stat = fsSync.lstatSync(entryPath, { bigint: true });
         if (stat.isSymbolicLink() || !stat.isDirectory())
             throw directoryComponentNotDirectoryError();
         return stat;

package/dist/durability.d.ts

@@ -1,4 +1,4 @@
 export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
 export { isHardlinkFallbackError, publishFileExclusive, type PublishFileExclusiveResult, type PublishFileExclusiveStrategy, type PublishFileExclusiveCleanup, type PublishFileExclusiveDirectorySyncFailure, type PublishFileExclusiveFailureDetails, type PublishFileExclusiveFailurePhase, type PublishFileExclusiveSyncFailurePolicy, } from "./publish-file.js";
-export { sha256File, type Sha256FileInput, type Sha256FileOptions, type Sha256FileResult, } from "./file-hash.js";
+export { sha256File, sha256FileSync, type Sha256FileInput, type Sha256FileSyncInput, type Sha256FileOptions, type Sha256FileResult, } from "./file-hash.js";
 //# sourceMappingURL=durability.d.ts.map

package/dist/durability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durability.d.ts","sourceRoot":"","sources":["../src/durability.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,uBAAuB,EACvB,2BAA2B,EAC3B,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,0BAA0B,EAC/B,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,wCAAwC,EAC7C,KAAK,kCAAkC,EACvC,KAAK,gCAAgC,EACrC,KAAK,qCAAqC,GAC3C,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"durability.d.ts","sourceRoot":"","sources":["../src/durability.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,uBAAuB,EACvB,2BAA2B,EAC3B,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,0BAA0B,EAC/B,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,wCAAwC,EAC7C,KAAK,kCAAkC,EACvC,KAAK,gCAAgC,EACrC,KAAK,qCAAqC,GAC3C,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,UAAU,EACV,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/durability.js

@@ -1,3 +1,3 @@
 export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, } from "./directory-durability.js";
 export { isHardlinkFallbackError, publishFileExclusive, } from "./publish-file.js";
-export { sha256File, } from "./file-hash.js";
+export { sha256File, sha256FileSync, } from "./file-hash.js";

package/dist/file-handle-transfer.d.ts

@@ -0,0 +1,14 @@
+import type { FileHandle } from "node:fs/promises";
+export type CopyFileHandleOptions = {
+    maxBytes?: number;
+    signal?: AbortSignal;
+    onChunk?: (chunk: Uint8Array) => void;
+    assertBeforeMutation?: () => void;
+};
+/** Copies caller-owned regular files from offset zero without moving either cursor. */
+export declare function copyFileHandle(source: FileHandle, target: FileHandle, options?: CopyFileHandleOptions): Promise<number>;
+export declare function transferFileHandle(source: FileHandle, target: FileHandle | number, options: CopyFileHandleOptions & {
+    sizeHint: number;
+    targetPosition?: number;
+}): Promise<number>;
+//# sourceMappingURL=file-handle-transfer.d.ts.map

package/dist/file-handle-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-handle-transfer.d.ts","sourceRoot":"","sources":["../src/file-handle-transfer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAWnD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC;AAEF,uFAAuF;AACvF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAGD,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,qBAAqB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,MAAM,CAAC,CAyBjB"}

package/dist/file-handle-transfer.js

@@ -0,0 +1,64 @@
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult, composeMutationAssertions, rethrowMutationAuthorityError, } from "./mutation-authority.js";
+import { writeAllToFile } from "./write-file-handle.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+/** Copies caller-owned regular files from offset zero without moving either cursor. */
+export async function copyFileHandle(source, target, options = {}) {
+    options.signal?.throwIfAborted();
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const sourceStat = await inspectFileIdentity(() => {
+        options.signal?.throwIfAborted();
+        return source.stat({ bigint: true });
+    });
+    options.signal?.throwIfAborted();
+    if (!sourceStat.isFile())
+        throw new FsSafeError("not-file", "copy source handle must be a regular file");
+    if (maxBytes !== undefined && Number.isFinite(maxBytes) && sourceStat.size > BigInt(maxBytes)) {
+        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`);
+    }
+    const targetStat = await inspectFileIdentity(() => {
+        options.signal?.throwIfAborted();
+        return target.stat({ bigint: true });
+    });
+    options.signal?.throwIfAborted();
+    if (!targetStat.isFile())
+        throw new FsSafeError("not-file", "copy target handle must be a regular file");
+    if (sourceStat.dev === targetStat.dev && sourceStat.ino === targetStat.ino) {
+        throw new FsSafeError("path-alias", "copy source and target handles refer to the same file");
+    }
+    return await transferFileHandle(source, target, {
+        ...options,
+        maxBytes,
+        sizeHint: Number(sourceStat.size),
+        targetPosition: 0,
+        assertBeforeMutation: composeMutationAssertions(undefined, options.assertBeforeMutation),
+    }).catch(rethrowMutationAuthorityError);
+}
+// Root.copyIn supplies already-admitted identities and retains its owned target cursor.
+export async function transferFileHandle(source, target, options) {
+    const maxBytes = options.maxBytes ?? Infinity;
+    const buffer = Buffer.allocUnsafe(Math.min(512 * 1024, Math.max(64 * 1024, options.sizeHint), maxBytes + 1));
+    let position = 0;
+    while (true) {
+        options.signal?.throwIfAborted();
+        const { bytesRead } = await source.read(buffer, 0, Math.min(buffer.length, maxBytes - position + 1), position);
+        options.signal?.throwIfAborted();
+        if (bytesRead > maxBytes - position) {
+            throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`);
+        }
+        if (bytesRead === 0)
+            return position;
+        const chunk = buffer.subarray(0, bytesRead);
+        if (options.onChunk)
+            assertSynchronousCallbackResult(options.onChunk(chunk), "onChunk");
+        await writeAllToFile(target, chunk, {
+            position: options.targetPosition === undefined ? undefined : options.targetPosition + position,
+            assertBeforeMutation: () => {
+                options.signal?.throwIfAborted();
+                options.assertBeforeMutation?.();
+            },
+        });
+        position += bytesRead;
+    }
+}

package/dist/file-hash.d.ts

@@ -1,6 +1,7 @@
 import type { FileHandle } from "node:fs/promises";
 import { type NativeBinding } from "./native.js";
 export type Sha256FileInput = string | FileHandle;
+export type Sha256FileSyncInput = string | number;
 export type Sha256FileOptions = {
     maxBytes?: number;
     signal?: AbortSignal;
@@ -11,4 +12,6 @@ export type Sha256FileResult = {
 };
 export declare function hashFileHandle(handle: FileHandle, native?: NativeBinding | undefined, { maxBytes, signal }?: Sha256FileOptions): Promise<Sha256FileResult>;
 export declare function sha256File(input: Sha256FileInput, options?: Sha256FileOptions): Promise<Sha256FileResult>;
+/** Hash synchronously from offset zero, retaining ownership and position of a borrowed fd. */
+export declare function sha256FileSync(input: Sha256FileSyncInput, options?: Sha256FileOptions): Sha256FileResult;
 //# sourceMappingURL=file-hash.d.ts.map

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;AAInE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,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,CAoD3B;AAoDD,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAM3B"}
+{"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;AAInE,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;AAyDD,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAuDD,8FAA8F;AAC9F,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAMlB"}

package/dist/file-hash.js

@@ -5,7 +5,7 @@ import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 export async function hashFileHandle(handle, native = getNativeBinding(), { maxBytes = Infinity, signal } = {}) {
     signal?.throwIfAborted();
     const stat = fsSync.fstatSync(handle.fd);
@@ -38,7 +38,7 @@ export async function hashFileHandle(handle, native = getNativeBinding(), { maxB
         }
     }
     const hash = createHash("sha256");
-    const buffer = Buffer.allocUnsafe(Math.min(256 * 1024, Math.max(64 * 1024, stat.size)));
+    let buffer = Buffer.allocUnsafe(Math.min(256 * 1024, Math.max(1, stat.size + 1), maxBytes + 1));
     let position = 0;
     while (true) {
         signal?.throwIfAborted();
@@ -53,48 +53,54 @@ export async function hashFileHandle(handle, native = getNativeBinding(), { maxB
         }
         hash.update(buffer.subarray(0, bytesRead));
         position += bytesRead;
+        // A full small buffer can mean growth or a virtual file with an unhelpful size.
+        if (bytesRead === buffer.length && buffer.length < 64 * 1024) {
+            buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1));
+        }
+    }
+}
+function hashPathIdentity(filePath, afterOpen = false) {
+    const stat = fsSync.lstatSync(filePath, { bigint: true });
+    if (afterOpen && (stat.isSymbolicLink() || !stat.isFile())) {
+        throw new FsSafeError("path-mismatch", "SHA-256 path changed while opening");
+    }
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", "SHA-256 path must not be a symbolic link");
     }
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "SHA-256 path is not a regular file");
+    }
+    return stat;
+}
+function hashDescriptorIdentity(fd) {
+    const stat = fsSync.fstatSync(fd, { bigint: true });
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "SHA-256 path is not a regular file");
+    }
+    return stat;
+}
+function rethrowHashOpenError(error) {
+    if (error?.code === "ELOOP") {
+        throw new FsSafeError("symlink", "SHA-256 path must not be a symbolic link", {
+            cause: error,
+        });
+    }
+    throw error;
 }
 async function hashPath(filePath, options) {
-    const before = await inspectFileIdentity(async () => {
-        const stat = fsSync.lstatSync(filePath, { bigint: true });
-        if (stat.isSymbolicLink()) {
-            throw new FsSafeError("symlink", "SHA-256 path must not be a symbolic link");
-        }
-        if (!stat.isFile()) {
-            throw new FsSafeError("not-file", "SHA-256 path is not a regular file");
-        }
-        return stat;
-    });
+    const before = await inspectFileIdentity(() => hashPathIdentity(filePath));
     let handle;
     try {
         options.signal?.throwIfAborted();
         handle = await fs.open(filePath, resolveReadOpenFlags());
     }
     catch (error) {
-        if (error?.code === "ELOOP") {
-            throw new FsSafeError("symlink", "SHA-256 path must not be a symbolic link", {
-                cause: error,
-            });
-        }
-        throw error;
+        rethrowHashOpenError(error);
     }
     try {
         options.signal?.throwIfAborted();
-        const opened = await inspectFileIdentity(async () => {
-            const stat = fsSync.fstatSync(handle.fd, { bigint: true });
-            if (!stat.isFile()) {
-                throw new FsSafeError("not-file", "SHA-256 path is not a regular file");
-            }
-            return stat;
-        }, before);
-        await inspectFileIdentity(async () => {
-            const stat = fsSync.lstatSync(filePath, { bigint: true });
-            if (stat.isSymbolicLink() || !stat.isFile()) {
-                throw new FsSafeError("path-mismatch", "SHA-256 path changed while opening");
-            }
-            return stat;
-        }, opened);
+        const opened = await inspectFileIdentity(() => hashDescriptorIdentity(handle.fd), before);
+        await inspectFileIdentity(() => hashPathIdentity(filePath, true), opened);
         return await hashFileHandle(handle, getNativeBinding(), options);
     }
     finally {
@@ -108,3 +114,64 @@ export async function sha256File(input, options = {}) {
         ? await hashPath(input, normalized)
         : await hashFileHandle(input, getNativeBinding(), normalized);
 }
+function hashDescriptorSync(fd, { maxBytes = Infinity, signal }) {
+    signal?.throwIfAborted();
+    const stat = fsSync.fstatSync(fd);
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "SHA-256 input is not a regular file");
+    }
+    if (stat.size > maxBytes) {
+        throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
+    }
+    const hash = createHash("sha256");
+    let buffer = Buffer.allocUnsafe(Math.min(256 * 1024, Math.max(1, stat.size + 1), maxBytes + 1));
+    let position = 0;
+    while (true) {
+        signal?.throwIfAborted();
+        const length = Math.min(buffer.length, maxBytes - position + 1);
+        const bytesRead = fsSync.readSync(fd, buffer, 0, length, position);
+        signal?.throwIfAborted();
+        if (bytesRead > maxBytes - position) {
+            throw new FsSafeError("too-large", `SHA-256 input exceeds ${maxBytes} bytes`);
+        }
+        if (bytesRead === 0) {
+            return { bytes: position, digest: hash.digest("hex") };
+        }
+        hash.update(buffer.subarray(0, bytesRead));
+        position += bytesRead;
+        if (bytesRead === buffer.length && buffer.length < 64 * 1024) {
+            buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1));
+        }
+    }
+}
+function hashPathSync(filePath, options) {
+    const before = inspectFileIdentitySync(() => hashPathIdentity(filePath));
+    let fd;
+    try {
+        options.signal?.throwIfAborted();
+        fd = fsSync.openSync(filePath, resolveReadOpenFlags());
+    }
+    catch (error) {
+        rethrowHashOpenError(error);
+    }
+    try {
+        options.signal?.throwIfAborted();
+        const opened = inspectFileIdentitySync(() => hashDescriptorIdentity(fd), before);
+        inspectFileIdentitySync(() => hashPathIdentity(filePath, true), opened);
+        return hashDescriptorSync(fd, options);
+    }
+    finally {
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch { /* Preserve the hashing outcome. */ }
+    }
+}
+/** Hash synchronously from offset zero, retaining ownership and position of a borrowed fd. */
+export function sha256FileSync(input, options = {}) {
+    options.signal?.throwIfAborted();
+    const normalized = { maxBytes: normalizeMaxBytes(options.maxBytes), signal: options.signal };
+    return typeof input === "string"
+        ? hashPathSync(input, normalized)
+        : hashDescriptorSync(input, normalized);
+}

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

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

package/dist/file-lock-sync.js

@@ -2,9 +2,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { readSidecarLockSnapshotSync, readSidecarLockRawSnapshotSync, parseSidecarLockSnapshot, relativeSidecarLockPath, removeSidecarLockIfUnchangedSync, serializeSidecarLockPayload, sidecarLockSnapshotMatches, } from "./sidecar-lock-reclaim.js";
-import { computeSidecarLockDelayMs, isTransientLockFileDenial, maxTransientLockDenials, sidecarLockPayloadCreatedAtMs, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
+import { computeSidecarLockDelayMs, isTransientLockFileDenial, maxTransientLockDenials, sidecarLockPayloadCreatedAtMs, validateSidecarLockStaleMs, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockRetryOptions, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
 import { getFsSafeLockConfig } from "./lock-config.js";
 import { sleepSync } from "./timing.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 const SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncSidecarLocks");
 const SYNC_CLEANUP_REGISTERED_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistered");
 const SYNC_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupHandler");
@@ -91,11 +93,11 @@ function createSyncHeldLockHandle(held) {
 }
 function canonicalLockParentSync(parent) {
     // Match Root's async realpath, including Windows short-name expansion.
-    return process.platform === "win32" ? fs.realpathSync.native(parent) : fs.realpathSync(parent);
+    return process.platform === "win32" ? realpathSync.native(parent) : realpathSync(parent);
 }
 function normalizeTargetPath(targetPath) {
     const resolved = path.resolve(targetPath);
-    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.mkdirSync(recursiveMkdirPath(path.dirname(resolved)), { recursive: true });
     try {
         return path.join(canonicalLockParentSync(path.dirname(resolved)), path.basename(resolved));
     }
@@ -140,6 +142,9 @@ export function acquireFileLockSync(targetPath, options) {
     const timeoutMs = options.timeoutMs ?? defaults.timeoutMs;
     validateSidecarLockRetryOptions(retry);
     validateSidecarLockTimeoutMs(timeoutMs);
+    const staleMs = options.staleMs ?? defaults.staleMs ?? 30_000;
+    validateSidecarLockStaleMs(staleMs);
+    validateSidecarLockCompromiseCheckIntervalMs(options.compromiseCheckIntervalMs);
     const normalizedTargetPath = normalizeTargetPath(targetPath);
     const lockPath = boundedLockPath(options.lockPath ?? `${normalizedTargetPath}.lock`, options.lockRoot);
     const heldLocks = getSyncHeldLocks();
@@ -153,7 +158,6 @@ export function acquireFileLockSync(targetPath, options) {
     }
     // Process defaults fill the same fields here as withLockDefaults() fills for
     // the asynchronous manager, so both acquirers honor configureFsSafeLocks().
-    const staleMs = options.staleMs ?? defaults.staleMs ?? 30_000;
     const staleRecovery = options.staleRecovery ?? defaults.staleRecovery;
     const startedAt = Date.now();
     let attempt = 0;

package/dist/file-store-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-store-boundary.d.ts","sourceRoot":"","sources":["../src/file-store-boundary.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAA4C,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAGhF,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAOjD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,IAAI,EAChB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhB;AAED,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAAC,GACnD,OAAO,CAAC,IAAI,CAAC,CASf;AAsCD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAwC1D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAWrE;AAUD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,eAAe,CAOlB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,eAAe,GAAG,OAAO,CAAC;CAC1C,GAAG,eAAe,CAyDlB"}
+{"version":3,"file":"file-store-boundary.d.ts","sourceRoot":"","sources":["../src/file-store-boundary.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAA4C,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAGhF,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAK1D,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAOjD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,IAAI,EAChB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhB;AAED,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAAC,GACnD,OAAO,CAAC,IAAI,CAAC,CASf;AAsCD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAwC1D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAWrE;AAUD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,eAAe,CAOlB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,eAAe,GAAG,OAAO,CAAC;CAC1C,GAAG,eAAe,CAyDlB"}

package/dist/file-store-boundary.js

@@ -13,6 +13,8 @@ import { ensureTrailingSep } from "./root-context.js";
 import { RootHandle } from "./root-impl.js";
 import { prepareSecretFileWrite } from "./secret-file.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 function parentRelativePath(relativePath) {
     const parent = path.posix.dirname(relativePath);
     return parent === "." ? "" : parent;
@@ -27,7 +29,7 @@ export async function ensureParentInRoot(scopedRoot, relativePath, mode) {
 }
 export async function openWritableStoreRoot(params) {
     const maxBytes = normalizeMaxBytes(params.maxBytes);
-    await fs.mkdir(params.rootDir, { recursive: true, mode: params.dirMode });
+    await fs.mkdir(recursiveMkdirPath(params.rootDir), { recursive: true, mode: params.dirMode });
     await fs.chmod(params.rootDir, params.dirMode).catch(() => undefined);
     return await root(params.rootDir, { hardlinks: "reject", maxBytes });
 }
@@ -149,12 +151,12 @@ export function ensureStoreDirectorySync(params) {
     if (isPathRelativeEscape(relative)) {
         throw new FsSafeError("outside-workspace", "file path escapes store root");
     }
-    syncFs.mkdirSync(rootDir, { recursive: true, mode: params.mode });
+    syncFs.mkdirSync(recursiveMkdirPath(rootDir), { recursive: true, mode: params.mode });
     const rootStat = syncFs.lstatSync(rootDir);
     if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
         throw new FsSafeError("not-file", `${params.messagePrefix} root must be a directory: ${rootDir}`);
     }
-    const rootReal = syncFs.realpathSync(rootDir);
+    const rootReal = realpathSync(rootDir);
     chmodDirectorySyncBestEffort(rootDir, params.mode);
     let current = rootDir;
     for (const segment of path.relative(rootDir, dir).split(path.sep).filter(Boolean)) {
@@ -172,8 +174,8 @@ export function ensureStoreDirectorySync(params) {
             syncFs.mkdirSync(current, { mode: params.mode });
         }
         const currentRootStat = syncFs.lstatSync(rootDir);
-        const currentRootReal = syncFs.realpathSync(rootDir);
-        const currentReal = syncFs.realpathSync(current);
+        const currentRootReal = realpathSync(rootDir);
+        const currentReal = realpathSync(current);
         if (currentRootStat.isSymbolicLink() ||
             !currentRootStat.isDirectory() ||
             !sameFileIdentity(rootStat, currentRootStat) ||

package/dist/file-store-path.d.ts

@@ -0,0 +1,3 @@
+export declare function assertRelativePath(relativePath: string): string;
+export declare function resolveStorePath(rootDir: string, relativePath: string): string;
+//# sourceMappingURL=file-store-path.d.ts.map

package/dist/file-store-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store-path.d.ts","sourceRoot":"","sources":["../src/file-store-path.ts"],"names":[],"mappings":"AAIA,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAe/D;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAS9E"}

package/dist/file-store-path.js

@@ -0,0 +1,27 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { isPathInside, splitSafeRelativePath } from "./path.js";
+export function assertRelativePath(relativePath) {
+    const raw = relativePath.trim();
+    if (!raw || raw !== relativePath) {
+        throw new FsSafeError("invalid-path", "store key must be non-empty and unpadded");
+    }
+    const segments = splitSafeRelativePath(raw);
+    if (segments.length === 0 ||
+        segments.join("/") !== raw ||
+        raw.normalize("NFC") !== raw ||
+        segments.some((segment) => /[ .]$/u.test(segment))) {
+        throw new FsSafeError("invalid-path", "store key must use one canonical relative spelling");
+    }
+    return raw;
+}
+export function resolveStorePath(rootDir, relativePath) {
+    const key = assertRelativePath(relativePath);
+    const root = path.resolve(rootDir);
+    // The immutable key already passed segment validation; keep the containment check.
+    const target = path.resolve(root, key);
+    if (!isPathInside(root, target)) {
+        throw new FsSafeError("outside-workspace", "relative path escapes root");
+    }
+    return target;
+}