@openclaw/signal 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/docs/path-scope.md

@@ -0,0 +1,159 @@
+# pathScope()
+
+`pathScope()` prepares absolute paths and returns plain `{ ok, path }` results. `resolve()` and `resolveAll()` check lexical containment without touching the filesystem; `existing()`, `files()`, and `writable()` add the filesystem checks described below. Use it to prepare paths before handing them to another library, whose file-opening and mutation behavior still applies.
+
+```ts
+import { pathScope } from "@openclaw/fs-safe/advanced";
+
+const uploads = pathScope("/srv/uploads", { label: "uploads directory" });
+
+const photo = uploads.resolve("user/photo.jpg");
+if (!photo.ok) throw new Error(photo.error);
+
+await sharp(photo.path).resize(800).toFile(/* … */);
+```
+
+## When to reach for it
+
+`root()` is the right answer when you want method-style I/O (`fs.write`, `fs.readText`). `pathScope()` is the right answer when:
+
+- You're handing absolute paths to **other libraries** that take absolute path strings (Sharp, FFmpeg, `tar`, native modules) and just want the boundary check up front.
+- You want to validate user-supplied paths in bulk and return a typed `Result` rather than catching exceptions.
+- You want the scope's `label` to appear in the error message: `"Invalid path: must stay within uploads directory"`.
+
+## Signature
+
+```ts
+import type { FsSafeError } from "@openclaw/fs-safe/errors";
+
+function pathScope(rootDir: string, options: PathScopeOptions): PathScope;
+
+type PathScopeOptions = {
+  label: string;          // appears in error messages
+};
+
+type PathScopeResolveOptions = {
+  defaultName?: string;   // used when the requested path is empty
+};
+
+type PathResult = { ok: true; path: string } | { ok: false; error: string };
+type PathsResult = { ok: true; paths: string[] } | { ok: false; error: string };
+// Illustrative result alias, not a named package export.
+type DirectoryResult =
+  | { ok: true; path: string }
+  | { ok: false; error: string; diagnostic?: FsSafeError };
+
+type PathScope = {
+  rootDir: string;
+  label: string;
+  resolve(requestedPath: string, options?: PathScopeResolveOptions): PathResult;
+  resolveAll(requestedPaths: string[]): PathsResult;
+  existing(requestedPaths: string[]): Promise<PathsResult>;
+  files(requestedPaths: string[]): Promise<PathsResult>;
+  writable(requestedPath: string, options?: PathScopeResolveOptions): Promise<PathResult>;
+  ensureDir(requestedPath: string, options?: PathScopeResolveOptions & { mode?: number }): Promise<DirectoryResult>;
+};
+```
+
+## Methods
+
+### `resolve(rel, options?)`
+
+Synchronous, lexical only — no filesystem touch. Resolves the relative path against `rootDir` and verifies the result stays inside the scope. Use when you only need the path string:
+
+```ts
+const r = uploads.resolve("user/photo.jpg");
+if (!r.ok) return reply(400, r.error);
+console.log(r.path); // /srv/uploads/user/photo.jpg
+```
+
+If the requested path is empty, `defaultName` (when set) is used.
+
+### `resolveAll(rels)`
+
+Synchronous bulk resolve. Returns `{ ok: true, paths }` if every input is in scope, or `{ ok: false, error }` on the first failure.
+
+### `existing(rels)`
+
+Async. Like `resolveAll`, but additionally allows trusted absolute paths whose `realpath` is inside the scope. Useful when callers pass either a relative path or an absolute path you've already validated.
+
+### `files(rels)`
+
+Async. Strict variant: every input must already exist as a regular file inside the scope, with `nlink === 1`. Symlinked entries are rejected.
+
+### `writable(rel, options?)`
+
+Async. Resolves a writable target: requires the parent directory to already
+exist canonically inside the scope, refuses targets whose existing inode is a
+symlink or hardlinked, and returns the absolute path to use for the write. Use
+`ensureDir()` first when the parent needs to be created.
+
+```ts
+const t = await uploads.writable("reports/2026/05/report.pdf");
+if (!t.ok) return reply(400, t.error);
+await fs.writeFile(t.path, body);
+```
+
+### `ensureDir(rel, options?)`
+
+Async. `mkdir -p` inside the scope. Walks each segment, refuses any symlink in the path, creates missing directories. Optional `mode` sets the directory mode.
+
+Failures remain nonthrowing results with `error: string`. Policy rejections
+(including traversal, NUL input, symlinks and non-directory segments) omit
+`diagnostic`. Operational failures from `lstat`, `realpath` or `mkdir` include
+an `FsSafeError` with `code: "helper-failed"`, `category: "operational"`, and
+the exact original error in `cause`, including its native `code`, `errno` and
+`syscall` when available. Only `ensureDir()` adds this diagnostic; other scope
+methods retain their existing result shapes.
+
+`error` equals `diagnostic.message` for operational failures, for example
+`"Could not prepare uploads directory: ENAMETOOLONG during lstat"`. Display
+text bounds and escapes the label and native code/syscall, without copying
+the requested path or native error message. Treat the raw cause as sensitive
+local diagnostic data, not as text to return to an untrusted caller. A failure
+can leave already-created parent directories; it does not roll them back or
+retry through an unchecked filesystem path.
+
+```ts
+const dir = await uploads.ensureDir("inbox", { mode: 0o755 });
+if (!dir.ok) {
+  // Pass the cause only to an appropriately restricted local diagnostic sink.
+  if (dir.diagnostic) recordLocalFailure(dir.diagnostic.cause);
+  return reply(dir.diagnostic ? 500 : 400, dir.error);
+}
+```
+
+## Result type vs throwing
+
+`pathScope` returns `{ ok: true, path }` / `{ ok: false, error }` instead of throwing. This makes it pleasant to use at validation boundaries:
+
+```ts
+function handle(req: Req, res: Res) {
+  const r = uploads.resolve(req.body.path);
+  if (!r.ok) return res.status(400).json({ error: r.error });
+  return doWork(r.path);
+}
+```
+
+For exception-flavored APIs, use `root()` instead — it throws `FsSafeError` with a typed `code`.
+
+## Combine with `root()`
+
+A common pattern at the edge of an HTTP handler: validate the input with `pathScope`, do the I/O with `root()`:
+
+```ts
+const uploads = pathScope("/srv/uploads", { label: "uploads" });
+const fs = await root("/srv/uploads", { hardlinks: "reject" });
+
+const r = uploads.resolve(req.body.path);
+if (!r.ok) return reply(400, r.error);
+const rel = path.relative(fs.rootReal, r.path);
+
+const text = await fs.readText(rel);
+```
+
+## See also
+
+- [`root()`](root.md) — method-style boundary that throws on failure.
+- [Path helpers](path.md) — `isPathInside`, `safeRealpathSync`, `isWithinDir` for ad-hoc checks.
+- [Errors](errors.md) — error semantics (note: `pathScope` returns errors, doesn't throw).

package/node_modules/@openclaw/fs-safe/docs/path-suffix-aliases.md

@@ -0,0 +1,204 @@
+---
+title: Path suffix alias probing
+description: "Bounded local observations for selected missing relative path suffixes."
+---
+
+# Path suffix alias probing
+
+`probePathSuffixAliasesSync()` observes whether selected missing relative suffixes
+would alias beneath an existing directory. It returns `boolean | undefined`; it
+does not infer filesystem behavior from the operating system or normalize a path
+into an authorization decision.
+
+```ts
+import { probePathSuffixAliasesSync } from "@openclaw/fs-safe/advanced";
+
+const aliases = probePathSuffixAliasesSync({
+  directory: "/trusted/existing-directory",
+  left: "Reports/Caf\u00e9",
+  right: "reports/Cafe\u0301",
+});
+if (aliases === undefined) {
+  // The caller must choose an explicit ambiguity policy.
+}
+```
+
+Use this for suffixes that do not yet exist. For local ASCII-case observations,
+including an explicit read-only mode, use
+[`probePathCaseInsensitiveSync()`](path-case.md). Suffix probing has no read-only
+mode: a nontrivial observation can create and remove directories and requires an
+approved writable parent.
+
+## API and validation
+
+```ts
+type ProbePathSuffixAliasesOptions = {
+  directory: string;
+  left: string;
+  right: string;
+  maxDepth?: number;
+  shouldProbeCaseVariants?: (leftNfc: string, rightNfc: string) => boolean;
+};
+
+function probePathSuffixAliasesSync(
+  options: ProbePathSuffixAliasesOptions,
+): boolean | undefined;
+```
+
+The helper reads `directory`, rejects non-string values and supplied paths longer
+than 32,768 code units, then rejects NUL-containing inputs. It resolves the path
+to an absolute path and applies the same limit to that result before reading
+`maxDepth`. Each option is read once. Later option getters or the predicate cannot retarget a
+relative directory by changing the working directory. When
+filesystem observations are needed, the directory is canonicalized and its
+identity is checked; an initial directory alias can be followed.
+
+Suffixes must have the same number of ordinary relative path components. Empty
+components, `.` and `..`, absolute suffixes, NUL characters, and non-string path
+inputs are rejected with `TypeError`. Windows additionally rejects drive-relative
+components, colons, and reserved device names, including device aliases with
+extensions or trailing ignored characters. On POSIX, backslashes and colons are
+ordinary filename characters. The optional predicate must be a function.
+`maxDepth` defaults to `32` and must be a non-negative safe integer; invalid
+values, including `Infinity`, throw `RangeError` before mutation or an
+identical-suffix return. A value of `0` admits no ordinary nonempty suffix.
+
+Both suffixes and the predicate are validated before the identical-suffix fast
+path. Identical, valid, within-budget suffixes return `true` without filesystem
+access or a predicate call. This does not prove that the directory exists or that
+the suffix can be created.
+
+The forward-observation allowance never exceeds 32,768, even with a large
+`maxDepth`. A deeper or repeatedly colliding probe can return `undefined` when
+that ceiling is reached. Reverse cleanup still runs outside this allowance.
+
+## Resource budgets
+
+The default limits for one call are:
+
+| Resource | Limit | On exceeding the limit |
+|---|---|---|
+| Each supplied suffix | 8,192 UTF-16 code units | `RangeError` before mutation |
+| Supplied and resolved directory paths | 32,768 UTF-16 code units each | `RangeError` before mutation |
+| Each suffix's component count | `maxDepth`, default 32 | `RangeError` before mutation |
+| Directory-creation attempts | 128 | `undefined` after cleanup |
+| Successfully created probe directories | 64 | `undefined` after cleanup |
+| Forward filesystem observations | 4,096 | `undefined` after cleanup |
+| Each generated actual path | 32,768 UTF-16 code units | `undefined` after cleanup |
+
+### Deeper observations
+
+Applications comparing deeper prospective paths can explicitly raise `maxDepth`:
+
+```ts
+const prefix = "future/".repeat(32);
+const aliases = probePathSuffixAliasesSync({
+  directory: "/trusted/existing-directory",
+  left: `${prefix}Report.sqlite`,
+  right: `${prefix}report.sqlite`,
+  maxDepth: 33,
+});
+```
+
+The 8,192-code-unit suffix limit and 32,768-code-unit path limits remain fixed.
+Ordinary-component validation, Windows path controls, identity checks, and
+cleanup rules also remain unchanged.
+
+Operation budgets grow proportionally from the actual admitted suffix depth,
+not the requested `maxDepth`. For actual depth `D`, let `B = max(32, D)`.
+Directory-creation attempts are limited to `4 × B`, successfully created
+directories to `2 × B`, and forward filesystem observations to `min(32,768, 4 × B²)`.
+The quadratic observation allowance accommodates rechecks of owned ancestors.
+
+For example, 33 components allow 132 creation attempts, 66 created directories,
+and 4,356 forward observations; 65 components allow 260, 130, and 16,900.
+Specifying a large `maxDepth` for a short suffix keeps the original budgets.
+The suffix-length limit bounds actual depth to at most 4,096, so every budget
+remains a finite safe integer.
+
+Admission does not guarantee a boolean result. Repeated collisions, many
+normalization probes, filesystem limits, or identity failures can exhaust the
+budget or prevent an observation. The helper then returns `undefined` after
+cleanup attempts; callers must preserve their explicit ambiguity policy.
+
+Input limits are checked even for identical suffixes. Dynamic budgets count work
+across the whole call, including collision retries; removing a probe does not
+restore its creation budget. Cleanup is still attempted when a forward budget is
+exhausted and is not disabled by that exhausted budget.
+
+Candidates are generated lazily, only as needed. The helper does not eagerly
+allocate every possible probe name or consume randomness for unused retries.
+These are count and string-size limits, not a wall-clock guarantee. Synchronous
+filesystem calls, randomness, and caller code can block; the helper cannot
+interrupt them or promise a maximum elapsed time.
+
+## Results and caller policy
+
+- `true`: the suffixes are identical, or the requested observations found aliases.
+- `false`: an observation found distinct entries, or the caller's predicate
+  excluded a pair.
+- `undefined`: no reliable answer was obtained, including filesystem failures,
+  identity changes, exhausted collision candidates or dynamic budgets, generated
+  path limits, or incomplete cleanup.
+
+`undefined` is not evidence of either case sensitivity or aliasing. The helper
+does not cache observations, choose a fallback, reserve the future destination,
+or establish a root-confinement boundary. A result applies only to the local
+observations made during that call, not to every Unicode pair, mount, or later
+filesystem state.
+
+The optional trusted, synchronous `shouldProbeCaseVariants` predicate receives
+NFC-normalized component pairs when they differ and are not equivalent under
+ASCII case folding. Without a predicate, those pairs are eligible for probing.
+It is called in component order. Returning `false` excludes
+that pair and produces `false`; it is caller policy, not a filesystem finding.
+A first-component exclusion needs no probes or randomness. A later exclusion
+can follow earlier mutations, so it does not make the call read-only.
+
+A non-boolean predicate result throws `TypeError`; a predicate exception is
+re-thrown unchanged after cleanup attempts. Cleanup problems do not replace the
+original predicate failure. Do not use an asynchronous predicate or rely on the
+resource limits to bound arbitrary callback work.
+
+## Probe design
+
+The helper works through corresponding components, creating nested directories
+to observe inherited lookup behavior. ASCII-case probes use generated names.
+Normalization probes retain the original non-ASCII spellings while substituting
+suitable ASCII letters. When a generated pair is unavailable, the exact raw pair
+can be tried inside an owned neutral directory. Requested names are never
+materialized directly in the caller's unowned parent.
+
+Generated names are conservatively excluded when their NFC lowercase or uppercase
+forms could collide with either requested component. These folds are only a name
+exclusion rule; they never classify two requested paths as aliases. Short neutral
+and ASCII probe names use at most six characters and are no longer than the
+shorter requested component. Generated normalization pairs are also limited by
+the longer original joined path length. A raw-pair fallback adds a directory
+level; filesystem-specific name or path limits can still make it unavailable.
+
+Probes use normal directory creation and the process umask, preserving inherited
+directory behavior. They do not force mode `0700`, change parent permissions, or
+promise private probe names. Creation and removal can affect directory timestamps
+and filesystem watchers.
+
+## Identity and cleanup limitations
+
+The requested directory, canonical parent, and owned probe chain are rechecked
+with exact bigint filesystem identities. An alternate spelling must identify the
+same ordinary directory, not a symlink or unrelated collision. Existing files,
+directories, and symlinks at a candidate name are not removed to make room.
+
+Cleanup attempts owned directories in reverse order with identity checks and
+non-recursive removal. Nonempty directories and observed replacements are
+preserved. A cleanup failure changes an otherwise boolean result to `undefined`.
+If the first identity observation after a successful creation fails, a directory
+can remain: the helper does not guess ownership to delete it.
+
+This is a pathname-based observation helper, not an atomic filesystem
+transaction. There are unavoidable gaps between creation and the first identity
+observation, and between an identity check and a subsequent syscall. No pinned
+directory handle or atomic conditional deletion closes those gaps. Use a trusted,
+approved writable directory and application-level concurrency control where
+needed; do not use this helper as authorization to access attacker-controlled
+paths.

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

@@ -0,0 +1,219 @@
+# Path helpers
+
+`@openclaw/fs-safe/path` is the lower-level lexical and canonical path surface — useful when you have your own logic that needs to know "is this path inside that directory" without going through `root()` or `pathScope()`.
+
+```ts
+import {
+  isPathInside,
+  isPathInsideWithRealpath,
+  isWithinDir,
+  resolveSafeBaseDir,
+  safeRealpathSync,
+  safeStatSync,
+  assertNoNulPathInput,
+  assertNoUnsafeDeviceReadPath,
+  isUnsafeDeviceReadPath,
+  isNotFoundPathError,
+  isSymlinkOpenError,
+  hasNodeErrorCode,
+} from "@openclaw/fs-safe/path";
+```
+
+Path helpers are deliberately a subpath import so the main entry stays focused
+on the root capability, its shared configuration, errors, and external-output
+helper.
+
+## Boundary checks
+
+### `isPathInside(rootDir, target)`
+
+Pure lexical check. Returns `true` if `target` is `rootDir` itself or a descendant, after normalizing both inputs. **Does not** touch the filesystem — does not follow symlinks.
+
+```ts
+isPathInside("/srv/uploads", "/srv/uploads/photo.jpg");      // true
+isPathInside("/srv/uploads", "/srv/uploads/../escape.txt");  // false
+isPathInside("/srv/uploads", "/srv/uploads-other/x");        // false
+isPathInside("/srv/uploads", "/srv/uploads");                // true (root itself counts)
+```
+
+The check is platform-aware: on Windows, paths are normalized for case and separator before comparison. This is deliberately a string-only, lexical answer; case folding does not prove that two differently cased prefixes name the same directory on a case-sensitive Windows directory. Root operations perform their own filesystem-identity admission when containment depends on case folding.
+It is a lexical comparison, not a filesystem-admission boundary: it does not
+reject Windows alternate data streams or index-allocation aliases. Use a
+filesystem operation such as `root()` when a caller-controlled path will be
+opened or mutated.
+
+### `isPathInsideWithRealpath(rootDir, target, opts?)`
+
+Synchronous. First requires lexical containment with `isPathInside`, then resolves both inputs through `realpath` and checks containment again. A lexically outside path is rejected even if its resolved target is inside the root.
+
+```ts
+isPathInsideWithRealpath("/srv/uploads", "/srv/symlink-to-elsewhere"); // false
+```
+
+```ts
+type Options = {
+  requireRealpath?: boolean;            // default true
+  cache?: Map<string, string>;
+};
+```
+
+Does not throw on missing inputs — `realpath` failures are absorbed by the underlying `safeRealpathSync`. By default (`requireRealpath: true`) the function returns `false` when either input cannot be resolved. Pass `{ requireRealpath: false }` to fall back to the lexical answer from `isPathInside` instead.
+On Windows it returns `false` for namespace aliases in either raw input or in
+a canonical value returned by `realpath` or the supplied cache. The
+`requireRealpath: false` fallback does not admit those aliases.
+
+### `isWithinDir(rootDir, targetPath)`
+
+Convenience wrapper around `isPathInside`. Same semantics, different name kept for callers that prefer the noun phrase.
+
+### `resolveSafeBaseDir(rootDir)`
+
+Resolve a base directory to an absolute, normalized form ready for prefix comparison. Pre-normalized directories make subsequent `isPathInside` checks unambiguous.
+
+```ts
+const base = resolveSafeBaseDir("/srv/uploads/.");  // "/srv/uploads/"
+```
+
+## Realpath and stat
+
+### `safeRealpathSync(targetPath, cache?)`
+
+Synchronous `realpath` that returns `null` instead of throwing on any error. Pass an optional `Map<string, string>` to cache results across calls within a single operation.
+
+```ts
+const real = safeRealpathSync("/srv/uploads/photo.jpg");
+if (real === null) return notFound();
+```
+
+All `realpath` failures collapse to `null` — there is no distinction between `ENOENT`, `EACCES`, and other I/O errors. Use `fs.realpathSync` directly if you need to branch on the error code.
+This convenience wrapper preserves ordinary Node `realpath` semantics; it is
+not a caller-path admission boundary on its own.
+
+### `safeStatSync(targetPath)`
+
+Synchronous `stat` that returns `Stats` on success and `null` on any failure,
+including missing paths and permission errors. Use `fs.statSync` directly when
+the distinction matters.
+Like `safeRealpathSync`, it does not apply the pathname-admission policy used
+by the higher-level filesystem boundaries.
+
+```ts
+const stat = safeStatSync("/srv/uploads/photo.jpg");
+if (!stat?.isFile()) return notFound();
+```
+
+### `assertNoNulPathInput(filePath, message?)`
+
+Throws `FsSafeError` with code `invalid-path` when a path string contains an embedded NUL byte. Use it before calling Node `fs` APIs directly; Node's native error can include raw path text in the message.
+
+### `assertNoUnsafeDeviceReadPath(filePath, options?)`
+
+Throws `FsSafeError` with code `device-path` when a read target is a known unsafe device or process-fd path. The built-in read/open helpers call this automatically before opening files; use it only when you are building your own read primitive.
+
+```ts
+assertNoUnsafeDeviceReadPath("/dev/zero"); // throws on POSIX
+isUnsafeDeviceReadPath("/dev/fd/0");       // true on POSIX
+```
+
+The check is intentionally not a normal consumer policy knob. Safe read APIs reject these targets by default because they can block forever, stream indefinitely, or alias process file descriptors.
+
+## Error inspection
+
+### `isNotFoundPathError(err)`
+
+`true` if the error has code `ENOENT` (file or directory missing) or `ENOTDIR` (a path component is not a directory).
+
+```ts
+try {
+  await fs.readFile(p);
+} catch (err) {
+  if (isNotFoundPathError(err)) return null;
+  throw err;
+}
+```
+
+### `isSymlinkOpenError(err)`
+
+`true` if the error indicates a symlink-related open failure (typically `ELOOP` or platform-specific symlink rejections from `O_NOFOLLOW`).
+
+### `hasNodeErrorCode(err, code)`
+
+Generic helper. `true` if `err` is a `NodeJS.ErrnoException` with the matching `code` string.
+
+```ts
+if (hasNodeErrorCode(err, "EACCES")) return reply(403);
+```
+
+## When to use these vs `root()`
+
+| Path helpers | `root()` |
+|---|---|
+| Pure functions over absolute path strings. | Boundary handle with method-style I/O. |
+| No I/O performed (except `safeRealpathSync`/`safeStatSync`). | Every method goes to disk. |
+| Fits inside other helpers / validation pipelines. | Standalone consumer of caller-supplied paths. |
+
+If you're writing a validator that says "is this safe?" without performing the operation, the path helpers are the right tool. If you're going to perform the read or write, use `root()` so the boundary check is fused with the operation.
+
+## Common patterns
+
+### "Resolve, then assert it's inside my dir"
+
+```ts
+import { isPathInsideWithRealpath, isNotFoundPathError } from "@openclaw/fs-safe/path";
+
+let canonical: string;
+try {
+  canonical = await fs.realpath(input);
+} catch (err) {
+  if (isNotFoundPathError(err)) return reply(404);
+  throw err;
+}
+if (!isPathInsideWithRealpath("/srv/uploads", canonical)) {
+  return reply(403);
+}
+```
+
+### Cache realpaths in a request scope
+
+```ts
+const cache = new Map<string, string>();
+for (const p of inputs) {
+  const real = safeRealpathSync(p, cache);
+  if (real && isPathInside(root, real)) keep.push(real);
+}
+```
+
+### Branch on `ENOENT` vs other errors
+
+```ts
+try {
+  return await fs.readFile(p);
+} catch (err) {
+  if (isNotFoundPathError(err)) return null;
+  if (hasNodeErrorCode(err, "EACCES")) return null;
+  throw err;
+}
+```
+
+## Path-policy helpers
+
+`path-policy.ts` exposes two assertions used by `root()` internally; they are exported for callers building their own helpers:
+
+```ts
+import {
+  assertNoPathAliasEscape,
+  assertNoHardlinkedFinalPath,
+  PATH_ALIAS_POLICIES,
+} from "@openclaw/fs-safe/advanced";
+```
+
+- `assertNoPathAliasEscape({ absolutePath, rootPath, boundaryLabel, policy? })` — async. Applies root path resolution and final hardlink checks. `policy` defaults to `PATH_ALIAS_POLICIES.strict`; `PATH_ALIAS_POLICIES.unlinkTarget` permits final symlink and hardlink aliases for unlink operations.
+- `assertNoHardlinkedFinalPath({ filePath, root, boundaryLabel, allowFinalHardlinkForUnlink? })` — async. Rejects a regular file with `nlink > 1`; missing paths and nonregular resolved entries are ignored. Setting `allowFinalHardlinkForUnlink: true` skips this check for unlink operations.
+
+Use these when writing a custom helper that wants the same guards `root()` uses but with different surrounding logic.
+
+## See also
+
+- [`root()`](root.md) — the high-level boundary that uses these checks internally.
+- [`pathScope()`](path-scope.md) — `Result`-style scope checks.
+- [Reading](reading.md) — `Root.read()` and friends use `isPathInside` + identity checks.