@openclaw/fs-safe 0.14.0 → 0.16.0

package/dist/directory-receipt.d.ts

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

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

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

package/dist/directory-receipt.js

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

package/dist/file-cleanup.d.ts

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

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

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

package/dist/file-cleanup.js

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

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

@@ -5,6 +5,8 @@ export type CopyFileHandleOptions = {
     onChunk?: (chunk: Uint8Array) => void;
     assertBeforeMutation?: () => void;
 };
+/** Copies caller-owned regular-file descriptors without moving either cursor. */
+export declare function copyFileDescriptorSync(sourceFd: number, targetFd: number, options?: CopyFileHandleOptions): number;
 /** Copies caller-owned regular files from offset zero without moving either cursor. */
 export declare function copyFileHandle(source: FileHandle, target: FileHandle, options?: CopyFileHandleOptions): Promise<number>;
 export declare function transferFileHandle(source: FileHandle, target: FileHandle | number, options: CopyFileHandleOptions & {

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

@@ -1 +1 @@
-{"version":3,"file":"file-handle-transfer.d.ts","sourceRoot":"","sources":["../src/file-handle-transfer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAWnD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC;AAkDF,uFAAuF;AACvF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA0CjB;AAGD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,qBAAqB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,MAAM,CAAC,CAwBjB"}
+{"version":3,"file":"file-handle-transfer.d.ts","sourceRoot":"","sources":["../src/file-handle-transfer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAWnD,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC;AAQF,iFAAiF;AACjF,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,qBAA0B,GAClC,MAAM,CA6CR;AAgDD,uFAAuF;AACvF,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA0CjB;AAGD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,OAAO,EAAE,qBAAqB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/file-handle-transfer.js

@@ -1,9 +1,64 @@
+import fs from "node:fs";
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult, composeMutationAssertions, rethrowMutationAuthorityError, } from "./mutation-authority.js";
 import { writeAllToFile } from "./write-file-handle.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 const NO_CALLBACK_ARGUMENTS = Object.freeze([]);
+function createTransferBuffer(sizeHint, limit) {
+    return Buffer.allocUnsafe(Math.min(512 * 1024, Math.max(64 * 1024, sizeHint), limit + 1));
+}
+/** Copies caller-owned regular-file descriptors without moving either cursor. */
+export function copyFileDescriptorSync(sourceFd, targetFd, options = {}) {
+    const signal = options.signal;
+    signal?.throwIfAborted();
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const onChunk = options.onChunk;
+    const assertBeforeMutation = options.assertBeforeMutation;
+    const sourceStat = inspectFileIdentitySync(() => {
+        signal?.throwIfAborted();
+        return fs.fstatSync(sourceFd, { bigint: true });
+    });
+    if (!sourceStat.isFile())
+        throw new FsSafeError("not-file", "copy source descriptor must be a regular file");
+    if (maxBytes !== undefined && Number.isFinite(maxBytes) && sourceStat.size > BigInt(maxBytes)) {
+        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`);
+    }
+    const targetStat = inspectFileIdentitySync(() => {
+        signal?.throwIfAborted();
+        return fs.fstatSync(targetFd, { bigint: true });
+    });
+    if (!targetStat.isFile())
+        throw new FsSafeError("not-file", "copy target descriptor must be a regular file");
+    if (sourceStat.dev === targetStat.dev && sourceStat.ino === targetStat.ino) {
+        throw new FsSafeError("path-alias", "copy source and target descriptors refer to the same file");
+    }
+    const limit = maxBytes ?? Infinity;
+    const buffer = createTransferBuffer(Number(sourceStat.size), limit);
+    let position = 0;
+    while (true) {
+        signal?.throwIfAborted();
+        const bytesRead = fs.readSync(sourceFd, buffer, 0, Math.min(buffer.length, limit - position + 1), position);
+        if (bytesRead > limit - position) {
+            throw new FsSafeError("too-large", `file exceeds limit of ${limit} bytes`);
+        }
+        if (bytesRead === 0)
+            return position;
+        const chunk = buffer.subarray(0, bytesRead);
+        assertSynchronousCallbackResult(onChunk?.(chunk), "onChunk");
+        let offset = 0;
+        while (offset < bytesRead) {
+            signal?.throwIfAborted();
+            assertSynchronousCallbackResult(assertBeforeMutation?.(), "assertBeforeMutation");
+            signal?.throwIfAborted();
+            const written = fs.writeSync(targetFd, chunk, offset, bytesRead - offset, position + offset);
+            if (written <= 0)
+                throw new FsSafeError("helper-failed", "file write made no progress");
+            offset += written;
+        }
+        position += bytesRead;
+    }
+}
 function defineReceiverValue(receiver, key, value) {
     Object.defineProperty(receiver, key, {
         value, enumerable: true, writable: true, configurable: true,
@@ -110,7 +165,7 @@ export function transferFileHandle(source, target, options) {
 }
 async function transferFileHandleCore(source, target, sizeHint, maxBytes, targetPosition, signal, onChunk, beforeWrite, callbackThis) {
     const limit = maxBytes ?? Infinity;
-    const buffer = Buffer.allocUnsafe(Math.min(512 * 1024, Math.max(64 * 1024, sizeHint), limit + 1));
+    const buffer = createTransferBuffer(sizeHint, limit);
     let position = 0;
     while (true) {
         signal?.throwIfAborted();

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

@@ -1 +1 @@
-{"version":3,"file":"file-identity.d.ts","sourceRoot":"","sources":["../src/file-identity.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB,CAAC;AAsBF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,MAAM,CAGlF;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAQT;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAWT"}
+{"version":3,"file":"file-identity.d.ts","sourceRoot":"","sources":["../src/file-identity.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB,CAAC;AAsBF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,MAAM,CAGlF;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAQT;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAqBT"}

package/dist/file-identity.js

@@ -23,12 +23,26 @@ export function sameFileIdentity(left, right, platform = process.platform) {
         !isStatValueProvablyDifferent(left.ino, right.ino, platform));
 }
 export function sameFileIdentityForCleanup(left, right, platform = process.platform) {
+    if (platform !== "win32") {
+        return sameStatValue(left.dev, right.dev) && sameStatValue(left.ino, right.ino);
+    }
     // A zero Windows device or inode is unknown, not proof that a pathname still
     // names the object we created. Cleanup must fail closed rather than delete a
     // replacement that happens to share the known half of the identity.
-    if (platform === "win32" &&
-        (isZero(left.dev) || isZero(left.ino) || isZero(right.dev) || isZero(right.ino))) {
+    // Capture each potentially adapter-backed observation once. This strengthens
+    // the fence against changing accessors; exact legacy getter traces are not a
+    // compatibility contract.
+    const leftDev = left.dev;
+    if (isZero(leftDev))
         return false;
-    }
-    return sameStatValue(left.dev, right.dev) && sameStatValue(left.ino, right.ino);
+    const leftIno = left.ino;
+    if (isZero(leftIno))
+        return false;
+    const rightDev = right.dev;
+    if (isZero(rightDev))
+        return false;
+    const rightIno = right.ino;
+    if (isZero(rightIno))
+        return false;
+    return sameStatValue(leftDev, rightDev) && sameStatValue(leftIno, rightIno);
 }

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

@@ -0,0 +1,19 @@
+import type { SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+export type SyncHeldLock = {
+    fd: number | undefined;
+    lockPath: string;
+    normalizedTargetPath: string;
+    parsePayload?: (raw: string) => unknown;
+    refCount: number;
+    reentrantOwner?: string;
+    snapshot: SidecarLockSnapshot;
+    timer?: NodeJS.Timeout;
+};
+export declare function foreignSyncHeldLock(route: "raw" | "root", target: string): object | undefined;
+export declare function getSyncHeldLocks(): Map<string, SyncHeldLock>;
+export declare function getSyncLockAdmissions(): Map<string, object>;
+export declare function syncLockTimeout(lockPath: string, normalizedTargetPath: string): Error;
+export declare function defaultSyncShouldReclaim(snapshot: SidecarLockSnapshot, staleMs: number, nowMs: number): boolean;
+export declare function syncReclaimGuardExists(reclaimGuardPath: string): boolean;
+export declare function ensureSyncLockExitCleanupRegistered(cleanup: () => void, lockPath: string, normalizedTargetPath: string): void;
+//# sourceMappingURL=file-lock-sync-admission.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock-sync-admission.d.ts","sourceRoot":"","sources":["../src/file-lock-sync-admission.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CACxB,CAAC;AAUF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO7F;AAED,wBAAgB,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAQ5D;AAED,wBAAgB,qBAAqB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ3D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,KAAK,CAMrF;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAIT;AAED,wBAAgB,sBAAsB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAQxE;AAED,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,MAAM,IAAI,EACnB,QAAQ,EAAE,MAAM,EAChB,oBAAoB,EAAE,MAAM,GAC3B,IAAI,CAwCN"}

package/dist/file-lock-sync-admission.js

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import { sidecarLockPayloadCreatedAtMs } from "./sidecar-lock-policy.js";
+const SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncSidecarLocks");
+const SYNC_ADMISSIONS_KEY = Symbol.for("fsSafe.syncSidecarLockAdmissions");
+const SYNC_CLEANUP_REGISTERED_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistered");
+const SYNC_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupHandler");
+const SYNC_CLEANUP_REGISTRATION_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistration");
+const ROOT_SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncRootSidecarLocks.v1");
+export function foreignSyncHeldLock(route, target) {
+    const key = route === "raw" ? ROOT_SYNC_HELD_LOCKS_KEY : SYNC_HELD_LOCKS_KEY;
+    const state = globalThis;
+    return state[key]?.get(target);
+}
+export function getSyncHeldLocks() {
+    const globalWithState = globalThis;
+    if (!globalWithState[SYNC_HELD_LOCKS_KEY]) {
+        globalWithState[SYNC_HELD_LOCKS_KEY] = new Map();
+    }
+    return globalWithState[SYNC_HELD_LOCKS_KEY];
+}
+export function getSyncLockAdmissions() {
+    const globalWithState = globalThis;
+    if (!globalWithState[SYNC_ADMISSIONS_KEY]) {
+        globalWithState[SYNC_ADMISSIONS_KEY] = new Map();
+    }
+    return globalWithState[SYNC_ADMISSIONS_KEY];
+}
+export function syncLockTimeout(lockPath, normalizedTargetPath) {
+    return Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
+        code: "file_lock_timeout",
+        lockPath,
+        normalizedTargetPath,
+    });
+}
+export function defaultSyncShouldReclaim(snapshot, staleMs, nowMs) {
+    const createdAtMs = sidecarLockPayloadCreatedAtMs(snapshot.payload);
+    if (createdAtMs !== null)
+        return nowMs - createdAtMs > staleMs;
+    return !snapshot.stat || nowMs - snapshot.stat.mtimeMs > staleMs;
+}
+export function syncReclaimGuardExists(reclaimGuardPath) {
+    try {
+        fs.lstatSync(reclaimGuardPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export function ensureSyncLockExitCleanupRegistered(cleanup, lockPath, normalizedTargetPath) {
+    const globalWithCleanup = globalThis;
+    if (globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY])
+        return;
+    if (globalWithCleanup[SYNC_CLEANUP_REGISTRATION_KEY]) {
+        // process.on() emits newListener synchronously. A nested synchronous
+        // acquisition cannot wait for this stack to finish registering.
+        throw syncLockTimeout(lockPath, normalizedTargetPath);
+    }
+    const registration = {};
+    globalWithCleanup[SYNC_CLEANUP_REGISTRATION_KEY] = registration;
+    try {
+        process.on("exit", cleanup);
+        globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY] = cleanup;
+        globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY] = true;
+    }
+    catch (error) {
+        if (process.listeners("exit").includes(cleanup)) {
+            try {
+                process.off("exit", cleanup);
+            }
+            catch {
+                // Reconcile the marker with the actual listener below.
+            }
+        }
+        if (process.listeners("exit").includes(cleanup)) {
+            globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY] = cleanup;
+            globalWithCleanup[SYNC_CLEANUP_REGISTERED_KEY] = true;
+        }
+        else {
+            if (globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY] === cleanup) {
+                delete globalWithCleanup[SYNC_CLEANUP_HANDLER_KEY];
+            }
+        }
+        throw error;
+    }
+    finally {
+        if (globalWithCleanup[SYNC_CLEANUP_REGISTRATION_KEY] === registration) {
+            delete globalWithCleanup[SYNC_CLEANUP_REGISTRATION_KEY];
+        }
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { FileLockSyncAcquireOptions, FileLockSyncHandle } from "./file-lock-sync.js";
+import type { Root } from "./root-impl.js";
+export declare function acquireFileLockSyncWithRoot<TPayload extends Record<string, unknown>>(targetPath: string, inputOptions: FileLockSyncAcquireOptions<TPayload>, lockRoot: Root): FileLockSyncHandle;
+//# sourceMappingURL=file-lock-sync-root-acquire.d.ts.map

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

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