@openclaw/matrix 2026.9.6 → 2026.9.8

package/node_modules/@openclaw/fs-safe/dist/root-move-noreplace.d.ts

@@ -0,0 +1,10 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { RootMoveOptions } from "./root-options.js";
+import { type RootContext } from "./root-context.js";
+export declare function admitMoveSourceStat<T extends Stats | BigIntStats>(stat: T, overwrite?: boolean): T;
+export declare function movePathNoReplaceNative(root: RootContext, params: Pick<RootMoveOptions, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">, paths: {
+    sourcePath: string;
+    sourceParentPath: string;
+    targetPath: string;
+    targetParentPath: string;
+}): Promise<void>;

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

@@ -0,0 +1,205 @@
+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 { openNativeParentAdmission, openNativeRootAdmission, } from "./native-parent-admission.js";
+import { requireNativeBinding } 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 { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, outsideWorkspaceError, } from "./root-errors.js";
+import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.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", errorCauseOptions(error));
+    }
+    return error;
+}
+function normalizeRenameNoReplaceError(error) {
+    if (error?.code === "EINVAL") {
+        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable on this filesystem", errorCauseOptions(error));
+    }
+    return normalizeMoveError(error);
+}
+export function admitMoveSourceStat(stat, overwrite = false) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", "symlink not allowed");
+    }
+    if (stat.isFile() && stat.nlink > 1) {
+        throw hardlinkedPathNotAllowedError();
+    }
+    if (!overwrite && stat.isDirectory()) {
+        throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
+    }
+    return stat;
+}
+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 = requireNativeBinding();
+    if (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);
+        // Capture an exact receipt only when admission must survive a callback.
+        let sourceStat;
+        if (params.assertBeforeMutation) {
+            sourceStat = inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true })));
+        }
+        else {
+            admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath));
+        }
+        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);
+        }
+        // The callback can change a leaf without replacing its admitted parent.
+        if (sourceStat !== undefined) {
+            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true })), sourceStat);
+        }
+        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", errorCauseOptions(error));
+            }
+            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 {
+            admission.close();
+        }
+        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/node_modules/@openclaw/fs-safe/dist/root-move-preflight.d.ts

@@ -0,0 +1,7 @@
+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>;

package/node_modules/@openclaw/fs-safe/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/node_modules/@openclaw/fs-safe/dist/root-observed-path.d.ts

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

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

@@ -0,0 +1,90 @@
+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 { errorCauseOptions, 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", errorCauseOptions(error.error));
+            }
+            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 {
+            resolved: resolved.canonicalPath,
+            receipt: observed.receipt,
+        };
+    }
+    const relativeResolved = path.relative(resolved.rootCanonicalPath, resolved.canonicalPath);
+    if (relativeResolved === "" || relativeResolved === ".") {
+        return {
+            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 {
+        resolved: admittedCanonicalPath.path,
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/root-options.d.ts

@@ -0,0 +1,84 @@
+import type { DenyMutationPolicy } from "./deny-mutations.js";
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
+import type { MutationSymlinkPolicy, SymlinkPolicy } from "./root-symlink-policy.js";
+import type { CopyCloneMode } from "./copy-policy.js";
+import type { RootCopyPublicationReceipt } from "./copy-publication.js";
+import type { Root } from "./root-impl.js";
+export declare const DEFAULT_ROOT_MAX_BYTES: number;
+export type RootOptions = {
+    rootDir: string;
+    defaults?: RootDefaults;
+};
+export type HardlinkPolicy = "reject" | "allow";
+export type WritableOpenMode = "replace" | "append" | "update";
+export type RootDefaults = {
+    assertBeforeMutation?: () => void;
+    durable?: boolean;
+    hardlinks?: HardlinkPolicy;
+    maxBytes?: number;
+    mkdir?: boolean;
+    mode?: number;
+    denyMutations?: DenyMutationPolicy;
+    nonBlockingRead?: boolean;
+    renameIdentity?: RenameIdentityPolicy;
+    symlinks?: SymlinkPolicy;
+    mutationSymlinks?: MutationSymlinkPolicy;
+};
+export type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
+export type RootOpenOptions = Omit<RootReadOptions, "maxBytes">;
+export type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks" | "durable" | "mkdir" | "mode" | "renameIdentity"> & {
+    encoding?: BufferEncoding;
+    overwrite?: boolean;
+};
+export type RootOpenWritableOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks" | "mkdir" | "mode"> & {
+    writeMode?: WritableOpenMode;
+};
+export type RootCopyOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks" | "durable" | "maxBytes" | "mkdir" | "mode"> & {
+    sourceHardlinks?: HardlinkPolicy;
+    overwrite?: boolean;
+    clone?: CopyCloneMode;
+    signal?: AbortSignal;
+    preserveSourceMode?: boolean;
+    onDestinationPublished?: (receipt: RootCopyPublicationReceipt) => void;
+};
+export type RootCopySource = string | {
+    root: Pick<Root, "open" | "stat">;
+    relativePath: string;
+};
+export type RootWriteJsonOptions = RootWriteOptions & {
+    replacer?: Parameters<typeof JSON.stringify>[1];
+    space?: Parameters<typeof JSON.stringify>[2];
+    trailingNewline?: boolean;
+};
+export type RootCreateOptions = Omit<RootWriteOptions, "overwrite" | "durable"> & {
+    /** Publish complete content without replacing an existing entry, including without native support. */
+    atomic?: boolean;
+    private?: boolean;
+    /** "file" requires file synchronization; directory synchronization remains best effort. */
+    durable?: boolean | "file";
+};
+export type RootCreateStreamOptions = Omit<RootCreateOptions, "atomic" | "encoding" | "renameIdentity"> & {
+    maxBytes?: number;
+    signal?: AbortSignal;
+};
+export type RootCreateJsonOptions = Omit<RootWriteJsonOptions, "overwrite" | "durable"> & Pick<RootCreateOptions, "atomic" | "durable" | "private">;
+export type RootAppendOptions = RootWriteOptions & {
+    prependNewlineIfNeeded?: boolean;
+};
+export type RootMoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+    overwrite?: boolean;
+};
+export type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+    recursive?: boolean;
+    force?: boolean;
+    order?: "filesystem" | "sorted";
+    maxEntries?: number;
+    maxDepth?: number;
+    signal?: AbortSignal;
+};
+export type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+    private?: boolean;
+};
+export type RootReadParams = Omit<RootReadOptions, "nonBlockingRead">;
+export declare function readDefaults(defaults: RootDefaults): RootReadParams;
+export declare function mergeReadOptions(defaults: RootDefaults, options: RootReadOptions): RootReadParams;

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

@@ -0,0 +1,18 @@
+import { normalizeMaxBytes } from "./byte-budget.js";
+export const DEFAULT_ROOT_MAX_BYTES = 16 * 1024 * 1024;
+export function readDefaults(defaults) {
+    return {
+        hardlinks: defaults.hardlinks,
+        maxBytes: normalizeMaxBytes(defaults.maxBytes, { defaultValue: DEFAULT_ROOT_MAX_BYTES }),
+        symlinks: defaults.symlinks,
+    };
+}
+export function mergeReadOptions(defaults, options) {
+    const merged = readDefaults(defaults);
+    if (options.hardlinks !== undefined)
+        merged.hardlinks = options.hardlinks;
+    merged.maxBytes = normalizeMaxBytes(options.maxBytes, { defaultValue: merged.maxBytes });
+    if (options.symlinks !== undefined)
+        merged.symlinks = options.symlinks;
+    return merged;
+}

package/node_modules/@openclaw/fs-safe/dist/root-path-errors.d.ts

@@ -0,0 +1,12 @@
+export declare function isRootPathEscapeError(error: unknown): error is Error;
+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;

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

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

package/node_modules/@openclaw/fs-safe/dist/root-path-existing.d.ts

@@ -0,0 +1,12 @@
+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;
+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/node_modules/@openclaw/fs-safe/dist/root-path-existing.js

@@ -0,0 +1,160 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { formatErrorDetail } from "./error-detail.js";
+import { isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path.js";
+import { realpathSync } from "./realpath.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))
+            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}${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;
+    const segments = raw.slice(filesystemRoot.length).split(path.sep);
+    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 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) {
+                throw new FsSafeError("symlink", "final symlink not allowed");
+            }
+            if (!isSymlink && !stat.isDirectory() && index < segments.length - 1)
+                return undefined;
+            traversedSymlink ||= isSymlink;
+            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)}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof FsSafeError)
+                throw error;
+            if (isSymlink)
+                return undefined;
+            continue;
+        }
+        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 [admitted.relativePath, ...segments.slice(index + 1)]
+            .filter(Boolean).join(path.sep);
+    }
+    return undefined;
+}
+function pathExists(targetPath) {
+    try {
+        return fs.lstatSync(pathForWindowsFilesystem(targetPath), { throwIfNoEntry: false }) !== undefined;
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function resolvePathViaExistingAncestor(targetPath) {
+    return resolveExistingAncestor(targetPath, "native");
+}
+function pathExistsSync(targetPath) {
+    return fs.existsSync(pathForWindowsFilesystem(targetPath));
+}
+export function resolvePathViaExistingAncestorSync(targetPath) {
+    return resolveExistingAncestor(targetPath, "ordinary");
+}
+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 filesystemRoot = path.parse(normalized).root;
+    while (cursor !== filesystemRoot &&
+        !exists(cursor)) {
+        cursor = path.dirname(cursor);
+    }
+    if (!exists(cursor)) {
+        return normalized;
+    }
+    let rawResolvedAncestor;
+    try {
+        rawResolvedAncestor = canonicalize(pathForWindowsFilesystem(cursor));
+    }
+    catch {
+        return normalized;
+    }
+    assertNoWindowsPathAlias(rawResolvedAncestor);
+    const resolvedAncestor = resolvePathPreservingWindowsRoot(rawResolvedAncestor);
+    assertNoWindowsPathAlias(resolvedAncestor);
+    // Keep a leading suffix separator relative to the canonical ancestor.
+    const resolved = cursor === normalized
+        ? resolvedAncestor
+        : 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;
+    }
+}