@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/root-path.js

@@ -1,12 +1,17 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import path from "node:path";
-import { formatErrorDetail, shortPath } from "./error-detail.js";
+import { shortPath } from "./error-detail.js";
+import { pathEscapeError, sanitizeRootPathError, symlinkEscapeError } from "./root-path-errors.js";
 import { FsSafeError } from "./errors.js";
-import { assertNoNulPathInput, isNotFoundPathError, isPathInside, isPathRelativeEscape, } from "./path.js";
-import { resolvePathViaExistingAncestor, resolvePathViaExistingAncestorSync, } from "./root-path-existing.js";
-import { resolveSymlinkHopPath, resolveSymlinkHopPathSync } from "./root-path-symlink.js";
+import { isNativeDirectoryObservationGuard } from "./native-directory-observation.js";
+import { assertNoNulPathInput, isNotFoundPathError, isPathRelativeEscape, } from "./path.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 { assertNoDriveRelativePathSegments } from "./safe-path-segment.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 export { resolvePathViaExistingAncestorSync } from "./root-path-existing.js";
+export { RootPathObservationError, } from "./root-path-observation.js";
 export const ROOT_PATH_ALIAS_POLICIES = {
     strict: Object.freeze({
         allowFinalSymlinkForUnlink: false,
@@ -18,98 +23,97 @@ export const ROOT_PATH_ALIAS_POLICIES = {
     }),
 };
 export async function resolveRootPath(params) {
-    try {
-        return await resolveRootPathInternal(params);
-    }
-    catch (error) {
-        throw sanitizeRootPathError(error);
-    }
+    return resolveRootPathInternal(params);
 }
-async function resolveRootPathInternal(params) {
-    assertValidRootPathInputs(params);
-    const rootPath = path.resolve(params.rootPath);
-    const absolutePath = path.resolve(params.absolutePath);
-    const rootCanonicalPath = params.rootCanonicalPath
-        ? path.resolve(params.rootCanonicalPath)
-        : await resolvePathViaExistingAncestor(rootPath);
-    const context = createBoundaryResolutionContext({
-        resolveParams: params,
-        rootPath,
-        absolutePath,
-        rootCanonicalPath,
-        outsideLexicalCanonicalPath: await resolveOutsideLexicalCanonicalPathAsync({
-            rootPath,
-            absolutePath,
-        }),
-    });
-    const outsideResult = await resolveOutsideRootPathAsync({
-        boundaryLabel: params.boundaryLabel,
-        context,
-    });
-    if (outsideResult) {
-        return outsideResult;
-    }
-    return resolveRootPathLexicalAsync({
-        params,
-        absolutePath: context.absolutePath,
-        rootPath: context.rootPath,
-        rootCanonicalPath: context.rootCanonicalPath,
-    });
+export async function resolveRootPathWithCanonicalRootObservation(params, observeRoot) {
+    return resolveRootPathInternal(params, { observeRoot });
+}
+export async function resolveRootPathWithObservation(params, request) {
+    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) {
+    return resolveRootPathInternal(params, { removalReceipts: receipts });
 }
 export function resolveRootPathSync(params) {
+    return resolveRootPathInternal(params, { mode: "ordinary" });
+}
+export function resolveRootPathSyncWithCanonicalRootObservation(params, observeRoot) {
+    return resolveRootPathInternal(params, { mode: "ordinary", observeRoot });
+}
+function resolveRootPathInternal(params, options = {}) {
     try {
-        return resolveRootPathSyncInternal(params);
+        return traverseRootPath(params, options);
     }
     catch (error) {
         throw sanitizeRootPathError(error);
     }
 }
-function resolveRootPathSyncInternal(params) {
-    assertValidRootPathInputs(params);
-    const rootPath = path.resolve(params.rootPath);
-    const absolutePath = path.resolve(params.absolutePath);
-    const rootCanonicalPath = params.rootCanonicalPath
-        ? path.resolve(params.rootCanonicalPath)
-        : resolvePathViaExistingAncestorSync(rootPath);
-    const context = createBoundaryResolutionContext({
-        resolveParams: params,
+function prepareRootTraversal(params, rootPath, rootCanonicalPath, absolutePath, rawAbsolutePath) {
+    let raw = rawAbsolutePath;
+    let trustedAbsolutePath = false;
+    const direct = admitRawPathInsideRoot(rootPath, raw, params.rootIdentity);
+    if (direct) {
+        raw = direct.path;
+        trustedAbsolutePath = direct.admission === "identity";
+    }
+    else {
+        const canonical = admitRawPathInsideRoot(rootCanonicalPath, raw, params.rootIdentity);
+        const relative = canonical?.relativePath
+            ?? rawPathRelativeToCanonicalRoot(raw, rootCanonicalPath, params);
+        if (relative === undefined) {
+            throw pathEscapeError({ rootPath, absolutePath: raw, boundaryLabel: params.boundaryLabel });
+        }
+        trustedAbsolutePath = canonical?.admission === "identity";
+        raw = relative === "" ? rootPath : `${rootPath}${path.sep}${relative}`;
+    }
+    return {
+        params,
+        rawAbsolutePath: raw,
+        rootPath,
+        rootCanonicalPath,
+        // Preserve the caller-spelling receipt for ordinary aliases. Only a
+        // Windows case-fold admission must return the identity-gated Root spelling,
+        // because downstream I/O must not reuse the ambiguous caller prefix.
+        absolutePath: trustedAbsolutePath ? resolvePathPreservingWindowsRoot(raw) : absolutePath,
+        observationEligible: raw === rawAbsolutePath && !trustedAbsolutePath,
+    };
+}
+function captureValidRootPathInputs(params) {
+    const rootPath = params.rootPath;
+    assertNoNulPathInput(rootPath, "root path contains a NUL byte");
+    const absolutePath = params.absolutePath;
+    assertNoNulPathInput(absolutePath, "absolute path contains a NUL byte");
+    assertNoWindowsPathAlias(rootPath, "filesystem", "root path uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(absolutePath, "filesystem", "absolute path uses a Windows filesystem namespace alias");
+    assertNoEmbeddedDriveRelativeSegment(rootPath, "root path");
+    assertNoEmbeddedDriveRelativeSegment(absolutePath, "absolute path");
+    const rootCanonicalPath = params.rootCanonicalPath;
+    if (rootCanonicalPath !== undefined) {
+        assertNoNulPathInput(rootCanonicalPath, "canonical root path contains a NUL byte");
+        assertNoWindowsPathAlias(rootCanonicalPath, "filesystem", "canonical root path uses a Windows filesystem namespace alias");
+        assertNoEmbeddedDriveRelativeSegment(rootCanonicalPath, "canonical root path");
+    }
+    // Keep traversal policy with the admitted paths across ancestor and symlink
+    // resolution. Caller-owned flags and getters must not change a running walk.
+    const policy = params.policy;
+    const rootIdentity = params.rootIdentity;
+    return {
         rootPath,
         absolutePath,
         rootCanonicalPath,
-        outsideLexicalCanonicalPath: resolveOutsideLexicalCanonicalPathSync({
-            rootPath,
-            absolutePath,
-        }),
-    });
-    const outsideResult = resolveOutsideRootPathSync({
+        rootIdentity: rootIdentity == null ? undefined : { dev: rootIdentity.dev, ino: rootIdentity.ino },
         boundaryLabel: params.boundaryLabel,
-        context,
-    });
-    if (outsideResult) {
-        return outsideResult;
-    }
-    return resolveRootPathLexicalSync({
-        params,
-        absolutePath: context.absolutePath,
-        rootPath: context.rootPath,
-        rootCanonicalPath: context.rootCanonicalPath,
-    });
-}
-function sanitizeRootPathError(error) {
-    if (error instanceof Error) {
-        error.message = formatErrorDetail(error.message);
-    }
-    return error;
-}
-function assertValidRootPathInputs(params) {
-    assertNoNulPathInput(params.rootPath, "root path contains a NUL byte");
-    assertNoNulPathInput(params.absolutePath, "absolute path contains a NUL byte");
-    assertNoEmbeddedDriveRelativeSegment(params.rootPath, "root path");
-    assertNoEmbeddedDriveRelativeSegment(params.absolutePath, "absolute path");
-    if (params.rootCanonicalPath !== undefined) {
-        assertNoNulPathInput(params.rootCanonicalPath, "canonical root path contains a NUL byte");
-        assertNoEmbeddedDriveRelativeSegment(params.rootCanonicalPath, "canonical root path");
-    }
+        policy: policy == null ? undefined : {
+            allowFinalSymlinkForUnlink: policy.allowFinalSymlinkForUnlink,
+        },
+        rejectSymlinks: params.rejectSymlinks,
+        rejectFinalSymlink: params.rejectFinalSymlink,
+        rejectUnresolvedSymlinks: params.rejectUnresolvedSymlinks,
+    };
 }
 function assertNoEmbeddedDriveRelativeSegment(filePath, label) {
     if (process.platform !== "win32") {
@@ -118,324 +122,283 @@ function assertNoEmbeddedDriveRelativeSegment(filePath, label) {
     const root = path.parse(filePath).root;
     assertNoDriveRelativePathSegments(filePath.slice(root.length).replaceAll("\\", "/"), label);
 }
-function createLexicalTraversalState(params) {
-    const rawAbsolutePath = params.params.absolutePath;
-    const rawRelativePath = rawPathRelativeToRoot(params.rootPath, rawAbsolutePath);
-    const relative = rawRelativePath ?? path.relative(params.rootPath, params.absolutePath);
-    return {
-        segments: splitTraversalSegments(relative),
-        allowFinalSymlink: params.params.policy?.allowFinalSymlinkForUnlink === true,
-        canonicalCursor: params.rootCanonicalPath,
-        lexicalCursor: params.rootPath,
-        preserveFinalSymlink: false,
-    };
-}
 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 {
-        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,
         absolutePath: params.absolutePath,
+        observationEligible: params.observationEligible,
     };
 }
+function createLexicalTraversalObservation(context, request) {
+    const observation = createRootPathTraversalObservation(context, request);
+    if (observation && observation.targetIndex >= 0) {
+        context.state.reuseLexicalCanonical = true;
+    }
+    return observation;
+}
 function splitTraversalSegments(value) {
-    return value
+    const segments = value
         .split(process.platform === "win32" ? /[\\/]+/ : /\/+/)
-        .filter((segment) => Boolean(segment) && segment !== ".");
+        .filter(Boolean);
+    if (value.endsWith("/") || (process.platform === "win32" && value.endsWith("\\")))
+        segments.push(".");
+    return segments;
 }
-function rawPathRelativeToRoot(rootPath, candidatePath) {
+function admitRawPathInsideRoot(rootPath, candidatePath, rootIdentity) {
     if (!path.isAbsolute(candidatePath)) {
         return undefined;
     }
-    const root = path.resolve(rootPath);
+    // Every caller supplies the already-resolved root selected by
+    // resolveRootPathInternal; resolving it again is redundant on each traversal.
+    const root = rootPath;
     const candidate = process.platform === "win32"
         ? candidatePath.replaceAll("/", path.sep)
         : candidatePath;
+    if (process.platform === "win32") {
+        return admitPathInsideRoot({ rootPath: root, candidatePath: candidate, rootIdentity });
+    }
     if (candidate === root) {
-        return "";
+        return { admission: "exact", path: candidate, relativePath: "" };
     }
     const rootWithSep = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
     const candidatePrefix = candidate.slice(0, rootWithSep.length);
-    const prefixMatches = process.platform === "win32"
-        ? candidatePrefix.toLowerCase() === rootWithSep.toLowerCase()
-        : candidatePrefix === rootWithSep;
-    return prefixMatches ? candidate.slice(rootWithSep.length) : undefined;
+    return candidatePrefix === rootWithSep
+        ? {
+            admission: "exact",
+            path: candidate,
+            relativePath: candidate.slice(rootWithSep.length),
+        }
+        : undefined;
 }
 function assertLexicalCursorInsideBoundary(context, candidatePath) {
-    assertInsideBoundary({
+    return assertInsideBoundary({
         boundaryLabel: context.resolveParams.boundaryLabel,
         rootCanonicalPath: context.rootCanonicalPath,
+        rootIdentity: context.resolveParams.rootIdentity,
         candidatePath,
         absolutePath: context.absolutePath,
     });
 }
-function applyMissingSuffixToCanonicalCursor(context, missingFromIndex) {
-    const missingSuffix = context.state.segments.slice(missingFromIndex);
-    for (const segment of missingSuffix) {
-        advanceCanonicalCursorForSegment(context, segment);
-    }
-}
 function advanceCanonicalCursorForSegment(context, segment) {
-    context.state.canonicalCursor = path.resolve(context.state.canonicalCursor, segment);
-    assertLexicalCursorInsideBoundary(context, context.state.canonicalCursor);
+    const candidatePath = context.state.reuseLexicalCanonical
+        ? context.state.lexicalCursor
+        : resolvePathFromBasePreservingWindowsRoot(context.state.canonicalCursor, segment);
+    context.state.canonicalCursor = assertLexicalCursorInsideBoundary(context, candidatePath);
+}
+function disableLexicalTraversalObservation(context, observation) {
+    observation.enabled = false;
+    context.state.reuseLexicalCanonical = false;
 }
 function finalizeLexicalResolution(context, kind) {
-    assertLexicalCursorInsideBoundary(context, context.state.canonicalCursor);
-    return buildResolvedRootPath({
+    context.state.canonicalCursor = assertLexicalCursorInsideBoundary(context, context.state.canonicalCursor);
+    return {
         absolutePath: context.absolutePath,
         canonicalPath: context.state.canonicalCursor,
         rootPath: context.rootPath,
         rootCanonicalPath: context.rootCanonicalPath,
-        kind,
-    });
-}
-function handleLexicalLstatFailure(context, error, missingFromIndex) {
-    if (!isNotFoundPathError(error)) {
-        return false;
-    }
-    applyMissingSuffixToCanonicalCursor(context, missingFromIndex);
-    return true;
-}
-function lexicalStatDisposition(params) {
-    if (!params.isSymbolicLink)
-        return "continue";
-    if (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) {
-    if (!isPathInside(context.rootCanonicalPath, linkCanonical)) {
+    let admitted;
+    try {
+        admitted = assertLexicalCursorInsideBoundary(context, linkCanonical);
+    }
+    catch {
         throw symlinkEscapeError({
             boundaryLabel: context.resolveParams.boundaryLabel,
             rootCanonicalPath: context.rootCanonicalPath,
             symlinkPath: context.state.lexicalCursor,
         });
     }
-    context.state.canonicalCursor = linkCanonical;
-    context.state.lexicalCursor = linkCanonical;
+    context.state.canonicalCursor = admitted;
+    context.state.lexicalCursor = admitted;
 }
 function applyParentTraversalStep(context) {
-    context.state.lexicalCursor = path.resolve(context.state.lexicalCursor, "..");
+    context.state.lexicalCursor = resolvePathFromBasePreservingWindowsRoot(context.state.lexicalCursor, "..");
     advanceCanonicalCursorForSegment(context, "..");
+    if (context.state.missingDepth > 0)
+        context.state.missingDepth -= 1;
 }
-async function resolveRootPathLexicalAsync(params) {
-    const context = createLexicalTraversalContext(params);
+function assertDirectoryBeforeMoreSegments(stat, pathname, isLast) {
+    if (!isLast && !stat.isDirectory()) {
+        throw Object.assign(new Error(`Path component is not a directory: ${pathname}`), { code: "ENOTDIR" });
+    }
+}
+function assertResolvedLinkDirectory(pathname, isLast) {
+    if (isLast)
+        return;
+    const stat = fs.statSync(pathForWindowsFilesystem(pathname));
+    assertDirectoryBeforeMoreSegments(stat, pathname, isLast);
+}
+// 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, observationOutput?.request);
     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;
+        let observed;
         try {
-            stat = fs.lstatSync(state.lexicalCursor);
+            if (removalReceipts && !isLast) {
+                const directoryStat = fs.lstatSync(pathForWindowsFilesystem(state.lexicalCursor), { bigint: true });
+                if (directoryStat.isDirectory() && !directoryStat.isSymbolicLink()) {
+                    removalReceipts.observeDirectory(state.lexicalCursor, directoryStat);
+                }
+                stat = directoryStat;
+            }
+            else {
+                const directorySlot = observation?.enabled === true && idx === observation.directoryIndex;
+                const targetSlot = observation?.enabled === true && idx === observation.targetIndex;
+                const observeExactly = directorySlot || targetSlot;
+                if (observeExactly) {
+                    observed = inspectRootPathTraversalEntry(state.lexicalCursor, directorySlot, observation);
+                }
+                stat = isNativeDirectoryObservationGuard(observed)
+                    ? undefined
+                    : observed?.stat ?? fs.lstatSync(state.lexicalCursor);
+            }
         }
         catch (error) {
-            if (handleLexicalLstatFailure(context, error, idx))
-                break;
-            throw error;
-        }
-        const isSymbolicLink = stat.isSymbolicLink();
-        const disposition = lexicalStatDisposition({
-            isSymbolicLink,
-            isLast,
-            rejectSymlinks: isSymbolicLink ? context.resolveParams.rejectSymlinks : undefined,
-            allowFinalSymlink: state.allowFinalSymlink,
-        });
-        if (disposition !== "resolve-link") {
-            state.preserveFinalSymlink = disposition === "break";
+            if (observation?.enabled && observation.request.kind === "stat" &&
+                idx === observation.targetIndex && observation.directoryGuard) {
+                const parentReceipt = {
+                    kind: "stat-parent",
+                    rootGuard: observation.request.rootGuard,
+                    directoryGuard: observation.directoryGuard,
+                    directoryObserver: observation.directoryObserver,
+                    targetPath: state.lexicalCursor,
+                };
+                // Stop here: the generic missing-path fallback would re-admit a parent.
+                // Preserve observation-only versus ordinary traversal error precedence.
+                throw new RootPathObservationError(error instanceof RootPathObservationError ? error.error : sanitizeRootPathError(error), parentReceipt, !(error instanceof RootPathObservationError));
+            }
+            if (!isNotFoundPathError(error))
+                throw error;
             advanceCanonicalCursorForSegment(context, segment);
-            if (state.preserveFinalSymlink)
-                break;
+            state.missingDepth = 1;
             continue;
         }
-        const linkCanonical = await resolveSymlinkHopPath(state.lexicalCursor, {
-            rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
-        });
-        applyResolvedSymlinkHop(context, linkCanonical);
-        if (context.resolveParams.rejectSymlinks === true) {
-            throw new FsSafeError("symlink", "symlink path component not allowed");
-        }
-    }
-    const kind = await getPathKind(state.canonicalCursor, state.preserveFinalSymlink);
-    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 === "..") {
-            applyParentTraversalStep(context);
+        if (isNativeDirectoryObservationGuard(observed)) {
+            advanceCanonicalCursorForSegment(context, segment);
+            captureRootPathObservedDirectory(observation, observed, state.lexicalCursor, state.canonicalCursor, context.rootCanonicalPath, context.resolveParams.rootIdentity);
+            if (idx === observation.targetIndex) {
+                observation.targetPath = state.canonicalCursor;
+                observation.target = observed;
+            }
             continue;
         }
-        state.lexicalCursor = path.join(state.lexicalCursor, segment);
-        let stat;
-        try {
-            stat = fs.lstatSync(state.lexicalCursor);
-        }
-        catch (error) {
-            if (handleLexicalLstatFailure(context, error, idx))
-                break;
-            throw error;
-        }
+        if (!stat)
+            throw new Error("directory observation did not return metadata");
         const isSymbolicLink = stat.isSymbolicLink();
-        const disposition = lexicalStatDisposition({
-            isSymbolicLink,
-            isLast,
-            rejectSymlinks: isSymbolicLink ? context.resolveParams.rejectSymlinks : undefined,
-            allowFinalSymlink: state.allowFinalSymlink,
-        });
-        if (disposition !== "resolve-link") {
-            state.preserveFinalSymlink = disposition === "break";
+        if (!isSymbolicLink)
+            assertDirectoryBeforeMoreSegments(stat, state.lexicalCursor, isLast);
+        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);
+            }
+            if (observation?.enabled && idx === observation.directoryIndex) {
+                const captured = observed?.identity && captureRootPathObservedDirectory(observation, observed, state.canonicalCursor, state.canonicalCursor, context.rootCanonicalPath, context.resolveParams.rootIdentity);
+                if (!captured)
+                    disableLexicalTraversalObservation(context, observation);
+            }
+            if (observation?.enabled && idx === observation.targetIndex) {
+                observation.targetPath = state.canonicalCursor;
+                observation.target = observed?.identity ? observed : undefined;
+            }
             if (state.preserveFinalSymlink)
                 break;
             continue;
         }
-        const linkCanonical = resolveSymlinkHopPathSync(state.lexicalCursor, {
-            rejectUnresolved: context.resolveParams.rejectUnresolvedSymlinks,
-        });
+        if (observation?.enabled)
+            disableLexicalTraversalObservation(context, observation);
+        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");
         }
-    }
-    const kind = getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
-    return finalizeLexicalResolution(context, kind);
-}
-function resolveCanonicalOutsideLexicalPath(params) {
-    return params.outsideLexicalCanonicalPath ?? params.absolutePath;
-}
-function createBoundaryResolutionContext(params) {
-    const lexicalInside = isPathInside(params.rootPath, params.absolutePath);
-    const canonicalOutsideLexicalPath = resolveCanonicalOutsideLexicalPath({
-        absolutePath: params.absolutePath,
-        outsideLexicalCanonicalPath: params.outsideLexicalCanonicalPath,
-    });
-    assertLexicalBoundaryOrCanonicalAlias({
-        skipLexicalRootCheck: params.resolveParams.skipLexicalRootCheck,
-        lexicalInside,
-        canonicalOutsideLexicalPath,
-        rootCanonicalPath: params.rootCanonicalPath,
-        boundaryLabel: params.resolveParams.boundaryLabel,
-        rootPath: params.rootPath,
-        absolutePath: params.absolutePath,
-    });
-    return {
-        rootPath: params.rootPath,
-        absolutePath: params.absolutePath,
-        rootCanonicalPath: params.rootCanonicalPath,
-        lexicalInside,
-        canonicalOutsideLexicalPath,
-    };
-}
-async function resolveOutsideRootPathAsync(params) {
-    if (params.context.lexicalInside) {
-        return null;
-    }
-    const kind = await getPathKind(params.context.absolutePath, false);
-    return buildOutsideRootPathFromContext({
-        boundaryLabel: params.boundaryLabel,
-        context: params.context,
-        kind,
-    });
-}
-function resolveOutsideRootPathSync(params) {
-    if (params.context.lexicalInside) {
-        return null;
-    }
-    const kind = getPathKindSync(params.context.absolutePath, false);
-    return buildOutsideRootPathFromContext({
-        boundaryLabel: params.boundaryLabel,
-        context: params.context,
-        kind,
-    });
-}
-function buildOutsideRootPathFromContext(params) {
-    return buildOutsideLexicalRootPath({
-        boundaryLabel: params.boundaryLabel,
-        rootCanonicalPath: params.context.rootCanonicalPath,
-        absolutePath: params.context.absolutePath,
-        canonicalOutsideLexicalPath: params.context.canonicalOutsideLexicalPath,
-        rootPath: params.context.rootPath,
-        kind: params.kind,
-    });
-}
-async function resolveOutsideLexicalCanonicalPathAsync(params) {
-    if (isPathInside(params.rootPath, params.absolutePath)) {
-        return undefined;
-    }
-    return await resolvePathViaExistingAncestor(params.absolutePath);
-}
-function resolveOutsideLexicalCanonicalPathSync(params) {
-    if (isPathInside(params.rootPath, params.absolutePath)) {
-        return undefined;
-    }
-    return resolvePathViaExistingAncestorSync(params.absolutePath);
-}
-function buildOutsideLexicalRootPath(params) {
-    assertInsideBoundary({
-        boundaryLabel: params.boundaryLabel,
-        rootCanonicalPath: params.rootCanonicalPath,
-        candidatePath: params.canonicalOutsideLexicalPath,
-        absolutePath: params.absolutePath,
-    });
-    return buildResolvedRootPath({
-        absolutePath: params.absolutePath,
-        canonicalPath: params.canonicalOutsideLexicalPath,
-        rootPath: params.rootPath,
-        rootCanonicalPath: params.rootCanonicalPath,
-        kind: params.kind,
-    });
-}
-function assertLexicalBoundaryOrCanonicalAlias(params) {
-    if (params.skipLexicalRootCheck || params.lexicalInside) {
-        return;
-    }
-    if (isPathInside(params.rootCanonicalPath, params.canonicalOutsideLexicalPath)) {
-        return;
-    }
-    throw pathEscapeError({
-        boundaryLabel: params.boundaryLabel,
-        rootPath: params.rootPath,
-        absolutePath: params.absolutePath,
-    });
-}
-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) {
-    try {
-        const stat = preserveFinalSymlink
-            ? fs.lstatSync(absolutePath)
-            : fs.statSync(absolutePath);
-        return { exists: true, kind: toResolvedKind(stat) };
-    }
-    catch (error) {
-        if (isNotFoundPathError(error)) {
-            return { exists: false, kind: "missing" };
+        assertResolvedLinkDirectory(linkCanonical, isLast);
+    }
+    const completeObservation = observation?.enabled === true && observation.directoryGuard !== undefined &&
+        observation.targetPath === state.canonicalCursor && observation.target !== undefined;
+    const kind = completeObservation
+        ? {
+            exists: true,
+            kind: isNativeDirectoryObservationGuard(observation.target)
+                ? "directory"
+                : toResolvedKind(observation.target.stat),
         }
-        throw error;
+        : getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
+    if (completeObservation && observationOutput) {
+        observationOutput.receipt = {
+            kind: observation.request.kind,
+            rootGuard: observation.request.rootGuard,
+            directoryGuard: observation.directoryGuard,
+            directoryObserver: observation.directoryObserver,
+            targetPath: observation.targetPath,
+            target: observation.target,
+        };
     }
+    return finalizeLexicalResolution(context, kind);
 }
 function getPathKindSync(absolutePath, preserveFinalSymlink) {
     try {
-        const stat = preserveFinalSymlink ? fs.lstatSync(absolutePath) : fs.statSync(absolutePath);
+        const operationPath = pathForWindowsFilesystem(absolutePath);
+        const stat = preserveFinalSymlink
+            ? fs.lstatSync(operationPath)
+            : fs.statSync(operationPath);
         return { exists: true, kind: toResolvedKind(stat) };
     }
     catch (error) {
@@ -458,7 +421,7 @@ function toResolvedKind(stat) {
     return "other";
 }
 function relativeInsideRoot(rootPath, targetPath) {
-    const relative = path.relative(path.resolve(rootPath), path.resolve(targetPath));
+    const relative = path.relative(resolvePathPreservingWindowsRoot(rootPath), resolvePathPreservingWindowsRoot(targetPath));
     if (!relative || relative === ".") {
         return "";
     }
@@ -468,14 +431,13 @@ function relativeInsideRoot(rootPath, targetPath) {
     return relative;
 }
 function assertInsideBoundary(params) {
-    if (isPathInside(params.rootCanonicalPath, params.candidatePath)) {
-        return;
+    const admitted = admitPathInsideRoot({
+        rootPath: params.rootCanonicalPath,
+        candidatePath: params.candidatePath,
+        rootIdentity: params.rootIdentity,
+    });
+    if (admitted) {
+        return admitted.path;
     }
     throw new Error(`Path resolves outside ${params.boundaryLabel} (${shortPath(params.rootCanonicalPath)}): ${shortPath(params.absolutePath)}`);
 }
-function pathEscapeError(params) {
-    return new Error(`Path escapes ${params.boundaryLabel} (${shortPath(params.rootPath)}): ${shortPath(params.absolutePath)}`);
-}
-function symlinkEscapeError(params) {
-    return new Error(`Symlink escapes ${params.boundaryLabel} (${shortPath(params.rootCanonicalPath)}): ${shortPath(params.symlinkPath)}`);
-}