@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -1,14 +1,23 @@
 import { FsSafeError } from "./errors.js";
 import { hasNodeErrorCode, isNodeError, isNotFoundPathError } from "./path.js";
 const REMOVE_NOT_EMPTY_CODES = new Set(["ENOTEMPTY", "EEXIST"]);
-export function fileNotFoundError(cause) {
+const PINNED_WRITE_ERRNO_MESSAGES = new Map([
+    ["EACCES", "permission denied"],
+    ["EPERM", "permission denied"],
+    ["EROFS", "read-only filesystem"],
+    ["ENOSPC", "no space left on device"],
+]);
+export function fileNotFoundError(cause, details) {
     return cause === undefined
-        ? new FsSafeError("not-found", "file not found")
-        : new FsSafeError("not-found", "file not found", { cause });
+        ? new FsSafeError("not-found", "file not found", { details })
+        : new FsSafeError("not-found", "file not found", { cause, details });
 }
 export function outsideWorkspaceError() {
     return new FsSafeError("outside-workspace", "file is outside workspace root");
 }
+export function rootPathChangedError(cause) {
+    return new FsSafeError("path-mismatch", "root path changed during operation", { cause });
+}
 export function directoryComponentNotDirectoryError(cause) {
     return cause === undefined
         ? new FsSafeError("not-file", "directory component must be a directory")
@@ -27,42 +36,46 @@ export function normalizePinnedWriteError(error) {
     if (isNotFoundPathError(error)) {
         return fileNotFoundError(error instanceof Error ? error : undefined);
     }
-    return new FsSafeError("invalid-path", "path is not a regular file under root", {
-        cause: error instanceof Error ? error : undefined,
-    });
+    const code = isNodeError(error) && typeof error.code === "string" && /^E[A-Z0-9_]+$/.test(error.code)
+        ? error.code : undefined;
+    const message = code
+        ? `${PINNED_WRITE_ERRNO_MESSAGES.get(code) ?? "filesystem write failed"} (${code})`
+        : "path is not a regular file under root";
+    return new FsSafeError("invalid-path", message, errorCauseOptions(error));
 }
-export function normalizePinnedPathError(error) {
+export function normalizePinnedPathError(error, details) {
     if (error instanceof FsSafeError) {
         return error;
     }
     return new FsSafeError("path-alias", "path is not under root", {
         cause: error instanceof Error ? error : undefined,
+        details,
     });
 }
-export function normalizeRemoveGuardError(error) {
+export function normalizeRemoveGuardError(error, details) {
     if (error instanceof FsSafeError) {
         return error;
     }
     if (isNotFoundPathError(error)) {
-        return fileNotFoundError(error instanceof Error ? error : undefined);
+        return fileNotFoundError(error instanceof Error ? error : undefined, details);
     }
-    return normalizePinnedPathError(error);
+    return normalizePinnedPathError(error, details);
 }
-export function normalizeRemovePathError(error) {
+export function normalizeRemovePathError(error, details) {
     if (error instanceof FsSafeError) {
         return error;
     }
     if (!isNodeError(error) || typeof error.code !== "string") {
-        return normalizePinnedPathError(error);
+        return normalizePinnedPathError(error, details);
     }
     const cause = error instanceof Error ? error : undefined;
     if (isNotFoundPathError(error)) {
-        return fileNotFoundError(cause);
+        return fileNotFoundError(cause, details);
     }
     if (REMOVE_NOT_EMPTY_CODES.has(error.code)) {
-        return new FsSafeError("not-empty", "directory is not empty", { cause });
+        return new FsSafeError("not-empty", "directory is not empty", { cause, details });
     }
-    return new FsSafeError("not-removable", "path could not be removed", { cause });
+    return new FsSafeError("not-removable", "path could not be removed", { cause, details });
 }
 export function throwFsSafeReadError(error, label) {
     if (error instanceof FsSafeError) {
@@ -73,3 +86,7 @@ export function throwFsSafeReadError(error, label) {
     }
     throw error;
 }
+/** Existing boundaries retain only Error instances as their cause. */
+export function errorCauseOptions(error) {
+    return { cause: error instanceof Error ? error : undefined };
+}

package/node_modules/@openclaw/fs-safe/dist/root-file-final-admission.d.ts

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import type { PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
+export type RootFileAdmissionFs = Pick<typeof fs, "lstatSync" | "realpathSync">;
+type ExactIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type CanonicalRootObservation = {
+    ok: true;
+    path: string;
+    identity: ExactIdentity;
+} | {
+    ok: false;
+    error: unknown;
+};
+export declare function observeCanonicalRoot(ioFs: RootFileAdmissionFs, rootPath: string): CanonicalRootObservation;
+export declare function createRootFileFinalAdmission(ioFs: RootFileAdmissionFs, root: Extract<CanonicalRootObservation, {
+    ok: true;
+}>, boundaryLabel: string, rejectHardlinks?: boolean): PinnedOpenSyncFinalAdmission;
+export {};

package/node_modules/@openclaw/fs-safe/dist/root-file-final-admission.js

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { hardlinkedPathNotAllowedError } from "./root-errors.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
+function rootIdentityMismatch(cause) {
+    return new FsSafeError("path-mismatch", "canonical root directory identity changed or could not be verified", cause === undefined ? {} : { cause });
+}
+function isExpectedPathError(error) {
+    const code = typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : "";
+    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
+}
+function inspectCanonicalRoot(ioFs, rootPath, expected) {
+    try {
+        assertNoWindowsPathAlias(rootPath);
+        const operationPath = ioFs === fs ? pathForWindowsFilesystem(rootPath) : rootPath;
+        return inspectFileIdentitySync(() => {
+            const stat = ioFs.lstatSync(operationPath, { bigint: true });
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw rootIdentityMismatch();
+            return stat;
+        }, expected);
+    }
+    catch (error) {
+        if (expected && isExpectedPathError(error))
+            throw rootIdentityMismatch(error);
+        throw error;
+    }
+}
+export function observeCanonicalRoot(ioFs, rootPath) {
+    try {
+        const stat = inspectCanonicalRoot(ioFs, rootPath);
+        const identity = Object.freeze({ dev: stat.dev, ino: stat.ino });
+        let observedPath = rootPath;
+        if (process.platform === "win32" && ioFs === fs) {
+            // Native leaf resolution expands Windows short names. Bind that root
+            // spelling before traversal without replacing the observed identity.
+            observedPath = realpathSync.native(pathForWindowsFilesystem(rootPath));
+            if (observedPath !== rootPath)
+                inspectCanonicalRoot(ioFs, observedPath, identity);
+        }
+        return { ok: true, path: observedPath, identity };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+function resolveConsumedPath(ioFs, filePath) {
+    return ioFs === fs ? realpathSync.native(filePath) : ioFs.realpathSync(filePath);
+}
+export function createRootFileFinalAdmission(ioFs, root, boundaryLabel, rejectHardlinks = true) {
+    const inspectRoot = (candidateRootPath, expected) => {
+        inspectCanonicalRoot(ioFs, candidateRootPath, expected);
+    };
+    return ({ path: consumedPath, descriptorIdentity }) => {
+        inspectCanonicalRoot(ioFs, root.path, root.identity);
+        const canonicalPath = resolveConsumedPath(ioFs, consumedPath);
+        assertNoWindowsPathAlias(canonicalPath, "filesystem", "resolved file path uses a Windows filesystem namespace alias");
+        const admitted = admitPathInsideRoot({
+            rootPath: root.path,
+            candidatePath: canonicalPath,
+            rootIdentity: root.identity,
+            inspectCandidateRoot: inspectRoot,
+        });
+        if (!admitted) {
+            throw new FsSafeError("outside-workspace", `resolved path escapes ${boundaryLabel}`);
+        }
+        try {
+            const current = inspectFileIdentitySync(() => ioFs.lstatSync(admitted.path, { bigint: true }), descriptorIdentity);
+            if (rejectHardlinks && current.isFile() && current.nlink > 1n)
+                throw hardlinkedPathNotAllowedError();
+        }
+        catch (error) {
+            if (isExpectedPathError(error)) {
+                throw new FsSafeError("path-mismatch", "canonical file identity changed or could not be verified", { cause: error });
+            }
+            throw error;
+        }
+        inspectCanonicalRoot(ioFs, root.path, root.identity);
+        return admitted.path;
+    };
+}

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

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import type { PathAliasPolicy } from "./path-policy.js";
+import { type SymlinkPolicy } from "./root-symlink-policy.js";
 import { type PinnedOpenSyncAllowedType, type PinnedOpenSyncFailureReason } from "./pinned-open.js";
 type BoundaryReadFs = Pick<typeof fs, "closeSync" | "constants" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "realpathSync">;
 export type RootFileOpenFailureReason = PinnedOpenSyncFailureReason | "validation";
@@ -25,6 +26,7 @@ export type OpenRootFileSyncParams = {
     maxBytes?: number;
     rejectHardlinks?: boolean;
     rejectSymlinks?: boolean;
+    symlinks?: SymlinkPolicy;
     allowedType?: PinnedOpenSyncAllowedType;
     skipLexicalRootCheck?: boolean;
     ioFs?: BoundaryReadFs;
@@ -42,4 +44,3 @@ export declare function matchRootFileOpenFailure<T>(failure: RootFileOpenFailure
 }): T;
 export declare function openRootFile(params: OpenRootFileParams): Promise<RootFileOpenResult>;
 export {};
-//# sourceMappingURL=root-file.d.ts.map

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

@@ -1,7 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
-import { resolveRootPath, resolveRootPathSync, } from "./root-path.js";
+import { resolveRootPathSyncWithCanonicalRootObservation, resolveRootPathWithCanonicalRootObservation, } from "./root-path.js";
+import { readSymlinkResolution } from "./root-symlink-policy.js";
 import { openPinnedFileSync, } from "./pinned-open.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { FsSafeError } from "./errors.js";
+import { createRootFileFinalAdmission, observeCanonicalRoot, } from "./root-file-final-admission.js";
 export function canUseRootFileOpen(ioFs) {
     return (typeof ioFs.openSync === "function" &&
         typeof ioFs.closeSync === "function" &&
@@ -12,19 +16,36 @@ export function canUseRootFileOpen(ioFs) {
         typeof ioFs.constants === "object" &&
         ioFs.constants !== null);
 }
+function absoluteRootFilePath(filePath) {
+    if (path.isAbsolute(filePath))
+        return filePath;
+    const drive = path.parse(filePath).root;
+    const base = drive ? path.resolve(drive) : process.cwd();
+    return `${base}${path.sep}${filePath.slice(drive.length)}`;
+}
 export function openRootFileSync(params) {
     const ioFs = params.ioFs ?? fs;
-    const absolutePath = path.resolve(params.absolutePath);
+    const rawAbsolutePath = params.absolutePath;
     let resolved;
     try {
-        resolved = mapResolvedRootPath(absolutePath, resolveRootPathSync({
+        const absolutePath = absoluteRootFilePath(rawAbsolutePath);
+        assertNoWindowsPathAlias(absolutePath);
+        const rootPath = params.rootPath;
+        const rootRealPath = params.rootRealPath;
+        const boundaryLabel = params.boundaryLabel;
+        let rootObservation;
+        const resolvedPath = resolveRootPathSyncWithCanonicalRootObservation({
             absolutePath,
-            rootPath: params.rootPath,
-            rootCanonicalPath: params.rootRealPath,
-            boundaryLabel: params.boundaryLabel,
-            rejectSymlinks: params.rejectSymlinks ?? true,
+            rootPath,
+            rootCanonicalPath: rootRealPath,
+            boundaryLabel,
+            ...readSymlinkResolution(params.symlinks ??
+                (params.rejectSymlinks === false ? "follow-within-root" : "reject")),
             skipLexicalRootCheck: params.skipLexicalRootCheck,
-        }));
+        }, rootCanonicalPath => {
+            rootObservation = observeCanonicalRoot(ioFs, rootCanonicalPath);
+        });
+        resolved = mapResolvedRootPath(absolutePath, boundaryLabel, resolvedPath, rootObservation);
     }
     catch (error) {
         resolved = toBoundaryValidationError(error);
@@ -49,13 +70,15 @@ export function matchRootFileOpenFailure(failure, handlers) {
     return handlers.fallback(failure);
 }
 function openRootFileResolved(params) {
+    const rejectHardlinks = params.rejectHardlinks ?? true;
     const opened = openPinnedFileSync({
         filePath: params.absolutePath,
         resolvedPath: params.resolvedPath,
-        rejectHardlinks: params.rejectHardlinks ?? true,
+        rejectHardlinks,
         maxBytes: params.maxBytes,
         allowedType: params.allowedType,
         ioFs: params.ioFs,
+        finalAdmission: createRootFileFinalAdmission(params.ioFs, params.rootObservation, params.boundaryLabel, rejectHardlinks),
     });
     if (!opened.ok) {
         return opened;
@@ -76,6 +99,8 @@ function finalizeRootFileOpen(params) {
         absolutePath: params.resolved.absolutePath,
         resolvedPath: params.resolved.resolvedPath,
         rootRealPath: params.resolved.rootRealPath,
+        boundaryLabel: params.resolved.boundaryLabel,
+        rootObservation: params.resolved.rootObservation,
         maxBytes: params.maxBytes,
         rejectHardlinks: params.rejectHardlinks,
         allowedType: params.allowedType,
@@ -84,37 +109,100 @@ function finalizeRootFileOpen(params) {
 }
 export async function openRootFile(params) {
     const ioFs = params.ioFs ?? fs;
-    const absolutePath = path.resolve(params.absolutePath);
-    let resolved;
+    const rawAbsolutePath = params.absolutePath;
+    let resolutionSnapshot;
     try {
-        resolved = mapResolvedRootPath(absolutePath, await resolveRootPath({
-            absolutePath,
-            rootPath: params.rootPath,
-            rootCanonicalPath: params.rootRealPath,
-            boundaryLabel: params.boundaryLabel,
-            policy: params.aliasPolicy,
-            rejectSymlinks: params.rejectSymlinks ?? true,
-            skipLexicalRootCheck: params.skipLexicalRootCheck,
-        }));
+        const absolutePath = absoluteRootFilePath(rawAbsolutePath);
+        assertNoWindowsPathAlias(absolutePath);
+        resolutionSnapshot = snapshotAsyncResolution(params, absolutePath);
     }
     catch (error) {
-        resolved = toBoundaryValidationError(error);
+        resolutionSnapshot = toBoundaryValidationError(error);
     }
-    return finalizeRootFileOpen({
-        resolved,
+    const openSnapshot = {
         maxBytes: params.maxBytes,
         rejectHardlinks: params.rejectHardlinks,
         allowedType: params.allowedType,
+    };
+    let resolved;
+    if ("ok" in resolutionSnapshot) {
+        resolved = resolutionSnapshot;
+    }
+    else {
+        try {
+            let rootObservation;
+            const resolvedPath = await resolveRootPathWithCanonicalRootObservation({
+                absolutePath: resolutionSnapshot.absolutePath,
+                rootPath: resolutionSnapshot.rootPath,
+                rootCanonicalPath: resolutionSnapshot.rootRealPath,
+                boundaryLabel: resolutionSnapshot.boundaryLabel,
+                policy: resolutionSnapshot.aliasPolicy,
+                rejectSymlinks: resolutionSnapshot.rejectSymlinks,
+                rejectFinalSymlink: resolutionSnapshot.rejectFinalSymlink,
+                skipLexicalRootCheck: resolutionSnapshot.skipLexicalRootCheck,
+            }, rootCanonicalPath => {
+                rootObservation = observeCanonicalRoot(ioFs, rootCanonicalPath);
+            });
+            resolved = mapResolvedRootPath(resolutionSnapshot.absolutePath, resolutionSnapshot.boundaryLabel, resolvedPath, rootObservation);
+        }
+        catch (error) {
+            resolved = toBoundaryValidationError(error);
+        }
+    }
+    return finalizeRootFileOpen({
+        resolved,
+        maxBytes: openSnapshot.maxBytes,
+        rejectHardlinks: openSnapshot.rejectHardlinks,
+        allowedType: openSnapshot.allowedType,
         ioFs,
     });
 }
 function toBoundaryValidationError(error) {
     return { ok: false, reason: "validation", error };
 }
-function mapResolvedRootPath(absolutePath, resolved) {
+function mapResolvedRootPath(absolutePath, boundaryLabel, resolved, rootObservation) {
+    if (!rootObservation) {
+        return toBoundaryValidationError(new FsSafeError("path-mismatch", "canonical root identity was not observed"));
+    }
+    if (!rootObservation.ok) {
+        return toRootObservationError(rootObservation.error);
+    }
     return {
         absolutePath,
         resolvedPath: resolved.canonicalPath,
-        rootRealPath: resolved.rootCanonicalPath,
+        rootRealPath: rootObservation.path,
+        boundaryLabel,
+        rootObservation,
+    };
+}
+function snapshotAsyncResolution(params, absolutePath) {
+    const rootPath = params.rootPath;
+    const rootRealPath = params.rootRealPath;
+    const boundaryLabel = params.boundaryLabel;
+    const sourceAliasPolicy = params.aliasPolicy;
+    const aliasPolicy = sourceAliasPolicy == null ? undefined : {
+        allowFinalSymlinkForUnlink: sourceAliasPolicy.allowFinalSymlinkForUnlink,
+        allowFinalHardlinkForUnlink: sourceAliasPolicy.allowFinalHardlinkForUnlink,
     };
+    const symlinkResolution = readSymlinkResolution(params.symlinks ?? (params.rejectSymlinks === false ? "follow-within-root" : "reject"));
+    return {
+        absolutePath,
+        rootPath,
+        rootRealPath,
+        boundaryLabel,
+        aliasPolicy,
+        ...symlinkResolution,
+        skipLexicalRootCheck: params.skipLexicalRootCheck,
+    };
+}
+function toRootObservationError(error) {
+    if (error instanceof FsSafeError)
+        return toBoundaryValidationError(error);
+    const code = typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : "";
+    if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP") {
+        return { ok: false, reason: "path", error };
+    }
+    return { ok: false, reason: "io", error };
 }

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

@@ -1,16 +1,14 @@
-import type { Stats } from "node:fs";
+import type { BigIntStats, Stats } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
 import type { ContainmentGuarantee } from "./containment.js";
-import { type DenyMutationPolicy } from "./deny-mutations.js";
-import { type RenameIdentityPolicy } from "./pinned-write.js";
 import { type ReadResult } from "./read-opened-file.js";
+import { type RootEntriesOptions } from "./root-entries.js";
 import { type RootContext } from "./root-context.js";
 import type { DirEntry, PathStat } from "./types.js";
 import { type RootWalkEntry, type RootWalkOptions } from "./root-walk.js";
-export type { DenyMutationPolicy } from "./deny-mutations.js";
-export type { RenameIdentityPolicy } from "./pinned-write.js";
+import { type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions } from "./root-options.js";
+export { DEFAULT_ROOT_MAX_BYTES } from "./root-options.js";
 export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
-export type { ReadResult } from "./read-opened-file.js";
 export type OpenResult = {
     handle: FileHandle;
     containment: ContainmentGuarantee;
@@ -18,52 +16,6 @@ export type OpenResult = {
     stat: Stats;
     [Symbol.asyncDispose](): Promise<void>;
 };
-export type RootOptions = {
-    rootDir: string;
-    defaults?: RootDefaults;
-};
-export type SymlinkPolicy = "reject" | "follow-within-root";
-export type HardlinkPolicy = "reject" | "allow";
-export type WritableOpenMode = "replace" | "append" | "update";
-export type RootDefaults = {
-    durable?: boolean;
-    hardlinks?: HardlinkPolicy;
-    maxBytes?: number;
-    mkdir?: boolean;
-    mode?: number;
-    denyMutations?: DenyMutationPolicy;
-    nonBlockingRead?: boolean;
-    renameIdentity?: RenameIdentityPolicy;
-    symlinks?: SymlinkPolicy;
-};
-export type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
-export type RootOpenOptions = Omit<RootReadOptions, "maxBytes">;
-export type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity"> & {
-    encoding?: BufferEncoding;
-    overwrite?: boolean;
-};
-export type RootOpenWritableOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode"> & {
-    writeMode?: WritableOpenMode;
-};
-export type RootCopyOptions = Pick<RootDefaults, "denyMutations" | "maxBytes" | "mkdir" | "mode"> & {
-    sourceHardlinks?: HardlinkPolicy;
-};
-export type RootWriteJsonOptions = RootWriteOptions & {
-    replacer?: Parameters<typeof JSON.stringify>[1];
-    space?: Parameters<typeof JSON.stringify>[2];
-    trailingNewline?: boolean;
-};
-export type RootCreateOptions = Omit<RootWriteOptions, "overwrite">;
-export type RootCreateJsonOptions = Omit<RootWriteJsonOptions, "overwrite">;
-export type RootAppendOptions = RootWriteOptions & {
-    prependNewlineIfNeeded?: boolean;
-};
-export type RootMoveOptions = Pick<RootDefaults, "denyMutations"> & {
-    overwrite?: boolean;
-};
-export type RootRemoveOptions = Pick<RootDefaults, "denyMutations">;
-export type RootMkdirOptions = Pick<RootDefaults, "denyMutations">;
-export declare const DEFAULT_ROOT_MAX_BYTES: number;
 export interface Root {
     readonly rootDir: string;
     readonly rootReal: string;
@@ -88,9 +40,10 @@ export interface Root {
     ensureRoot(options?: RootMkdirOptions): Promise<void>;
     write(relativePath: string, data: string | Buffer, options?: RootWriteOptions): Promise<void>;
     create(relativePath: string, data: string | Buffer, options?: RootCreateOptions): Promise<void>;
+    create(relativePath: string, data: AsyncIterable<Uint8Array>, options?: RootCreateStreamOptions): Promise<void>;
     writeJson(relativePath: string, data: unknown, options?: RootWriteJsonOptions): Promise<void>;
     createJson(relativePath: string, data: unknown, options?: RootCreateJsonOptions): Promise<void>;
-    copyIn(relativePath: string, sourcePath: string, options?: RootCopyOptions): Promise<void>;
+    copyIn(relativePath: string, source: RootCopySource, options?: RootCopyOptions): Promise<void>;
     exists(relativePath: string): Promise<boolean>;
     stat(relativePath: string): Promise<PathStat>;
     list(relativePath: string, options?: {
@@ -99,17 +52,17 @@ export interface Root {
     list(relativePath: string, options: {
         withFileTypes: true;
     }): Promise<DirEntry[]>;
+    entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
     move(fromRelative: string, toRelative: string, options?: RootMoveOptions): Promise<void>;
     walk(relativePath: string, options: RootWalkOptions): AsyncIterableIterator<RootWalkEntry>;
 }
 export declare class RootHandle implements Root {
-    private readonly rootIdentity;
+    private readonly context;
     readonly rootDir: string;
     readonly rootReal: string;
     readonly rootWithSep: string;
     readonly defaults: RootDefaults;
     constructor(context: RootContext, defaults?: RootDefaults);
-    private get context();
     private mutationOptions;
     resolve(relativePath: string): Promise<string>;
     open(relativePath: string, options?: RootOpenOptions): Promise<OpenResult>;
@@ -130,9 +83,10 @@ export declare class RootHandle implements Root {
     ensureRoot(options?: RootMkdirOptions): Promise<void>;
     write(relativePath: string, data: string | Buffer, options?: RootWriteOptions): Promise<void>;
     create(relativePath: string, data: string | Buffer, options?: RootCreateOptions): Promise<void>;
+    create(relativePath: string, data: AsyncIterable<Uint8Array>, options?: RootCreateStreamOptions): Promise<void>;
     writeJson(relativePath: string, data: unknown, options?: RootWriteJsonOptions): Promise<void>;
     createJson(relativePath: string, data: unknown, options?: RootCreateJsonOptions): Promise<void>;
-    copyIn(relativePath: string, sourcePath: string, options?: RootCopyOptions): Promise<void>;
+    copyIn(relativePath: string, source: RootCopySource, options?: RootCopyOptions): Promise<void>;
     exists(relativePath: string): Promise<boolean>;
     stat(relativePath: string): Promise<PathStat>;
     list(relativePath: string, options?: {
@@ -142,9 +96,15 @@ export declare class RootHandle implements Root {
         withFileTypes: true;
     }): Promise<DirEntry[]>;
     move(fromRelative: string, toRelative: string, options?: RootMoveOptions): Promise<void>;
+    entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
     walk(relativePath: string, options: RootWalkOptions): AsyncIterableIterator<RootWalkEntry>;
 }
 export declare function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
+export declare function rootFromDirectoryGuard(guard: {
+    readonly dir: string;
+    readonly realPath: string;
+    readonly stat: BigIntStats;
+}, defaults?: RootDefaults): Root;
 export declare function readLocalFileSafely(params: {
     filePath: string;
     maxBytes?: number;
@@ -152,12 +112,6 @@ export declare function readLocalFileSafely(params: {
 export declare function openLocalFileSafely(params: {
     filePath: string;
 }): Promise<OpenResult>;
-export type WritableOpenResult = {
-    handle: FileHandle;
-    containment: ContainmentGuarantee;
+export type WritableOpenResult = OpenResult & {
     createdForWrite: boolean;
-    realPath: string;
-    stat: Stats;
-    [Symbol.asyncDispose](): Promise<void>;
 };
-//# sourceMappingURL=root-impl.d.ts.map