@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/root-path-existing.d.ts

@@ -7,4 +7,6 @@ export declare function rawPathRelativeToCanonicalRoot(candidate: string, rootCa
 }): string | undefined;
 export declare function resolvePathViaExistingAncestor(targetPath: string): Promise<string>;
 export declare function resolvePathViaExistingAncestorSync(targetPath: string): string;
-//# sourceMappingURL=root-path-existing.d.ts.map
+export type RootPathMetadataMode = "native" | "ordinary";
+export declare function resolveExistingAncestor(targetPath: string, mode: RootPathMetadataMode): string;
+export declare function resolveSymlinkHopPath(symlinkPath: string, mode: RootPathMetadataMode, rejectUnresolved?: boolean): string;

package/dist/root-path-existing.js

@@ -2,10 +2,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { formatErrorDetail } from "./error-detail.js";
-import { isNotFoundPathError, isPathInside } from "./path.js";
+import { isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path.js";
 import { realpathSync } from "./realpath.js";
-import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
+import { errorCauseOptions } from "./root-errors.js";
 export function absolutePathWithRawSegments(candidate) {
     if (path.sep !== "\\") {
         if (path.isAbsolute(candidate))
@@ -81,9 +82,6 @@ export function rawPathRelativeToCanonicalRoot(candidate, rootCanonicalPath, opt
     }
     return undefined;
 }
-function isFilesystemRoot(candidate) {
-    return path.parse(candidate).root === candidate;
-}
 function pathExists(targetPath) {
     try {
         return fs.lstatSync(pathForWindowsFilesystem(targetPath), { throwIfNoEntry: false }) !== undefined;
@@ -96,28 +94,25 @@ function pathExists(targetPath) {
     }
 }
 export async function resolvePathViaExistingAncestor(targetPath) {
-    return resolveExistingAncestor(targetPath, pathExists, realpathSync.native);
+    return resolveExistingAncestor(targetPath, "native");
 }
 function pathExistsSync(targetPath) {
     return fs.existsSync(pathForWindowsFilesystem(targetPath));
 }
 export function resolvePathViaExistingAncestorSync(targetPath) {
-    return resolveExistingAncestor(targetPath, pathExistsSync, realpathSync);
+    return resolveExistingAncestor(targetPath, "ordinary");
 }
-function resolveExistingAncestor(targetPath, exists, canonicalize) {
+export function resolveExistingAncestor(targetPath, mode) {
+    const exists = mode === "native" ? pathExists : pathExistsSync;
+    const canonicalize = mode === "native" ? realpathSync.native : realpathSync;
     assertNoWindowsPathAlias(targetPath);
     const normalized = resolvePathPreservingWindowsRoot(targetPath);
     assertNoWindowsPathAlias(normalized);
     let cursor = normalized;
-    const missingSuffix = [];
-    while (!isFilesystemRoot(cursor) &&
+    const filesystemRoot = path.parse(normalized).root;
+    while (cursor !== filesystemRoot &&
         !exists(cursor)) {
-        missingSuffix.unshift(path.basename(cursor));
-        const parent = path.dirname(cursor);
-        if (parent === cursor) {
-            break;
-        }
-        cursor = parent;
+        cursor = path.dirname(cursor);
     }
     if (!exists(cursor)) {
         return normalized;
@@ -132,9 +127,34 @@ function resolveExistingAncestor(targetPath, exists, canonicalize) {
     assertNoWindowsPathAlias(rawResolvedAncestor);
     const resolvedAncestor = resolvePathPreservingWindowsRoot(rawResolvedAncestor);
     assertNoWindowsPathAlias(resolvedAncestor);
-    const resolved = missingSuffix.length === 0
+    // Keep a leading suffix separator relative to the canonical ancestor.
+    const resolved = cursor === normalized
         ? resolvedAncestor
-        : path.resolve(resolvedAncestor, ...missingSuffix);
+        : path.resolve(resolvedAncestor, `.${path.sep}${normalized.slice(cursor.length)}`);
     assertNoWindowsPathAlias(resolved);
     return resolved;
 }
+export function resolveSymlinkHopPath(symlinkPath, mode, rejectUnresolved) {
+    try {
+        const canonicalize = mode === "native" ? realpathSync.native : realpathSync;
+        const rawRealPath = canonicalize(symlinkPath);
+        assertNoWindowsPathAlias(rawRealPath, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        const realPath = resolvePathPreservingWindowsRoot(rawRealPath);
+        assertNoWindowsPathAlias(realPath, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        return realPath;
+    }
+    catch (error) {
+        if (isSymlinkOpenError(error) || (rejectUnresolved && isNotFoundPathError(error))) {
+            throw new FsSafeError("symlink", "symlink path could not be resolved", errorCauseOptions(error));
+        }
+        if (!isNotFoundPathError(error))
+            throw error;
+        const linkTarget = fs.readlinkSync(symlinkPath);
+        assertNoWindowsPathAlias(linkTarget, "filesystem", "symlink target uses a Windows filesystem namespace alias");
+        const linkDir = resolvePathPreservingWindowsRoot(path.dirname(symlinkPath));
+        const targetPath = resolvePathFromBasePreservingWindowsRoot(linkDir, linkTarget);
+        const resolved = resolveExistingAncestor(targetPath, mode);
+        assertNoWindowsPathAlias(resolved, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        return resolved;
+    }
+}

package/dist/root-path-observation.d.ts

@@ -60,4 +60,3 @@ export type RootPathTraversalContext = {
 export declare function createRootPathTraversalObservation(context: RootPathTraversalContext, request?: RootPathObservationRequest): RootPathTraversalObservation | undefined;
 export declare function inspectRootPathTraversalEntry(pathname: string, directorySlot: boolean, observation: RootPathTraversalObservation): RootPathObservedTraversalEntry;
 export declare function captureRootPathObservedDirectory(observation: RootPathTraversalObservation, observed: RootPathObservedTraversalEntry, publicPath: string, canonicalPath: string, rootCanonicalPath: string, rootIdentity?: RootBoundaryIdentity): boolean;
-//# sourceMappingURL=root-path-observation.d.ts.map

package/dist/root-path-stat.d.ts

@@ -2,4 +2,3 @@ import type { RootContext } from "./root-context.js";
 import type { RootPathObservationReceipt } from "./root-path.js";
 import type { PathStat } from "./types.js";
 export declare function statResolvedPathInRoot(root: RootContext, resolvedPath: string, receipt?: RootPathObservationReceipt): Promise<PathStat>;
-//# sourceMappingURL=root-path-stat.d.ts.map

package/dist/root-path-stat.js

@@ -4,7 +4,7 @@ import { FsSafeError } from "./errors.js";
 import { fileObservation, recordFileObservationFailure } from "./file-observation.js";
 import { hasNodeErrorCode, isNotFoundPathError } from "./path.js";
 import { assertRootDirectoryObservationGuard, assertRootPathObservationReceiptCurrent, createRootDirectoryObservationGuard, pathStatFromStats, } from "./root-directory-list.js";
-import { fileNotFoundError } from "./root-errors.js";
+import { errorCauseOptions, fileNotFoundError } from "./root-errors.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertStatObservationSync } from "./stat-observation.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
@@ -32,9 +32,7 @@ async function captureChangedObservedFile(error, pathname, before, observed, ass
     }
 }
 async function missingObservedFileError(cause, pathname, before, assertParents, proof) {
-    const failure = new FsSafeError("path-mismatch", "file changed during operation", {
-        cause: cause instanceof Error ? cause : undefined,
-    });
+    const failure = new FsSafeError("path-mismatch", "file changed during operation", errorCauseOptions(cause));
     if (hasNodeErrorCode(cause, "ENOENT") && before?.isFile() && !before.isSymbolicLink() &&
         (before.nlink === 1 || before.nlink === 1n)) {
         try {

package/dist/root-path.d.ts

@@ -51,4 +51,3 @@ export declare function resolveRootPathWithObservation(params: ResolveRootPathPa
 export declare function resolveRootPathForRemoval(params: ResolveRootPathParams, receipts: RemovalPathReceipts): Promise<ResolvedRootPath>;
 export declare function resolveRootPathSync(params: ResolveRootPathParams): ResolvedRootPath;
 export declare function resolveRootPathSyncWithCanonicalRootObservation(params: ResolveRootPathParams, observeRoot: (rootCanonicalPath: string) => void): ResolvedRootPath;
-//# sourceMappingURL=root-path.d.ts.map

package/dist/root-path.js

@@ -5,10 +5,9 @@ import { pathEscapeError, sanitizeRootPathError, symlinkEscapeError } from "./ro
 import { FsSafeError } from "./errors.js";
 import { isNativeDirectoryObservationGuard } from "./native-directory-observation.js";
 import { assertNoNulPathInput, isNotFoundPathError, isPathRelativeEscape, } from "./path.js";
-import { absolutePathWithRawSegments, rawPathRelativeToCanonicalRoot, resolvePathViaExistingAncestor, resolvePathViaExistingAncestorSync, } from "./root-path-existing.js";
+import { absolutePathWithRawSegments, rawPathRelativeToCanonicalRoot, resolveExistingAncestor, resolveSymlinkHopPath, } from "./root-path-existing.js";
 import { admitPathInsideRoot, } from "./root-boundary.js";
 import { RootPathObservationError, captureRootPathObservedDirectory, createRootPathTraversalObservation, inspectRootPathTraversalEntry, } from "./root-path-observation.js";
-import { resolveSymlinkHopPath, resolveSymlinkHopPathSync } from "./root-path-symlink.js";
 import { assertNoDriveRelativePathSegments } from "./safe-path-segment.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 export { resolvePathViaExistingAncestorSync } from "./root-path-existing.js";
@@ -24,85 +23,35 @@ export const ROOT_PATH_ALIAS_POLICIES = {
     }),
 };
 export async function resolveRootPath(params) {
-    try {
-        return await resolveRootPathInternal(params);
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
+    return resolveRootPathInternal(params);
 }
 export async function resolveRootPathWithCanonicalRootObservation(params, observeRoot) {
-    try {
-        return await resolveRootPathInternal(params, undefined, undefined, observeRoot);
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
-}
-async function resolveRootPathInternal(params, observationRequest, observationOutput, observeRoot, removalReceipts) {
-    const input = captureValidRootPathInputs(params);
-    const rawAbsolutePath = absolutePathWithRawSegments(input.absolutePath);
-    const rootPath = resolvePathPreservingWindowsRoot(input.rootPath);
-    const absolutePath = resolvePathPreservingWindowsRoot(rawAbsolutePath);
-    const rootCanonicalPath = input.rootCanonicalPath
-        ? resolvePathPreservingWindowsRoot(input.rootCanonicalPath)
-        : await resolvePathViaExistingAncestor(rootPath);
-    assertNoWindowsPathAlias(rootPath);
-    assertNoWindowsPathAlias(absolutePath);
-    assertNoWindowsPathAlias(rootCanonicalPath);
-    observeRoot?.(rootCanonicalPath);
-    return resolveRootPathLexicalAsync(prepareRootTraversal(input, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath), observationRequest, observationOutput, removalReceipts);
+    return resolveRootPathInternal(params, { observeRoot });
 }
 export async function resolveRootPathWithObservation(params, request) {
-    const output = {};
-    try {
-        const resolved = await resolveRootPathInternal(params, request, output);
-        return output.receipt ? { resolved, receipt: output.receipt } : { resolved };
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
+    const observation = { request };
+    const resolved = resolveRootPathInternal(params, { observation });
+    return observation.receipt ? { resolved, receipt: observation.receipt } : { resolved };
 }
 // Removal receipts are separate from metadata observations and canonical-root
 // callbacks; the public resolver's options and result remain unchanged.
 export async function resolveRootPathForRemoval(params, receipts) {
-    try {
-        return await resolveRootPathInternal(params, undefined, undefined, undefined, receipts);
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
+    return resolveRootPathInternal(params, { removalReceipts: receipts });
 }
 export function resolveRootPathSync(params) {
-    try {
-        return resolveRootPathSyncInternal(params);
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
+    return resolveRootPathInternal(params, { mode: "ordinary" });
 }
 export function resolveRootPathSyncWithCanonicalRootObservation(params, observeRoot) {
+    return resolveRootPathInternal(params, { mode: "ordinary", observeRoot });
+}
+function resolveRootPathInternal(params, options = {}) {
     try {
-        return resolveRootPathSyncInternal(params, observeRoot);
+        return traverseRootPath(params, options);
     }
     catch (error) {
         throw sanitizeRootPathError(error);
     }
 }
-function resolveRootPathSyncInternal(params, observeRoot) {
-    const input = captureValidRootPathInputs(params);
-    const rawAbsolutePath = absolutePathWithRawSegments(input.absolutePath);
-    const rootPath = resolvePathPreservingWindowsRoot(input.rootPath);
-    const absolutePath = resolvePathPreservingWindowsRoot(rawAbsolutePath);
-    const rootCanonicalPath = input.rootCanonicalPath
-        ? resolvePathPreservingWindowsRoot(input.rootCanonicalPath)
-        : resolvePathViaExistingAncestorSync(rootPath);
-    assertNoWindowsPathAlias(rootPath);
-    assertNoWindowsPathAlias(absolutePath);
-    assertNoWindowsPathAlias(rootCanonicalPath);
-    observeRoot?.(rootCanonicalPath);
-    return resolveRootPathLexicalSync(prepareRootTraversal(input, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath));
-}
 function prepareRootTraversal(params, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath) {
     let raw = rawAbsolutePath;
     let trustedAbsolutePath = false;
@@ -173,27 +122,23 @@ function assertNoEmbeddedDriveRelativeSegment(filePath, label) {
     const root = path.parse(filePath).root;
     assertNoDriveRelativePathSegments(filePath.slice(root.length).replaceAll("\\", "/"), label);
 }
-function createLexicalTraversalState(params) {
-    const rawAbsolutePath = params.rawAbsolutePath;
-    const relative = admitRawPathInsideRoot(params.rootPath, rawAbsolutePath, params.params.rootIdentity)?.relativePath;
+function createLexicalTraversalContext(params) {
+    const relative = admitRawPathInsideRoot(params.rootPath, params.rawAbsolutePath, params.params.rootIdentity)?.relativePath;
     if (relative === undefined)
         throw new Error("Path traversal must begin at the root");
     const segments = splitTraversalSegments(relative);
     return {
-        segments,
-        relativePath: relative,
-        reuseLexicalCanonical: false,
-        finalComponentIndex: segments.findLastIndex((segment) => segment !== "."),
-        allowFinalSymlink: params.params.policy?.allowFinalSymlinkForUnlink === true,
-        canonicalCursor: params.rootCanonicalPath,
-        lexicalCursor: params.rootPath,
-        preserveFinalSymlink: false,
-        missingDepth: 0,
-    };
-}
-function createLexicalTraversalContext(params) {
-    return {
-        state: createLexicalTraversalState(params),
+        state: {
+            segments,
+            relativePath: relative,
+            reuseLexicalCanonical: false,
+            finalComponentIndex: segments.findLastIndex((segment) => segment !== "."),
+            allowFinalSymlink: params.params.policy?.allowFinalSymlinkForUnlink === true,
+            canonicalCursor: params.rootCanonicalPath,
+            lexicalCursor: params.rootPath,
+            preserveFinalSymlink: false,
+            missingDepth: 0,
+        },
         resolveParams: params.params,
         rootPath: params.rootPath,
         rootCanonicalPath: params.rootCanonicalPath,
@@ -263,29 +208,15 @@ function disableLexicalTraversalObservation(context, observation) {
 }
 function finalizeLexicalResolution(context, kind) {
     context.state.canonicalCursor = assertLexicalCursorInsideBoundary(context, context.state.canonicalCursor);
-    return buildResolvedRootPath({
+    return {
         absolutePath: context.absolutePath,
         canonicalPath: context.state.canonicalCursor,
         rootPath: context.rootPath,
         rootCanonicalPath: context.rootCanonicalPath,
-        kind,
-    });
-}
-function handleLexicalLstatFailure(context, error, segment) {
-    if (!isNotFoundPathError(error)) {
-        return false;
-    }
-    advanceCanonicalCursorForSegment(context, segment);
-    context.state.missingDepth = 1;
-    return true;
-}
-function lexicalStatDisposition(params) {
-    if (!params.isSymbolicLink)
-        return "continue";
-    if (params.rejectFinalSymlink || (params.rejectSymlinks === true && params.isLast)) {
-        throw new FsSafeError("symlink", "symlink path component not allowed");
-    }
-    return params.allowFinalSymlink && params.isLast ? "break" : "resolve-link";
+        relativePath: relativeInsideRoot(context.rootCanonicalPath, context.state.canonicalCursor),
+        exists: kind.exists,
+        kind: kind.kind,
+    };
 }
 function applyResolvedSymlinkHop(context, linkCanonical) {
     let admitted;
@@ -319,10 +250,23 @@ function assertResolvedLinkDirectory(pathname, isLast) {
     const stat = fs.statSync(pathForWindowsFilesystem(pathname));
     assertDirectoryBeforeMoreSegments(stat, pathname, isLast);
 }
-async function resolveRootPathLexicalAsync(params, observationRequest, observationOutput, removalReceipts) {
-    const context = createLexicalTraversalContext(params);
+// Both public APIs use synchronous metadata; only canonicalization and ancestor
+// existence differ. Promise wrappers preserve the asynchronous rejection API.
+function traverseRootPath(params, { mode = "native", observation: observationOutput, observeRoot, removalReceipts }) {
+    const input = captureValidRootPathInputs(params);
+    const rawAbsolutePath = absolutePathWithRawSegments(input.absolutePath);
+    const rootPath = resolvePathPreservingWindowsRoot(input.rootPath);
+    const absolutePath = resolvePathPreservingWindowsRoot(rawAbsolutePath);
+    const rootCanonicalPath = input.rootCanonicalPath
+        ? resolvePathPreservingWindowsRoot(input.rootCanonicalPath)
+        : resolveExistingAncestor(rootPath, mode);
+    assertNoWindowsPathAlias(rootPath);
+    assertNoWindowsPathAlias(absolutePath);
+    assertNoWindowsPathAlias(rootCanonicalPath);
+    observeRoot?.(rootCanonicalPath);
+    const context = createLexicalTraversalContext(prepareRootTraversal(input, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath));
     const { state } = context;
-    const observation = createLexicalTraversalObservation(context, observationRequest);
+    const observation = createLexicalTraversalObservation(context, observationOutput?.request);
     for (let idx = 0; idx < state.segments.length; idx += 1) {
         const segment = state.segments[idx] ?? "";
         const isLast = idx === state.segments.length - 1;
@@ -374,9 +318,11 @@ async function resolveRootPathLexicalAsync(params, observationRequest, observati
                 // Preserve observation-only versus ordinary traversal error precedence.
                 throw new RootPathObservationError(error instanceof RootPathObservationError ? error.error : sanitizeRootPathError(error), parentReceipt, !(error instanceof RootPathObservationError));
             }
-            if (handleLexicalLstatFailure(context, error, segment))
-                continue;
-            throw error;
+            if (!isNotFoundPathError(error))
+                throw error;
+            advanceCanonicalCursorForSegment(context, segment);
+            state.missingDepth = 1;
+            continue;
         }
         if (isNativeDirectoryObservationGuard(observed)) {
             advanceCanonicalCursorForSegment(context, segment);
@@ -392,15 +338,13 @@ async function resolveRootPathLexicalAsync(params, observationRequest, observati
         const isSymbolicLink = stat.isSymbolicLink();
         if (!isSymbolicLink)
             assertDirectoryBeforeMoreSegments(stat, state.lexicalCursor, isLast);
-        const disposition = lexicalStatDisposition({
-            isSymbolicLink,
-            isLast,
-            rejectSymlinks: isSymbolicLink ? context.resolveParams.rejectSymlinks : undefined,
-            rejectFinalSymlink: context.resolveParams.rejectFinalSymlink === true && idx === state.finalComponentIndex,
-            allowFinalSymlink: state.allowFinalSymlink,
-        });
-        if (disposition !== "resolve-link") {
-            state.preserveFinalSymlink = disposition === "break";
+        if (isSymbolicLink && ((context.resolveParams.rejectFinalSymlink === true && idx === state.finalComponentIndex) ||
+            (context.resolveParams.rejectSymlinks === true && isLast))) {
+            throw new FsSafeError("symlink", "symlink path component not allowed");
+        }
+        const preserveFinalSymlink = isSymbolicLink && state.allowFinalSymlink && isLast;
+        if (!isSymbolicLink || preserveFinalSymlink) {
+            state.preserveFinalSymlink = preserveFinalSymlink;
             advanceCanonicalCursorForSegment(context, segment);
             if (observation?.enabled && isSymbolicLink) {
                 disableLexicalTraversalObservation(context, observation);
@@ -420,9 +364,7 @@ async function resolveRootPathLexicalAsync(params, observationRequest, observati
         }
         if (observation?.enabled)
             disableLexicalTraversalObservation(context, observation);
-        const linkCanonical = await resolveSymlinkHopPath(state.lexicalCursor, {
-            rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
-        });
+        const linkCanonical = resolveSymlinkHopPath(state.lexicalCursor, mode, context.resolveParams.rejectUnresolvedSymlinks);
         applyResolvedSymlinkHop(context, linkCanonical);
         if (context.resolveParams.rejectSymlinks === true) {
             throw new FsSafeError("symlink", "symlink path component not allowed");
@@ -438,7 +380,7 @@ async function resolveRootPathLexicalAsync(params, observationRequest, observati
                 ? "directory"
                 : toResolvedKind(observation.target.stat),
         }
-        : await getPathKind(state.canonicalCursor, state.preserveFinalSymlink);
+        : getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
     if (completeObservation && observationOutput) {
         observationOutput.receipt = {
             kind: observation.request.kind,
@@ -451,76 +393,6 @@ async function resolveRootPathLexicalAsync(params, observationRequest, observati
     }
     return finalizeLexicalResolution(context, kind);
 }
-function resolveRootPathLexicalSync(params) {
-    const context = createLexicalTraversalContext(params);
-    const { state } = context;
-    for (let idx = 0; idx < state.segments.length; idx += 1) {
-        const segment = state.segments[idx] ?? "";
-        const isLast = idx === state.segments.length - 1;
-        if (segment === ".")
-            continue;
-        if (segment === "..") {
-            applyParentTraversalStep(context);
-            continue;
-        }
-        state.lexicalCursor = path.join(state.lexicalCursor, segment);
-        if (state.missingDepth > 0) {
-            advanceCanonicalCursorForSegment(context, segment);
-            state.missingDepth += 1;
-            continue;
-        }
-        let stat;
-        try {
-            stat = fs.lstatSync(state.lexicalCursor);
-        }
-        catch (error) {
-            if (handleLexicalLstatFailure(context, error, segment))
-                continue;
-            throw error;
-        }
-        const isSymbolicLink = stat.isSymbolicLink();
-        if (!isSymbolicLink)
-            assertDirectoryBeforeMoreSegments(stat, state.lexicalCursor, isLast);
-        const disposition = lexicalStatDisposition({
-            isSymbolicLink,
-            isLast,
-            rejectSymlinks: isSymbolicLink ? context.resolveParams.rejectSymlinks : undefined,
-            rejectFinalSymlink: context.resolveParams.rejectFinalSymlink === true && idx === state.finalComponentIndex,
-            allowFinalSymlink: state.allowFinalSymlink,
-        });
-        if (disposition !== "resolve-link") {
-            state.preserveFinalSymlink = disposition === "break";
-            advanceCanonicalCursorForSegment(context, segment);
-            if (state.preserveFinalSymlink)
-                break;
-            continue;
-        }
-        const linkCanonical = resolveSymlinkHopPathSync(state.lexicalCursor, {
-            rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
-        });
-        applyResolvedSymlinkHop(context, linkCanonical);
-        if (context.resolveParams.rejectSymlinks === true) {
-            throw new FsSafeError("symlink", "symlink path component not allowed");
-        }
-        assertResolvedLinkDirectory(linkCanonical, isLast);
-    }
-    const kind = getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
-    return finalizeLexicalResolution(context, kind);
-}
-function buildResolvedRootPath(params) {
-    return {
-        absolutePath: params.absolutePath,
-        canonicalPath: params.canonicalPath,
-        rootPath: params.rootPath,
-        rootCanonicalPath: params.rootCanonicalPath,
-        relativePath: relativeInsideRoot(params.rootCanonicalPath, params.canonicalPath),
-        exists: params.kind.exists,
-        kind: params.kind.kind,
-    };
-}
-async function getPathKind(absolutePath, preserveFinalSymlink) {
-    return getPathKindSync(absolutePath, preserveFinalSymlink);
-}
 function getPathKindSync(absolutePath, preserveFinalSymlink) {
     try {
         const operationPath = pathForWindowsFilesystem(absolutePath);

package/dist/root-paths-lexical.d.ts

@@ -6,4 +6,3 @@ export declare function resolvePathWithinRoot(params: ResolvePathWithinRootParam
     ok: false;
     error: string;
 };
-//# sourceMappingURL=root-paths-lexical.d.ts.map

package/dist/root-paths.d.ts

@@ -60,4 +60,3 @@ export declare function resolvePathsWithinRoot(params: ResolvePathsWithinRootPar
 export declare function resolveExistingPathsWithinRoot(params: ResolvePathsWithinRootParams): Promise<ResolvePathsWithinRootResult>;
 export declare function resolveStrictExistingPathsWithinRoot(params: ResolvePathsWithinRootParams): Promise<ResolvePathsWithinRootResult>;
 export declare function pathScope(rootDir: string, options: PathScopeOptions): PathScope;
-//# sourceMappingURL=root-paths.d.ts.map

package/dist/root-public-types.d.ts

@@ -0,0 +1,11 @@
+export type { OpenResult, WritableOpenResult, } from "./root-impl.js";
+export type { HardlinkPolicy, RootAppendOptions, RootCopyOptions, RootCopySource, RootCreateJsonOptions, RootCreateOptions, RootCreateStreamOptions, RootDefaults, RootMkdirOptions, RootMoveOptions, RootOpenOptions, RootOpenWritableOptions, RootOptions, RootReadOptions, RootRemoveOptions, RootWriteJsonOptions, RootWriteOptions, WritableOpenMode, } from "./root-options.js";
+export type { DenyMutationPolicy } from "./deny-mutations.js";
+export type { RenameIdentityPolicy } from "./pinned-write-types.js";
+export type { MutationSymlinkPolicy, SymlinkPolicy, } from "./root-symlink-policy.js";
+export type { ReadResult } from "./read-opened-file.js";
+export type { RootCopyPublicationReceipt } from "./copy-publication.js";
+export type { CopyCloneMode } from "./copy-policy.js";
+export type { RootEntriesOptions } from "./root-entries.js";
+export type { ContainmentGuarantee } from "./containment.js";
+export type { RootWalkDataEntry, RootWalkDataEntryKind, RootWalkDirectoryErrorBehavior, RootWalkEntry, RootWalkEntryFilter, RootWalkEntryFilterResult, RootWalkEntryKind, RootWalkLimitBehavior, RootWalkOptions, RootWalkSymlinkPolicy, } from "./root-walk.js";

package/dist/root-read-admission.d.ts

@@ -23,4 +23,3 @@ export declare function admitRootReadHandle<T extends OwnedRootReadHandle>(param
     realPath: string;
 }>;
 export {};
-//# sourceMappingURL=root-read-admission.d.ts.map

package/dist/root-read-admission.js

@@ -31,40 +31,6 @@ export function inspectOpenedPathIdentitySync(filePath, symlinks) {
     }
     return stat;
 }
-function assertRootReadAdmissionCurrent(params) {
-    assertRootIdentityCurrentSync(params.root);
-    const admittedPath = (() => {
-        try {
-            const current = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(params.filePath, params.symlinks), params.identity);
-            if (params.hardlinks !== "allow" && current.nlink > 1n)
-                throw hardlinkedPathNotAllowedError();
-            const canonicalPath = resolveFinalOpenedRealPath(params.filePath);
-            assertNoWindowsPathAlias(canonicalPath, "filesystem", "resolved file path uses a Windows filesystem namespace alias");
-            const admittedRealPath = admitPathInsideRoot({
-                rootPath: params.root.rootReal,
-                candidatePath: canonicalPath,
-                rootIdentity: params.root.rootIdentity,
-            });
-            if (!admittedRealPath) {
-                throw openedPathResolutionError(outsideWorkspaceError());
-            }
-            // This is a fresh no-follow observation even when canonicalPath and
-            // filePath have the same spelling; realpath may have raced a replacement.
-            const canonical = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(canonicalPath, undefined), params.identity);
-            if (params.hardlinks !== "allow" && canonical.nlink > 1n)
-                throw hardlinkedPathNotAllowedError();
-            return admittedRealPath.path;
-        }
-        catch (error) {
-            throw isNotFoundPathError(error)
-                ? openedPathResolutionError(fileNotFoundError())
-                : error;
-        }
-    })();
-    params.afterPathIdentityCheck?.(params.filePath, params.handle);
-    assertRootIdentityCurrentSync(params.root);
-    return admittedPath;
-}
 export async function admitRootReadHandle(params) {
     try {
         if (params.hardlinks !== "allow" && params.opened.stat.nlink > 1) {
@@ -74,16 +40,37 @@ export async function admitRootReadHandle(params) {
             await params.beforeFinalFence(params.filePath, params.opened.handle);
         }
         try {
-            const finalRealPath = assertRootReadAdmissionCurrent({
-                root: params.root,
-                filePath: params.filePath,
-                handle: params.opened.handle,
-                identity: params.identity,
-                hardlinks: params.hardlinks,
-                symlinks: params.symlinks,
-                afterPathIdentityCheck: params.afterPathIdentityCheck,
-            });
-            return { ...params.opened, realPath: finalRealPath };
+            assertRootIdentityCurrentSync(params.root);
+            let realPath;
+            try {
+                const current = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(params.filePath, params.symlinks), params.identity);
+                if (params.hardlinks !== "allow" && current.nlink > 1n)
+                    throw hardlinkedPathNotAllowedError();
+                const canonicalPath = resolveFinalOpenedRealPath(params.filePath);
+                assertNoWindowsPathAlias(canonicalPath, "filesystem", "resolved file path uses a Windows filesystem namespace alias");
+                const admittedRealPath = admitPathInsideRoot({
+                    rootPath: params.root.rootReal,
+                    candidatePath: canonicalPath,
+                    rootIdentity: params.root.rootIdentity,
+                });
+                if (!admittedRealPath) {
+                    throw openedPathResolutionError(outsideWorkspaceError());
+                }
+                // This is a fresh no-follow observation even when canonicalPath and
+                // filePath have the same spelling; realpath may have raced a replacement.
+                const canonical = inspectFileIdentitySync(() => inspectOpenedPathIdentitySync(canonicalPath, undefined), params.identity);
+                if (params.hardlinks !== "allow" && canonical.nlink > 1n)
+                    throw hardlinkedPathNotAllowedError();
+                realPath = admittedRealPath.path;
+            }
+            catch (error) {
+                throw isNotFoundPathError(error)
+                    ? openedPathResolutionError(fileNotFoundError())
+                    : error;
+            }
+            params.afterPathIdentityCheck?.(params.filePath, params.opened.handle);
+            assertRootIdentityCurrentSync(params.root);
+            return { ...params.opened, realPath };
         }
         catch (error) {
             if (params.identity.nlink <= 1n) {

package/dist/root-remove-identity.d.ts

@@ -12,4 +12,3 @@ export type RemovalDirectoryAssertion = Readonly<{
 export declare function createRemovalDirectoryAssertion(path: string, identity: ExactDirectoryIdentity, realPath?: string, platform?: NodeJS.Platform): RemovalDirectoryAssertion;
 export declare function assertRemovalDirectoryCurrent(assertion: RemovalDirectoryAssertion): void;
 export {};
-//# sourceMappingURL=root-remove-identity.d.ts.map

package/dist/root-remove-identity.js

@@ -2,12 +2,10 @@ import fsSync from "node:fs";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { realpathSync } from "./realpath.js";
-import { directoryComponentNotDirectoryError } from "./root-errors.js";
+import { directoryComponentNotDirectoryError, errorCauseOptions } from "./root-errors.js";
 const MAX_SAFE_DIRECTORY_IDENTITY = BigInt(Number.MAX_SAFE_INTEGER);
 function identityMismatch(cause) {
-    return new FsSafeError("path-mismatch", "removal ancestor identity changed or could not be verified", {
-        cause: cause instanceof Error ? cause : undefined,
-    });
+    return new FsSafeError("path-mismatch", "removal ancestor identity changed or could not be verified", errorCauseOptions(cause));
 }
 function safeIdentityNumber(value) {
     if (value < 0n || value > MAX_SAFE_DIRECTORY_IDENTITY)

package/dist/root-remove-receipt.d.ts

@@ -14,4 +14,3 @@ export declare class RemovalPathReceipts {
         directories: readonly CapturedRemovalDirectory[];
     } | undefined;
 }
-//# sourceMappingURL=root-remove-receipt.d.ts.map

package/dist/root-remove.d.ts

@@ -4,4 +4,3 @@ import type { RemovalPathReceipts } from "./root-remove-receipt.js";
 export declare const nonrecursiveRemovalKind: unique symbol;
 export declare function validateRemoveOptions(options: RootRemoveOptions): void;
 export declare function removePathInRootFallback(root: RootContext, targetPath: string, options: RootRemoveOptions, receipts?: RemovalPathReceipts): Promise<void>;
-//# sourceMappingURL=root-remove.d.ts.map