@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/root-move-noreplace.d.ts

@@ -0,0 +1,14 @@
+import { type DenyMutationPolicy } from "./deny-mutations.js";
+import { type RootContext } from "./root-context.js";
+import { type MutationSymlinkPolicy } from "./root-symlink-policy.js";
+export declare function movePathNoReplaceNative(root: RootContext, params: {
+    assertBeforeMutation?: () => void;
+    denyMutations?: DenyMutationPolicy;
+    mutationSymlinks?: MutationSymlinkPolicy;
+}, paths: {
+    sourcePath: string;
+    sourceParentPath: string;
+    targetPath: string;
+    targetParentPath: string;
+}): Promise<void>;
+//# sourceMappingURL=root-move-noreplace.d.ts.map

package/dist/root-move-noreplace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-move-noreplace.d.ts","sourceRoot":"","sources":["../src/root-move-noreplace.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AASvF,OAAO,EAA4D,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAU/G,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAqDlG,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE;IACN,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CAC1C,EACD,KAAK,EAAE;IACL,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GACA,OAAO,CAAC,IAAI,CAAC,CA0If"}

package/dist/root-move-noreplace.js

@@ -0,0 +1,202 @@
+import fsSync, {} from "node:fs";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { assertMutationNotDenied } from "./deny-mutations.js";
+import { closeNativeParentAdmission, openNativeParentAdmission, openNativeRootAdmission, } from "./native-parent-admission.js";
+import { getNativeBinding } from "./native.js";
+import { isNotFoundPathError } from "./path.js";
+import { assertRootIdentityCurrent, assertRootIdentityCurrentSync } from "./root-context.js";
+import { resolveRootPathSync } from "./root-path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, outsideWorkspaceError, } from "./root-errors.js";
+import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function nativeParentRelativePath(rootReal, parentPath) {
+    const relative = path.relative(rootReal, parentPath);
+    if (relative === "" || relative === ".")
+        return "";
+    const firstSegment = relative.split(path.sep)[0];
+    if (firstSegment === ".." ||
+        path.isAbsolute(relative)) {
+        throw outsideWorkspaceError();
+    }
+    return relative.split(path.sep).join(path.posix.sep);
+}
+function admitMovePath(root, parent, basename) {
+    const admitted = admitPathInsideRoot({
+        rootPath: root.rootReal,
+        candidatePath: path.join(parent.guard.realPath, basename),
+        rootIdentity: root.rootIdentity,
+    });
+    if (!admitted)
+        throw outsideWorkspaceError();
+    return admitted.path;
+}
+function nativePrimitiveUnavailable(error) {
+    const code = error?.code;
+    return code === "ENOSYS" || code === "ENOTSUP" || code === "EOPNOTSUPP";
+}
+function normalizeMoveError(error) {
+    if (isNotFoundPathError(error)) {
+        return fileNotFoundError(error instanceof Error ? error : undefined);
+    }
+    if (nativePrimitiveUnavailable(error)) {
+        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    return error;
+}
+function normalizeRenameNoReplaceError(error) {
+    if (error?.code === "EINVAL") {
+        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable on this filesystem", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    return normalizeMoveError(error);
+}
+export async function movePathNoReplaceNative(root, params, paths) {
+    try {
+        fsSync.lstatSync(paths.targetPath);
+        throw new FsSafeError("already-exists", "destination exists");
+    }
+    catch (error) {
+        if (error instanceof FsSafeError)
+            throw error;
+        if (!isNotFoundPathError(error))
+            throw error;
+        // Advisory fast rejection only. renameNoReplace owns the collision decision.
+    }
+    const binding = getNativeBinding();
+    if (!binding || typeof binding.renameNoReplace !== "function") {
+        throw new FsSafeError("helper-unavailable", "native no-replace move is unavailable");
+    }
+    const rootAdmission = await openNativeRootAdmission(binding, {
+        rootPath: root.rootReal,
+        rootIdentity: root.rootIdentity,
+        operation: "native move",
+    });
+    let sourceParent;
+    let targetParent;
+    let failed = false;
+    let operationError;
+    try {
+        const sourceParentRelativePath = nativeParentRelativePath(root.rootReal, paths.sourceParentPath);
+        sourceParent = await openNativeParentAdmission(binding, rootAdmission, sourceParentRelativePath);
+        const targetParentRelativePath = nativeParentRelativePath(root.rootReal, paths.targetParentPath);
+        targetParent = targetParentRelativePath === sourceParentRelativePath
+            ? sourceParent
+            : await openNativeParentAdmission(binding, rootAdmission, targetParentRelativePath);
+        const parentAdmissions = targetParent === sourceParent
+            ? [sourceParent]
+            : [sourceParent, targetParent];
+        await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("move", paths.targetPath);
+        const admittedSourcePath = admitMovePath(root, sourceParent, path.basename(paths.sourcePath));
+        const admittedTargetPath = admitMovePath(root, targetParent, path.basename(paths.targetPath));
+        if (params.denyMutations) {
+            // Native admission can follow a newly introduced contained parent alias.
+            // Authorize the selected names, then recheck every retained directory.
+            await assertMutationNotDenied(admittedSourcePath, params.denyMutations, { protectAncestors: true });
+            await assertMutationNotDenied(admittedTargetPath, params.denyMutations, { protectAncestors: true });
+        }
+        await assertRootIdentityCurrent(root);
+        for (const admission of parentAdmissions)
+            assertSyncDirectoryGuard(admission.guard);
+        let sourceStat;
+        try {
+            sourceStat = fsSync.lstatSync(admittedSourcePath);
+        }
+        catch (error) {
+            throw normalizeMoveError(error);
+        }
+        if (sourceStat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", "symlink not allowed");
+        }
+        if (sourceStat.isFile() && sourceStat.nlink > 1) {
+            throw hardlinkedPathNotAllowedError();
+        }
+        if (sourceStat.isDirectory()) {
+            throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
+        }
+        assertFinalSymlinkRejected(admittedTargetPath, params.mutationSymlinks !== undefined);
+        params.assertBeforeMutation?.();
+        if (params.assertBeforeMutation || params.mutationSymlinks === "reject") {
+            // Do not carry directory freshness across the live authority callback.
+            assertRootIdentityCurrentSync(root);
+            if (params.mutationSymlinks === "reject") {
+                // Validate both full pre-native routes; selected canonical names have
+                // already erased any parent symlink followed during admission.
+                for (const absolutePath of [paths.sourcePath, paths.targetPath]) {
+                    resolveRootPathSync({
+                        absolutePath,
+                        rootPath: root.rootReal,
+                        rootCanonicalPath: root.rootReal,
+                        rootIdentity: root.rootIdentity,
+                        boundaryLabel: "root",
+                        rejectSymlinks: true,
+                        rejectFinalSymlink: true,
+                    });
+                }
+            }
+            for (const admission of parentAdmissions)
+                assertSyncDirectoryGuard(admission.guard);
+        }
+        try {
+            binding.renameNoReplace(sourceParent.fd, path.basename(paths.sourcePath), targetParent.fd, path.basename(paths.targetPath));
+        }
+        catch (error) {
+            if (isAlreadyExistsError(error) || error?.code === "ENOTEMPTY") {
+                throw new FsSafeError("already-exists", "destination exists", {
+                    cause: error instanceof Error ? error : undefined,
+                });
+            }
+            throw normalizeRenameNoReplaceError(error);
+        }
+        try {
+            for (const admission of parentAdmissions)
+                await assertAsyncDirectoryGuard(admission.guard);
+        }
+        catch (error) {
+            throw normalizePinnedPathError(error);
+        }
+    }
+    catch (error) {
+        failed = true;
+        operationError = normalizeMoveError(error);
+    }
+    const closeErrors = [];
+    const closedFds = new Set();
+    for (const admission of [targetParent, sourceParent]) {
+        if (!admission || closedFds.has(admission.fd))
+            continue;
+        closedFds.add(admission.fd);
+        try {
+            closeNativeParentAdmission(admission);
+        }
+        catch (error) {
+            closeErrors.push(error);
+        }
+    }
+    try {
+        await rootAdmission.root.close();
+    }
+    catch (error) {
+        closeErrors.push(error);
+    }
+    if (failed) {
+        if (closeErrors.length > 0) {
+            const closeError = closeErrors.length === 1
+                ? closeErrors[0]
+                : new AggregateError(closeErrors, "native move descriptor closes failed");
+            throw createSuppressedError(closeError, operationError, "native move and descriptor close failed");
+        }
+        throw operationError;
+    }
+    if (closeErrors.length === 1)
+        throw closeErrors[0];
+    if (closeErrors.length > 1) {
+        throw new AggregateError(closeErrors, "native move descriptor closes failed");
+    }
+}

package/dist/root-move-preflight.d.ts

@@ -0,0 +1,8 @@
+import { type DenyMutationPolicy } from "./deny-mutations.js";
+import { type RootContext } from "./root-context.js";
+export declare function assertMoveMutationAllowed(root: RootContext, params: {
+    fromRelative: string;
+    toRelative: string;
+    denyMutations?: DenyMutationPolicy;
+}): Promise<void>;
+//# sourceMappingURL=root-move-preflight.d.ts.map

package/dist/root-move-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-move-preflight.d.ts","sourceRoot":"","sources":["../src/root-move-preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAExE,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE;IACN,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACpC,GACA,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/root-move-preflight.js

@@ -0,0 +1,16 @@
+import { assertMutationNotDenied, } from "./deny-mutations.js";
+import { resolvePathInRoot } from "./root-context.js";
+export async function assertMoveMutationAllowed(root, params) {
+    // Keep this preflight separate from the pinned resolutions in movePathFallback:
+    // mutation denials must take precedence over source alias or identity failures.
+    const source = await resolvePathInRoot(root, params.fromRelative, {
+        aliasErrorCode: "path-alias",
+        allowFinalSymlink: true,
+    });
+    await assertMutationNotDenied(source.resolved, params.denyMutations, { protectAncestors: true });
+    const target = await resolvePathInRoot(root, params.toRelative, {
+        aliasErrorCode: "path-alias",
+        allowFinalSymlink: true,
+    });
+    await assertMutationNotDenied(target.resolved, params.denyMutations, { protectAncestors: true });
+}

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

@@ -0,0 +1,9 @@
+import { type RootPathObservationKind, type RootPathObservationReceipt } from "./root-path.js";
+import { type RootContext } from "./root-context.js";
+export type PinnedObservedPath = {
+    rootReal: string;
+    resolved: string;
+    receipt?: RootPathObservationReceipt;
+};
+export declare function resolvePinnedObservedPathInRoot(root: RootContext, relativePath: string, kind: RootPathObservationKind): Promise<PinnedObservedPath | undefined>;
+//# sourceMappingURL=root-observed-path.d.ts.map

package/dist/root-observed-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-observed-path.d.ts","sourceRoot":"","sources":["../src/root-observed-path.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAChC,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAI3B,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,0BAA0B,CAAC;CACtC,CAAC;AAEF,wBAAsB,+BAA+B,CACnD,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAgFzC"}

package/dist/root-observed-path.js

@@ -0,0 +1,95 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { getNativeDirectoryObservationBackend } from "./native-directory-observation.js";
+import { isNotFoundPathError } from "./path.js";
+import { PATH_ALIAS_POLICIES } from "./path-policy.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { assertRootPathObservationReceiptCurrent } from "./root-directory-list.js";
+import { RootPathObservationError, resolveRootPathWithObservation, } from "./root-path.js";
+import { createRootObservationGuard, ensureTrailingSep, expandRelativePathWithHome, } from "./root-context.js";
+import { fileNotFoundError, outsideWorkspaceError } from "./root-errors.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+export async function resolvePinnedObservedPathInRoot(root, relativePath, kind) {
+    const rootGuard = await createRootObservationGuard(root);
+    if (!rootGuard)
+        return undefined;
+    // Race hooks exercise the established JavaScript observation points. Do not
+    // silently move those points into the native helper in test configurations.
+    const directoryObserver = getNativeDirectoryObservationBackend(getFsSafeTestHooks() === undefined);
+    const rootReal = root.rootReal;
+    let observed;
+    try {
+        const expandedPath = await expandRelativePathWithHome(relativePath);
+        const observationPath = process.platform === "win32"
+            ? expandedPath.replaceAll("/", path.sep)
+            : expandedPath;
+        observed = await resolveRootPathWithObservation({
+            absolutePath: path.isAbsolute(observationPath)
+                ? observationPath
+                : observationPath === ""
+                    ? rootReal
+                    : `${ensureTrailingSep(rootReal)}${observationPath}`,
+            rootPath: rootReal,
+            rootCanonicalPath: rootReal,
+            rootIdentity: root.rootIdentity,
+            boundaryLabel: "root",
+            policy: PATH_ALIAS_POLICIES.strict,
+        }, { kind, rootGuard, directoryObserver });
+    }
+    catch (error) {
+        if (error instanceof RootPathObservationError) {
+            if (error.parentReceipt) {
+                assertRootPathObservationReceiptCurrent(root, error.parentReceipt);
+                if (error.traversalFailure && !isNotFoundPathError(error.error)) {
+                    if (error.error instanceof FsSafeError && error.error.code === "symlink")
+                        throw error.error;
+                    throw new FsSafeError("path-alias", "path alias escape blocked", { cause: error.error });
+                }
+            }
+            if (isNotFoundPathError(error.error)) {
+                if (kind === "stat") {
+                    throw fileNotFoundError(error.error instanceof Error ? error.error : undefined);
+                }
+                throw new FsSafeError("not-found", "directory not found", {
+                    cause: error.error instanceof Error ? error.error : undefined,
+                });
+            }
+            throw error.error;
+        }
+        if (error instanceof FsSafeError && error.code === "symlink")
+            throw error;
+        throw new FsSafeError("path-alias", "path alias escape blocked", { cause: error });
+    }
+    const resolved = observed.resolved;
+    if (observed.receipt) {
+        // A receipt is emitted only for the straight traversal whose lexical and
+        // canonical cursors stayed identical and inside the checked boundary.
+        return {
+            rootReal: resolved.rootCanonicalPath,
+            resolved: resolved.canonicalPath,
+            receipt: observed.receipt,
+        };
+    }
+    const relativeResolved = path.relative(resolved.rootCanonicalPath, resolved.canonicalPath);
+    if (relativeResolved === "" || relativeResolved === ".") {
+        return {
+            rootReal: resolved.rootCanonicalPath,
+            resolved: resolved.canonicalPath,
+        };
+    }
+    const firstSegment = relativeResolved.split(path.sep)[0];
+    if (firstSegment === ".." || path.isAbsolute(relativeResolved)) {
+        throw outsideWorkspaceError();
+    }
+    const admittedCanonicalPath = admitPathInsideRoot({
+        rootPath: resolved.rootCanonicalPath,
+        candidatePath: resolved.canonicalPath,
+        rootIdentity: root.rootIdentity,
+    });
+    if (!admittedCanonicalPath)
+        throw outsideWorkspaceError();
+    return {
+        rootReal: resolved.rootCanonicalPath,
+        resolved: admittedCanonicalPath.path,
+    };
+}

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

@@ -0,0 +1,12 @@
+export declare function sanitizeRootPathError(error: unknown): unknown;
+export declare function pathEscapeError(params: {
+    boundaryLabel: string;
+    rootPath: string;
+    absolutePath: string;
+}): Error;
+export declare function symlinkEscapeError(params: {
+    boundaryLabel: string;
+    rootCanonicalPath: string;
+    symlinkPath: string;
+}): Error;
+//# sourceMappingURL=root-path-errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"root-path-errors.d.ts","sourceRoot":"","sources":["../src/root-path-errors.ts"],"names":[],"mappings":"AAEA,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK7D;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,KAAK,CAIR;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,KAAK,CAIR"}

package/dist/root-path-errors.js

@@ -0,0 +1,13 @@
+import { formatErrorDetail, shortPath } from "./error-detail.js";
+export function sanitizeRootPathError(error) {
+    if (error instanceof Error) {
+        error.message = formatErrorDetail(error.message);
+    }
+    return error;
+}
+export function pathEscapeError(params) {
+    return new Error(`Path escapes ${params.boundaryLabel} (${shortPath(params.rootPath)}): ${shortPath(params.absolutePath)}`);
+}
+export function symlinkEscapeError(params) {
+    return new Error(`Symlink escapes ${params.boundaryLabel} (${shortPath(params.rootCanonicalPath)}): ${shortPath(params.symlinkPath)}`);
+}

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

@@ -1,7 +1,9 @@
+import { type RootBoundaryIdentity } from "./root-boundary.js";
 export declare function absolutePathWithRawSegments(candidate: string): string;
 export declare function rawPathRelativeToCanonicalRoot(candidate: string, rootCanonicalPath: string, options?: {
     rejectSymlinks?: boolean;
     rejectFinalSymlink?: boolean;
+    rootIdentity?: RootBoundaryIdentity;
 }): string | undefined;
 export declare function resolvePathViaExistingAncestor(targetPath: string): Promise<string>;
 export declare function resolvePathViaExistingAncestorSync(targetPath: string): string;

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

@@ -1 +1 @@
-{"version":3,"file":"root-path-existing.d.ts","sourceRoot":"","sources":["../src/root-path-existing.ts"],"names":[],"mappings":"AAOA,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,MAAM,EACzB,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAO,GACvE,MAAM,GAAG,SAAS,CAuCpB;AAkBD,wBAAsB,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BxF;AAED,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA0B7E"}
+{"version":3,"file":"root-path-existing.d.ts","sourceRoot":"","sources":["../src/root-path-existing.ts"],"names":[],"mappings":"AAWA,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEpF,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAarE;AAED,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,MAAM,EACzB,OAAO,GAAE;IACP,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,oBAAoB,CAAC;CAChC,GACL,MAAM,GAAG,SAAS,CAqDpB;AAkBD,wBAAsB,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkCxF;AAED,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAqC7E"}

package/dist/root-path-existing.js

@@ -4,14 +4,28 @@ import { FsSafeError } from "./errors.js";
 import { formatErrorDetail } from "./error-detail.js";
 import { isNotFoundPathError, isPathInside } from "./path.js";
 import { realpathSync } from "./realpath.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
 export function absolutePathWithRawSegments(candidate) {
-    if (path.isAbsolute(candidate))
-        return candidate;
-    const drive = path.parse(candidate).root;
+    if (path.sep !== "\\") {
+        if (path.isAbsolute(candidate))
+            return candidate;
+        const base = process.cwd();
+        return `${base}${base.endsWith(path.sep) ? "" : path.sep}${candidate}`;
+    }
+    const raw = path.sep === "\\" ? candidate.replaceAll("/", "\\") : candidate;
+    const absolute = path.isAbsolute(raw);
+    if (absolute && raw[0] !== "\\")
+        return raw;
+    const drive = path.parse(raw).root;
+    if (absolute && drive !== "\\")
+        return raw;
     const base = drive ? path.resolve(drive) : process.cwd();
-    return `${base}${path.sep}${candidate.slice(drive.length)}`;
+    return `${base}${base.endsWith(path.sep) ? "" : path.sep}${raw.slice(drive.length)}`;
 }
 export function rawPathRelativeToCanonicalRoot(candidate, rootCanonicalPath, options = {}) {
+    assertNoWindowsPathAlias(candidate);
+    assertNoWindowsPathAlias(rootCanonicalPath);
     const absolute = absolutePathWithRawSegments(candidate);
     const raw = process.platform === "win32" ? absolute.replaceAll("/", path.sep) : absolute;
     const filesystemRoot = path.parse(raw).root;
@@ -19,12 +33,14 @@ export function rawPathRelativeToCanonicalRoot(candidate, rootCanonicalPath, opt
     const finalComponentIndex = segments.findLastIndex(segment => segment !== "" && segment !== ".");
     let prefix = filesystemRoot;
     let traversedSymlink = false;
+    const identityCache = process.platform === "win32" ? new Map() : undefined;
     for (let index = 0; index < segments.length; index += 1) {
         prefix += `${prefix.endsWith(path.sep) ? "" : path.sep}${segments[index]}`;
         let canonical;
         let isSymlink = false;
         try {
-            const stat = fs.lstatSync(prefix);
+            const operationPath = pathForWindowsFilesystem(prefix);
+            const stat = fs.lstatSync(operationPath);
             isSymlink = stat.isSymbolicLink();
             // Check the original leaf before canonicalization can erase an entry alias.
             if (isSymlink && options.rejectFinalSymlink && index === finalComponentIndex) {
@@ -33,8 +49,10 @@ export function rawPathRelativeToCanonicalRoot(candidate, rootCanonicalPath, opt
             if (!isSymlink && !stat.isDirectory() && index < segments.length - 1)
                 return undefined;
             traversedSymlink ||= isSymlink;
-            canonical = realpathSync.native(prefix);
-            if (isSymlink && index < segments.length - 1 && !fs.statSync(canonical).isDirectory())
+            canonical = realpathSync.native(operationPath);
+            assertNoWindowsPathAlias(canonical);
+            if (isSymlink && index < segments.length - 1 &&
+                !fs.statSync(pathForWindowsFilesystem(canonical)).isDirectory())
                 return undefined;
             if (isSymlink && !isPathInside(rootCanonicalPath, canonical) && !isPathInside(canonical, rootCanonicalPath)) {
                 throw new FsSafeError("outside-workspace", `symlink prefix resolves outside the root ancestry: ${formatErrorDetail(candidate)}`);
@@ -47,12 +65,18 @@ export function rawPathRelativeToCanonicalRoot(candidate, rootCanonicalPath, opt
                 return undefined;
             continue;
         }
-        if (!isPathInside(rootCanonicalPath, canonical))
+        const admitted = admitPathInsideRoot({
+            rootPath: rootCanonicalPath,
+            candidatePath: canonical,
+            rootIdentity: options.rootIdentity,
+            identityCache,
+        });
+        if (!admitted)
             continue;
         if (options.rejectSymlinks && traversedSymlink) {
             throw new FsSafeError("symlink", "symlink path component not allowed");
         }
-        return [path.relative(rootCanonicalPath, canonical), ...segments.slice(index + 1)]
+        return [admitted.relativePath, ...segments.slice(index + 1)]
             .filter(Boolean).join(path.sep);
     }
     return undefined;
@@ -62,7 +86,7 @@ function isFilesystemRoot(candidate) {
 }
 async function pathExists(targetPath) {
     try {
-        fs.lstatSync(targetPath);
+        fs.lstatSync(pathForWindowsFilesystem(targetPath));
         return true;
     }
     catch (error) {
@@ -73,7 +97,9 @@ async function pathExists(targetPath) {
     }
 }
 export async function resolvePathViaExistingAncestor(targetPath) {
-    const normalized = path.resolve(targetPath);
+    assertNoWindowsPathAlias(targetPath);
+    const normalized = resolvePathPreservingWindowsRoot(targetPath);
+    assertNoWindowsPathAlias(normalized);
     let cursor = normalized;
     const missingSuffix = [];
     while (!isFilesystemRoot(cursor) && !(await pathExists(cursor))) {
@@ -87,21 +113,30 @@ export async function resolvePathViaExistingAncestor(targetPath) {
     if (!(await pathExists(cursor))) {
         return normalized;
     }
+    let rawResolvedAncestor;
     try {
-        const resolvedAncestor = path.resolve(realpathSync.native(cursor));
-        return missingSuffix.length === 0
-            ? resolvedAncestor
-            : path.resolve(resolvedAncestor, ...missingSuffix);
+        rawResolvedAncestor = realpathSync.native(pathForWindowsFilesystem(cursor));
     }
     catch {
         return normalized;
     }
+    assertNoWindowsPathAlias(rawResolvedAncestor);
+    const resolvedAncestor = resolvePathPreservingWindowsRoot(rawResolvedAncestor);
+    assertNoWindowsPathAlias(resolvedAncestor);
+    const resolved = missingSuffix.length === 0
+        ? resolvedAncestor
+        : path.resolve(resolvedAncestor, ...missingSuffix);
+    assertNoWindowsPathAlias(resolved);
+    return resolved;
 }
 export function resolvePathViaExistingAncestorSync(targetPath) {
-    const normalized = path.resolve(targetPath);
+    assertNoWindowsPathAlias(targetPath);
+    const normalized = resolvePathPreservingWindowsRoot(targetPath);
+    assertNoWindowsPathAlias(normalized);
     let cursor = normalized;
     const missingSuffix = [];
-    while (!isFilesystemRoot(cursor) && !fs.existsSync(cursor)) {
+    while (!isFilesystemRoot(cursor) &&
+        !fs.existsSync(pathForWindowsFilesystem(cursor))) {
         missingSuffix.unshift(path.basename(cursor));
         const parent = path.dirname(cursor);
         if (parent === cursor) {
@@ -109,16 +144,22 @@ export function resolvePathViaExistingAncestorSync(targetPath) {
         }
         cursor = parent;
     }
-    if (!fs.existsSync(cursor)) {
+    if (!fs.existsSync(pathForWindowsFilesystem(cursor))) {
         return normalized;
     }
+    let rawResolvedAncestor;
     try {
-        const resolvedAncestor = path.resolve(realpathSync(cursor));
-        return missingSuffix.length === 0
-            ? resolvedAncestor
-            : path.resolve(resolvedAncestor, ...missingSuffix);
+        rawResolvedAncestor = realpathSync(pathForWindowsFilesystem(cursor));
     }
     catch {
         return normalized;
     }
+    assertNoWindowsPathAlias(rawResolvedAncestor);
+    const resolvedAncestor = resolvePathPreservingWindowsRoot(rawResolvedAncestor);
+    assertNoWindowsPathAlias(resolvedAncestor);
+    const resolved = missingSuffix.length === 0
+        ? resolvedAncestor
+        : path.resolve(resolvedAncestor, ...missingSuffix);
+    assertNoWindowsPathAlias(resolved);
+    return resolved;
 }

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

@@ -0,0 +1,63 @@
+import fs, { type BigIntStats } from "node:fs";
+import { type DirectoryObservationGuard } from "./directory-guard.js";
+import { type NativeDirectoryObservationBackend, type NativeDirectoryObservationGuard } from "./native-directory-observation.js";
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+import { type StatObservationReceipt } from "./stat-observation.js";
+export type RootPathObservationKind = "stat" | "directory";
+export type RootPathDirectoryObservationGuard = DirectoryObservationGuard | NativeDirectoryObservationGuard;
+export type RootPathTargetObservation = StatObservationReceipt | NativeDirectoryObservationGuard;
+/** An exact receipt owned by one stat/list operation. Never cache it. */
+export type RootPathObservationReceipt = {
+    kind: RootPathObservationKind;
+    rootGuard: DirectoryObservationGuard;
+    directoryGuard: RootPathDirectoryObservationGuard;
+    directoryObserver?: NativeDirectoryObservationBackend;
+    targetPath: string;
+    target: RootPathTargetObservation;
+};
+/** A failed initial target lookup must not discard its already admitted parent. */
+export type RootPathParentObservationReceipt = Omit<RootPathObservationReceipt, "kind" | "target"> & {
+    kind: "stat-parent";
+};
+export type RootPathObservationRequest = {
+    kind: RootPathObservationKind;
+    rootGuard: DirectoryObservationGuard;
+    directoryObserver?: NativeDirectoryObservationBackend;
+};
+export type RootPathTraversalObservation = {
+    enabled: boolean;
+    request: RootPathObservationRequest;
+    targetIndex: number;
+    directoryIndex: number;
+    directoryGuard?: RootPathDirectoryObservationGuard;
+    directoryObserver?: NativeDirectoryObservationBackend;
+    targetPath?: string;
+    target?: RootPathTargetObservation;
+};
+export type RootPathObservedTraversalEntry = StatObservationReceipt | {
+    stat: fs.Stats | BigIntStats;
+    identity?: undefined;
+} | NativeDirectoryObservationGuard;
+export declare class RootPathObservationError extends Error {
+    readonly error: unknown;
+    readonly parentReceipt?: RootPathParentObservationReceipt | undefined;
+    readonly traversalFailure: boolean;
+    constructor(error: unknown, parentReceipt?: RootPathParentObservationReceipt | undefined, traversalFailure?: boolean);
+}
+export type RootPathTraversalContext = {
+    observationEligible: boolean;
+    rootPath: string;
+    rootCanonicalPath: string;
+    resolveParams: {
+        rootIdentity?: RootBoundaryIdentity;
+    };
+    state: {
+        finalComponentIndex: number;
+        relativePath: string;
+        segments: string[];
+    };
+};
+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-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-path-observation.d.ts","sourceRoot":"","sources":["../src/root-path-observation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAIL,KAAK,iCAAiC,EACtC,KAAK,+BAA+B,EACrC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAA8B,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEhG,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,MAAM,iCAAiC,GACzC,yBAAyB,GACzB,+BAA+B,CAAC;AAEpC,MAAM,MAAM,yBAAyB,GACjC,sBAAsB,GACtB,+BAA+B,CAAC;AAEpC,yEAAyE;AACzE,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,SAAS,EAAE,yBAAyB,CAAC;IACrC,cAAc,EAAE,iCAAiC,CAAC;IAClD,iBAAiB,CAAC,EAAE,iCAAiC,CAAC;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,yBAAyB,CAAC;CACnC,CAAC;AAEF,mFAAmF;AACnF,MAAM,MAAM,gCAAgC,GAAG,IAAI,CAAC,0BAA0B,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG;IACnG,IAAI,EAAE,aAAa,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,SAAS,EAAE,yBAAyB,CAAC;IACrC,iBAAiB,CAAC,EAAE,iCAAiC,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,0BAA0B,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,iCAAiC,CAAC;IACnD,iBAAiB,CAAC,EAAE,iCAAiC,CAAC;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,yBAAyB,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,8BAA8B,GACtC,sBAAsB,GACtB;IAAE,IAAI,EAAE,EAAE,CAAC,KAAK,GAAG,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,GACtD,+BAA+B,CAAC;AAIpC,qBAAa,wBAAyB,SAAQ,KAAK;IAE/C,QAAQ,CAAC,KAAK,EAAE,OAAO;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,gCAAgC;IACzD,QAAQ,CAAC,gBAAgB;IAH3B,YACW,KAAK,EAAE,OAAO,EACd,aAAa,CAAC,EAAE,gCAAgC,YAAA,EAChD,gBAAgB,UAAQ,EAIlC;CACF;AAoBD,MAAM,MAAM,wBAAwB,GAAG;IACrC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE;QAAE,YAAY,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAC;IACvD,KAAK,EAAE;QACL,mBAAmB,EAAE,MAAM,CAAC;QAC5B,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH,CAAC;AAEF,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,wBAAwB,EACjC,OAAO,CAAC,EAAE,0BAA0B,GACnC,4BAA4B,GAAG,SAAS,CAkF1C;AAED,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,OAAO,EACtB,WAAW,EAAE,4BAA4B,GACxC,8BAA8B,CAyBhC;AAED,wBAAgB,gCAAgC,CAC9C,WAAW,EAAE,4BAA4B,EACzC,QAAQ,EAAE,8BAA8B,EACxC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,iBAAiB,EAAE,MAAM,EACzB,YAAY,CAAC,EAAE,oBAAoB,GAClC,OAAO,CAgCT"}