@openclaw/fs-safe 0.10.0 → 0.12.0

package/dist/root-boundary.js

@@ -0,0 +1,177 @@
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { isPathRelativeEscape } from "./path.js";
+import { realpathSync } from "./realpath.js";
+function windowsComparablePath(value, normalize) {
+    const original = normalize
+        ? path.win32.normalize(value.replaceAll("/", "\\"))
+        : value.replaceAll("/", "\\");
+    if (/^\\\\\?\\UNC\\/i.test(original)) {
+        return {
+            original,
+            comparison: `\\\\${original.slice(8)}`,
+            originalIndex: (comparisonIndex) => comparisonIndex + 6,
+        };
+    }
+    if (original.startsWith("\\\\?\\")) {
+        return {
+            original,
+            comparison: original.slice(4),
+            originalIndex: (comparisonIndex) => comparisonIndex + 4,
+        };
+    }
+    return { original, comparison: original, originalIndex: (comparisonIndex) => comparisonIndex };
+}
+function trimWindowsTrailingSeparators(value) {
+    const rootLength = path.win32.parse(value).root.length;
+    let end = value.length;
+    while (end > rootLength && value[end - 1] === "\\")
+        end -= 1;
+    return value.slice(0, end);
+}
+function trimWindowsLeadingSeparators(value) {
+    let start = 0;
+    while (value[start] === "\\")
+        start += 1;
+    return value.slice(start);
+}
+function exactWindowsRootPrefix(rootPath, candidatePath) {
+    const root = trimWindowsTrailingSeparators(rootPath.replaceAll("/", "\\"));
+    const candidate = candidatePath.replaceAll("/", "\\");
+    let relativePath;
+    if (candidate === root) {
+        relativePath = "";
+    }
+    else {
+        const rootWithSep = root.endsWith("\\") ? root : `${root}\\`;
+        if (!candidate.startsWith(rootWithSep))
+            return undefined;
+        relativePath = trimWindowsLeadingSeparators(candidate.slice(rootWithSep.length));
+    }
+    return {
+        admission: "exact",
+        candidateRootPath: root,
+        path: relativePath === "" ? root : `${root}${root.endsWith("\\") ? "" : "\\"}${relativePath}`,
+        relativePath,
+    };
+}
+function windowsRootPrefix(rootPath, candidatePath) {
+    const exact = exactWindowsRootPrefix(rootPath, candidatePath);
+    if (exact)
+        return exact;
+    const trusted = windowsComparablePath(rootPath, true);
+    const supplied = windowsComparablePath(candidatePath, false);
+    const root = trimWindowsTrailingSeparators(trusted.original);
+    const rootComparison = trimWindowsTrailingSeparators(trusted.comparison);
+    const candidate = supplied.comparison;
+    if (!path.win32.isAbsolute(supplied.original))
+        return undefined;
+    let relativePath;
+    let candidateRootPath;
+    let admission;
+    if (candidate === rootComparison) {
+        relativePath = "";
+        candidateRootPath = supplied.original;
+        admission = "exact";
+    }
+    else if (candidate.toLowerCase() === rootComparison.toLowerCase()) {
+        relativePath = "";
+        candidateRootPath = supplied.original;
+        admission = "identity";
+    }
+    else {
+        const rootWithSep = rootComparison.endsWith("\\") ? rootComparison : `${rootComparison}\\`;
+        const candidatePrefix = candidate.slice(0, rootWithSep.length);
+        if (candidatePrefix === rootWithSep) {
+            admission = "exact";
+        }
+        else if (candidatePrefix.toLowerCase() === rootWithSep.toLowerCase()) {
+            admission = "identity";
+        }
+        else {
+            return undefined;
+        }
+        relativePath = trimWindowsLeadingSeparators(candidate.slice(rootWithSep.length));
+        candidateRootPath = supplied.original.slice(0, supplied.originalIndex(rootComparison.length));
+    }
+    const rebasedPath = relativePath === ""
+        ? root
+        : `${root}${root.endsWith("\\") ? "" : "\\"}${relativePath}`;
+    return { candidateRootPath, path: rebasedPath, relativePath, admission };
+}
+function exactRootIdentity(rootPath, expected) {
+    if (typeof expected?.dev === "bigint" && typeof expected.ino === "bigint") {
+        return { dev: expected.dev, ino: expected.ino };
+    }
+    const observed = inspectDirectoryIdentitySync(rootPath);
+    return { dev: observed.dev, ino: observed.ino };
+}
+/**
+ * Admit a path at a trusted directory boundary.
+ *
+ * On Windows, an exact structural prefix is allocation-only and performs no
+ * filesystem observation. A match which depends on case folding is accepted
+ * only when the candidate prefix names the exact trusted root object. Accepted
+ * paths are always returned under the trusted root spelling.
+ */
+export function admitPathInsideRoot(params) {
+    // Some platform-fallback tests intentionally spoof process.platform while
+    // retaining Node's POSIX path module. A single-slash absolute root remains
+    // unambiguously POSIX; double-slash and slash-backslash roots are reserved
+    // for the synthetic Windows namespace cases below.
+    const usesPosixBoundary = process.platform !== "win32" || (path.sep === "/" &&
+        params.rootPath.startsWith("/") &&
+        params.rootPath[1] !== "/" &&
+        params.rootPath[1] !== "\\");
+    if (usesPosixBoundary) {
+        if (params.rootPath.startsWith("/") &&
+            params.candidatePath.startsWith("/") &&
+            !params.candidatePath.includes("/..") &&
+            (params.candidatePath === params.rootPath ||
+                (params.candidatePath.startsWith(params.rootPath) &&
+                    (params.rootPath.endsWith("/") || params.candidatePath[params.rootPath.length] === "/")))) {
+            const relativeStart = params.rootPath.endsWith("/")
+                ? params.rootPath.length
+                : params.rootPath.length + 1;
+            return {
+                admission: "exact",
+                path: params.candidatePath,
+                relativePath: params.candidatePath === params.rootPath
+                    ? ""
+                    : params.candidatePath.slice(relativeStart),
+            };
+        }
+        const root = path.resolve(params.rootPath);
+        const candidate = path.resolve(params.candidatePath);
+        const relativePath = path.relative(root, candidate);
+        if (isPathRelativeEscape(relativePath))
+            return undefined;
+        return { path: candidate, relativePath: relativePath === "." ? "" : relativePath, admission: "exact" };
+    }
+    const match = windowsRootPrefix(params.rootPath, params.candidatePath);
+    if (!match)
+        return undefined;
+    const admitted = () => ({
+        admission: match.admission,
+        path: match.path,
+        relativePath: match.relativePath,
+    });
+    if (match.admission === "exact")
+        return admitted();
+    const cached = params.identityCache?.get(match.candidateRootPath);
+    if (cached !== undefined)
+        return cached ? admitted() : undefined;
+    try {
+        const expected = exactRootIdentity(params.rootPath, params.rootIdentity);
+        const candidateRootPath = params.resolveCandidateRoot
+            ? realpathSync.native(match.candidateRootPath)
+            : match.candidateRootPath;
+        inspectDirectoryIdentitySync(candidateRootPath, expected);
+        params.identityCache?.set(match.candidateRootPath, true);
+        return admitted();
+    }
+    catch {
+        params.identityCache?.set(match.candidateRootPath, false);
+        return undefined;
+    }
+}

package/dist/root-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAED,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKzE;AAMD,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBtF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA4B9E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAgBhF;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhF;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqDtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}
+{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,UAAW,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAED,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAKzE;AAMD,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAetF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA4B9E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAyBhF;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhF;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GACA,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAoEtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}

package/dist/root-context.js

@@ -6,8 +6,10 @@ import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
 import { outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
 import { isDriveRelativePath } from "./safe-path-segment.js";
+import { realpathSync } from "./realpath.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 export const ensureTrailingSep = (value) => value.endsWith(path.sep) ? value : value + path.sep;
 export function assertValidRootRelativePath(relativePath) {
@@ -23,23 +25,22 @@ let cachedHomePath;
 const POSIX_PARENT_COMPONENT = /(?:^|\/)\.\.(?:\/|$)/;
 const WINDOWS_PARENT_COMPONENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
 export async function expandRelativePathWithHome(relativePath) {
+    const homeOnly = relativePath === "~";
+    const homePrefix = relativePath.startsWith("~/") || (path.sep === "\\" && relativePath.startsWith("~\\"));
+    if (!homeOnly && !homePrefix)
+        return relativePath;
     const rawHome = process.env.HOME || process.env.USERPROFILE || os.homedir();
     if (cachedHomePath?.raw !== rawHome) {
         let realHome = rawHome;
         try {
-            realHome = fs.realpathSync.native(rawHome);
+            realHome = realpathSync.native(rawHome);
         }
         catch {
             // If the home dir cannot be canonicalized, keep lexical expansion behavior.
         }
         cachedHomePath = { raw: rawHome, real: realHome };
     }
-    if (relativePath === "~")
-        return cachedHomePath.real;
-    if (relativePath.startsWith("~/") || (path.sep === "\\" && relativePath.startsWith("~\\"))) {
-        return `${ensureTrailingSep(cachedHomePath.real)}${relativePath.slice(2)}`;
-    }
-    return relativePath;
+    return homeOnly ? cachedHomePath.real : `${ensureTrailingSep(cachedHomePath.real)}${relativePath.slice(2)}`;
 }
 export async function resolveRootContext(rootDir) {
     assertNoNulPathInput(rootDir, "root dir contains a NUL byte");
@@ -47,7 +48,7 @@ export async function resolveRootContext(rootDir) {
     let rootReal;
     let rootIdentity;
     try {
-        rootReal = fs.realpathSync.native(rootDir);
+        rootReal = realpathSync.native(rootDir);
         const rootStat = await inspectFileIdentity(() => {
             const stat = fs.statSync(rootReal, { bigint: true });
             if (!stat.isDirectory())
@@ -77,11 +78,21 @@ export function rootRelativeReadPath(root, filePath) {
     if (!absoluteInput)
         return filePath;
     const raw = process.platform === "win32" ? filePath.replaceAll("/", path.sep) : filePath;
-    for (const base of [root.rootDir, root.rootReal]) {
+    const bases = root.rootDir === root.rootReal ? [root.rootReal] : [root.rootDir, root.rootReal];
+    for (const base of bases) {
+        if (process.platform === "win32") {
+            const admitted = admitPathInsideRoot({
+                rootPath: base,
+                candidatePath: raw,
+                rootIdentity: root.rootIdentity,
+                resolveCandidateRoot: base === root.rootDir && root.rootDir !== root.rootReal,
+            });
+            if (admitted)
+                return admitted.relativePath;
+            continue;
+        }
         const prefix = ensureTrailingSep(base);
-        const matches = process.platform === "win32"
-            ? raw.slice(0, prefix.length).toLowerCase() === prefix.toLowerCase()
-            : raw.startsWith(prefix);
+        const matches = raw.startsWith(prefix);
         if (matches) {
             let start = prefix.length;
             while (raw[start] === path.sep)
@@ -128,6 +139,7 @@ export async function resolvePathInRoot(root, relativePath, options) {
             absolutePath: rawAbsolutePath,
             rootPath: root.rootReal,
             rootCanonicalPath: root.rootReal,
+            rootIdentity: root.rootIdentity,
             boundaryLabel: "root",
             policy: options?.allowFinalSymlink ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
             rejectSymlinks: options?.rejectSymlinks,
@@ -142,8 +154,23 @@ export async function resolvePathInRoot(root, relativePath, options) {
                 throw new FsSafeError("path-alias", "parent traversal resolves differently through a symlink");
             }
         }
-        if (options?.resolveCanonical)
+        if (options?.resolveCanonical) {
             resolved = checked.canonicalPath;
+        }
+        else {
+            // resolveRootPath preserves ordinary caller spelling as part of its
+            // public receipt. Re-admit the exact normalized spelling before it is
+            // reused for Root I/O: on a case-sensitive Windows directory it may
+            // otherwise name a distinct case-folded sibling after raw traversal.
+            const admitted = admitPathInsideRoot({
+                rootPath: root.rootReal,
+                candidatePath: checked.absolutePath,
+                rootIdentity: root.rootIdentity,
+            });
+            if (!admitted)
+                throw outsideWorkspaceError();
+            resolved = admitted.path;
+        }
     }
     catch (error) {
         if (error instanceof FsSafeError && error.code === "symlink") {

package/dist/root-create-input.d.ts

@@ -0,0 +1,10 @@
+import type { PinnedWriteInput } from "./pinned-write.js";
+import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
+export type RootWriteParams = RootWriteOptions & RootCreateStreamOptions & {
+    relativePath: string;
+    data: string | Buffer | AsyncIterable<Uint8Array>;
+};
+export declare function rethrowCreateInputError(error: unknown): never;
+export declare function createInputOptions(data: RootWriteParams["data"], options: RootCreateOptions & RootCreateStreamOptions, defaultMaxBytes?: number): RootCreateOptions & RootCreateStreamOptions;
+export declare function rootWriteInput(params: RootWriteParams): PinnedWriteInput;
+//# sourceMappingURL=root-create-input.d.ts.map

package/dist/root-create-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-create-input.d.ts","sourceRoot":"","sources":["../src/root-create-input.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEtG,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,uBAAuB,GAAG;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;CACnD,CAAC;AAQF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAG7D;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,EAC7B,OAAO,EAAE,iBAAiB,GAAG,uBAAuB,EACpD,eAAe,CAAC,EAAE,MAAM,GACvB,iBAAiB,GAAG,uBAAuB,CAe7C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAwCxE"}

package/dist/root-create-input.js

@@ -0,0 +1,80 @@
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { MutationAuthorityError } from "./mutation-authority.js";
+class CreateInputError extends FsSafeError {
+    rejection;
+    constructor(rejection) {
+        super("helper-failed", "create input failed", { cause: rejection });
+        this.rejection = rejection;
+    }
+}
+export function rethrowCreateInputError(error) {
+    if (error instanceof CreateInputError)
+        throw error.rejection;
+    throw error;
+}
+export function createInputOptions(data, options, defaultMaxBytes) {
+    if (typeof data === "string" || Buffer.isBuffer(data))
+        return options;
+    options.signal?.throwIfAborted();
+    if (options.encoding !== undefined || options.renameIdentity !== undefined) {
+        throw new TypeError("streamed create does not accept encoding or renameIdentity");
+    }
+    const maxBytes = normalizeMaxBytes(options.maxBytes, { defaultValue: defaultMaxBytes });
+    return {
+        ...options,
+        maxBytes,
+        assertBeforeMutation: () => {
+            options.signal?.throwIfAborted();
+            return options.assertBeforeMutation?.();
+        },
+    };
+}
+export function rootWriteInput(params) {
+    const data = params.data;
+    if (typeof data === "string" || Buffer.isBuffer(data)) {
+        return { kind: "buffer", data, encoding: params.encoding };
+    }
+    return {
+        kind: "stream",
+        stageBeforePublish: true,
+        stream: (async function* () {
+            let iterator;
+            let completed = false;
+            try {
+                params.signal?.throwIfAborted();
+                iterator = data[Symbol.asyncIterator]();
+                while (true) {
+                    if (params.signal?.aborted)
+                        throw new MutationAuthorityError(params.signal.reason);
+                    const next = await iterator.next();
+                    completed = next.done === true;
+                    if (params.signal?.aborted)
+                        throw new MutationAuthorityError(params.signal.reason);
+                    if (completed)
+                        return;
+                    const chunk = next.value;
+                    if (!(chunk instanceof Uint8Array)) {
+                        throw new TypeError("streamed create chunks must be Uint8Array values");
+                    }
+                    yield chunk;
+                }
+            }
+            catch (error) {
+                if (error instanceof MutationAuthorityError)
+                    throw error;
+                throw new CreateInputError(error);
+            }
+            finally {
+                if (iterator && !completed) {
+                    try {
+                        await iterator.return?.();
+                    }
+                    catch (error) {
+                        throw new CreateInputError(error);
+                    }
+                }
+            }
+        })(),
+    };
+}

package/dist/root-directory-list.d.ts

@@ -18,7 +18,9 @@ export type RootDirectoryListingOptions = {
     order: "sorted" | "filesystem";
     signal?: AbortSignal;
     snapshot: boolean;
+    maxNames?: number;
+    metadataBatchSize?: number;
     admitEntry(): boolean;
 };
-export declare function listDirectoryForWalk(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
+export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
 //# sourceMappingURL=root-directory-list.d.ts.map

package/dist/root-directory-list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-directory-list.d.ts","sourceRoot":"","sources":["../src/root-directory-list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAQ1C,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhF,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIrD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAcvD;AAWD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;AAClH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;AAqBhI,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAClG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,KAAK,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,IAAI,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAqI/B"}
+{"version":3,"file":"root-directory-list.d.ts","sourceRoot":"","sources":["../src/root-directory-list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAQ1C,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIhF,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIrD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAcvD;AAWD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;AAClH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;AAqBhI,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAClG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,KAAK,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,IAAI,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CA6J/B"}

package/dist/root-directory-list.js

@@ -4,9 +4,10 @@ import path from "node:path";
 import { setImmediate as yieldToEventLoop } from "node:timers/promises";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
-import { isNotFoundPathError, isPathInside } from "./path.js";
+import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent } from "./root-context.js";
 import { rootPathChangedError } from "./root-errors.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
 import { createSuppressedError } from "./suppressed-error.js";
 const METADATA_BATCH_SIZE = 32;
 export function pathStatFromStats(stat) {
@@ -48,13 +49,20 @@ export async function listDirectoryPath(root, directory, withFileTypes) {
         throw normalizeDirectoryError(error);
     }
 }
-export async function listDirectoryForWalk(root, directory, options) {
+export async function openRootDirectoryListing(root, directory, options) {
     const guard = await createAsyncDirectoryGuard(directory, { bigint: true }).catch((error) => {
         throw normalizeDirectoryError(error);
     });
-    if (!isPathInside(root.rootReal, guard.realPath)) {
+    const admittedRealPath = admitPathInsideRoot({
+        rootPath: root.rootReal,
+        candidatePath: guard.realPath,
+        rootIdentity: root.rootIdentity,
+    });
+    if (!admittedRealPath) {
         throw new FsSafeError("outside-workspace", "directory is outside workspace root");
     }
+    guard.dir = admittedRealPath.path;
+    guard.realPath = admittedRealPath.path;
     const guardPinsRoot = guard.dir === root.rootReal &&
         guard.stat.dev === root.rootIdentity.dev && guard.stat.ino === root.rootIdentity.ino;
     const assertCurrent = async () => {
@@ -97,6 +105,22 @@ export async function listDirectoryForWalk(root, directory, options) {
         else if (options.snapshot) {
             snapshot = await listDirectoryPath(root, guard.realPath, true);
         }
+        else if (options.maxNames !== undefined) {
+            names = [];
+            handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
+            while (true) {
+                await assertCurrent();
+                const name = (await handle.read())?.name;
+                await assertCurrent();
+                if (name === undefined)
+                    break;
+                if (names.length >= options.maxNames) {
+                    throw new FsSafeError("too-large", "directory entry budget exceeded");
+                }
+                names.push(name);
+            }
+            await close();
+        }
         else {
             names = await fs.readdir(guard.realPath);
         }
@@ -115,8 +139,10 @@ export async function listDirectoryForWalk(root, directory, options) {
     }
     const prepareBatch = async (sortedNames) => {
         let name = sortedNames[index++];
-        if (name === undefined)
+        if (name === undefined) {
+            await assertCurrent();
             return;
+        }
         if (!options.admitEntry()) {
             pendingLimit = name;
             return;
@@ -132,7 +158,7 @@ export async function listDirectoryForWalk(root, directory, options) {
                 const entry = { name, ...pathStatFromStats(fsSync.lstatSync(path.join(guard.realPath, name))) };
                 prepared.push(entry);
                 // No later sibling can be observed before a possible recursive descent.
-                if (entry.isDirectory || entry.isSymbolicLink || prepared.length >= METADATA_BATCH_SIZE)
+                if (entry.isDirectory || entry.isSymbolicLink || prepared.length >= (options.metadataBatchSize ?? METADATA_BATCH_SIZE))
                     break;
             }
             catch (error) {

package/dist/root-entries.d.ts

@@ -0,0 +1,11 @@
+import { type RootContext } from "./root-context.js";
+import { type SymlinkPolicy } from "./root-symlink-policy.js";
+import type { DirEntry } from "./types.js";
+export type RootEntriesOptions = {
+    maxEntries?: number;
+    order?: "filesystem" | "sorted";
+    signal?: AbortSignal;
+    symlinks?: SymlinkPolicy;
+};
+export declare function entriesInRoot(root: RootContext, relativePath: string, options: RootEntriesOptions): AsyncGenerator<DirEntry>;
+//# sourceMappingURL=root-entries.d.ts.map

package/dist/root-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-entries.d.ts","sourceRoot":"","sources":["../src/root-entries.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAErF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,YAAY,GAAG,QAAQ,CAAC;IAChC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AAEF,wBAAuB,aAAa,CAClC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,kBAAkB,GAC1B,cAAc,CAAC,QAAQ,CAAC,CAkD1B"}

package/dist/root-entries.js

@@ -0,0 +1,61 @@
+import { FsSafeError } from "./errors.js";
+import { validatePinnedOperationPayload } from "./pinned-operation.js";
+import { resolvePathInRoot } from "./root-context.js";
+import { openRootDirectoryListing } from "./root-directory-list.js";
+import { readSymlinkResolution } from "./root-symlink-policy.js";
+import { createSuppressedError } from "./suppressed-error.js";
+export async function* entriesInRoot(root, relativePath, options) {
+    const maxEntries = options.maxEntries;
+    if (maxEntries !== undefined && (!Number.isSafeInteger(maxEntries) || maxEntries < 0)) {
+        throw new RangeError("maxEntries must be a non-negative safe integer");
+    }
+    if (options.order !== undefined && options.order !== "filesystem" && options.order !== "sorted") {
+        throw new TypeError(`invalid root entries order: ${String(options.order)}`);
+    }
+    options.signal?.throwIfAborted();
+    validatePinnedOperationPayload({ relativePath });
+    const resolved = await resolvePathInRoot(root, relativePath, {
+        ...readSymlinkResolution(options.symlinks),
+        resolveCanonical: true,
+    });
+    options.signal?.throwIfAborted();
+    let examined = 0;
+    const listing = await openRootDirectoryListing(root, resolved.resolved, {
+        order: options.order ?? "filesystem",
+        signal: options.signal,
+        snapshot: false,
+        maxNames: maxEntries,
+        metadataBatchSize: 1,
+        admitEntry: () => maxEntries === undefined || examined++ < maxEntries,
+    });
+    let failed = false;
+    let operationError;
+    try {
+        while (true) {
+            const next = await listing.next();
+            options.signal?.throwIfAborted();
+            if (next === undefined)
+                return;
+            if (next.kind === "limit") {
+                throw new FsSafeError("too-large", "directory entry budget exceeded");
+            }
+            yield next.entry;
+        }
+    }
+    catch (error) {
+        failed = true;
+        operationError = error;
+        throw error;
+    }
+    finally {
+        try {
+            await listing[Symbol.asyncDispose]();
+        }
+        catch (closeError) {
+            if (failed) {
+                throw createSuppressedError(closeError, operationError, "directory iteration and close both failed");
+            }
+            throw closeError;
+        }
+    }
+}

package/dist/root-errors.d.ts

@@ -1,13 +1,13 @@
-import { FsSafeError } from "./errors.js";
-export declare function fileNotFoundError(cause?: unknown): FsSafeError;
+import { FsSafeError, type FsSafeErrorDetails } from "./errors.js";
+export declare function fileNotFoundError(cause?: unknown, details?: FsSafeErrorDetails): FsSafeError;
 export declare function outsideWorkspaceError(): FsSafeError;
 export declare function rootPathChangedError(cause?: Error): FsSafeError;
 export declare function directoryComponentNotDirectoryError(cause?: unknown): FsSafeError;
 export declare function hardlinkedPathNotAllowedError(): FsSafeError;
 export declare function isAlreadyExistsError(error: unknown): boolean;
 export declare function normalizePinnedWriteError(error: unknown): Error;
-export declare function normalizePinnedPathError(error: unknown): Error;
-export declare function normalizeRemoveGuardError(error: unknown): Error;
-export declare function normalizeRemovePathError(error: unknown): Error;
+export declare function normalizePinnedPathError(error: unknown, details?: FsSafeErrorDetails): Error;
+export declare function normalizeRemoveGuardError(error: unknown, details?: FsSafeErrorDetails): Error;
+export declare function normalizeRemovePathError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function throwFsSafeReadError(error: unknown, label: string): never;
 //# sourceMappingURL=root-errors.d.ts.map

package/dist/root-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-errors.d.ts","sourceRoot":"","sources":["../src/root-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK1C,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAI9D;AAED,wBAAgB,qBAAqB,IAAI,WAAW,CAEnD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,WAAW,CAE/D;AAED,wBAAgB,mCAAmC,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAIhF;AAED,wBAAgB,6BAA6B,IAAI,WAAW,CAE3D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAU/D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAO9D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAQ/D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAe9D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAQzE"}
+{"version":3,"file":"root-errors.d.ts","sourceRoot":"","sources":["../src/root-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKnE,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAI5F;AAED,wBAAgB,qBAAqB,IAAI,WAAW,CAEnD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,WAAW,CAE/D;AAED,wBAAgB,mCAAmC,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAIhF;AAED,wBAAgB,6BAA6B,IAAI,WAAW,CAE3D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAU/D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAQ5F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAQ7F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAe5F;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAQzE"}

package/dist/root-errors.js

@@ -1,10 +1,10 @@
 import { FsSafeError } from "./errors.js";
 import { hasNodeErrorCode, isNodeError, isNotFoundPathError } from "./path.js";
 const REMOVE_NOT_EMPTY_CODES = new Set(["ENOTEMPTY", "EEXIST"]);
-export function fileNotFoundError(cause) {
+export function fileNotFoundError(cause, details) {
     return cause === undefined
-        ? new FsSafeError("not-found", "file not found")
-        : new FsSafeError("not-found", "file not found", { cause });
+        ? new FsSafeError("not-found", "file not found", { details })
+        : new FsSafeError("not-found", "file not found", { cause, details });
 }
 export function outsideWorkspaceError() {
     return new FsSafeError("outside-workspace", "file is outside workspace root");
@@ -34,38 +34,39 @@ export function normalizePinnedWriteError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
-export function normalizePinnedPathError(error) {
+export function normalizePinnedPathError(error, details) {
     if (error instanceof FsSafeError) {
         return error;
     }
     return new FsSafeError("path-alias", "path is not under root", {
         cause: error instanceof Error ? error : undefined,
+        details,
     });
 }
-export function normalizeRemoveGuardError(error) {
+export function normalizeRemoveGuardError(error, details) {
     if (error instanceof FsSafeError) {
         return error;
     }
     if (isNotFoundPathError(error)) {
-        return fileNotFoundError(error instanceof Error ? error : undefined);
+        return fileNotFoundError(error instanceof Error ? error : undefined, details);
     }
-    return normalizePinnedPathError(error);
+    return normalizePinnedPathError(error, details);
 }
-export function normalizeRemovePathError(error) {
+export function normalizeRemovePathError(error, details) {
     if (error instanceof FsSafeError) {
         return error;
     }
     if (!isNodeError(error) || typeof error.code !== "string") {
-        return normalizePinnedPathError(error);
+        return normalizePinnedPathError(error, details);
     }
     const cause = error instanceof Error ? error : undefined;
     if (isNotFoundPathError(error)) {
-        return fileNotFoundError(cause);
+        return fileNotFoundError(cause, details);
     }
     if (REMOVE_NOT_EMPTY_CODES.has(error.code)) {
-        return new FsSafeError("not-empty", "directory is not empty", { cause });
+        return new FsSafeError("not-empty", "directory is not empty", { cause, details });
     }
-    return new FsSafeError("not-removable", "path could not be removed", { cause });
+    return new FsSafeError("not-removable", "path could not be removed", { cause, details });
 }
 export function throwFsSafeReadError(error, label) {
     if (error instanceof FsSafeError) {