@openclaw/fs-safe 0.8.6 → 0.10.0

package/dist/archive-tar-wasm.js

@@ -17,6 +17,7 @@ const types = new Map([
     [51, "CharacterDevice"], [52, "BlockDevice"], [53, "Directory"],
     [54, "FIFO"], [55, "ContiguousFile"], [68, "GNUDumpDir"],
 ]);
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
 function parserError(message) {
     const mapped = classifyArchiveParserError(message);
     if (mapped)
@@ -47,7 +48,7 @@ export class TarParserStream extends Transform {
     }
     text() {
         const abi = this.abi;
-        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(this.bytes(abi.text_ptr(), abi.text_len()));
+        return utf8Decoder.decode(this.bytes(abi.text_ptr(), abi.text_len()));
     }
     _transform(chunk, _encoding, callback) {
         try {

package/dist/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AA6MpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4CjF"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AAiNpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CjF"}

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 { constants as fsConstants } from "node:fs";
+import fsSync, { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { Readable } from "node:stream";
@@ -77,6 +77,8 @@ async function writeZipFileEntry(params) {
             dir: path.dirname(destinationPath),
             chmodDir: false,
             mode: 0o600,
+            syncTempFile: false,
+            syncParentDir: false,
             writeTemp: async (tempPath) => {
                 tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o600);
                 const writable = tempHandle.createWriteStream();
@@ -134,7 +136,7 @@ async function extractZip(params) {
         await withStagedArchiveDestination({
             destinationRealDir,
             run: async (stagingDir) => {
-                const stagingRealDir = await fs.realpath(stagingDir);
+                const stagingRealDir = fsSync.realpathSync.native(stagingDir);
                 const acceptedEntries = [];
                 for (const entry of entries) {
                     params.deadline.check();
@@ -185,6 +187,7 @@ async function extractZip(params) {
                 params.deadline.check();
                 await mergePlannedArchiveIntoDestination({
                     entries: acceptedEntries,
+                    durable: params.durable,
                     sourceDir: stagingRealDir,
                     destinationDir: params.destDir,
                     destinationRealDir,
@@ -212,6 +215,7 @@ export async function extractArchive(params) {
     // getters and inherited policy must survive identically on every backend.
     const options = {
         archivePath: params.archivePath, destDir: params.destDir,
+        durable: params.durable,
         stripComponents: params.stripComponents, limits,
         entryModes: params.entryModes, entryFilter: params.entryFilter, onFiltered,
     };
@@ -246,7 +250,7 @@ async function extractWasmTar(params) {
     deadline.check();
     const destinationRealDir = await prepareArchiveDestinationDir(options.destDir);
     await withStagedArchiveDestination({ destinationRealDir, run: async (stagingPath) => {
-            const stagingDir = await fs.realpath(stagingPath);
+            const stagingDir = fsSync.realpathSync.native(stagingPath);
             const planEntry = createTarEntryPlanner({ ...options, rootDir: destinationRealDir, limits: params.limits });
             const accepted = manifest.flatMap((entry) => {
                 deadline.check();
@@ -262,6 +266,7 @@ async function extractWasmTar(params) {
                     if (member.kind === "file") {
                         await runPinnedWriteHelper({ rootPath: stagingDir, relativeParentPath: path.posix.dirname(member.path),
                             basename: path.posix.basename(member.path), mkdir: false, mode: 0o600, overwrite: false,
+                            sync: false,
                             maxBytes: member.size, input: { kind: "stream", stream: Readable.from(payload) } });
                     }
                     deadline.check();
@@ -269,7 +274,7 @@ async function extractWasmTar(params) {
             });
             deadline.check();
             await mergePlannedArchiveIntoDestination({ entries: accepted, sourceDir: stagingDir,
-                destinationDir: options.destDir, destinationRealDir, deadline });
+                destinationDir: options.destDir, destinationRealDir, deadline, durable: options.durable });
             deadline.check();
         } });
 }

package/dist/bounded-read.d.ts

@@ -1,5 +1,12 @@
 import type { FileHandle } from "node:fs/promises";
 type ReadableFileHandle = Pick<FileHandle, "read">;
+export declare function readBoundedAsync(maxBytes: number, readChunk: (scratch: Buffer, length: number) => Promise<number>, options?: {
+    observeRegularFileSize?: () => number | undefined;
+    initialSize?: number;
+    createLimitError?: () => Error;
+    /** Keep the result outside Node's shared small-buffer allocation pool. */
+    unpooled?: boolean;
+}): Promise<Buffer>;
 /**
  * Reads from the handle's current offset without closing it. A bounded read
  * consumes at most maxBytes + 1 bytes so growth after an earlier stat cannot

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;AAMnD,KAAK,kBAAkB,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AA+DnD;;;;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,CAalF"}
+{"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"}

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,31 @@ 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) {
     normalizeMaxBytes(maxBytes);
-    const chunks = [];
-    const scratch = createScratchBuffer(maxBytes);
     let total = 0;
+    // Small budgets already bound the first allocation without a size lookup.
+    const size = maxBytes <= READ_CHUNK_BYTES ? maxBytes : regularFileSize(fd);
+    let buffer = size === undefined ? createScratchBuffer(maxBytes) : createInitialBuffer(maxBytes, size);
+    if (size !== undefined) {
+        const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, null);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, 0);
+        const currentSize = bytesRead < buffer.length ? regularFileSize(fd) : undefined;
+        total = addReadBytes(total, bytesRead, maxBytes);
+        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 = fs.readSync(fd, remaining, 0, remaining.length, null);
+        if (bytesRead === 0)
+            return finishReadBuffer(buffer, total);
+        total = addReadBytes(total, bytesRead, maxBytes);
     }
 }

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,23 @@
+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 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;
+//# 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,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"}

package/dist/copy-file-input.js

@@ -0,0 +1,91 @@
+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 { writeAllToFile } from "./write-file-handle.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* 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?.();
+            },
+        });
+    }
+}
+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

@@ -0,0 +1,15 @@
+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"];
+};
+//# sourceMappingURL=copy-publication.d.ts.map

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

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

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