@openclaw/openshell-sandbox 2026.9.2 → 2026.9.4

package/node_modules/@openclaw/fs-safe/docs/testing.md

@@ -0,0 +1,189 @@
+# Testing
+
+`@openclaw/fs-safe/test-hooks` exposes test-only injection points. Registration
+is allowed only when `process.env.NODE_ENV === "test"` or
+`process.env.VITEST === "true"`; registering a non-empty hook set elsewhere
+throws. Production code must not import this subpath.
+
+```ts
+import {
+  __setFsSafeTestHooksForTest,
+  type FsSafeTestHooks,
+} from "@openclaw/fs-safe/test-hooks";
+```
+
+The double-underscore prefix is a deliberate "hands off" signal: production code should never import this module. ESLint or your equivalent linter should flag it.
+
+## When to reach for hooks
+
+- Reproduce a TOCTOU race deterministically: simulate a symlink swap between resolve and open, or between write and rename.
+- Force guarded JavaScript behavior without removing platform packages from your runners.
+- Inject latency to test cancellation/timeout paths.
+
+If you don't need to inject a race, you don't need hooks — most tests should drive the library through normal calls and assert on observable behavior.
+
+## Hooks API
+
+```ts
+type FsSafeTestHooks = {
+  afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
+  beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
+  afterOpen?: (filePath: string, handle: import("node:fs/promises").FileHandle) => Promise<void> | void;
+  afterPublishTargetCreated?: (method, targetPath, identity) => Promise<void> | void;
+  beforePublishDirectorySync?: (method, targetPath, identity) => Promise<void> | void;
+  // Additional archive, store, root-fallback, temp, and trash race hooks are
+  // documented on the focused Test hooks reference page.
+};
+
+function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;
+function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
+```
+
+Hooks are called at well-defined points in the library's hot paths:
+
+- **`afterPreOpenLstat`** — runs after the pre-open `lstat`. A common use is to swap the path's target via `fs.symlink`/`fs.unlink` to drive a TOCTOU race.
+- **`beforeOpen`** — runs before `fs.open` with the exact flags the root read path will use.
+- **`afterOpen`** — runs after the file handle is opened. Useful to wrap handle methods or inject a size race before a stream is consumed.
+- **`afterPublishTargetCreated`** — runs after exclusive publication created a target but before its final fences.
+- **`beforePublishDirectorySync`** — runs after target verification and immediately before strict parent sync; useful for exercising `onSyncFailure`.
+
+`__setFsSafeTestHooksForTest(undefined)` clears all hooks. Always clean up between tests.
+
+## Example: simulate a TOCTOU swap
+
+```ts
+import { describe, it, beforeEach, afterEach, expect } from "vitest";
+import { mkdtemp, mkdir, rm, symlink, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { root, FsSafeError } from "@openclaw/fs-safe";
+import { __setFsSafeTestHooksForTest } from "@openclaw/fs-safe/test-hooks";
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(path.join(os.tmpdir(), "fs-safe-toctou-"));
+  await writeFile(path.join(dir, "real.txt"), "secret");
+  await writeFile(path.join(dir, "decoy.txt"), "decoy");
+});
+afterEach(async () => {
+  __setFsSafeTestHooksForTest(undefined);
+  await rm(dir, { recursive: true, force: true });
+});
+
+it("rejects a swap between resolve and open", async () => {
+  const fs = await root(dir, { symlinks: "reject" });
+
+  __setFsSafeTestHooksForTest({
+    afterPreOpenLstat: async (absPath) => {
+      // swap real.txt for a symlink to decoy.txt right before the open
+      await unlink(absPath);
+      await symlink(path.join(dir, "decoy.txt"), absPath);
+    },
+  });
+
+  await expect(fs.read("real.txt")).rejects.toMatchObject({
+    name: "FsSafeError",
+    code: expect.stringMatching(/symlink|path-mismatch/),
+  });
+});
+```
+
+The `code` may be `symlink` (caught at open by `O_NOFOLLOW`) or `path-mismatch` (caught by the post-open identity check) depending on platform — both are correct refusals.
+
+## Example: force guarded JavaScript fallback behavior
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+beforeEach(() => {
+  configureFsSafeNative({ mode: "off" });
+});
+
+afterEach(() => {
+  configureFsSafeNative({ mode: "auto" });
+});
+
+it("runs without the native helper", async () => {
+  const fs = await root(dir);
+  await fs.write("file.txt", "ok");
+  await expect(fs.readText("file.txt")).resolves.toBe("ok");
+});
+```
+
+## Cleanup is mandatory
+
+Hooks set by `__setFsSafeTestHooksForTest` persist across tests until explicitly cleared. Always clear in `afterEach` (or your test framework's equivalent) — leaked hooks will silently change behavior in unrelated tests and cause maddening intermittent failures.
+
+```ts
+import { afterEach } from "vitest";
+import { __setFsSafeTestHooksForTest } from "@openclaw/fs-safe/test-hooks";
+
+afterEach(() => {
+  __setFsSafeTestHooksForTest(undefined);
+});
+```
+
+A global hook clear in your test setup file is a good safety net.
+
+See the [complete Test hooks reference](test-hooks.md) for every optional hook.
+
+## Patterns for testing fs-safe-using code
+
+You usually don't need hooks. Most tests follow this shape:
+
+```ts
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { root } from "@openclaw/fs-safe";
+
+let dir: string;
+let fs: Awaited<ReturnType<typeof root>>;
+
+beforeEach(async () => {
+  dir = await mkdtemp(path.join(os.tmpdir(), "my-feature-"));
+  fs = await root(dir, { symlinks: "reject", hardlinks: "reject", mkdir: true });
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+it("writes and reads through the boundary", async () => {
+  await fs.write("notes/today.txt", "hello");
+  expect(await fs.readText("notes/today.txt")).toBe("hello");
+});
+```
+
+For tests that need a private temp workspace, [`withTempWorkspace`](temp.md) makes the setup-and-teardown story trivial.
+
+## Repo test shards
+
+Run the full local gate before handoff:
+
+```sh
+pnpm check
+```
+
+Run only the security boundary corpus while iterating on root/path/archive/temp hardening:
+
+```sh
+pnpm test:security
+```
+
+Run the static primitive guard after changing low-level filesystem helpers:
+
+```sh
+pnpm lint:fs-boundary
+```
+
+It catches the specific raw fallback patterns that previously led to
+check-then-use bugs, such as direct copy-to-destination fallback and sync temp
+workspace reads that bypass pinned file descriptors.
+
+`pnpm check` also runs `pnpm lint:file-size`. New source and test files should stay under 500 lines. Existing larger files have explicit budgets in `scripts/check-file-size.mjs`; do not increase those budgets as part of unrelated work.
+
+## See also
+
+- [Security model](security-model.md) — what the boundary is supposed to defend; design tests around the same threats.
+- [`root()`](root.md) — the surface most tests will exercise.
+- [Temp workspaces](temp.md) — `withTempWorkspace` for cleanup-on-exit test directories.

package/node_modules/@openclaw/fs-safe/docs/timing.md

@@ -0,0 +1,121 @@
+# Timing
+
+`withTimeout(promise, timeoutMs, labelOrOptions?)` is a small helper for putting a wall-clock ceiling on an async operation. It rejects with a synthetic timeout error after `timeoutMs` and clears its internal timer when the wrapped promise settles first.
+
+```ts
+import { withTimeout } from "@openclaw/fs-safe/advanced";
+```
+
+## Signature
+
+```ts
+function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  labelOrOptions?: string | {
+    label?: string;
+    message?: string;
+    createError?: () => Error;
+  },
+): Promise<T>;
+```
+
+If `timeoutMs` is `0`, negative, `Infinity`, or `NaN`, the helper is a no-op and simply awaits the original promise.
+
+## Examples
+
+### Simple ceiling
+
+```ts
+import { withTimeout } from "@openclaw/fs-safe/advanced";
+
+const buf = await withTimeout(
+  fs.readFile("/srv/big.bin"),
+  5_000,
+  "read big.bin",
+);
+```
+
+If the read doesn't resolve within 5 seconds, the returned promise rejects with `Error: read big.bin timed out after 5000ms`. The underlying `fs.readFile` continues until Node finishes it — `withTimeout` does not cancel the wrapped work, only the wait.
+
+### Custom message
+
+```ts
+await withTimeout(work(), 5_000, {
+  message: "build did not finish in time",
+});
+```
+
+### Custom error factory
+
+```ts
+class BuildTimeout extends Error {}
+
+await withTimeout(work(), 5_000, {
+  createError: () => new BuildTimeout("build timeout (5s)"),
+});
+```
+
+`createError` is called when the timer fires; the returned error is what the promise rejects with. Use this when callers branch on `instanceof` or want a custom `cause`.
+
+## Cancellation
+
+`withTimeout` does **not** abort the wrapped operation when the timer fires — it just stops waiting. If you need real cancellation, the wrapped operation must opt into an `AbortSignal` itself:
+
+```ts
+const controller = new AbortController();
+const timer = setTimeout(() => controller.abort(), 5_000);
+
+try {
+  const res = await fetch(url, { signal: controller.signal });
+  // ...
+} finally {
+  clearTimeout(timer);
+}
+```
+
+For the common "I want a deadline AND cancellation" shape, use `AbortSignal.timeout(ms)` directly — it's the standard library's answer and handles both at once.
+
+## Patterns
+
+### Bound a credential refresh
+
+```ts
+const fresh = await withTimeout(
+  refreshToken(currentRefresh),
+  5_000,
+  "refresh oauth token",
+);
+await writeSecretFileAtomic({ rootDir, filePath, content: JSON.stringify(fresh) });
+```
+
+### Compose with archive extraction
+
+```ts
+import { extractArchive } from "@openclaw/fs-safe/archive";
+
+await extractArchive({
+  archivePath,
+  destDir,
+  kind: "zip",
+  timeoutMs: 30_000,
+});
+```
+
+`extractArchive` already takes `timeoutMs` and carries its own abort signal/deadline checks — you don't need to wrap it. Reach for `withTimeout` for operations that don't carry their own timeout knob.
+
+### Disable in tests
+
+When unit-testing flaky code, you might want to disable the timeout. Pass `0`:
+
+```ts
+await withTimeout(work(), process.env.NODE_ENV === "test" ? 0 : 5_000, "work");
+```
+
+Better, gate it from the caller — `withTimeout(p, 0, ...)` returns the promise as-is.
+
+## See also
+
+- [Archive extraction](archive.md) — `extractArchive` already takes `timeoutMs`.
+- [File lock](sidecar-lock.md) — retry policy is a different form of bounded waiting.
+- [`AbortSignal.timeout`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static) — standard-library cancellation when you need to *abort*, not just *give up*.

package/node_modules/@openclaw/fs-safe/docs/types.md

@@ -0,0 +1,188 @@
+# Types
+
+The types most callers reach for. Shared data shapes are exported from `@openclaw/fs-safe/types`; method-specific option/result types live next to their subpath.
+
+For atomic replacement, `ReplaceFileAtomicFileSystem` and `ReplaceFileAtomicSyncFileSystem` are exported from `@openclaw/fs-safe/atomic`. Async adapters use `chmod()` on the `FileHandle` returned by their required `open()` operation. The synchronous type adds optional `fchmodSync(fd, mode)`; custom sync adapters that explicitly request `mode` or `preserveExistingMode` must implement it. See [Atomic writes](atomic.md#test-injection).
+
+```ts
+import type {
+  BasePathOptions,
+  DirEntry,
+  FastPathMode,
+  PathStat,
+  SafeEncoding,
+} from "@openclaw/fs-safe/types";
+```
+
+## `PathStat`
+
+```ts
+type PathStat = {
+  dev: number;
+  gid: number;
+  ino: number;
+  isDirectory: boolean;
+  isFile: boolean;
+  isSymbolicLink: boolean;
+  mode: number;
+  mtimeMs: number;
+  nlink: number;
+  size: number;
+  uid: number;
+};
+```
+
+The shape returned by `Root.stat()`. It is a serializable view of the identity,
+ownership, mode, size, timestamp, link count, and three file-kind facts the
+boundary uses. Unlike Node's `Stats`, `isFile`, `isDirectory`, and
+`isSymbolicLink` are boolean fields rather than methods.
+
+## `DirEntry`
+
+```ts
+type DirEntry = PathStat & {
+  name: string;       // base name within the listed directory
+};
+```
+
+Returned by `Root.list(rel, { withFileTypes: true })`. Includes every
+`PathStat` field plus the entry's `name`.
+
+## `BasePathOptions`
+
+```ts
+type BasePathOptions = {
+  rootDir: string;
+  relativePath: string;
+};
+
+type FastPathMode = "auto" | "never" | "require";
+```
+
+`BasePathOptions` is the shared root-plus-relative-path record. `FastPathMode`
+is retained as a public compatibility union; no current exported options record
+consumes it, so setting a fast-path policy is not part of the current API.
+
+## `SafeEncoding`
+
+```ts
+type SafeEncoding = BufferEncoding | null;
+```
+
+Used by helpers that accept either an encoding (returning a string) or `null` (returning a `Buffer`). The Node `BufferEncoding` type is widened to include `null` for "give me bytes."
+
+## `OpenResult` / `ReadResult`
+
+Returned by `Root.open()` and `Root.read()`:
+
+```ts
+type OpenResult = {
+  handle: import("node:fs/promises").FileHandle;
+  containment: "kernel-atomic" | "best-effort";
+  realPath: string;
+  stat: import("node:fs").Stats;
+};
+
+type ReadResult = {
+  buffer: Buffer;
+  containment: "kernel-atomic" | "best-effort";
+  realPath: string;
+  stat: import("node:fs").Stats;
+};
+```
+
+`realPath` is the canonical real path the read or open landed on, after symlink resolution; `stat` is the verified `fstat` result. Public root results currently report `containment: "best-effort"`; the union also describes direct native `openBeneath()` results, which report `"kernel-atomic"` on Linux. See the [security model](security-model.md#containment-guarantees-by-platform).
+
+## `RootDefaults` / `RootOptions`
+
+```ts
+type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
+
+type RootDefaults = {
+  denyMutations?: DenyMutationPolicy;
+  durable?: boolean; // default true for write/create/writeJson/createJson/append
+  hardlinks?: "reject" | "allow";
+  maxBytes?: number;
+  mkdir?: boolean; // default true for mutation methods
+  mode?: number;
+  nonBlockingRead?: boolean;
+  renameIdentity?: RenameIdentityPolicy;
+  symlinks?: "reject" | "follow-within-root";
+};
+
+type DenyMutationPolicy = {
+  paths?: readonly string[];
+  prefixes?: readonly string[];
+};
+
+type RootOptions = {
+  rootDir: string;
+  defaults?: RootDefaults;
+};
+```
+
+`RootDefaults` is what `root(rootDir, defaults)` accepts. See [`root()`](root.md) for the per-method options that override these. `denyMutations` is the exception: root and per-call deny entries are merged.
+
+## `RootReadOptions` / `RootWriteOptions` / `RootCopyOptions`
+
+```ts
+type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
+type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity"> & {
+  encoding?: BufferEncoding;
+  overwrite?: boolean;
+};
+type RootCopyOptions = Pick<RootDefaults, "denyMutations" | "maxBytes" | "mkdir" | "mode"> & {
+  sourceHardlinks?: "reject" | "allow";
+};
+type RootOpenWritableOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode"> & {
+  writeMode?: "replace" | "append" | "update";
+};
+type RootWriteJsonOptions = RootWriteOptions & {
+  replacer?: Parameters<typeof JSON.stringify>[1];
+  space?: Parameters<typeof JSON.stringify>[2];
+  trailingNewline?: boolean;
+};
+type RootAppendOptions = RootWriteOptions & {
+  prependNewlineIfNeeded?: boolean;
+};
+type RootMoveOptions = Pick<RootDefaults, "denyMutations"> & {
+  overwrite?: boolean;
+};
+type RootRemoveOptions = Pick<RootDefaults, "denyMutations">;
+type RootMkdirOptions = Pick<RootDefaults, "denyMutations">;
+```
+
+Per-method option shapes. Each picks the `RootDefaults` keys that apply, plus method-specific extras.
+
+## `SymlinkPolicy` / `HardlinkPolicy`
+
+```ts
+type SymlinkPolicy = "reject" | "follow-within-root";
+type HardlinkPolicy = "reject" | "allow";
+```
+
+The two policy unions you'll see throughout. `"reject"` is conservative; `"follow-within-root"` allows symlinks whose final target is still inside the root; `"allow"` (hardlinks only) is permissive. Defaults for both symlinks and hardlinks are `"reject"`; switch hardlinks to `"allow"` only when you intentionally accept hardlink aliases.
+
+## `FsSafeErrorCode` / `FsSafeErrorCategory`
+
+```ts
+type FsSafeErrorCode =
+  | "already-exists" | "denied-path" | "device-path" | "hardlink"
+  | "helper-failed"
+  | "helper-unavailable" | "insecure-permissions" | "invalid-path"
+  | "not-empty" | "not-file" | "not-found" | "not-owned"
+  | "not-removable" | "outside-workspace" | "path-alias"
+  | "path-mismatch" | "permission-unverified" | "read-failed" | "secret-exists"
+  | "store-reentrant-update" | "symlink"
+  | "timeout" | "too-large" | "unsupported-platform";
+```
+
+Closed union you switch on. See the [Errors](errors.md) reference for what each one means.
+
+`FsSafeError.category` is `"policy"` for unsafe input or target state rejected by a safety policy and `"operational"` for routine filesystem outcomes or environment/runtime failures. `not-found`, `not-empty`, `not-removable`, and `read-failed` are operational.
+
+## See also
+
+- [`root()`](root.md) — how `RootDefaults` and `Root*Options` are used.
+- [Errors](errors.md) — the closed code union in context.
+- [Reading](reading.md), [Writing](writing.md) — option shapes per verb.

package/node_modules/@openclaw/fs-safe/docs/walk.md

@@ -0,0 +1,128 @@
+# Directory walking
+
+`walkDirectory()` and `walkDirectorySync()` provide budget-bounded directory scans for callers that would otherwise hand-roll recursive `readdir()` loops. The bounds are `maxDepth` and `maxEntries`; this helper does not create a security boundary. Use [`root()`](root.md) when the path itself is caller-influenced.
+
+```ts
+import { walkDirectory } from "@openclaw/fs-safe/walk";
+
+const scan = await walkDirectory("/safe/workspace", {
+  maxDepth: 3,
+  maxEntries: 10_000,
+  symlinks: "skip",
+  include: (entry) => entry.kind === "file",
+  descend: (entry) => entry.name !== ".git",
+});
+
+if (scan.truncated) {
+  throw new Error("workspace scan exceeded entry budget");
+}
+```
+
+## Result
+
+```ts
+type WalkDirectoryResult = {
+  entries: WalkDirectoryEntry[];
+  scannedEntryCount: number;
+  truncated: boolean;
+  failedDirs?: WalkDirectoryFailure[];
+};
+
+type WalkDirectoryEntry = {
+  name: string;
+  path: string;
+  relativePath: string;
+  depth: number;
+  kind: "file" | "directory" | "symlink" | "other";
+  dirent: import("node:fs").Dirent;
+};
+
+type WalkDirectoryFailure = {
+  path: string;
+  relativePath: string;
+  depth: number;
+  error: unknown;
+};
+```
+
+`depth` starts at `1` for direct children of `rootDir`. `relativePath` is always relative to the supplied root. `scannedEntryCount` counts directory entries examined, including entries filtered out by `include`.
+
+`walkDirectory()` and `walkDirectorySync()` always return `failedDirs`; the property remains optional on the exported `WalkDirectoryResult` type so existing callers that manually construct the legacy result shape remain source-compatible. It lists every directory whose `realpath`/`readdir` threw, so its contents are absent from `entries`. `error` is the thrown value (a `NodeJS.ErrnoException` at runtime), so callers can distinguish a benign missing-directory race (`ENOENT`) from a real read failure (`EACCES`, `EIO`, `ESTALE`, …). The walk-root failure has an empty `relativePath` and `depth: 0`. Failures resolving a symlink's target kind are not reported here.
+
+## Options
+
+```ts
+type WalkDirectoryOptions = {
+  maxDepth?: number;
+  maxEntries?: number;
+  symlinks?: "skip" | "follow" | "include";
+  include?: (entry: WalkDirectoryEntry) => boolean;
+  descend?: (entry: WalkDirectoryEntry) => boolean;
+};
+```
+
+`symlinks` defaults to `"skip"`. `"include"` returns symlink entries without following them. `"follow"` resolves symlinks with `stat()` and may descend into linked directories, so use it only when that is intentional. Already-visited real directories are skipped so symlink cycles do not recurse forever.
+
+`include` controls which entries are returned. `descend` controls which directory entries are traversed. A skipped directory can still be returned if `include` accepts it.
+
+Unreadable directories are skipped rather than throwing, but every skipped directory is recorded in `failedDirs`. This keeps the helper suitable for best-effort inventories while letting pruning jobs tell an incomplete scan from an empty one: a destructive reconcile that deletes state for paths missing from `entries` must first confirm `failedDirs` holds no real read failures, or a transient `EIO`/`EACCES` blip would be mistaken for mass deletion. Use a stricter root-bounded operation when every entry must be accounted for.
+
+## Root-bounded async iteration
+
+`Root.walk(rel, options)` is the root-bounded counterpart to these standalone
+inventory helpers. It yields `{ relativePath, kind, size }` incrementally and
+accepts `maxDepth`, `maxEntries`, `symlinkPolicy: "skip" |
+"follow-within-root"`, and an `AbortSignal`. The default budget behavior yields
+one `kind: "truncated"` marker and ends; pass `limitBehavior: "throw"` for a
+typed `FsSafeError("too-large")` instead.
+
+`entryFilter` is evaluated for each resolved file, directory, or other entry:
+
+```ts
+for await (const entry of capability.walk("", {
+  symlinkPolicy: "skip",
+  entryFilter: (entry) =>
+    entry.kind === "directory" && entry.relativePath === ".git"
+      ? "skip-subtree"
+      : "include",
+  onDirectoryError: "skip-and-report",
+})) {
+  if (entry.kind === "directory-error") {
+    console.warn("incomplete subtree", entry.relativePath, entry.error);
+    continue;
+  }
+  consume(entry);
+}
+```
+
+The result values are `"include"`, `"skip"`, and `"skip-subtree"`. Plain
+`"skip"` omits an entry but still descends when it is a directory;
+`"skip-subtree"` omits that directory and prunes its descendants. Returning
+`"skip-subtree"` for a non-directory is equivalent to `"skip"`.
+
+`onDirectoryError` defaults to `"throw"`, preserving the original fail-fast
+contract. `"skip-and-report"` yields a discriminated
+`{ kind: "directory-error", relativePath, size: 0, error }` marker for a
+directory that cannot be resolved or listed, then continues with its siblings.
+Every examined directory entry consumes `maxEntries` before filtering, so
+`"skip"` cannot turn the iterator into an unbounded traversal. Reporting and
+`"truncated"` markers describe already-reached state and do not authorize
+further descent.
+
+The pure-Node path validates every directory canonically inside the root,
+revalidates each listing through the normal `Root.list()` boundary, and tracks
+canonical directories to stop symlink cycles. It does not hold a descriptor
+for the entire tree, so it is not a process sandbox against a hostile peer that
+can continuously swap and restore directories. Each individual lookup retains
+the documented Node `Root` boundary checks.
+
+Unlike `walkDirectory()` and `walkDirectorySync()`, `Root.walk()` is
+root-bounded and reports failures inline because an async iterator has no final
+result summary. Its default remains to throw on unreadable or invalid
+directories.
+
+## See also
+
+- [`fileStore`](file-store.md) — managed stores use bounded walking for pruning.
+- [Path scopes](path-scope.md) — boundary checks for known absolute paths.
+- [Migrating to 0.5](migrating-to-0.5.md) — adopting bounded pruning and partial-result handling.