@openclaw/fs-safe 0.13.1 → 0.15.0

package/dist/native-policy-parent-windows.js

@@ -0,0 +1,200 @@
+import fsSync, {} from "node:fs";
+import path from "node:path";
+import { assertDirectoryIdentitySync, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { openNativeParentAdmission } from "./native-parent-admission.js";
+import { captureNativeFdClose } from "./native-binding.js";
+import { inspectNativeDirectoryObservation } from "./native-directory-observation.js";
+import { createPathSegmentRoute, joinPathSegmentRoute } from "./path-segment-route.js";
+import { isSymlinkOpenError } from "./path.js";
+import { checkedMutationDirectory } from "./pinned-mutation-observation.js";
+import { canReuseParentWithMutationAssertion } from "./root-write-lock-binding.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+function assertParentCurrent(parent) {
+    const current = inspectFileIdentitySync(() => fsSync.fstatSync(parent.fd, { bigint: true }), parent.guard.stat);
+    assertDirectoryIdentitySync(parent.guard.dir, {
+        dev: parent.guard.stat.dev,
+        ino: parent.guard.stat.ino,
+        realPath: parent.guard.realPath,
+    });
+    return current;
+}
+function closeAfterFailure(closeFd, fd) {
+    if (fd === undefined)
+        return;
+    try {
+        closeFd(fd);
+    }
+    catch {
+        // Windows retains the operation failure while attempting every owned close.
+    }
+}
+export async function capturePolicyAwareWindowsParent(binding, params, rootAdmission) {
+    const closeFd = captureNativeFdClose(binding);
+    let session;
+    function parentObservation(fd, guard) {
+        return checkedMutationDirectory(guard.dir, guard.realPath, guard.stat, typeof binding.observeDirectory === "function" ? () => {
+            const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), guard.stat);
+            let observed;
+            try {
+                observed = inspectNativeDirectoryObservation(binding, guard.dir, stat);
+            }
+            catch (error) {
+                if (error?.code === "OBSERVATION_UNAVAILABLE")
+                    return undefined;
+                throw error;
+            }
+            return { canonicalPath: observed.realPath,
+                identity: { dev: stat.dev, ino: stat.ino, mode: stat.mode, nlink: stat.nlink } };
+        } : undefined);
+    }
+    async function openParent(fd, parentPath, relativePath) {
+        try {
+            const admitted = await openNativeParentAdmission(binding, {
+                ...rootAdmission,
+                root: { fd },
+                rootPath: parentPath,
+                // Policy fences retain every identity bit even with a legacy numeric root.
+                exactRoot: true,
+            }, relativePath, "native-directory");
+            const guard = { ...admitted.guard, stat: admitted.guard.stat };
+            return { fd: admitted.fd, guard, observation: parentObservation(admitted.fd, guard) };
+        }
+        catch (error) {
+            if (!isSymlinkOpenError(error))
+                throw error;
+            throw new FsSafeError(params.mutationAdmission.rejectParentSymlinks ? "symlink" : "path-mismatch", "native write parent changed during policy admission", { cause: error instanceof Error ? error : undefined });
+        }
+    }
+    async function authorize(targetPath, mutationPath = targetPath, phase = "parent") {
+        const request = Object.freeze({ targetPath, mutationPath, phase });
+        return await (session ? session.authorize(request) : params.mutationAdmission.authorize(request));
+    }
+    // Existing complete parents need one open and one target admission. Exact
+    // parent denies apply only to creation, never to merely using a directory.
+    let complete;
+    try {
+        complete = await openParent(rootAdmission.root.fd, params.rootPath, params.relativeParentPath);
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT" || !params.mkdir)
+            throw error;
+    }
+    if (complete) {
+        try {
+            await authorize(path.join(complete.guard.realPath, params.basename));
+            assertParentCurrent(complete);
+            return complete;
+        }
+        catch (error) {
+            closeAfterFailure(closeFd, complete.fd);
+            throw error;
+        }
+    }
+    const segments = params.relativeParentPath.split("/").filter(Boolean);
+    const route = createPathSegmentRoute(segments);
+    const rootStat = inspectDirectoryIdentitySync(params.rootPath, inspectFileIdentitySync(() => fsSync.fstatSync(rootAdmission.root.fd, { bigint: true })));
+    let current = {
+        fd: rootAdmission.root.fd,
+        guard: { dir: params.rootPath, realPath: params.rootPath, stat: rootStat },
+        observation: parentObservation(rootAdmission.root.fd, {
+            dir: params.rootPath, realPath: params.rootPath, stat: rootStat,
+        }),
+    };
+    let ownedFd;
+    const initialTarget = joinPathSegmentRoute(params.rootPath, route, 0, params.basename);
+    if (canReuseParentWithMutationAssertion(params.assertBeforeMutation, params.rootPath, initialTarget)) {
+        session = params.mutationAdmission?.beginNativeParentWalk?.() ??
+            params.mutationAdmission?.beginSharedParentWalk?.();
+        if (session && session.retainedTargetPath !== initialTarget) {
+            session.dispose();
+            session = undefined;
+        }
+    }
+    try {
+        for (let index = 0; index < segments.length; index += 1) {
+            const segment = segments[index];
+            const parentPath = current.guard.realPath;
+            let child;
+            let createdByMkdir = false;
+            let createReceipt;
+            try {
+                child = await openParent(current.fd, parentPath, segment);
+            }
+            catch (error) {
+                if (error?.code !== "ENOENT")
+                    throw error;
+                // The request admits both the prospective leaf and this missing direct
+                // child. A deeper denial can leave already admitted ancestors intact.
+                const targetPath = session?.retainedTargetPath ??
+                    joinPathSegmentRoute(parentPath, route, index, params.basename);
+                const mutationPath = path.join(parentPath, segment);
+                const request = Object.freeze({ targetPath, mutationPath, phase: "parent-create" });
+                createReceipt = session?.tryAuthorizeAtParent(request, current.observation);
+                if (!createReceipt) {
+                    createReceipt = await authorize(targetPath, mutationPath, "parent-create");
+                    assertParentCurrent(current);
+                }
+                if (params.assertBeforeMutation) {
+                    // Opaque callbacks retain their post-callback descriptor/path fence.
+                    params.assertBeforeMutation();
+                    assertParentCurrent(current);
+                }
+                // Synchronous session admission already ends at the exact parent fence.
+                const mkdirChild = binding.mkdirChildBeneath;
+                if (typeof mkdirChild !== "function") {
+                    throw new FsSafeError("helper-unavailable", "native direct-child parent creation is unavailable");
+                }
+                createdByMkdir = mkdirChild.call(binding, current.fd, segment, 0o777) === true;
+                child = await openParent(current.fd, parentPath, segment);
+            }
+            try {
+                const targetPath = joinPathSegmentRoute(child.guard.realPath, route, index + 1, params.basename);
+                if (session && targetPath !== session.retainedTargetPath) {
+                    session.dispose();
+                    session = undefined;
+                }
+                let evidence;
+                if (session && createdByMkdir && createReceipt) {
+                    try {
+                        evidence = Object.freeze({
+                            admission: createReceipt,
+                            parent: parentObservation(current.fd, { ...current.guard,
+                                stat: inspectFileIdentitySync(() => fsSync.fstatSync(current.fd, { bigint: true }), current.guard.stat),
+                            }),
+                            child: child.observation,
+                        });
+                    }
+                    catch {
+                        // Incomplete optional evidence returns to ordered admission below.
+                    }
+                }
+                // Advancement refreshes both named directories after all Root/policy
+                // observations; these receipts supply expectations, not cached authority.
+                const advanced = evidence && session.advanceCreatedDirectory(evidence);
+                if (!advanced) {
+                    await authorize(targetPath);
+                    assertParentCurrent(child);
+                }
+            }
+            catch (error) {
+                closeAfterFailure(closeFd, child.fd);
+                throw error;
+            }
+            const previousFd = ownedFd;
+            current = child;
+            ownedFd = child.fd;
+            if (previousFd !== undefined)
+                closeFd(previousFd);
+        }
+        if (ownedFd === undefined) {
+            throw new FsSafeError("path-mismatch", "native write parent admission did not complete");
+        }
+        ownedFd = undefined;
+        return current;
+    }
+    finally {
+        session?.dispose();
+        closeAfterFailure(closeFd, ownedFd);
+    }
+}

package/dist/native-rename-outcome.d.ts

@@ -0,0 +1,4 @@
+export declare const NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH = "FS_SAFE_INTERNAL_RENAME_SOURCE_IDENTITY_MISMATCH";
+export type NativeRenameFailureOutcome = "uncommitted" | "indeterminate";
+export declare function classifyNativeRenameFailure(error: unknown): NativeRenameFailureOutcome;
+//# sourceMappingURL=native-rename-outcome.d.ts.map

package/dist/native-rename-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-rename-outcome.d.ts","sourceRoot":"","sources":["../src/native-rename-outcome.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sCAAsC,qDACC,CAAC;AAErD,MAAM,MAAM,0BAA0B,GAAG,aAAa,GAAG,eAAe,CAAC;AAEzE,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAMtF"}

package/dist/native-rename-outcome.js

@@ -0,0 +1,8 @@
+export const NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH = "FS_SAFE_INTERNAL_RENAME_SOURCE_IDENTITY_MISMATCH";
+export function classifyNativeRenameFailure(error) {
+    const code = error?.code ?? "";
+    // Ordinary errno can follow a committed remote rename whose reply was lost.
+    return code === NATIVE_RENAME_SOURCE_IDENTITY_MISMATCH
+        ? "uncommitted"
+        : "indeterminate";
+}

package/dist/native-staged-file.d.ts

@@ -8,8 +8,8 @@ export type NativeStagingBinding = NativeBinding & Required<Pick<NativeBinding,
 export declare function assertNativeStaging(binding: NativeBinding): asserts binding is NativeStagingBinding;
 declare class NativeStagedFile implements StagedFile {
     #private;
-    constructor(binding: NativeStagingBinding, parentFd: number, closeParentFd: (fd: number) => void, directory: StagedFileReceipt["directory"], portableNames: boolean, publishedMode: number, sync: boolean, assertBeforeMutation?: () => void);
-    static create(binding: NativeStagingBinding, parentFd: number, closeParentFd: (fd: number) => void, directory: StagedFileReceipt["directory"], input: PinnedWriteInput, mode: number, maxBytes?: number, portableNames?: boolean, sync?: boolean, assertBeforeMutation?: () => void): Promise<NativeStagedFile>;
+    constructor(binding: NativeStagingBinding, parentFd: number, closeParentFd: (fd: number) => void, directory: StagedFileReceipt["directory"], portableNames: boolean, publishedMode: number, sync: boolean, assertBeforeMutation?: () => void, name?: string);
+    static create(binding: NativeStagingBinding, parentFd: number, closeParentFd: (fd: number) => void, directory: StagedFileReceipt["directory"], input: PinnedWriteInput, mode: number, maxBytes?: number, portableNames?: boolean, sync?: boolean, assertBeforeMutation?: () => void, exclusiveBasename?: string): Promise<NativeStagedFile>;
     static write(binding: NativeStagingBinding, parentFd: number, closeParentFd: (fd: number) => void, directory: StagedFileReceipt["directory"], params: PinnedWriteParams, parentGuard: AnyAsyncDirectoryGuard): Promise<FileIdentityStat>;
     get receipt(): StagedFileReceipt;
     assertCurrent(): Promise<void>;

package/dist/native-staged-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-staged-file.d.ts","sourceRoot":"","sources":["../src/native-staged-file.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"native-staged-file.d.ts","sourceRoot":"","sources":["../src/native-staged-file.ts"],"names":[],"mappings":"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"}

package/dist/native-staged-file.js

@@ -62,6 +62,7 @@ import { writeNativeInput } from "./native-operations.js";
 import { assertNativeCopyCompleted, createNativeCopyFile } from "./copy-file-input.js";
 import { assertStagedDirectoryCurrent, openStagedDirectory } from "./staged-directory.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { classifyNativeRenameFailure } from "./native-rename-outcome.js";
 export function assertNativeStaging(binding) {
     if ([
         binding.closeOwnedFd,
@@ -81,11 +82,6 @@ function assertBasename(name, portable) {
     }
 }
 const NOT_PUBLISHED = Object.freeze({ status: "not-published" });
-const UNCOMMITTED_RENAME_ERRORS = new Set([
-    "EACCES", "EBADF", "EBUSY", "EEXIST", "EINVAL", "EISDIR", "ELOOP", "EMLINK",
-    "ENAMETOOLONG", "ENOENT", "ENOSPC", "ENOSYS", "ENOTDIR", "ENOTEMPTY", "ENOTSUP",
-    "EPERM", "EROFS", "ETXTBSY", "EXDEV",
-]);
 function failure(error, details) {
     const code = error instanceof FsSafeError
         ? error.code
@@ -102,11 +98,13 @@ class NativeStagedFile {
     #publishedMode;
     #sync;
     #assertBeforeMutation;
-    #name = `.fs-safe-${randomUUID()}.tmp`;
+    #name;
     #state = { status: "open", publication: NOT_PUBLISHED };
     #receipt;
     #rejectFinalSymlink = false;
-    constructor(binding, parentFd, closeParentFd, directory, portableNames, publishedMode, sync, assertBeforeMutation) {
+    constructor(binding, parentFd, closeParentFd, directory, portableNames, publishedMode, sync, assertBeforeMutation, name = `.fs-safe-${randomUUID()}.tmp`) {
+        assertBasename(name, portableNames);
+        this.#name = name;
         this.#closeFd = captureNativeFdClose(binding);
         this.#binding = binding;
         this.#parentFd = parentFd;
@@ -121,10 +119,10 @@ class NativeStagedFile {
     // The supplied closer owns parentFd even on construction or preparation failure.
     static async create(binding, parentFd, closeParentFd, directory, input, mode, maxBytes, 
     // Public staging uses portable names; existing POSIX writes accept literal names.
-    portableNames = true, sync = true, assertBeforeMutation) {
+    portableNames = true, sync = true, assertBeforeMutation, exclusiveBasename) {
         let staged;
         try {
-            staged = new NativeStagedFile(binding, parentFd, closeParentFd, directory, portableNames, mode, sync, assertBeforeMutation);
+            staged = new NativeStagedFile(binding, parentFd, closeParentFd, directory, portableNames, mode, sync, assertBeforeMutation, exclusiveBasename);
         }
         catch (error) {
             try {
@@ -141,13 +139,20 @@ class NativeStagedFile {
     static async write(binding, parentFd, closeParentFd, directory, params, parentGuard) {
         const env_1 = { stack: [], error: void 0, hasError: false };
         try {
+            const exclusive = params.overwrite === false && params.input.kind === "buffer" && params.input.stageBeforePublish === false;
             // This owner never escapes. Only the internal verifier borrows its fd;
             // public descriptor methods remain await-free and cannot race disposal.
-            const staged = __addDisposableResource(env_1, await NativeStagedFile.create(binding, parentFd, closeParentFd, directory, params.input, params.mode, params.maxBytes, false, params.sync, params.assertBeforeMutation), true);
+            const staged = __addDisposableResource(env_1, await NativeStagedFile.create(binding, parentFd, closeParentFd, directory, params.input, params.mode, params.maxBytes, false, params.sync, params.assertBeforeMutation, exclusive ? params.basename : undefined), true);
             staged.#rejectFinalSymlink = params.rejectFinalSymlink === true;
             if (params.input.kind === "file")
                 await params.input.verifySource();
-            const published = await staged.publish(params.basename, { overwrite: params.overwrite !== false }, params.onPublished);
+            if (exclusive) {
+                staged.#assertCurrent();
+                params.assertBeforeMutation?.();
+            }
+            const published = exclusive
+                ? staged.#completePublication(params.basename, false, params.onPublished)
+                : await staged.publish(params.basename, { overwrite: params.overwrite !== false }, params.onPublished);
             const identity = published.staged.identity;
             await params.verifyPublished?.(staged.#file(), identity, parentGuard);
             return { dev: identity.dev, ino: identity.ino };
@@ -279,39 +284,13 @@ class NativeStagedFile {
                 }
             }
             catch (error) {
-                // Unknown rename errors can be indeterminate on remote filesystems.
-                if (!UNCOMMITTED_RENAME_ERRORS.has(error?.code ?? "")) {
+                // Only explicit pre-dispatch provenance can rule out a committed rename.
+                if (classifyNativeRenameFailure(error) === "indeterminate") {
                     state.publication = Object.freeze({ status: "indeterminate", basename, overwrite });
                 }
                 throw error;
             }
-            // Commit is recorded synchronously before any post-rename operation.
-            const receipt = Object.freeze({
-                status: "published",
-                staged: this.receipt,
-                basename,
-                overwrite,
-            });
-            state.publication = receipt;
-            onPublished?.(receipt.staged.identity);
-            const stagedMode = this.#assertNamed(basename);
-            assertStagedDirectoryCurrent(this.#directory);
-            // Keep contents private until the published name passes its identity
-            // fence. Mode changes use the owned fd, including for final mode 000.
-            const fd = this.#file();
-            if (this.#publishedMode !== 0o600 || stagedMode !== 0o600)
-                fs.fchmodSync(fd, this.#publishedMode);
-            // With sync enabled, content was synced before rename. A lost chmod leaves staged 0600,
-            // no wider than modes retaining owner rw. Restrictive modes and observed
-            // widening of the stage still need the permission correction made durable.
-            if (this.#sync && ((this.#publishedMode & 0o600) !== 0o600 || (stagedMode & ~this.#publishedMode) !== 0)) {
-                syncFileBestEffortSync(fd);
-            }
-            if (this.#sync)
-                syncFileBestEffortSync(this.#parentFd);
-            this.#assertNamed(basename);
-            assertStagedDirectoryCurrent(this.#directory);
-            return receipt;
+            return this.#completePublication(basename, overwrite, onPublished);
         }
         catch (error) {
             if (error instanceof MutationAuthorityError)
@@ -323,6 +302,29 @@ class NativeStagedFile {
             throw failure(error, { phase: "publish", publication });
         }
     }
+    #completePublication(basename, overwrite, onPublished) {
+        // Record complete content before fallible post-publication verification.
+        const receipt = Object.freeze({ status: "published", staged: this.receipt, basename, overwrite });
+        this.#open().publication = receipt;
+        onPublished?.(receipt.staged.identity);
+        const stagedMode = this.#assertNamed(basename);
+        assertStagedDirectoryCurrent(this.#directory);
+        // Keep contents private until the name passes its identity fence. Mode
+        // changes use the owned fd, including for final mode 000.
+        const fd = this.#file();
+        if (this.#publishedMode !== 0o600 || stagedMode !== 0o600)
+            fs.fchmodSync(fd, this.#publishedMode);
+        // Content was synced during preparation. A lost chmod leaves 0600, no wider
+        // than modes retaining owner rw; restrictive modes still need a durable correction.
+        if (this.#sync && ((this.#publishedMode & 0o600) !== 0o600 || (stagedMode & ~this.#publishedMode) !== 0)) {
+            syncFileBestEffortSync(fd);
+        }
+        if (this.#sync)
+            syncFileBestEffortSync(this.#parentFd);
+        this.#assertNamed(basename);
+        assertStagedDirectoryCurrent(this.#directory);
+        return receipt;
+    }
     #finalize() {
         if (this.#state.status === "closed") {
             return this.#state;

package/dist/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAyDF,wBAAsB,2BAA2B,CAAC,CAAC,GAAG,IAAI,EACxD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CA2DrC"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,IAAI,IAAI;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAyDF,wBAAsB,2BAA2B,CAAC,CAAC,GAAG,IAAI,EACxD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CA+DrC"}

package/dist/output.js

@@ -57,6 +57,10 @@ export async function writeExternalFileWithinRoot(options) {
     const requestedTargetPath = options.path;
     assertNoWindowsPathAlias(path.dirname(requestedTargetPath), "filesystem", "output target parent uses a Windows filesystem namespace alias");
     const producerIsolation = options.producerIsolation;
+    const write = options.write;
+    const mode = options.mode;
+    const staging = options.staging;
+    const fallbackFileName = options.fallbackFileName;
     const targetRoot = await root(rootDir);
     if (requestedTargetPath.length === 0) {
         throw new FsSafeError("invalid-path", "target path is required");
@@ -68,11 +72,11 @@ export async function writeExternalFileWithinRoot(options) {
         targetPath: requestedTargetPath,
     });
     assertFileTargetPath(rawTargetPath);
-    const targetPath = sanitizedTargetPath(rawTargetPath, options.fallbackFileName);
+    const targetPath = sanitizedTargetPath(rawTargetPath, fallbackFileName);
     assertNoWindowsPathAlias(targetPath, "filesystem", "output target uses a Windows filesystem namespace alias");
     const finalPath = await targetRoot.resolve(targetPath);
     assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
-    if (options.staging === "sibling") {
+    if (staging === "sibling") {
         const parentPath = path.dirname(targetPath);
         if (parentPath !== ".") {
             await targetRoot.mkdir(parentPath);
@@ -80,23 +84,23 @@ export async function writeExternalFileWithinRoot(options) {
         const siblingFinalPath = await targetRoot.resolve(targetPath);
         const result = await writeExternalFileViaSibling({
             finalPath: siblingFinalPath,
-            write: options.write,
+            write,
             producerIsolation,
-            fallbackFileName: options.fallbackFileName,
+            fallbackFileName,
             maxBytes,
-            mode: options.mode,
+            mode,
         });
         return { path: siblingFinalPath, result };
     }
     const staged = await tempFile({
         prefix: "fs-safe-output",
-        fileName: tempFileNameForTarget(targetPath, options.fallbackFileName),
+        fileName: tempFileNameForTarget(targetPath, fallbackFileName),
     });
     try {
-        const result = await options.write(staged.path);
+        const result = await Function.prototype.call.call(write, options, staged.path);
         await targetRoot.copyIn(targetPath, staged.path, {
             maxBytes,
-            mode: options.mode,
+            mode,
             mkdir: true,
             sourceHardlinks: "reject",
         });

package/dist/path-prefix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-prefix.d.ts","sourceRoot":"","sources":["../src/path-prefix.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD,CAAC;AAkBF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAsDvE"}
+{"version":3,"file":"path-prefix.d.ts","sourceRoot":"","sources":["../src/path-prefix.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD,CAAC;AAuBF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAuEvE"}

package/dist/path-prefix.js

@@ -19,15 +19,23 @@ function resolutionError(code, absolutePath) {
         code, syscall: "resolvePathPrefix", path: absolutePath,
     });
 }
+// Leave ample room for ordinary shallow paths to retain the legacy small-array
+// path. At 32 components, repeated front removal can reindex at most 496 array
+// positions per constructed queue; longer queues use a forward cursor instead.
+const SHIFT_QUEUE_COMPONENT_LIMIT = 32;
 export function resolvePathPrefixSync(input) {
     assertNoNulPathInput(input);
     const absolutePath = absolutePathWithRawSegments(input);
     let resolved = rawRoot(absolutePath);
-    const remaining = absolutePath.slice(resolved.length).split(path.sep);
+    let remaining = absolutePath.slice(resolved.length).split(path.sep);
+    let shiftQueue = remaining.length <= SHIFT_QUEUE_COMPONENT_LIMIT;
+    let nextSegment = 0;
+    let remainingCount = remaining.length;
     const visitedStates = new Set();
     let symlinkHops = 0;
-    while (remaining.length > 0) {
-        const segment = remaining.shift();
+    while (remainingCount > 0) {
+        const segment = shiftQueue ? remaining.shift() : remaining[nextSegment++];
+        remainingCount--;
         if (segment === "")
             continue;
         if (segment === "." || segment === "..") {
@@ -51,32 +59,46 @@ export function resolvePathPrefixSync(input) {
             return {
                 absolutePath,
                 existingPath: realpathSync.native(pathForWindowsFilesystem(resolved)),
-                unresolvedSegments: [segment, ...remaining],
+                unresolvedSegments: shiftQueue ? [segment, ...remaining] : remaining.slice(nextSegment - 1),
             };
         }
         if (!stat.isSymbolicLink()) {
-            if (!stat.isDirectory() && remaining.length > 0)
+            if (!stat.isDirectory() && remainingCount > 0)
                 throw resolutionError("ENOTDIR", absolutePath);
             resolved = candidate;
             continue;
         }
-        const state = JSON.stringify([String(stat.dev), String(stat.ino), candidate, remaining]);
+        const pendingSuffix = shiftQueue ? remaining : remaining.slice(nextSegment);
+        const state = JSON.stringify([String(stat.dev), String(stat.ino), candidate, pendingSuffix]);
         if (symlinkHops >= 64 || visitedStates.has(state))
             throw resolutionError("ELOOP", absolutePath);
         visitedStates.add(state);
         symlinkHops++;
         const target = fs.readlinkSync(candidate);
         const rawTarget = path.sep === "\\" ? target.replaceAll("/", "\\") : target;
+        let targetSegments;
         if (path.isAbsolute(rawTarget)) {
             const targetRoot = rawRoot(rawTarget);
             // A rooted Windows link target uses the link's drive/share, not cwd's.
             resolved = path.sep === "\\" && targetRoot === "\\" ? rawRoot(resolved) : targetRoot;
-            remaining.unshift(...rawTarget.slice(targetRoot.length).split(path.sep));
+            targetSegments = rawTarget.slice(targetRoot.length).split(path.sep);
         }
         else {
             // A target's parent traversal applies after resolving its preceding links.
-            remaining.unshift(...rawTarget.split(path.sep));
+            targetSegments = rawTarget.split(path.sep);
         }
+        const expandedCount = targetSegments.length + pendingSuffix.length;
+        if (expandedCount <= SHIFT_QUEUE_COMPONENT_LIMIT) {
+            // The spread is bounded by the same fixed limit as subsequent shifts.
+            remaining = pendingSuffix;
+            remaining.unshift(...targetSegments);
+        }
+        else {
+            remaining = targetSegments.concat(pendingSuffix);
+        }
+        remainingCount = remaining.length;
+        shiftQueue = remainingCount <= SHIFT_QUEUE_COMPONENT_LIMIT;
+        nextSegment = 0;
     }
     return { absolutePath, existingPath: realpathSync.native(pathForWindowsFilesystem(resolved)), unresolvedSegments: [] };
 }

package/dist/path-suffix-aliases.d.ts

@@ -2,6 +2,8 @@ export type ProbePathSuffixAliasesOptions = {
     directory: string;
     left: string;
     right: string;
+    /** Maximum relative component count; defaults to 32. */
+    maxDepth?: number;
     /** Synchronous caller policy for differing NFC pairs not equivalent under ASCII case folding. */
     shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
 };

package/dist/path-suffix-aliases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-suffix-aliases.d.ts","sourceRoot":"","sources":["../src/path-suffix-aliases.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1E,CAAC;AA6UF,4FAA4F;AAC5F,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,GAAG,SAAS,CA8CtG"}
+{"version":3,"file":"path-suffix-aliases.d.ts","sourceRoot":"","sources":["../src/path-suffix-aliases.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1E,CAAC;AAkVF,4FAA4F;AAC5F,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,GAAG,SAAS,CAmDtG"}