@openclaw/fs-safe 0.10.0 → 0.11.0

package/dist/archive.js

@@ -1,7 +1,7 @@
 import { createTarEntryPlanner } from "./archive-tar.js";
 import { inspectTar, replayTar } from "./archive-tar-stream.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
-import fsSync, { constants as fsConstants } from "node:fs";
+import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { Readable } from "node:stream";
@@ -10,7 +10,7 @@ import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchiveP
 import { createPipelineTimeoutError, waitForDeadline, withExtractionDeadline, } from "./archive-deadline.js";
 import { assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, createExtractBudgetTransform, resolveExtractLimits, resolveTarMeterLimits, } from "./archive-limits.js";
 import { assertPortableArchiveKind, resolveArchiveKind } from "./archive-kind.js";
-import { prepareArchiveDestinationDir, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+import { prepareArchiveDestinationGuard, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
 import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
 import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
 import { isZipSymlinkEntry, zipEntryDeclaredSize, zipEntryMode, } from "./archive-zip-entry.js";
@@ -22,6 +22,7 @@ import { stageArchiveFileForExtraction } from "./archive-input.js";
 import { getNativeBinding } from "./native.js";
 import { resolveArchiveFilteredEntryPolicy, shouldExtractArchiveEntry, } from "./archive-policy.js";
 import { writeSiblingTempFile } from "./sibling-temp.js";
+import { realpathSync } from "./realpath.js";
 export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 export { resolveArchiveKind, resolvePackedRootDir } from "./archive-kind.js";
 export { readArchiveEntry } from "./archive-read.js";
@@ -122,7 +123,8 @@ async function extractZip(params) {
         deadline: params.deadline,
     });
     try {
-        const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
+        const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
+        const destinationRealDir = destinationGuard.realPath;
         params.deadline.check();
         const buffer = await fs.readFile(stagedArchive.path, { signal: params.deadline.signal });
         params.deadline.check();
@@ -136,7 +138,7 @@ async function extractZip(params) {
         await withStagedArchiveDestination({
             destinationRealDir,
             run: async (stagingDir) => {
-                const stagingRealDir = fsSync.realpathSync.native(stagingDir);
+                const stagingRealDir = realpathSync.native(stagingDir);
                 const acceptedEntries = [];
                 for (const entry of entries) {
                     params.deadline.check();
@@ -189,8 +191,7 @@ async function extractZip(params) {
                     entries: acceptedEntries,
                     durable: params.durable,
                     sourceDir: stagingRealDir,
-                    destinationDir: params.destDir,
-                    destinationRealDir,
+                    destinationGuard,
                     deadline: params.deadline,
                 });
                 params.deadline.check();
@@ -248,9 +249,10 @@ async function extractWasmTar(params) {
     await inspectTar({ archivePath: params.archivePath, limits: tarLimits, signal: deadline.signal,
         onMember: (entry) => { manifest.push(entry); } });
     deadline.check();
-    const destinationRealDir = await prepareArchiveDestinationDir(options.destDir);
+    const destinationGuard = await prepareArchiveDestinationGuard(options.destDir);
+    const destinationRealDir = destinationGuard.realPath;
     await withStagedArchiveDestination({ destinationRealDir, run: async (stagingPath) => {
-            const stagingDir = fsSync.realpathSync.native(stagingPath);
+            const stagingDir = realpathSync.native(stagingPath);
             const planEntry = createTarEntryPlanner({ ...options, rootDir: destinationRealDir, limits: params.limits });
             const accepted = manifest.flatMap((entry) => {
                 deadline.check();
@@ -273,8 +275,8 @@ async function extractWasmTar(params) {
                 },
             });
             deadline.check();
-            await mergePlannedArchiveIntoDestination({ entries: accepted, sourceDir: stagingDir,
-                destinationDir: options.destDir, destinationRealDir, deadline, durable: options.durable });
+            await mergePlannedArchiveIntoDestination({ entries: accepted, sourceDir: stagingDir, destinationGuard,
+                deadline, durable: options.durable });
             deadline.check();
         } });
 }

package/dist/bounded-read.d.ts

@@ -15,6 +15,11 @@ export declare function readBoundedAsync(maxBytes: number, readChunk: (scratch:
 export declare function readFileHandleBounded(handle: ReadableFileHandle, maxBytes: number): Promise<Buffer>;
 /** Async bounded read from a numeric descriptor. The caller owns the descriptor. */
 export declare function readFileDescriptorBounded(fd: number, maxBytes: number): Promise<Buffer>;
+export declare function readBoundedSync(maxBytes: number, readChunk: (scratch: Buffer, length: number) => number, options?: {
+    observeRegularFileSize?: () => number | undefined;
+    initialSize?: number;
+    createLimitError?: () => Error;
+}): Buffer;
 /** Sync bounded read from a numeric descriptor. The caller owns the descriptor. */
 export declare function readFileDescriptorBoundedSync(fd: number, maxBytes: number): Buffer;
 export {};

package/dist/bounded-read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bounded-read.d.ts","sourceRoot":"","sources":["../src/bounded-read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAQnD,KAAK,kBAAkB,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AA8CnD,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/D,OAAO,GAAE;IACP,sBAAsB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,KAAK,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACf,GACL,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAMjB;AAyBD,oFAAoF;AACpF,wBAAsB,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK7F;AAED,mFAAmF;AACnF,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBlF"}
+{"version":3,"file":"bounded-read.d.ts","sourceRoot":"","sources":["../src/bounded-read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAQnD,KAAK,kBAAkB,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AA8CnD,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/D,OAAO,GAAE;IACP,sBAAsB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,KAAK,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACf,GACL,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAMjB;AAyBD,oFAAoF;AACpF,wBAAsB,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK7F;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,EACtD,OAAO,GAAE;IACP,sBAAsB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,KAAK,CAAC;CAC3B,GACL,MAAM,CAoBR;AAED,mFAAmF;AACnF,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMlF"}

package/dist/bounded-read.js

@@ -108,19 +108,18 @@ export async function readFileDescriptorBounded(fd, maxBytes) {
         return await readDescriptorChunk(fd, scratch, length);
     }, { observeRegularFileSize: () => regularFileSize(fd) });
 }
-/** Sync bounded read from a numeric descriptor. The caller owns the descriptor. */
-export function readFileDescriptorBoundedSync(fd, maxBytes) {
+export function readBoundedSync(maxBytes, readChunk, options = {}) {
     normalizeMaxBytes(maxBytes);
     let total = 0;
-    // Small budgets already bound the first allocation without a size lookup.
-    const size = maxBytes <= READ_CHUNK_BYTES ? maxBytes : regularFileSize(fd);
+    const { observeRegularFileSize, createLimitError } = options;
+    const size = options.initialSize ?? observeRegularFileSize?.();
     let buffer = size === undefined ? createScratchBuffer(maxBytes) : createInitialBuffer(maxBytes, size);
     if (size !== undefined) {
-        const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, null);
+        const bytesRead = readChunk(buffer, buffer.length);
         if (bytesRead === 0)
             return finishReadBuffer(buffer, 0);
-        const currentSize = bytesRead < buffer.length ? regularFileSize(fd) : undefined;
-        total = addReadBytes(total, bytesRead, maxBytes);
+        const currentSize = bytesRead < buffer.length ? observeRegularFileSize?.() : undefined;
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
         if (currentSize !== undefined && bytesRead >= currentSize)
             return finishReadBuffer(buffer, total);
     }
@@ -128,9 +127,17 @@ export function readFileDescriptorBoundedSync(fd, maxBytes) {
         if (total === buffer.length)
             buffer = growReadBuffer(buffer, maxBytes);
         const remaining = buffer.subarray(total);
-        const bytesRead = fs.readSync(fd, remaining, 0, remaining.length, null);
+        const bytesRead = readChunk(remaining, remaining.length);
         if (bytesRead === 0)
             return finishReadBuffer(buffer, total);
-        total = addReadBytes(total, bytesRead, maxBytes);
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
     }
 }
+/** Sync bounded read from a numeric descriptor. The caller owns the descriptor. */
+export function readFileDescriptorBoundedSync(fd, maxBytes) {
+    return readBoundedSync(maxBytes, (buffer, length) => fs.readSync(fd, buffer, 0, length, null), {
+        // Small budgets already bound the first allocation without a size lookup.
+        initialSize: maxBytes <= READ_CHUNK_BYTES ? maxBytes : undefined,
+        observeRegularFileSize: () => regularFileSize(fd),
+    });
+}

package/dist/copy-file-input.d.ts

@@ -16,7 +16,6 @@ export declare function assertCopySourceCurrent(source: {
     handle: FileHandle;
     realPath: string;
 }, identity: BigIntStats): Promise<void>;
-export declare function copyFileChunks(input: CopyFileInput, maxBytes?: number): AsyncGenerator<Buffer>;
 export declare function writeCopyFileToFd(fd: number, input: CopyFileInput, maxBytes?: number, assertBeforeMutation?: () => void): Promise<void>;
 export declare function createNativeCopyFile(native: NativeBinding, input: CopyFileInput, parentFd: number, basename: string, maxBytes: number | undefined, sync: boolean): Promise<NativeFileCopyResult | undefined>;
 export declare function assertNativeCopyCompleted(input: CopyFileInput, copied?: NativeFileCopyResult): void;

package/dist/copy-file-input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copy-file-input.d.ts","sourceRoot":"","sources":["../src/copy-file-input.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAIhE,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,aAAa,CAM5E;AAED,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAChD,QAAQ,EAAE,WAAW,GACpB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAuB,cAAc,CACnC,KAAK,EAAE,aAAa,EACpB,QAAQ,SAAW,GAClB,cAAc,CAAC,MAAM,CAAC,CAiBxB;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,aAAa,EACpB,QAAQ,CAAC,EAAE,MAAM,EACjB,oBAAoB,CAAC,EAAE,MAAM,IAAI,GAChC,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CA8B3C;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAWnG"}
+{"version":3,"file":"copy-file-input.d.ts","sourceRoot":"","sources":["../src/copy-file-input.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAIhE,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,aAAa,CAM5E;AAED,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAChD,QAAQ,EAAE,WAAW,GACpB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,aAAa,EACpB,QAAQ,CAAC,EAAE,MAAM,EACjB,oBAAoB,CAAC,EAAE,MAAM,IAAI,GAChC,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CA8B3C;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAWnG"}

package/dist/copy-file-input.js

@@ -3,7 +3,7 @@ import { resolveCopyCloneMode } from "./copy-policy.js";
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
-import { writeAllToFile } from "./write-file-handle.js";
+import { transferFileHandle } from "./file-handle-transfer.js";
 export function resolveFileCopyCloneMode(mode) {
     const clone = resolveCopyCloneMode(mode, "never");
     if (clone === "always" && !getNativeBinding()?.copyFileExclusive) {
@@ -21,32 +21,10 @@ export async function assertCopySourceCurrent(source, identity) {
         return current;
     }, identity);
 }
-export async function* copyFileChunks(input, maxBytes = Infinity) {
-    const buffer = Buffer.allocUnsafe(Math.min(256 * 1024, Math.max(64 * 1024, input.size)));
-    let position = 0;
-    while (true) {
-        input.signal?.throwIfAborted();
-        const { bytesRead } = await input.handle.read(buffer, 0, Math.min(buffer.length, maxBytes - position + 1), position);
-        input.signal?.throwIfAborted();
-        if (bytesRead > maxBytes - position) {
-            throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`);
-        }
-        if (bytesRead === 0)
-            return;
-        position += bytesRead;
-        // The consumer finishes writing before the next iteration reuses this buffer.
-        yield buffer.subarray(0, bytesRead);
-    }
-}
 export async function writeCopyFileToFd(fd, input, maxBytes, assertBeforeMutation) {
-    for await (const chunk of copyFileChunks(input, maxBytes)) {
-        await writeAllToFile(fd, chunk, {
-            assertBeforeMutation: () => {
-                input.signal?.throwIfAborted();
-                assertBeforeMutation?.();
-            },
-        });
-    }
+    await transferFileHandle(input.handle, fd, {
+        maxBytes, sizeHint: input.size, signal: input.signal, assertBeforeMutation,
+    });
 }
 export async function createNativeCopyFile(native, input, parentFd, basename, maxBytes, sync) {
     input.signal?.throwIfAborted();

package/dist/copy-tree-portable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copy-tree-portable.d.ts","sourceRoot":"","sources":["../src/copy-tree-portable.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAGL,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B,0FAA0F;AAC1F,wBAAsB,aAAa,CACjC,MAAM,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,EAC9C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IACP,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACtD,GACA,OAAO,CAAC,IAAI,CAAC,CAkLf"}
+{"version":3,"file":"copy-tree-portable.d.ts","sourceRoot":"","sources":["../src/copy-tree-portable.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAGL,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAQ/B,0FAA0F;AAC1F,wBAAsB,aAAa,CACjC,MAAM,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,EAC9C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IACP,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACtD,GACA,OAAO,CAAC,IAAI,CAAC,CAiNf"}

package/dist/copy-tree-portable.js

@@ -4,6 +4,11 @@ import fsp, {} from "node:fs/promises";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { assertStagedDirectoryCurrent, exactIdentityMatches, openStagedDirectory, } from "./staged-directory.js";
+function timestampSeconds(nanoseconds) {
+    // Dates discard sub-millisecond precision; negative numbers mean "now" in
+    // Node's utimes API. Numeric strings retain fractional, pre-epoch timestamps.
+    return String(Number(nanoseconds / 1000000000n) + Number(nanoseconds % 1000000000n) / 1e9);
+}
 /** Byte-copy adapter for the shared immutable-source, caller-owned namespace contract. */
 export async function copyOwnedTree(source, destination, options) {
     options.signal?.throwIfAborted();
@@ -13,11 +18,9 @@ export async function copyOwnedTree(source, destination, options) {
     const abort = () => cancellation.abort(options.signal?.reason);
     options.signal?.addEventListener("abort", abort, { once: true });
     const pending = new Set();
+    const finishing = new Set();
     const buffers = [];
-    const settle = async () => {
-        await Promise.all(pending);
-    };
-    async function schedule(operation) {
+    async function schedule(operation, children) {
         signal.throwIfAborted();
         const task = operation()
             .catch((error) => {
@@ -25,8 +28,10 @@ export async function copyOwnedTree(source, destination, options) {
         })
             .finally(() => {
             pending.delete(task);
+            children.delete(task);
         });
         pending.add(task);
+        children.add(task);
         if (pending.size >= options.concurrency)
             await Promise.race(pending);
         signal.throwIfAborted();
@@ -82,7 +87,7 @@ export async function copyOwnedTree(source, destination, options) {
             signal.throwIfAborted();
             if (process.platform !== "win32")
                 await output.chmod(Number(stat.mode & 4095n));
-            await output.utimes(stat.atime, stat.mtime);
+            await output.utimes(timestampSeconds(stat.atimeNs), timestampSeconds(stat.mtimeNs));
         }
         catch (error) {
             cancellation.abort(error);
@@ -97,13 +102,14 @@ export async function copyOwnedTree(source, destination, options) {
             }
         }
     }
-    async function copyDirectory(from, to) {
+    async function copyDirectory(from, to, parentChildren) {
         signal?.throwIfAborted();
         const stat = await fsp.lstat(from, { bigint: true });
         // Exclusive admission prevents merging a pre-existing directory, including
         // any destination left by an unsuccessful native clone.
         await fsp.mkdir(to, { mode: 0o700 });
         const target = openStagedDirectory(to);
+        const children = new Set();
         let original;
         try {
             original = openStagedDirectory(from);
@@ -118,10 +124,10 @@ export async function copyOwnedTree(source, destination, options) {
                 const childTarget = path.join(to, entry.name);
                 const child = await fsp.lstat(childSource, { bigint: true });
                 if (child.isDirectory()) {
-                    await copyDirectory(childSource, childTarget);
+                    await copyDirectory(childSource, childTarget, children);
                 }
                 else if (child.isFile()) {
-                    await schedule(() => copyFile(childSource, childTarget, child));
+                    await schedule(() => copyFile(childSource, childTarget, child), children);
                 }
                 else if (child.isSymbolicLink()) {
                     const link = process.platform === "win32"
@@ -152,40 +158,65 @@ export async function copyOwnedTree(source, destination, options) {
                     throw new FsSafeError("not-file", "tree copying does not support special files");
                 }
             }
-            await settle();
-            signal.throwIfAborted();
-            assertStagedDirectoryCurrent(original.receipt);
-            assertStagedDirectoryCurrent(target.receipt);
-            if (process.platform !== "win32")
-                fs.fchmodSync(target.fd, Number(stat.mode & 4095n));
-            await fsp.utimes(to, stat.atime, stat.mtime);
-            assertStagedDirectoryCurrent(target.receipt);
         }
         catch (error) {
             cancellation.abort(error);
             throw error;
         }
         finally {
-            // Directory descriptors and destination ownership outlive every admitted
-            // write, including when traversal, a sibling copy, or cancellation fails.
-            await settle();
-            try {
-                if (original)
-                    fs.closeSync(original.fd);
-            }
-            finally {
-                fs.closeSync(target.fd);
-            }
+            // Traversal can advance into siblings while this directory's own files
+            // settle. Children retain their parents and finish metadata bottom-up.
+            const completion = (async () => {
+                try {
+                    await Promise.all(children);
+                    signal.throwIfAborted();
+                    if (original) {
+                        assertStagedDirectoryCurrent(original.receipt);
+                        assertStagedDirectoryCurrent(target.receipt);
+                        if (process.platform !== "win32")
+                            fs.fchmodSync(target.fd, Number(stat.mode & 4095n));
+                        await fsp.utimes(to, timestampSeconds(stat.atimeNs), timestampSeconds(stat.mtimeNs));
+                        assertStagedDirectoryCurrent(target.receipt);
+                    }
+                }
+                finally {
+                    try {
+                        if (original)
+                            fs.closeSync(original.fd);
+                    }
+                    finally {
+                        fs.closeSync(target.fd);
+                    }
+                }
+            })()
+                .catch((error) => {
+                cancellation.abort(error);
+            })
+                .finally(() => {
+                finishing.delete(completion);
+                parentChildren?.delete(completion);
+            });
+            finishing.add(completion);
+            parentChildren?.add(completion);
+            // Bound traversed-but-unsettled directories as well as file workers;
+            // ancestors stay open along the current traversal path.
+            if (finishing.size >= options.concurrency)
+                await Promise.race(finishing);
         }
+        signal.throwIfAborted();
     }
     try {
         await copyDirectory(source.receipt.realPath, destination);
+        await Promise.all(finishing);
+        signal.throwIfAborted();
     }
     catch (error) {
+        await Promise.all(finishing);
         options.signal?.throwIfAborted();
         throw error;
     }
     finally {
+        await Promise.all(finishing);
         options.signal?.removeEventListener("abort", abort);
     }
 }

package/dist/copy.d.ts

@@ -1,7 +1,7 @@
 import { type CopyCloneMode } from "./copy-policy.js";
 export { readCloneFileMetadata, type CloneFileMetadata } from "./clone-metadata.js";
 export type { CopyCloneMode } from "./copy-policy.js";
-export type TreeCloneBackend = "apfs" | "btrfs" | "refs" | "xfs";
+export type TreeCloneBackend = "apfs" | "btrfs" | "refs" | "xfs" | "zfs";
 export type CopyTreeOptions = {
     clone?: CopyCloneMode;
     signal?: AbortSignal;

package/dist/copy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copy.d.ts","sourceRoot":"","sources":["../src/copy.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAK5E,OAAO,EAAE,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACpF,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AACjE,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAS/E;AAED,0FAA0F;AAC1F,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAM,GAC5C,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,mGAAmG;AACnG,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAIf"}
+{"version":3,"file":"copy.d.ts","sourceRoot":"","sources":["../src/copy.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAK5E,OAAO,EAAE,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACpF,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AACzE,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAS/E;AAED,0FAA0F;AAC1F,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAM,GAC5C,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,mGAAmG;AACnG,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/copy.js

@@ -104,7 +104,9 @@ async function materializeTree(source, destination, options, policy) {
             await copyOwnedTree(original, target, {
                 signal: options.signal,
                 concurrency: options.concurrency ?? (process.platform === "win32" ? 4 : 1),
-                copyFileContents: process.platform === "win32" ? native?.copyFileContents : undefined,
+                copyFileContents: process.platform === "win32" || process.platform === "linux"
+                    ? native?.copyFileContents
+                    : undefined,
             });
             options.signal?.throwIfAborted();
             assertStagedDirectoryCurrent(parent.receipt);

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