@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -1,5 +1,8 @@
+import fs, { type BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard, type DirectoryObservationGuard } from "./directory-guard.js";
 export type RootContext = {
     rootDir: string;
+    rootGuard?: AsyncDirectoryGuard<BigIntStats>;
     rootIdentity: {
         dev: number;
         ino: number;
@@ -16,23 +19,25 @@ export declare function assertValidRootDestinationPath(relativePath: string): vo
 export declare function expandRelativePathWithHome(relativePath: string): Promise<string>;
 export declare function resolveRootContext(rootDir: string): Promise<RootContext>;
 export declare function rootRelativeReadPath(root: RootContext, filePath: string): string;
-export declare function assertRootIdentityCurrent(root: RootContext): Promise<void>;
+export declare function assertRootIdentityCurrentSync(root: RootContext, observe?: (stat: fs.BigIntStats) => void): void;
+export declare function assertRootIdentityCurrent(root: RootContext, observe?: (stat: fs.BigIntStats) => void): Promise<void>;
+/**
+ * Observe the current Root with an exact, operation-local receipt.
+ *
+ * This is deliberately separate from {@link assertRootIdentityCurrent}: callers
+ * must not retain the returned guard beyond the operation that requested it.
+ */
+export declare function createRootObservationGuard(root: RootContext): Promise<DirectoryObservationGuard | undefined>;
 export declare function resolvePathInRoot(root: RootContext, relativePath: string, options?: {
     aliasErrorCode?: "outside-workspace" | "path-alias";
     allowFinalSymlink?: boolean;
     rejectUnsafeDeviceReads?: boolean;
     rejectSymlinks?: boolean;
+    rejectFinalSymlink?: boolean;
+    resolveCanonical?: boolean;
+    rejectAmbiguousParents?: boolean;
 }): Promise<{
     rootReal: string;
     rootWithSep: string;
     resolved: string;
 }>;
-export declare function resolvePathWithinRoot(params: {
-    rootDir: string;
-    relativePath: string;
-}): Promise<{
-    rootReal: string;
-    rootWithSep: string;
-    resolved: string;
-}>;
-//# sourceMappingURL=root-context.d.ts.map

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

@@ -1,17 +1,24 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { inspectDirectoryIdentity } from "./directory-guard.js";
+import { extendDirectoryObservationGuard, inspectDirectoryIdentitySync, inspectDirectoryObservationSync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
-import { expandHomePrefix } from "./home-dir.js";
 import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
-import { outsideWorkspaceError } from "./root-errors.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { errorCauseOptions, outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
 import { isDriveRelativePath } from "./safe-path-segment.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function hasExactRootIdentity(identity) {
+    return typeof identity.dev === "bigint" && typeof identity.ino === "bigint";
+}
 export const ensureTrailingSep = (value) => value.endsWith(path.sep) ? value : value + path.sep;
 export function assertValidRootRelativePath(relativePath) {
     assertNoNulPathInput(relativePath, "relative path contains a NUL byte");
+    assertNoWindowsPathAlias(relativePath, "filesystem", "relative path uses a Windows filesystem namespace alias");
 }
 export function assertValidRootDestinationPath(relativePath) {
     assertValidRootRelativePath(relativePath);
@@ -20,30 +27,52 @@ export function assertValidRootDestinationPath(relativePath) {
     }
 }
 let cachedHomePath;
+const POSIX_PARENT_COMPONENT = /(?:^|\/)\.\.(?:\/|$)/;
+const WINDOWS_PARENT_COMPONENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
 export async function expandRelativePathWithHome(relativePath) {
+    const homeOnly = relativePath === "~";
+    const homePrefix = relativePath.startsWith("~/") || (path.sep === "\\" && relativePath.startsWith("~\\"));
+    if (!homeOnly && !homePrefix) {
+        assertNoWindowsPathAlias(relativePath, "filesystem", "relative path uses a Windows filesystem namespace alias");
+        return relativePath;
+    }
     const rawHome = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    assertNoWindowsPathAlias(rawHome, "filesystem", "home path uses a Windows filesystem namespace alias");
     if (cachedHomePath?.raw !== rawHome) {
         let realHome = rawHome;
         try {
-            realHome = fs.realpathSync.native(rawHome);
+            realHome = realpathSync.native(pathForWindowsFilesystem(rawHome));
         }
         catch {
             // If the home dir cannot be canonicalized, keep lexical expansion behavior.
         }
         cachedHomePath = { raw: rawHome, real: realHome };
     }
-    return expandHomePrefix(relativePath, { home: cachedHomePath.real });
+    if (homeOnly) {
+        assertNoWindowsPathAlias(cachedHomePath.real, "filesystem", "home path uses a Windows filesystem namespace alias");
+        return cachedHomePath.real;
+    }
+    const expanded = `${ensureTrailingSep(cachedHomePath.real)}${relativePath.slice(2)}`;
+    assertNoWindowsPathAlias(expanded, "filesystem", "expanded path uses a Windows filesystem namespace alias");
+    return expanded;
 }
 export async function resolveRootContext(rootDir) {
     assertNoNulPathInput(rootDir, "root dir contains a NUL byte");
+    assertNoWindowsPathAlias(rootDir, "filesystem", "root dir uses a Windows filesystem namespace alias");
+    const lexicalRoot = resolvePathPreservingWindowsRoot(rootDir);
+    assertNoWindowsPathAlias(lexicalRoot, "filesystem", "root dir uses a Windows filesystem namespace alias");
     let rootReal;
+    let rootStat;
     let rootIdentity;
     try {
-        rootReal = fs.realpathSync.native(rootDir);
-        const rootStat = fs.statSync(rootReal);
-        if (!rootStat.isDirectory()) {
-            throw new FsSafeError("invalid-path", "root dir is not a directory");
-        }
+        rootReal = realpathSync.native(pathForWindowsFilesystem(rootDir));
+        assertNoWindowsPathAlias(rootReal, "filesystem", "canonical root path uses a Windows filesystem namespace alias");
+        rootStat = await inspectFileIdentity(() => {
+            const stat = fs.statSync(rootReal, { bigint: true });
+            if (!stat.isDirectory())
+                throw new FsSafeError("invalid-path", "root dir is not a directory");
+            return stat;
+        });
         rootIdentity = { dev: rootStat.dev, ino: rootStat.ino };
     }
     catch (err) {
@@ -56,7 +85,8 @@ export async function resolveRootContext(rootDir) {
         throw err;
     }
     return {
-        rootDir: path.resolve(rootDir),
+        rootDir: lexicalRoot,
+        rootGuard: { dir: rootReal, realPath: rootReal, stat: rootStat },
         rootIdentity,
         rootReal,
         rootWithSep: ensureTrailingSep(rootReal),
@@ -64,44 +94,83 @@ export async function resolveRootContext(rootDir) {
 }
 export function rootRelativeReadPath(root, filePath) {
     const absoluteInput = path.isAbsolute(filePath);
-    const candidatePath = absoluteInput
-        ? path.resolve(filePath)
-        : path.resolve(root.rootDir, filePath);
-    let relativeBase = root.rootDir;
-    if (absoluteInput &&
-        !isPathInside(root.rootDir, candidatePath) &&
-        isPathInside(root.rootReal, candidatePath)) {
-        // A Root created through an alias has two valid in-root absolute spellings.
-        relativeBase = root.rootReal;
-    }
-    return path.relative(relativeBase, candidatePath);
+    if (!absoluteInput)
+        return filePath;
+    const raw = process.platform === "win32" ? filePath.replaceAll("/", path.sep) : filePath;
+    const bases = root.rootDir === root.rootReal ? [root.rootReal] : [root.rootDir, root.rootReal];
+    for (const base of bases) {
+        if (process.platform === "win32") {
+            const admitted = admitPathInsideRoot({
+                rootPath: base,
+                candidatePath: raw,
+                rootIdentity: root.rootIdentity,
+                resolveCandidateRoot: base === root.rootDir && root.rootDir !== root.rootReal,
+            });
+            if (admitted)
+                return admitted.relativePath;
+            continue;
+        }
+        const prefix = ensureTrailingSep(base);
+        const matches = raw.startsWith(prefix);
+        if (matches) {
+            let start = prefix.length;
+            while (raw[start] === path.sep)
+                start += 1;
+            return raw.slice(start);
+        }
+    }
+    return raw;
 }
-export async function assertRootIdentityCurrent(root) {
+export function assertRootIdentityCurrentSync(root, observe) {
     let current;
     try {
         if (typeof root.rootIdentity.dev === "bigint" && typeof root.rootIdentity.ino === "bigint") {
-            await inspectDirectoryIdentity(root.rootReal, { dev: root.rootIdentity.dev, ino: root.rootIdentity.ino });
+            const stat = inspectDirectoryIdentitySync(root.rootReal, { dev: root.rootIdentity.dev, ino: root.rootIdentity.ino });
+            observe?.(stat);
             return;
         }
         current = fs.lstatSync(root.rootReal);
     }
     catch (error) {
-        throw new FsSafeError("path-mismatch", "root path changed during operation", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
     }
     if (current.isSymbolicLink() ||
         !current.isDirectory() ||
         !sameFileIdentity(current, root.rootIdentity)) {
-        throw new FsSafeError("path-mismatch", "root path changed during operation");
+        throw rootPathChangedError();
+    }
+}
+export async function assertRootIdentityCurrent(root, observe) {
+    assertRootIdentityCurrentSync(root, observe);
+}
+/**
+ * Observe the current Root with an exact, operation-local receipt.
+ *
+ * This is deliberately separate from {@link assertRootIdentityCurrent}: callers
+ * must not retain the returned guard beyond the operation that requested it.
+ */
+export async function createRootObservationGuard(root) {
+    const rootIdentity = root.rootIdentity;
+    if (!hasExactRootIdentity(rootIdentity)) {
+        await assertRootIdentityCurrent(root);
+        return undefined;
+    }
+    try {
+        const observed = await inspectDirectoryObservationSync(root.rootReal, rootIdentity);
+        return extendDirectoryObservationGuard(observed, root.rootReal, root.rootReal);
+    }
+    catch (error) {
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
     }
 }
 export async function resolvePathInRoot(root, relativePath, options) {
     assertValidRootRelativePath(relativePath);
     await assertRootIdentityCurrent(root);
     const expanded = await expandRelativePathWithHome(relativePath);
-    const resolved = path.resolve(root.rootWithSep, expanded);
-    if (!isPathInside(root.rootWithSep, resolved)) {
+    assertNoWindowsPathAlias(expanded, "filesystem", "expanded path uses a Windows filesystem namespace alias");
+    let resolved = resolvePathFromBasePreservingWindowsRoot(root.rootWithSep, expanded);
+    assertNoWindowsPathAlias(resolved, "filesystem", "resolved path uses a Windows filesystem namespace alias");
+    if (!options?.resolveCanonical && !isPathInside(root.rootWithSep, resolved)) {
         throw outsideWorkspaceError();
     }
     if (options?.rejectUnsafeDeviceReads === true) {
@@ -110,32 +179,54 @@ export async function resolvePathInRoot(root, relativePath, options) {
     const rawAbsolutePath = path.isAbsolute(expanded)
         ? expanded
         : `${root.rootWithSep}${expanded}`;
+    assertNoWindowsPathAlias(rawAbsolutePath, "filesystem", "resolved path uses a Windows filesystem namespace alias");
     try {
-        await resolveRootPath({
+        const resolution = {
             absolutePath: rawAbsolutePath,
             rootPath: root.rootReal,
             rootCanonicalPath: root.rootReal,
+            rootIdentity: root.rootIdentity,
             boundaryLabel: "root",
             policy: options?.allowFinalSymlink ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
             rejectSymlinks: options?.rejectSymlinks,
-        });
+            rejectFinalSymlink: options?.rejectFinalSymlink,
+        };
+        const checked = await resolveRootPath(resolution);
+        const parentComponent = process.platform === "win32" ? WINDOWS_PARENT_COMPONENT : POSIX_PARENT_COMPONENT;
+        if (options?.rejectAmbiguousParents && parentComponent.test(expanded) &&
+            path.relative(checked.canonicalPath, resolved) !== "") {
+            const normalized = await resolveRootPath({ ...resolution, absolutePath: resolved });
+            if (path.relative(checked.canonicalPath, normalized.canonicalPath) !== "") {
+                throw new FsSafeError("path-alias", "parent traversal resolves differently through a symlink");
+            }
+        }
+        if (options?.resolveCanonical) {
+            resolved = checked.canonicalPath;
+        }
+        else {
+            // resolveRootPath preserves ordinary caller spelling as part of its
+            // public receipt. Re-admit the exact normalized spelling before it is
+            // reused for Root I/O: on a case-sensitive Windows directory it may
+            // otherwise name a distinct case-folded sibling after raw traversal.
+            const admitted = admitPathInsideRoot({
+                rootPath: root.rootReal,
+                candidatePath: checked.absolutePath,
+                rootIdentity: root.rootIdentity,
+            });
+            if (!admitted)
+                throw outsideWorkspaceError();
+            resolved = admitted.path;
+        }
     }
     catch (error) {
         if (error instanceof FsSafeError && error.code === "symlink") {
             throw error;
         }
         if (hasNodeErrorCode(error, "ENAMETOOLONG")) {
-            throw new FsSafeError("invalid-path", "relative path is too long", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("invalid-path", "relative path is too long", errorCauseOptions(error));
         }
         const code = options?.aliasErrorCode ?? "outside-workspace";
-        throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", errorCauseOptions(error));
     }
     return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
 }
-export async function resolvePathWithinRoot(params) {
-    return await resolvePathInRoot(await resolveRootContext(params.rootDir), params.relativePath);
-}

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

@@ -0,0 +1,16 @@
+import type { PinnedWriteInput } from "./pinned-write-types.js";
+import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
+declare const exclusiveSidecarCreate: unique symbol;
+export declare const sidecarExclusiveCreate: Readonly<{
+    [exclusiveSidecarCreate]: true;
+}>;
+export type RootWriteParams = RootWriteOptions & RootCreateOptions & RootCreateStreamOptions & {
+    relativePath: string;
+    data: string | Buffer | AsyncIterable<Uint8Array>;
+    strictFileSync?: boolean;
+    [exclusiveSidecarCreate]?: true;
+};
+export declare function rethrowCreateInputError(error: unknown): never;
+export declare function createInputOptions(data: RootWriteParams["data"], options: RootCreateOptions & RootCreateStreamOptions, defaultMaxBytes?: number): RootCreateOptions & RootCreateStreamOptions;
+export declare function rootWriteInput(params: RootWriteParams): PinnedWriteInput;
+export {};

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

@@ -0,0 +1,93 @@
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { MutationAuthorityError } from "./mutation-authority.js";
+// Lock records need exclusive creation, not private-before-visible publication.
+// Keep this composition hook off the public Root options and package exports.
+const exclusiveSidecarCreate = Symbol("exclusiveSidecarCreate");
+export const sidecarExclusiveCreate = Object.freeze({ [exclusiveSidecarCreate]: true });
+class CreateInputError extends FsSafeError {
+    rejection;
+    constructor(rejection) {
+        super("helper-failed", "create input failed", { cause: rejection });
+        this.rejection = rejection;
+    }
+}
+export function rethrowCreateInputError(error) {
+    if (error instanceof CreateInputError)
+        throw error.rejection;
+    throw error;
+}
+export function createInputOptions(data, options, defaultMaxBytes) {
+    if (typeof data === "string" || Buffer.isBuffer(data))
+        return options;
+    const { signal } = options;
+    signal?.throwIfAborted();
+    if (options.encoding !== undefined || options.renameIdentity !== undefined) {
+        throw new TypeError("streamed create does not accept encoding or renameIdentity");
+    }
+    const maxBytes = normalizeMaxBytes(options.maxBytes, { defaultValue: defaultMaxBytes });
+    const { assertBeforeMutation } = options;
+    return {
+        ...options,
+        maxBytes,
+        signal,
+        assertBeforeMutation: () => {
+            signal?.throwIfAborted();
+            return assertBeforeMutation == null ? undefined : Reflect.apply(assertBeforeMutation, options, []);
+        },
+    };
+}
+export function rootWriteInput(params) {
+    if (params.atomic !== undefined && typeof params.atomic !== "boolean") {
+        throw new TypeError("atomic must be a boolean");
+    }
+    const data = params.data;
+    if (typeof data === "string" || Buffer.isBuffer(data)) {
+        return {
+            kind: "buffer", data, encoding: params.encoding,
+            stageBeforePublish: params[exclusiveSidecarCreate] ? false : params.atomic === true ? true : undefined,
+        };
+    }
+    return {
+        kind: "stream",
+        stageBeforePublish: true,
+        stream: (async function* () {
+            let iterator;
+            let completed = false;
+            try {
+                params.signal?.throwIfAborted();
+                iterator = data[Symbol.asyncIterator]();
+                while (true) {
+                    if (params.signal?.aborted)
+                        throw new MutationAuthorityError(params.signal.reason);
+                    const next = await iterator.next();
+                    completed = next.done === true;
+                    if (params.signal?.aborted)
+                        throw new MutationAuthorityError(params.signal.reason);
+                    if (completed)
+                        return;
+                    const chunk = next.value;
+                    if (!(chunk instanceof Uint8Array)) {
+                        throw new TypeError("streamed create chunks must be Uint8Array values");
+                    }
+                    yield chunk;
+                }
+            }
+            catch (error) {
+                if (error instanceof MutationAuthorityError)
+                    throw error;
+                throw new CreateInputError(error);
+            }
+            finally {
+                if (iterator && !completed) {
+                    try {
+                        await iterator.return?.();
+                    }
+                    catch (error) {
+                        throw new CreateInputError(error);
+                    }
+                }
+            }
+        })(),
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { PinnedWriteMutationAdmission } from "./pinned-write-types.js";
+import { type RootContext } from "./root-context.js";
+/**
+ * Complete the common Root.mkdir case with one exact existing parent. This is
+ * optional evidence: every uncertain probe returns to the ordered root walk.
+ */
+export declare function tryMkdirAtExactParent(root: RootContext, targetPath: string, mutationAdmission: PinnedWriteMutationAdmission): Promise<boolean>;
+export declare function prepareRootWriteTarget(root: RootContext, targetPath: string, assertBeforeMutation?: () => void, mutationAdmission?: PinnedWriteMutationAdmission, privateMode?: boolean): Promise<string>;
+export declare function mkdirPathFallback(root: RootContext, resolved: {
+    rootReal: string;
+    resolved: string;
+}, assertBeforeMutation?: () => void, rejectSymlinks?: boolean, mutationAdmission?: PinnedWriteMutationAdmission, privateMode?: boolean): Promise<void>;

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

@@ -0,0 +1,225 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertPrivateDirectory } from "./creation-boundary.js";
+import { assertAsyncDirectoryGuard, assertDirectoryIdentitySync, assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
+import { hasNodeErrorCode } from "./path.js";
+import { checkedMutationDirectory, } from "./pinned-mutation-observation.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
+import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
+import { canReuseParentWithMutationAssertion } from "./root-write-lock-binding.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function mutationWalkOptions(mutationAdmission, operationTarget, assertBeforeMutation, rootPath, targetPath) {
+    const session = canReuseParentWithMutationAssertion(assertBeforeMutation, rootPath, targetPath)
+        ? mutationAdmission.beginSharedParentWalk?.()
+        : undefined;
+    return {
+        dispose: () => session?.dispose(),
+        options: {
+            rejectSymlinks: mutationAdmission.rejectParentSymlinks,
+            revalidateParentAfterBeforeComponent: true,
+            retainedTargetPath: session?.retainedTargetPath,
+            synchronousAuthorizationIncludesFence: session !== undefined,
+            afterCreateComponent: session?.advanceCreatedDirectory,
+            beforeCreateComponent: (componentPath, prospectiveDirectory, retainedTargetPath, parent) => {
+                const targetPath = retainedTargetPath ?? operationTarget(prospectiveDirectory);
+                const request = Object.freeze({
+                    targetPath,
+                    mutationPath: componentPath,
+                    phase: "parent-create",
+                });
+                return session?.tryAuthorizeAtParent(request, parent) ??
+                    (session?.authorize(request) ?? mutationAdmission.authorize(request));
+            },
+            beforeUseComponent: async (_componentPath, prospectiveDirectory, retainedTargetPath) => {
+                const targetPath = retainedTargetPath ?? operationTarget(prospectiveDirectory);
+                const request = Object.freeze({
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                });
+                await (session?.authorize(request) ?? mutationAdmission.authorize(request));
+            },
+        },
+    };
+}
+/**
+ * Complete the common Root.mkdir case with one exact existing parent. This is
+ * optional evidence: every uncertain probe returns to the ordered root walk.
+ */
+export async function tryMkdirAtExactParent(root, targetPath, mutationAdmission) {
+    if (getFsSafeTestHooks()?.beforeRootFallbackMutation)
+        return false;
+    if (typeof root.rootIdentity.dev !== "bigint" ||
+        typeof root.rootIdentity.ino !== "bigint" ||
+        root.rootIdentity.dev === 0n || root.rootIdentity.ino === 0n)
+        return false;
+    const rootIdentity = Object.freeze({
+        dev: root.rootIdentity.dev,
+        ino: root.rootIdentity.ino,
+    });
+    const session = mutationAdmission.beginSharedParentWalk?.();
+    if (!session)
+        return false;
+    try {
+        if (path.resolve(session.retainedTargetPath) !== path.resolve(targetPath))
+            return false;
+        const parentPath = path.dirname(targetPath);
+        let parentGuard;
+        try {
+            parentGuard = await createAsyncDirectoryGuard(parentPath, { bigint: true });
+        }
+        catch {
+            return false;
+        }
+        try {
+            fsSync.lstatSync(targetPath, { bigint: true });
+            return false;
+        }
+        catch (error) {
+            if (!hasNodeErrorCode(error, "ENOENT"))
+                return false;
+        }
+        const admittedParent = admitPathInsideRoot({
+            rootPath: root.rootReal,
+            candidatePath: parentPath,
+            rootIdentity,
+        });
+        if (admittedParent?.admission !== "exact" || admittedParent.path !== parentPath ||
+            parentGuard.realPath !== parentPath)
+            return false;
+        await session.authorize(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent",
+        }));
+        await assertAsyncDirectoryGuard(parentGuard);
+        try {
+            fsSync.lstatSync(targetPath, { bigint: true });
+            return false;
+        }
+        catch (error) {
+            if (!hasNodeErrorCode(error, "ENOENT"))
+                return false;
+        }
+        assertSyncDirectoryGuard(parentGuard);
+        const createAdmission = session.tryAuthorizeAtParent(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent-create",
+        }), checkedMutationDirectory(parentPath, parentGuard.realPath, parentGuard.stat));
+        if (!createAdmission)
+            return false;
+        try {
+            await fs.mkdir(targetPath);
+        }
+        catch (error) {
+            if (hasNodeErrorCode(error, "EEXIST"))
+                return false;
+            throw error;
+        }
+        const observeCreated = async () => {
+            const childGuard = await createAsyncDirectoryGuard(targetPath, { bigint: true });
+            const parentAfter = inspectDirectoryIdentitySync(parentPath, parentGuard.stat);
+            assertDirectoryIdentitySync(root.rootReal, rootIdentity);
+            const admittedChild = admitPathInsideRoot({
+                rootPath: root.rootReal,
+                candidatePath: childGuard.realPath,
+                rootIdentity,
+            });
+            if (childGuard.realPath !== targetPath || childGuard.dir !== targetPath ||
+                admittedChild?.admission !== "exact" || admittedChild.path !== targetPath) {
+                throw new FsSafeError("path-mismatch", "created directory changed during operation");
+            }
+            return { childGuard, parentAfter };
+        };
+        try {
+            const created = await observeCreated();
+            if (session.advanceCreatedDirectory(Object.freeze({
+                admission: createAdmission,
+                parent: checkedMutationDirectory(parentPath, parentGuard.realPath, created.parentAfter),
+                child: checkedMutationDirectory(targetPath, created.childGuard.realPath, created.childGuard.stat),
+            })))
+                return true;
+        }
+        catch {
+            // Post-create observations are optional receipt evidence. The directory
+            // was already created, so renew ordered admission without a second mkdir.
+        }
+        await session.authorize(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent",
+        }));
+        await assertAsyncDirectoryGuard(parentGuard);
+        assertDirectoryIdentitySync(root.rootReal, rootIdentity);
+        assertFinalSymlinkRejected(targetPath, true);
+        const refreshed = await observeCreated();
+        await assertAsyncDirectoryGuard(parentGuard);
+        await assertAsyncDirectoryGuard(refreshed.childGuard);
+        assertDirectoryIdentitySync(root.rootReal, rootIdentity);
+        return true;
+    }
+    finally {
+        session.dispose();
+    }
+}
+export async function prepareRootWriteTarget(root, targetPath, assertBeforeMutation, mutationAdmission, privateMode = false) {
+    const basename = path.basename(targetPath);
+    const baseParams = {
+        rootReal: root.rootReal,
+        rootIdentity: root.rootIdentity,
+        targetPath: path.dirname(targetPath),
+        assertBeforeMutation,
+        private: privateMode,
+        mode: privateMode ? 0o700 : undefined,
+    };
+    const mutationWalk = mutationAdmission
+        ? mutationWalkOptions(mutationAdmission, (prospectiveParent) => path.join(prospectiveParent, basename), assertBeforeMutation, root.rootReal, targetPath)
+        : undefined;
+    let parentPath;
+    try {
+        parentPath = await mkdirPathComponentsWithGuards(mutationWalk ? {
+            ...baseParams,
+            ...mutationWalk.options,
+        } : baseParams);
+    }
+    finally {
+        mutationWalk?.dispose();
+    }
+    // Continue through the guarded walk's real parent instead of re-entering
+    // the original path through a symlinked component.
+    return path.join(parentPath, basename);
+}
+export async function mkdirPathFallback(root, resolved, assertBeforeMutation, rejectSymlinks = false, mutationAdmission, privateMode = false) {
+    const baseParams = {
+        rootReal: resolved.rootReal, targetPath: resolved.resolved, assertBeforeMutation,
+        rootIdentity: root.rootIdentity,
+        rejectSymlinks,
+        private: privateMode,
+        mode: privateMode ? 0o700 : undefined,
+        beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
+    };
+    const mutationWalk = mutationAdmission
+        ? mutationWalkOptions(mutationAdmission, (prospectiveDirectory) => prospectiveDirectory, assertBeforeMutation, root.rootReal, resolved.resolved)
+        : undefined;
+    try {
+        const directory = await mkdirPathComponentsWithGuards(mutationWalk ? {
+            ...baseParams,
+            ...mutationWalk.options,
+            rejectSymlinks: rejectSymlinks || mutationAdmission.rejectParentSymlinks,
+        } : baseParams);
+        if (privateMode) {
+            const guard = await createAsyncDirectoryGuard(directory, { bigint: true });
+            await assertPrivateDirectory(directory);
+            await assertAsyncDirectoryGuard(guard);
+            await assertRootIdentityCurrent(root);
+        }
+    }
+    finally {
+        mutationWalk?.dispose();
+    }
+}