@openclaw/fs-safe 0.19.0 → 0.21.0

package/dist/root-directory-list.d.ts

@@ -2,6 +2,7 @@ import type { BigIntStats, Stats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type RootContext } from "./root-context.js";
 import type { RootPathDirectoryObservationGuard, RootPathObservationReceipt, RootPathParentObservationReceipt } from "./root-path.js";
+import { type ExactStatIdentity } from "./stat-observation.js";
 import type { DirEntry, PathStat } from "./types.js";
 export declare function pathStatFromStats(stat: Stats | BigIntStats): PathStat;
 export type RootDirectoryObservationGuard = AsyncDirectoryGuard<BigIntStats>;
@@ -21,6 +22,7 @@ export type RootDirectoryListing = {
     next(): Promise<{
         kind: "entry";
         entry: DirEntry;
+        identity?: ExactStatIdentity;
     } | {
         kind: "limit";
         name: string;
@@ -33,6 +35,10 @@ export type RootDirectoryListingOptions = {
     snapshot: boolean;
     maxNames?: number;
     metadataBatchSize?: number;
+    /** Internal exact metadata lane, supported by streaming filesystem order. */
+    exactIdentity?: boolean;
+    /** Internal owner receives cleanup failures, including acquisition rollback. */
+    onCleanupFailure?: (error: unknown) => void;
     admitEntry(): boolean;
 };
-export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
+export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions, receipt?: RootPathObservationReceipt): Promise<RootDirectoryListing>;

package/dist/root-directory-list.js

@@ -11,6 +11,7 @@ import { errorCauseOptions, rootPathChangedError } from "./root-errors.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { realpathSync } from "./realpath.js";
+import { inspectStatObservationSync } from "./stat-observation.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const METADATA_BATCH_SIZE = 32;
 export function pathStatFromStats(stat) {
@@ -173,14 +174,7 @@ function normalizeInitialDirectoryError(error) {
 export async function listDirectoryPath(root, directory, withFileTypes, receipt) {
     let guard;
     if (receipt) {
-        if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
-            receipt.directoryGuard.dir !== directory ||
-            receipt.target !== receipt.directoryGuard ||
-            (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
-                !receipt.directoryGuard.stat.isDirectory())) {
-            throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
-        }
-        guard = receipt.directoryGuard;
+        guard = directoryGuardFromReceipt(directory, receipt);
     }
     else {
         try {
@@ -192,6 +186,16 @@ export async function listDirectoryPath(root, directory, withFileTypes, receipt)
     }
     return await listGuardedDirectoryPath(root, guard, withFileTypes, receipt);
 }
+function directoryGuardFromReceipt(directory, receipt) {
+    if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
+        receipt.directoryGuard.dir !== directory ||
+        receipt.target !== receipt.directoryGuard ||
+        (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
+            !receipt.directoryGuard.stat.isDirectory())) {
+        throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
+    }
+    return receipt.directoryGuard;
+}
 async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
     let entries;
     try {
@@ -221,19 +225,30 @@ async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
         await assertRootDirectoryObservationGuard(root, guard);
     return entries;
 }
-export async function openRootDirectoryListing(root, directory, options) {
-    const admitted = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
-        throw normalizeDirectoryError(error);
-    });
-    // Retain exact admission identities; metadata rechecks can use numeric Stats
-    // only when every identity component is losslessly representable.
-    const guard = extendDirectoryObservationGuard({
-        stat: admitted.stat,
-        identity: { dev: admitted.stat.dev, ino: admitted.stat.ino },
-    }, admitted.dir, admitted.realPath);
+export async function openRootDirectoryListing(root, directory, options, receipt) {
+    if (options.exactIdentity && options.order !== "filesystem")
+        throw new TypeError("exact entry identities require filesystem order");
+    let guard;
+    if (receipt) {
+        guard = directoryGuardFromReceipt(directory, receipt);
+    }
+    else {
+        const admitted = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
+            throw normalizeDirectoryError(error);
+        });
+        // Retain exact admission identities; metadata rechecks can use numeric Stats
+        // only when every identity component is losslessly representable.
+        guard = extendDirectoryObservationGuard({
+            stat: admitted.stat,
+            identity: { dev: admitted.stat.dev, ino: admitted.stat.ino },
+        }, admitted.dir, admitted.realPath);
+    }
     const assertCurrent = async () => {
         options.signal?.throwIfAborted();
-        await assertRootDirectoryObservationGuard(root, guard);
+        if (receipt)
+            assertRootPathObservationReceiptCurrent(root, receipt);
+        else
+            await assertRootDirectoryObservationGuard(root, guard);
         options.signal?.throwIfAborted();
     };
     let handle;
@@ -248,7 +263,13 @@ export async function openRootDirectoryListing(root, directory, options) {
     const close = async () => {
         const owned = handle;
         handle = undefined;
-        await owned?.close();
+        try {
+            await owned?.close();
+        }
+        catch (error) {
+            options.onCleanupFailure?.(error);
+            throw error;
+        }
     };
     try {
         await assertCurrent();
@@ -257,7 +278,7 @@ export async function openRootDirectoryListing(root, directory, options) {
             handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
         }
         else if (options.snapshot) {
-            snapshot = await listGuardedDirectoryPath(root, guard, true);
+            snapshot = await listGuardedDirectoryPath(root, guard, true, receipt);
         }
         else if (options.maxNames !== undefined) {
             names = [];
@@ -369,9 +390,13 @@ export async function openRootDirectoryListing(root, directory, options) {
                 if (!options.admitEntry())
                     return { kind: "limit", name };
                 // The stream's post-read fence is also the pre-stat fence in this owned operation.
-                const stat = fsSync.lstatSync(path.join(guard.realPath, name));
+                const pathname = path.join(guard.realPath, name);
+                const observed = options.exactIdentity ? inspectStatObservationSync(bigint => bigint
+                    ? fsSync.lstatSync(pathname, { bigint: true }) : fsSync.lstatSync(pathname)) : undefined;
+                const stat = observed?.stat ?? fsSync.lstatSync(pathname);
                 await assertCurrent();
-                return { kind: "entry", entry: { name, ...pathStatFromStats(stat) } };
+                const entry = { name, ...pathStatFromStats(stat) };
+                return observed ? { kind: "entry", entry, identity: observed.identity } : { kind: "entry", entry };
             }
             catch (error) {
                 throw normalizeDirectoryError(error);

package/dist/root-handle-context.d.ts

@@ -0,0 +1,4 @@
+import type { RootContext } from "./root-context.js";
+/** Internal registration; never reconstruct authority from public pathname fields. */
+export declare function registerRootHandleContext(handle: object, context: RootContext): void;
+export declare function rootHandleContext(handle: object): RootContext;

package/dist/root-handle-context.js

@@ -0,0 +1,12 @@
+import { FsSafeError } from "./errors.js";
+const contexts = new WeakMap();
+/** Internal registration; never reconstruct authority from public pathname fields. */
+export function registerRootHandleContext(handle, context) {
+    contexts.set(handle, context);
+}
+export function rootHandleContext(handle) {
+    const context = contexts.get(handle);
+    if (!context)
+        throw new FsSafeError("invalid-path", "watch requires a genuine fs-safe Root");
+    return context;
+}

package/dist/root-impl.d.ts

@@ -5,7 +5,7 @@ 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";
+import { type RootWalkEntry, type RootWalkOptions, type RootWalkSymlinkPolicy } from "./root-walk.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";
@@ -54,7 +54,7 @@ export interface Root {
     }): 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>;
+    walk<Policy extends RootWalkSymlinkPolicy>(relativePath: string, options: RootWalkOptions<Policy>): AsyncIterableIterator<RootWalkEntry<Policy>>;
 }
 export declare class RootHandle implements Root {
     private readonly context;
@@ -97,7 +97,7 @@ export declare class RootHandle implements Root {
     }): 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>;
+    walk<Policy extends RootWalkSymlinkPolicy>(relativePath: string, options: RootWalkOptions<Policy>): AsyncIterableIterator<RootWalkEntry<Policy>>;
 }
 export declare function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 export declare function rootFromDirectoryGuard(guard: {

package/dist/root-impl.js

@@ -51,6 +51,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { randomUUID } from "node:crypto";
+import { registerRootHandleContext } from "./root-handle-context.js";
 import fsSync, { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -85,7 +86,7 @@ import { listDirectoryPath, openRootDirectoryListing } from "./root-directory-li
 import { statResolvedPathInRoot } from "./root-path-stat.js";
 import { entriesInRoot } from "./root-entries.js";
 import { assertMoveMutationAllowed } from "./root-move-preflight.js";
-import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
+import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, createRootObservationGuard, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
 import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
@@ -199,6 +200,7 @@ export class RootHandle {
         this.rootWithSep = context.rootWithSep;
         this.defaults = defaults;
         registerFileLockSyncRootAdapter(this, context, defaults);
+        registerRootHandleContext(this, context);
     }
     mutationOptions(options) {
         return {
@@ -409,9 +411,13 @@ export class RootHandle {
         assertValidRootRelativePath(relativePath);
         return walkRoot({
             rootReal: this.context.rootReal,
+            observeRoot: () => createRootObservationGuard(this.context),
             stat: relative => this.stat(relative),
-            list: async (relative, listingOptions) => {
+            list: async (relative, listingOptions, receipt) => {
                 validatePinnedRelativePath(relative);
+                if (receipt) {
+                    return await openRootDirectoryListing(this.context, receipt.targetPath, listingOptions, receipt);
+                }
                 const resolved = await resolvePinnedPathInRoot(this.context, { relativePath: relative, allowRoot: true });
                 return await openRootDirectoryListing(this.context, resolved.resolved, listingOptions);
             },
@@ -798,7 +804,6 @@ async function mkdirPathInRoot(root, params) {
     const prepared = policy && resolved.relativePosix !== ""
         ? await preparePinnedWriteMutationAdmission({
             rootReal: resolved.rootReal,
-            rootWithSep: ensureTrailingSep(resolved.rootReal),
             rootIdentity: root.rootIdentity,
             resolvedTargetPath: resolved.resolved,
             originalPath: params.relativePath,
@@ -1045,10 +1050,8 @@ async function resolvePinnedRootPathInRoot(root, params) {
             throw err;
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
-    const rootWithSep = ensureTrailingSep(resolved.rootCanonicalPath);
     return {
         rootReal: resolved.rootCanonicalPath,
-        rootWithSep,
         canonicalPath: resolved.canonicalPath,
     };
 }

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

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

package/dist/root-observed-path.js

@@ -63,7 +63,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
         // 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,
         };
@@ -71,7 +70,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
     const relativeResolved = path.relative(resolved.rootCanonicalPath, resolved.canonicalPath);
     if (relativeResolved === "" || relativeResolved === ".") {
         return {
-            rootReal: resolved.rootCanonicalPath,
             resolved: resolved.canonicalPath,
         };
     }
@@ -87,7 +85,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
     if (!admittedCanonicalPath)
         throw outsideWorkspaceError();
     return {
-        rootReal: resolved.rootCanonicalPath,
         resolved: admittedCanonicalPath.path,
     };
 }

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

@@ -7,14 +7,11 @@ 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;
+export type RootPathObservationReceipt = Pick<RootPathObservationRequest & {
     directoryGuard: RootPathDirectoryObservationGuard;
-    directoryObserver?: NativeDirectoryObservationBackend;
     targetPath: string;
     target: RootPathTargetObservation;
-};
+}, "kind" | "rootGuard" | "directoryGuard" | "directoryObserver" | "targetPath" | "target">;
 /** A failed initial target lookup must not discard its already admitted parent. */
 export type RootPathParentObservationReceipt = Omit<RootPathObservationReceipt, "kind" | "target"> & {
     kind: "stat-parent";
@@ -24,16 +21,12 @@ export type RootPathObservationRequest = {
     rootGuard: DirectoryObservationGuard;
     directoryObserver?: NativeDirectoryObservationBackend;
 };
-export type RootPathTraversalObservation = {
+export type RootPathTraversalObservation = Omit<Partial<RootPathObservationReceipt> & {
     enabled: boolean;
     request: RootPathObservationRequest;
     targetIndex: number;
     directoryIndex: number;
-    directoryGuard?: RootPathDirectoryObservationGuard;
-    directoryObserver?: NativeDirectoryObservationBackend;
-    targetPath?: string;
-    target?: RootPathTargetObservation;
-};
+}, "kind" | "rootGuard">;
 export type RootPathObservedTraversalEntry = StatObservationReceipt | {
     stat: fs.Stats | BigIntStats;
     identity?: undefined;

package/dist/root-path.js

@@ -214,8 +214,8 @@ function finalizeLexicalResolution(context, kind) {
         rootPath: context.rootPath,
         rootCanonicalPath: context.rootCanonicalPath,
         relativePath: relativeInsideRoot(context.rootCanonicalPath, context.state.canonicalCursor),
-        exists: kind.exists,
-        kind: kind.kind,
+        exists: kind !== "missing",
+        kind,
     };
 }
 function applyResolvedSymlinkHop(context, linkCanonical) {
@@ -374,12 +374,9 @@ function traverseRootPath(params, { mode = "native", observation: observationOut
     const completeObservation = observation?.enabled === true && observation.directoryGuard !== undefined &&
         observation.targetPath === state.canonicalCursor && observation.target !== undefined;
     const kind = completeObservation
-        ? {
-            exists: true,
-            kind: isNativeDirectoryObservationGuard(observation.target)
-                ? "directory"
-                : toResolvedKind(observation.target.stat),
-        }
+        ? isNativeDirectoryObservationGuard(observation.target)
+            ? "directory"
+            : toResolvedKind(observation.target.stat)
         : getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
     if (completeObservation && observationOutput) {
         observationOutput.receipt = {
@@ -399,11 +396,11 @@ function getPathKindSync(absolutePath, preserveFinalSymlink) {
         const stat = preserveFinalSymlink
             ? fs.lstatSync(operationPath)
             : fs.statSync(operationPath);
-        return { exists: true, kind: toResolvedKind(stat) };
+        return toResolvedKind(stat);
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
-            return { exists: false, kind: "missing" };
+            return "missing";
         }
         throw error;
     }

package/dist/root-walk.d.ts

@@ -1,17 +1,21 @@
+import type { DirectoryObservationGuard } from "./directory-guard.js";
+import { type RootPathObservationReceipt } from "./root-path.js";
 import type { RootDirectoryListing, RootDirectoryListingOptions } from "./root-directory-list.js";
 import type { PathStat } from "./types.js";
-export type RootWalkSymlinkPolicy = "skip" | "follow-within-root";
+export type RootWalkSymlinkPolicy = "skip" | "follow-within-root" | "include";
+type LegacyRootWalkSymlinkPolicy = Exclude<RootWalkSymlinkPolicy, "include">;
 export type RootWalkLimitBehavior = "truncate" | "throw";
 export type RootWalkDirectoryErrorBehavior = "throw" | "skip-and-report";
 export type RootWalkEntryFilterResult = "include" | "skip" | "skip-subtree";
-export type RootWalkDataEntryKind = "file" | "directory" | "other";
-export type RootWalkEntryKind = RootWalkDataEntryKind | "directory-error" | "truncated";
-export type RootWalkDataEntry = {
+export type RootWalkDataEntryKind<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = "file" | "directory" | "other" | ("include" extends Policy ? "symlink" : never);
+export type RootWalkEntryKind<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = RootWalkDataEntryKind<Policy> | "directory-error" | "truncated";
+type WalkEntryOfKind<Kind extends RootWalkDataEntryKind<RootWalkSymlinkPolicy>> = {
     relativePath: string;
-    kind: RootWalkDataEntryKind;
+    kind: Kind;
     size: number;
 };
-export type RootWalkEntry = RootWalkDataEntry | {
+export type RootWalkDataEntry<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = WalkEntryOfKind<RootWalkDataEntryKind> | ("include" extends Policy ? WalkEntryOfKind<"symlink"> : never);
+export type RootWalkEntry<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = RootWalkDataEntry<Policy> | {
     relativePath: string;
     kind: "truncated";
     size: 0;
@@ -21,21 +25,24 @@ export type RootWalkEntry = RootWalkDataEntry | {
     size: 0;
     error: unknown;
 };
-export type RootWalkEntryFilter = (entry: RootWalkDataEntry) => RootWalkEntryFilterResult | Promise<RootWalkEntryFilterResult>;
-export type RootWalkOptions = {
+export type RootWalkEntryFilter<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = (entry: RootWalkDataEntry<Policy>) => RootWalkEntryFilterResult | Promise<RootWalkEntryFilterResult>;
+export type RootWalkOptions<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = {
     maxDepth?: number;
     maxEntries?: number;
     order?: "sorted" | "filesystem";
-    symlinkPolicy: RootWalkSymlinkPolicy;
+    symlinkPolicy: Policy;
     signal?: AbortSignal;
     limitBehavior?: RootWalkLimitBehavior;
-    entryFilter?: RootWalkEntryFilter;
+    entryFilter?: RootWalkEntryFilter<Policy>;
     onDirectoryError?: RootWalkDirectoryErrorBehavior;
 };
+type AnyRootWalkOptions = RootWalkOptions | RootWalkOptions<"include"> | RootWalkOptions<RootWalkSymlinkPolicy>;
+type AnyRootWalkEntry = RootWalkEntry<RootWalkSymlinkPolicy>;
 type RootWalkCapability = {
     rootReal: string;
+    observeRoot(): Promise<DirectoryObservationGuard | undefined>;
     stat(relativePath: string): Promise<PathStat>;
-    list(relativePath: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
+    list(relativePath: string, options: RootDirectoryListingOptions, receipt?: RootPathObservationReceipt): Promise<RootDirectoryListing>;
 };
-export declare function walkRoot(root: RootWalkCapability, relativePath: string, options: RootWalkOptions): AsyncGenerator<RootWalkEntry>;
+export declare function walkRoot(root: RootWalkCapability, relativePath: string, options: AnyRootWalkOptions): AsyncGenerator<AnyRootWalkEntry>;
 export {};

package/dist/root-walk.js

@@ -1,8 +1,14 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { expandRelativePathWithHome } from "./root-context.js";
-import { resolveRootPath, ROOT_PATH_ALIAS_POLICIES } from "./root-path.js";
+import { resolveRootPath, resolveRootPathWithObservation, ROOT_PATH_ALIAS_POLICIES, RootPathObservationError, } from "./root-path.js";
 import { createSuppressedError } from "./suppressed-error.js";
+function filterEntry(options, entry) {
+    if (entry.kind === "symlink") {
+        return options.symlinkPolicy === "include" ? options.entryFilter?.(entry) ?? "include" : "skip";
+    }
+    return options.entryFilter?.(entry) ?? "include";
+}
 function validateBudget(name, value) {
     if (value === undefined)
         return Number.POSITIVE_INFINITY;
@@ -24,7 +30,7 @@ function limitEntry(relativePath) {
     return { relativePath, kind: "truncated", size: 0 };
 }
 export async function* walkRoot(root, relativePath, options) {
-    if (!["skip", "follow-within-root"].includes(options.symlinkPolicy)) {
+    if (!["skip", "follow-within-root", "include"].includes(options.symlinkPolicy)) {
         throw new TypeError(`invalid root walk symlink policy: ${String(options.symlinkPolicy)}`);
     }
     if (options.order !== undefined && !["sorted", "filesystem"].includes(options.order)) {
@@ -62,24 +68,50 @@ export async function* walkRoot(root, relativePath, options) {
             throw error;
         return { relativePath: directory, kind: "directory-error", size: 0, error };
     };
-    async function* visit(directory, depth) {
+    async function* visit(directory, depth, admittedChildPath) {
         options.signal?.throwIfAborted();
         let listing;
+        let canonicalDirectory;
         try {
             const expandedDirectory = depth === 0 ? await expandRelativePathWithHome(directory) : directory;
-            const skipChildSymlinks = depth > 0 && options.symlinkPolicy === "skip";
-            const resolvedDirectory = await resolveRootPath({
-                absolutePath: path.resolve(root.rootReal, expandedDirectory),
+            const noFollowChildSymlinks = depth > 0 && options.symlinkPolicy !== "follow-within-root";
+            const includeChild = depth > 0 && options.symlinkPolicy === "include";
+            const resolution = {
+                absolutePath: admittedChildPath ?? path.resolve(root.rootReal, expandedDirectory),
                 rootPath: root.rootReal,
                 rootCanonicalPath: root.rootReal,
                 boundaryLabel: "root walk",
-                policy: skipChildSymlinks ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
-            });
-            if (skipChildSymlinks && resolvedDirectory.kind === "symlink")
-                return;
+                policy: noFollowChildSymlinks ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
+            };
+            let receipt;
+            let resolvedDirectory;
+            if (includeChild) {
+                const rootGuard = await root.observeRoot();
+                if (!rootGuard) {
+                    throw new FsSafeError("helper-unavailable", "root walk requires an exact directory observation");
+                }
+                const observed = await resolveRootPathWithObservation({
+                    ...resolution,
+                    rootIdentity: rootGuard.identity,
+                }, { kind: "directory", rootGuard });
+                resolvedDirectory = observed.resolved;
+                receipt = observed.receipt;
+            }
+            else {
+                resolvedDirectory = await resolveRootPath(resolution);
+            }
+            if (noFollowChildSymlinks && resolvedDirectory.kind === "symlink") {
+                if (options.symlinkPolicy === "skip")
+                    return;
+                throw new FsSafeError("path-mismatch", `root walk directory became a symlink: ${directory}`);
+            }
             if (!resolvedDirectory.exists || resolvedDirectory.kind !== "directory") {
                 throw new FsSafeError("not-file", `root walk path is not a directory: ${directory || "."}`);
             }
+            if (includeChild && (!receipt || receipt.directoryGuard.realPath !== resolvedDirectory.canonicalPath)) {
+                throw new FsSafeError("path-mismatch", "root walk directory observation was not retained");
+            }
+            canonicalDirectory = resolvedDirectory.canonicalPath;
             if (visitedDirectories.has(resolvedDirectory.canonicalPath)) {
                 return;
             }
@@ -97,10 +129,10 @@ export async function* walkRoot(root, relativePath, options) {
                 signal: options.signal,
                 snapshot: maxEntries === Number.POSITIVE_INFINITY,
                 admitEntry,
-            });
+            }, receipt);
         }
         catch (error) {
-            yield onDirectoryError(directory, error);
+            yield onDirectoryError(directory, error instanceof RootPathObservationError ? error.error : error);
             return;
         }
         // A thrown undefined still needs to be retained if closing also fails.
@@ -131,10 +163,9 @@ export async function* walkRoot(root, relativePath, options) {
                 const entry = next.entry;
                 let kind = entryKind(entry);
                 let size = entry.size;
-                if (kind === "symlink") {
-                    if (options.symlinkPolicy === "skip") {
-                        continue;
-                    }
+                if (kind === "symlink" && options.symlinkPolicy === "skip")
+                    continue;
+                if (kind === "symlink" && options.symlinkPolicy === "follow-within-root") {
                     const resolved = await resolveRootPath({
                         absolutePath: path.resolve(root.rootReal, child),
                         rootPath: root.rootReal,
@@ -149,7 +180,7 @@ export async function* walkRoot(root, relativePath, options) {
                     size = target.size;
                 }
                 const walkEntry = { relativePath: child, kind, size };
-                let filterResult = options.entryFilter?.(walkEntry) ?? "include";
+                let filterResult = filterEntry(options, walkEntry);
                 if (typeof filterResult !== "string") {
                     filterResult = (await filterResult) ?? "include";
                     options.signal?.throwIfAborted();
@@ -177,7 +208,7 @@ export async function* walkRoot(root, relativePath, options) {
                     yield onLimit(child);
                     return;
                 }
-                yield* visit(child, depth + 1);
+                yield* visit(child, depth + 1, options.symlinkPolicy === "include" ? path.join(canonicalDirectory, name) : undefined);
                 if (truncated)
                     return;
             }

package/dist/root-write-admission.js

@@ -201,7 +201,6 @@ export async function resolveGuardedWriteTargetInRoot(root, params) {
     const relativeParent = path.relative(resolvedPath.rootReal, path.dirname(resolvedPath.resolved));
     const prepared = await preparePinnedWriteMutationAdmission({
         rootReal: resolvedPath.rootReal,
-        rootWithSep: resolvedPath.rootWithSep,
         rootIdentity: root.rootIdentity,
         resolvedTargetPath: resolvedPath.resolved,
         originalPath: params.relativePath,
@@ -288,7 +287,6 @@ export async function resolvePinnedWriteTargetInRoot(root, relativePath, request
     if (policy) {
         ({ relativeParentPath, mutationAdmission } = await preparePinnedWriteMutationAdmission({
             rootReal,
-            rootWithSep,
             rootIdentity: root.rootIdentity,
             resolvedTargetPath: resolved,
             originalPath: relativePath,

package/dist/safe-path-segment.d.ts

@@ -7,5 +7,6 @@ export declare function assertNoDriveRelativePathSegments(value: string, label:
 export declare function trimHyphenEdges(value: string): string;
 export declare function isSafePathSegment(segment: string, options?: SafePathSegmentOptions): boolean;
 export declare function assertSafePathSegment(segment: string, options?: SafePathSegmentOptions): string;
+export declare function normalizeSafePathSegment(value: string): string;
 export declare function sanitizeSafePathSegment(value: string): string | undefined;
 export declare function assertSafePathPrefix(prefix: string, options?: SafePathSegmentOptions): string;

package/dist/safe-path-segment.js

@@ -1,3 +1,4 @@
+import { isWindowsReservedDeviceName } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 const SAFE_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
 const SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
@@ -34,6 +35,8 @@ export function isSafePathSegment(segment, options = {}) {
         !segment.includes("/") &&
         !segment.includes("\\") &&
         !segment.includes("\0") &&
+        // Segments are portable identifiers: CON.json and CON.<pid>.tmp name devices on Windows.
+        !isWindowsReservedDeviceName(segment) &&
         (options.allowDotPrefix === true || !segment.startsWith(".")) &&
         (options.allowDotPrefix === true
             ? SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN.test(segment)
@@ -47,13 +50,16 @@ export function assertSafePathSegment(segment, options = {}) {
     }
     return segment;
 }
-export function sanitizeSafePathSegment(value) {
+export function normalizeSafePathSegment(value) {
     const sanitized = value
         .trim()
         .replace(/[\\/]+/g, "-")
         .replace(/\0/g, "")
         .replace(/[^A-Za-z0-9._-]+/g, "-");
-    const trimmed = trimHyphenEdges(sanitized);
+    return trimHyphenEdges(sanitized);
+}
+export function sanitizeSafePathSegment(value) {
+    const trimmed = normalizeSafePathSegment(value);
     return isSafePathSegment(trimmed, { allowDotPrefix: true }) ? trimmed : undefined;
 }
 export function assertSafePathPrefix(prefix, options = {}) {

package/dist/secure-file.js

@@ -202,7 +202,8 @@ function inspectOpenedPermissions(stat, platform) {
         groupReadable: isGroupReadable(bits),
     };
 }
-async function assertSecurePermissions(options, stat, realPath, identity, fd) {
+async function assertSecurePermissions(options, opened, fd) {
+    const { pathStat: stat, realPath, identity } = opened;
     if (options.permissions?.allowInsecure) {
         return undefined;
     }
@@ -282,7 +283,7 @@ export async function readSecureFile(options) {
     const opened = await openSecureHandle(options, maxBytes);
     try {
         assertTrustedDirs(options, opened.realPath);
-        const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath, opened.identity, opened.handle.fd);
+        const permissions = await assertSecurePermissions(options, opened, opened.handle.fd);
         const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs, maxBytes);
         const finalIdentity = inspectFileIdentitySync(() => fsSync.fstatSync(opened.handle.fd, { bigint: true }), opened.identity);
         if (!finalIdentity.isFile()) {