@openclaw/fs-safe 0.9.0 → 0.11.0

package/dist/bounded-read.js

@@ -2,50 +2,69 @@ import fs from "node:fs";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
 const READ_CHUNK_BYTES = 64 * 1024;
-function createScratchBuffer(maxBytes) {
-    const initialReadBytes = Number.isFinite(maxBytes)
-        ? Math.min(READ_CHUNK_BYTES, maxBytes + 1)
-        : READ_CHUNK_BYTES;
-    return Buffer.allocUnsafe(Math.max(1, initialReadBytes));
+// Preserve one-read performance through the default Root byte budget.
+const MAX_INITIAL_READ_BYTES = 16 * 1024 * 1024;
+function createInitialBuffer(maxBytes, size, allocate = Buffer.allocUnsafe) {
+    // A size hint can describe a huge sparse file or an already exhausted fd.
+    return allocate(Math.min(maxBytes, size, MAX_INITIAL_READ_BYTES) + 1);
 }
-function nextReadLength(total, maxBytes, capacity) {
-    return Number.isFinite(maxBytes)
-        ? Math.min(capacity, maxBytes - total + 1)
-        : capacity;
+function createScratchBuffer(maxBytes, allocate = Buffer.allocUnsafe) {
+    return allocate(Math.min(READ_CHUNK_BYTES, maxBytes + 1));
 }
-function appendChunk(params) {
-    const total = params.total + params.bytesRead;
-    if (total > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got at least ${total})`);
+function growReadBuffer(buffer, maxBytes, allocate = Buffer.allocUnsafe) {
+    // Grow only after consuming the whole buffer, never from an unchecked size hint.
+    const capacity = Math.min(maxBytes + 1, Math.max(READ_CHUNK_BYTES, buffer.length * 2));
+    const grown = allocate(capacity);
+    buffer.copy(grown);
+    return grown;
+}
+function finishReadBuffer(buffer, total, allocate) {
+    if (total === 0)
+        return Buffer.alloc(0);
+    const result = buffer.subarray(0, total);
+    if (total >= buffer.length / 2)
+        return result;
+    if (!allocate)
+        return Buffer.from(result);
+    const compact = allocate(total);
+    result.copy(compact);
+    return compact;
+}
+function addReadBytes(total, bytesRead, maxBytes, createLimitError) {
+    const next = total + bytesRead;
+    if (next > maxBytes) {
+        if (createLimitError)
+            throw createLimitError();
+        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${next})`);
     }
-    params.chunks.push(Buffer.from(params.scratch.subarray(0, params.bytesRead)));
-    return total;
+    return next;
 }
-async function readBoundedAsync(maxBytes, readChunk, observeRegularFileSize) {
+export async function readBoundedAsync(maxBytes, readChunk, options = {}) {
     normalizeMaxBytes(maxBytes);
-    const chunks = [];
     let total = 0;
-    const size = observeRegularFileSize?.();
+    const { observeRegularFileSize, createLimitError } = options;
+    const allocate = options.unpooled ? Buffer.allocUnsafeSlow : undefined;
+    const size = options.initialSize ?? observeRegularFileSize?.();
+    let buffer = size === undefined ? createScratchBuffer(maxBytes, allocate) : createInitialBuffer(maxBytes, size, allocate);
     if (size !== undefined) {
-        const first = Buffer.allocUnsafe(Math.min(maxBytes, size) + 1);
-        const bytesRead = await readChunk(first, first.length);
+        const bytesRead = await readChunk(buffer, buffer.length);
         if (bytesRead === 0)
-            return first.subarray(0, 0);
-        // Short reads can occur before EOF. Only accept one when a fresh fd size
-        // observation proves we consumed at least the entire current file size.
-        const currentSize = bytesRead < first.length ? observeRegularFileSize?.() : undefined;
+            return finishReadBuffer(buffer, 0, allocate);
+        // Short reads can occur before EOF. Only use the size shortcut on this
+        // initial read; virtual files can report zero or stale sizes thereafter.
+        const currentSize = bytesRead < buffer.length ? observeRegularFileSize?.() : undefined;
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
         if (currentSize !== undefined && bytesRead >= currentSize)
-            return first.subarray(0, bytesRead);
-        total = appendChunk({ chunks, scratch: first, bytesRead, total, maxBytes });
+            return finishReadBuffer(buffer, total, allocate);
     }
-    const scratch = createScratchBuffer(maxBytes);
     while (true) {
-        const length = nextReadLength(total, maxBytes, scratch.length);
-        const bytesRead = await readChunk(scratch, length);
-        if (bytesRead === 0) {
-            return Buffer.concat(chunks, total);
-        }
-        total = appendChunk({ chunks, scratch, bytesRead, total, maxBytes });
+        if (total === buffer.length)
+            buffer = growReadBuffer(buffer, maxBytes, allocate);
+        const remaining = buffer.subarray(total);
+        const bytesRead = await readChunk(remaining, remaining.length);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, total, allocate);
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
     }
 }
 /**
@@ -58,7 +77,7 @@ export async function readFileHandleBounded(handle, maxBytes) {
     const fd = "fd" in handle && typeof handle.fd === "number" ? handle.fd : undefined;
     return await readBoundedAsync(maxBytes, async (scratch, length) => {
         return (await handle.read(scratch, 0, length, null)).bytesRead;
-    }, fd === undefined ? undefined : () => regularFileSize(fd));
+    }, { observeRegularFileSize: fd === undefined ? undefined : () => regularFileSize(fd) });
 }
 function regularFileSize(fd) {
     try {
@@ -87,20 +106,38 @@ export async function readFileDescriptorBounded(fd, maxBytes) {
     normalizeMaxBytes(maxBytes);
     return await readBoundedAsync(maxBytes, async (scratch, length) => {
         return await readDescriptorChunk(fd, scratch, length);
-    }, () => regularFileSize(fd));
+    }, { 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);
-    const chunks = [];
-    const scratch = createScratchBuffer(maxBytes);
     let total = 0;
+    const { observeRegularFileSize, createLimitError } = options;
+    const size = options.initialSize ?? observeRegularFileSize?.();
+    let buffer = size === undefined ? createScratchBuffer(maxBytes) : createInitialBuffer(maxBytes, size);
+    if (size !== undefined) {
+        const bytesRead = readChunk(buffer, buffer.length);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, 0);
+        const currentSize = bytesRead < buffer.length ? observeRegularFileSize?.() : undefined;
+        total = addReadBytes(total, bytesRead, maxBytes, createLimitError);
+        if (currentSize !== undefined && bytesRead >= currentSize)
+            return finishReadBuffer(buffer, total);
+    }
     while (true) {
-        const length = nextReadLength(total, maxBytes, scratch.length);
-        const bytesRead = fs.readSync(fd, scratch, 0, length, null);
-        if (bytesRead === 0) {
-            return Buffer.concat(chunks, total);
-        }
-        total = appendChunk({ chunks, scratch, bytesRead, total, maxBytes });
+        if (total === buffer.length)
+            buffer = growReadBuffer(buffer, maxBytes);
+        const remaining = buffer.subarray(total);
+        const bytesRead = readChunk(remaining, remaining.length);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, total);
+        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/clone-metadata.d.ts

@@ -0,0 +1,19 @@
+export type CloneFileMetadata = {
+    dev: number;
+    type: number;
+    mtimeSec: number;
+    mtimeNs: number;
+    ctimeSec: number;
+    ctimeNs: number;
+    uid: number;
+    gid: number;
+    mode: number;
+    ino: bigint;
+    size: bigint;
+    cloneId: bigint;
+};
+/** Batched APFS metadata snapshots; absent on unsupported files or filesystems.
+ * These are point-in-time facts, not authorization or a guarantee against later edits.
+ */
+export declare function readCloneFileMetadata(files: readonly string[]): Promise<(CloneFileMetadata | undefined)[]>;
+//# sourceMappingURL=clone-metadata.d.ts.map

package/dist/clone-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone-metadata.d.ts","sourceRoot":"","sources":["../src/clone-metadata.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,OAAO,CAAC,CAAC,iBAAiB,GAAG,SAAS,CAAC,EAAE,CAAC,CA4B5C"}

package/dist/clone-metadata.js

@@ -0,0 +1,32 @@
+import { assertAbsolutePathInput } from "./absolute-path.js";
+import { requireNativeBinding } from "./native.js";
+/** Batched APFS metadata snapshots; absent on unsupported files or filesystems.
+ * These are point-in-time facts, not authorization or a guarantee against later edits.
+ */
+export async function readCloneFileMetadata(files) {
+    const paths = files.map(assertAbsolutePathInput);
+    const results = await requireNativeBinding().readCloneFileMetadata(paths);
+    return results.map((result) => {
+        if (!result ||
+            result.length !== 100 ||
+            result.readUInt32LE(0) !== 100 ||
+            result.readUInt32LE(4) !== 0x82038c0a ||
+            result.readUInt32LE(16) !== 0x200 ||
+            result.readUInt32LE(20) !== 0x100)
+            return undefined;
+        return {
+            dev: result.readUInt32LE(24),
+            type: result.readUInt32LE(28),
+            mtimeSec: Number(result.readBigInt64LE(32)),
+            mtimeNs: Number(result.readBigInt64LE(40)),
+            ctimeSec: Number(result.readBigInt64LE(48)),
+            ctimeNs: Number(result.readBigInt64LE(56)),
+            uid: result.readUInt32LE(64),
+            gid: result.readUInt32LE(68),
+            mode: result.readUInt32LE(72),
+            ino: result.readBigUInt64LE(76),
+            size: result.readBigUInt64LE(84),
+            cloneId: result.readBigUInt64LE(92),
+        };
+    });
+}

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

@@ -0,0 +1,22 @@
+import { type BigIntStats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import { type CopyCloneMode } from "./copy-policy.js";
+import { type NativeBinding } from "./native.js";
+import type { NativeFileCopyResult } from "./native-binding.js";
+export type CopyFileInput = {
+    kind: "file";
+    handle: FileHandle;
+    size: number;
+    clone: CopyCloneMode;
+    signal?: AbortSignal;
+    verifySource(): Promise<void>;
+};
+export declare function resolveFileCopyCloneMode(mode?: CopyCloneMode): CopyCloneMode;
+export declare function assertCopySourceCurrent(source: {
+    handle: FileHandle;
+    realPath: string;
+}, identity: BigIntStats): Promise<void>;
+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;
+//# sourceMappingURL=copy-file-input.d.ts.map

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

@@ -0,0 +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,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

@@ -0,0 +1,69 @@
+import fs, {} from "node:fs";
+import { resolveCopyCloneMode } from "./copy-policy.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { transferFileHandle } from "./file-handle-transfer.js";
+export function resolveFileCopyCloneMode(mode) {
+    const clone = resolveCopyCloneMode(mode, "never");
+    if (clone === "always" && !getNativeBinding()?.copyFileExclusive) {
+        throw new FsSafeError("helper-unavailable", "native file cloning is unavailable");
+    }
+    return clone;
+}
+export async function assertCopySourceCurrent(source, identity) {
+    await inspectFileIdentity(() => fs.fstatSync(source.handle.fd, { bigint: true }), identity);
+    await inspectFileIdentity(() => {
+        const current = fs.lstatSync(source.realPath, { bigint: true });
+        if (current.isSymbolicLink() || !current.isFile()) {
+            throw new FsSafeError("path-mismatch", "copy source path changed");
+        }
+        return current;
+    }, identity);
+}
+export async function writeCopyFileToFd(fd, input, maxBytes, 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();
+    if (!native.copyFileExclusive) {
+        if (input.clone === "always") {
+            throw new FsSafeError("helper-unavailable", "native file cloning is unavailable");
+        }
+        return undefined;
+    }
+    const nativeSignal = input.signal ? AbortSignal.any([input.signal]) : undefined;
+    try {
+        // The caller adopts this descriptor before observing a later cancellation.
+        return await native.copyFileExclusive(input.handle.fd, parentFd, basename, input.clone, maxBytes !== undefined && Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal, sync);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "Cancelled" || code === "ABORT_ERR")
+            input.signal?.throwIfAborted();
+        if (code === "too-large") {
+            throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`, { cause: error });
+        }
+        if (code === "ENOTSUP" && input.clone !== "always")
+            return undefined;
+        if (code === "ENOTSUP") {
+            throw new FsSafeError("unsupported-platform", "native file cloning is unsupported", { cause: error });
+        }
+        throw new FsSafeError("helper-failed", "native file copy failed", { cause: error });
+    }
+    finally {
+        if (nativeSignal)
+            nativeSignal.onabort = null;
+    }
+}
+export function assertNativeCopyCompleted(input, copied) {
+    if (copied?.errorCode) {
+        if (copied.errorCode === "Cancelled" || copied.errorCode === "ABORT_ERR")
+            input.signal?.throwIfAborted();
+        const unsupported = ["ENOTSUP", "EOPNOTSUPP", "ENOSYS", "EXDEV", "EINVAL"].includes(copied.errorCode);
+        throw new FsSafeError(copied.errorCode === "too-large" ? "too-large" : unsupported ? "unsupported-platform" : "helper-failed", copied.errorMessage ?? "native file copy failed", { cause: Object.assign(new Error(copied.errorMessage ?? "native file copy failed"), { code: copied.errorCode }) });
+    }
+    input.signal?.throwIfAborted();
+}

package/dist/copy-policy.d.ts

@@ -0,0 +1,3 @@
+export type CopyCloneMode = "auto" | "always" | "never";
+export declare function resolveCopyCloneMode(mode: CopyCloneMode | undefined, defaultMode: CopyCloneMode): CopyCloneMode;
+//# sourceMappingURL=copy-policy.d.ts.map

package/dist/copy-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy-policy.d.ts","sourceRoot":"","sources":["../src/copy-policy.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,WAAW,EAAE,aAAa,GACzB,aAAa,CAMf"}

package/dist/copy-policy.js

@@ -0,0 +1,8 @@
+import { FsSafeError } from "./errors.js";
+export function resolveCopyCloneMode(mode, defaultMode) {
+    const policy = mode === undefined ? defaultMode : mode;
+    if (policy !== "auto" && policy !== "always" && policy !== "never") {
+        throw new FsSafeError("invalid-path", "copy clone policy must be auto, always, or never");
+    }
+    return policy;
+}

package/dist/copy-publication.d.ts

@@ -1,4 +1,13 @@
-import type { PinnedWriteParams } from "./pinned-write.js";
+import type { PinnedWriteParams, PublishedWriteIdentity } from "./pinned-write.js";
+export type RootCopyPublicationReceipt = Readonly<{
+    path: string;
+    dev: bigint;
+    ino: bigint;
+}>;
+export declare function createCopyPublicationObserver(path: string, notify?: (receipt: RootCopyPublicationReceipt) => void): {
+    onPublished(identity: PublishedWriteIdentity): void;
+    rethrowObserverFailure(error: unknown): void;
+};
 export declare const onCopyPublication: unique symbol;
 export type CopyPublicationOptions = {
     [onCopyPublication]?: PinnedWriteParams["verifyPublished"];

package/dist/copy-publication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copy-publication.d.ts","sourceRoot":"","sources":["../src/copy-publication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAC7D,MAAM,MAAM,sBAAsB,GAAG;IACnC,CAAC,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;CAC5D,CAAC"}
+{"version":3,"file":"copy-publication.d.ts","sourceRoot":"","sources":["../src/copy-publication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAGnF,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb,CAAC,CAAC;AAEH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,0BAA0B,KAAK,IAAI;IAIpD,WAAW,WAAW,sBAAsB,GAAG,IAAI;IAcnD,sBAAsB,QAAQ,OAAO,GAAG,IAAI;EAO/C;AAID,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAC7D,MAAM,MAAM,sBAAsB,GAAG;IACnC,CAAC,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;CAC5D,CAAC"}

package/dist/copy-publication.js

@@ -1,3 +1,30 @@
+import { FsSafeError } from "./errors.js";
+export function createCopyPublicationObserver(path, notify) {
+    let rejected;
+    return {
+        onPublished(identity) {
+            const receipt = Object.freeze({ path, dev: identity.dev, ino: identity.ino });
+            try {
+                const result = notify?.(receipt);
+                if (result !== null && (typeof result === "object" || typeof result === "function") &&
+                    "then" in result && typeof result.then === "function") {
+                    void Promise.resolve(result).catch(() => undefined);
+                    throw new TypeError("onDestinationPublished must be synchronous");
+                }
+            }
+            catch (error) {
+                rejected = { error };
+                throw error;
+            }
+        },
+        rethrowObserverFailure(error) {
+            if (rejected && (error === rejected.error ||
+                (error instanceof FsSafeError && error.cause === rejected.error && error.details?.phase === "publish"))) {
+                throw rejected.error;
+            }
+        },
+    };
+}
 // Internal composition hook; the descriptor is borrowed until the callback returns.
 // Kept off RootCopyOptions and all public package exports.
 export const onCopyPublication = Symbol("onCopyPublication");

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

@@ -0,0 +1,9 @@
+import type { NativeBinding } from "./native-binding.js";
+import { openStagedDirectory } from "./staged-directory.js";
+/** Byte-copy adapter for the shared immutable-source, caller-owned namespace contract. */
+export declare function copyOwnedTree(source: ReturnType<typeof openStagedDirectory>, destination: string, options: {
+    signal?: AbortSignal;
+    concurrency: number;
+    copyFileContents?: NativeBinding["copyFileContents"];
+}): Promise<void>;
+//# sourceMappingURL=copy-tree-portable.d.ts.map

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

@@ -0,0 +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;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

@@ -0,0 +1,222 @@
+import { setMaxListeners } from "node:events";
+import fs from "node:fs";
+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();
+    const cancellation = new AbortController();
+    const signal = cancellation.signal;
+    setMaxListeners(options.concurrency, signal);
+    const abort = () => cancellation.abort(options.signal?.reason);
+    options.signal?.addEventListener("abort", abort, { once: true });
+    const pending = new Set();
+    const finishing = new Set();
+    const buffers = [];
+    async function schedule(operation, children) {
+        signal.throwIfAborted();
+        const task = operation()
+            .catch((error) => {
+            cancellation.abort(error);
+        })
+            .finally(() => {
+            pending.delete(task);
+            children.delete(task);
+        });
+        pending.add(task);
+        children.add(task);
+        if (pending.size >= options.concurrency)
+            await Promise.race(pending);
+        signal.throwIfAborted();
+    }
+    async function copyFile(from, to, stat) {
+        const input = await fsp.open(from, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+        let output;
+        try {
+            const opened = await input.stat({ bigint: true });
+            if (!opened.isFile() || !exactIdentityMatches(stat, opened)) {
+                throw new FsSafeError("path-mismatch", "copy source changed while opening");
+            }
+            output = await fsp.open(to, "wx", 0o600);
+            if (options.copyFileContents) {
+                // napi-rs owns onabort. Each admitted file gets a separate signal so
+                // concurrent native copies cannot replace one another's cancellation.
+                const fileCancellation = new AbortController();
+                const abortFile = () => fileCancellation.abort();
+                signal.addEventListener("abort", abortFile, { once: true });
+                try {
+                    signal.throwIfAborted();
+                    await options.copyFileContents(input.fd, output.fd, fileCancellation.signal);
+                }
+                finally {
+                    signal.removeEventListener("abort", abortFile);
+                }
+            }
+            else {
+                const buffer = buffers.pop() ??
+                    Buffer.allocUnsafe(process.platform === "win32" ? 1024 * 1024 : 128 * 1024);
+                try {
+                    let position = 0;
+                    while (true) {
+                        signal?.throwIfAborted();
+                        const { bytesRead } = await input.read(buffer, 0, buffer.length, position);
+                        if (bytesRead === 0)
+                            break;
+                        let written = 0;
+                        while (written < bytesRead) {
+                            signal?.throwIfAborted();
+                            const { bytesWritten } = await output.write(buffer, written, bytesRead - written, position + written);
+                            if (bytesWritten === 0)
+                                throw new Error("copy write made no progress");
+                            written += bytesWritten;
+                        }
+                        position += bytesRead;
+                    }
+                }
+                finally {
+                    buffers.push(buffer);
+                }
+            }
+            signal.throwIfAborted();
+            if (process.platform !== "win32")
+                await output.chmod(Number(stat.mode & 4095n));
+            await output.utimes(timestampSeconds(stat.atimeNs), timestampSeconds(stat.mtimeNs));
+        }
+        catch (error) {
+            cancellation.abort(error);
+            throw error;
+        }
+        finally {
+            try {
+                await output?.close();
+            }
+            finally {
+                await input.close();
+            }
+        }
+    }
+    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);
+            if (!exactIdentityMatches(stat, original.receipt.identity)) {
+                throw new FsSafeError("path-mismatch", "copy source directory changed while opening");
+            }
+            for (const entry of await fsp.readdir(from, { withFileTypes: true })) {
+                signal?.throwIfAborted();
+                assertStagedDirectoryCurrent(target.receipt);
+                assertStagedDirectoryCurrent(original.receipt);
+                const childSource = path.join(from, entry.name);
+                const childTarget = path.join(to, entry.name);
+                const child = await fsp.lstat(childSource, { bigint: true });
+                if (child.isDirectory()) {
+                    await copyDirectory(childSource, childTarget, children);
+                }
+                else if (child.isFile()) {
+                    await schedule(() => copyFile(childSource, childTarget, child), children);
+                }
+                else if (child.isSymbolicLink()) {
+                    const link = process.platform === "win32"
+                        ? await fsp.readlink(childSource)
+                        : await fsp.readlink(childSource, { encoding: "buffer" });
+                    let type;
+                    if (process.platform === "win32") {
+                        // Older Node releases infer link type from the destination, where a
+                        // relative directory target may not exist yet. Inspect the source.
+                        // lstat does not expose the Windows link's directory attribute, so
+                        // an unresolved source cannot be recreated with a proven type.
+                        try {
+                            type = (await fsp.stat(childSource)).isDirectory() ? "dir" : "file";
+                        }
+                        catch (error) {
+                            if (error instanceof Error &&
+                                "code" in error &&
+                                (error.code === "ENOENT" || error.code === "ENOTDIR" || error.code === "ELOOP")) {
+                                throw new FsSafeError("unsupported-platform", "byte copying cannot determine the type of an unresolved Windows symbolic link", { cause: error });
+                            }
+                            throw error;
+                        }
+                    }
+                    signal?.throwIfAborted();
+                    await fsp.symlink(link, childTarget, type);
+                }
+                else {
+                    throw new FsSafeError("not-file", "tree copying does not support special files");
+                }
+            }
+        }
+        catch (error) {
+            cancellation.abort(error);
+            throw error;
+        }
+        finally {
+            // 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

@@ -0,0 +1,16 @@
+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" | "zfs";
+export type CopyTreeOptions = {
+    clone?: CopyCloneMode;
+    signal?: AbortSignal;
+    concurrency?: number;
+};
+/** Inspect an existing real directory without creating probe files. */
+export declare function probeTreeClone(parentPath: string): TreeCloneBackend | undefined;
+/** Create an empty clone source: a Btrfs subvolume or an ordinary supported directory. */
+export declare function createCloneSource(destination: string, options?: Pick<CopyTreeOptions, "signal">): Promise<void>;
+/** Copy an immutable, caller-owned tree, preferring native cloning unless configured otherwise. */
+export declare function copyTree(source: string, destination: string, options?: CopyTreeOptions): Promise<void>;
+//# sourceMappingURL=copy.d.ts.map

package/dist/copy.d.ts.map

@@ -0,0 +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,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"}