@openclaw/signal 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/docs/test-hooks.md

@@ -0,0 +1,110 @@
+---
+title: Test hooks
+description: "Internal-only injection hooks used by the fs-safe test suite. Active only when NODE_ENV=test or VITEST=true."
+---
+
+# `@openclaw/fs-safe/test-hooks`
+
+Internal injection points the `fs-safe` test suite uses to deterministically reproduce open/lstat races. They are exposed as a public subpath so downstream test suites can reuse the same harness, but they are **not** part of the supported runtime API.
+
+```ts
+import {
+  getFsSafeTestHooks,
+  __setFsSafeTestHooksForTest,
+  type FsSafeTestHooks,
+} from "@openclaw/fs-safe/test-hooks";
+```
+
+## When the hooks are active
+
+Hooks are only honored when one of the following is true:
+
+- `process.env.NODE_ENV === "test"`
+- `process.env.VITEST === "true"`
+
+Calling `__setFsSafeTestHooksForTest(hooks)` outside of those environments throws. `getFsSafeTestHooks()` returns `undefined` when no hooks are registered, regardless of the environment.
+
+## Shape
+
+```ts
+type FsSafeTestHooks = {
+  afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
+  beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
+  afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterOpenedPathIdentityCheck?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterRootReadPathResolution?: (filePath: string) => Promise<void> | void;
+  beforeRootReadFinalFence?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+  afterRootReadFinalPathIdentityCheck?: (filePath: string, handle: FileHandle) => void;
+  beforeArchiveOutputMutation?: (operation: "mkdir" | "chmod", targetPath: string) => Promise<void> | void;
+  beforeFileStorePruneDescend?: (dirPath: string) => Promise<void> | void;
+  beforeFileStoreSyncPrivateWrite?: (filePath: string) => void;
+  beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
+  beforeRootStatObservation?: (targetPath: string) => Promise<void> | void;
+  beforeRootStatInitialObservation?: (targetPath: string) => Promise<void> | void;
+  beforeRootListObservation?: (directoryPath: string, withFileTypes: boolean) => Promise<void> | void;
+  afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
+  beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
+  beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
+  beforeTrashMove?: (targetPath: string, destPath: string) => void;
+  afterPublishTargetCreated?: (method, targetPath, identity) => Promise<void> | void;
+  beforePublishDirectorySync?: (method, targetPath, identity) => Promise<void> | void;
+};
+```
+
+| Hook | Fires when |
+|---|---|
+| `afterPreOpenLstat` | A pre-open `lstat` has just resolved. Use this to swap a path between validation and open. |
+| `beforeOpen` | The library is about to call `open(path, flags)`. Use this to inject a TOCTOU window. |
+| `afterOpen` | An open just succeeded. Use this to mutate state before the post-open identity check runs. |
+| `afterOpenedPathIdentityCheck` | A standalone local-file or absolute copy-source descriptor matches its pathname and the generic opened-path resolver is about to run. Root reads use their final admission hooks instead. |
+| `afterRootReadPathResolution` | A Root read path was resolved and has not yet entered local-file open admission. |
+| `beforeRootReadFinalFence` | A Root read descriptor passed pre-open/descriptor identity and hardlink checks and is about to enter its single final root/path/canonical-path/root admission fence. |
+| `afterRootReadFinalPathIdentityCheck` | The final pathname-to-descriptor comparison passed and the second root check has not run. This hook is synchronous-only. |
+| `beforeArchiveOutputMutation` | Archive staging is about to create a directory or apply a mode. |
+| `beforeFileStorePruneDescend` | File-store pruning is about to descend into a directory. |
+| `beforeFileStoreSyncPrivateWrite` | A synchronous private-store write is about to mutate its target. |
+| `beforeRootFallbackMutation` | A guarded JS root fallback is about to mkdir, move, or remove. |
+| `beforeRootStatObservation` | `Root.stat()` admitted its exact target and parent and is about to collect returned metadata. |
+| `beforeRootStatInitialObservation` | `Root.stat()` admitted its exact parent and is about to inspect the target for the first time. |
+| `beforeRootListObservation` | `Root.list()` admitted its exact selected directory and is about to collect names and optional metadata. |
+| `afterPinnedWriteFallbackRename` | A fallback rename committed and post-commit identity checks have not run yet. |
+| `beforeSiblingTempWrite` | A sibling temp file exists and its writer is about to run. |
+| `beforeSidecarLockSnapshotOpen` | A sidecar lock was inspected and is about to be opened for a bounded snapshot read. |
+| `beforeTrashMove` | Trash handling is about to move the target. |
+| `afterPublishTargetCreated` | Exclusive publication created its target and final fences have not run yet. |
+| `beforePublishDirectorySync` | Publication verified the target and is about to sync its parent directory. |
+
+Hooks typed `Promise<void> | void` may be sync or async and are awaited.
+Hooks used by synchronous code paths are typed `void` and must not return a
+promise.
+
+## Usage
+
+```ts
+import { afterEach, beforeEach } from "vitest";
+import { __setFsSafeTestHooksForTest } from "@openclaw/fs-safe/test-hooks";
+
+beforeEach(() => {
+  __setFsSafeTestHooksForTest({
+    beforeOpen: async (filePath) => {
+      // swap a victim file with a symlink right before fs-safe opens it
+      await replaceWithSymlink(filePath);
+    },
+  });
+});
+
+afterEach(() => {
+  __setFsSafeTestHooksForTest(undefined);
+});
+```
+
+Always clear the hooks in `afterEach` so a stuck hook does not leak across tests.
+
+## Stability
+
+The shape can grow new optional fields between minor versions. Treat the surface as test-only and do not rely on it from production code.
+
+## Related pages
+
+- [Testing](testing.md) — broader notes on testing against `fs-safe`.
+- [Security model](security-model.md) — the races these hooks help reproduce.

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,123 @@
+# 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.
+
+Finite delays above Node's single-timer limit (2,147,483,647 ms, about 24.9 days) are scheduled in bounded intervals without expiring early. The timer is still cleared if the wrapped promise settles first.
+
+## 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,211 @@
+# 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 })` and [`Root.entries()`](entries.md). 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 = {
+  assertBeforeMutation?: () => void;
+  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" | "follow-parents-within-root";
+  mutationSymlinks?: MutationSymlinkPolicy;
+};
+
+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` and `assertBeforeMutation` are exceptions: deny entries are merged, and the root authority assertion runs before the per-call assertion.
+
+## `RootReadOptions` / `RootWriteOptions` / `RootCopyOptions`
+
+```ts
+import type { CopyCloneMode, RootCopyPublicationReceipt } from "@openclaw/fs-safe";
+
+type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
+type RootWriteOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity" | "mutationSymlinks"> & {
+  encoding?: BufferEncoding;
+  overwrite?: boolean;
+};
+type RootCopyOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "durable" | "maxBytes" | "mkdir" | "mode" | "mutationSymlinks"> & {
+  sourceHardlinks?: "reject" | "allow";
+  overwrite?: boolean;
+  clone?: CopyCloneMode;
+  signal?: AbortSignal;
+  preserveSourceMode?: boolean;
+  onDestinationPublished?: (receipt: RootCopyPublicationReceipt) => void;
+};
+type RootOpenWritableOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mkdir" | "mode" | "mutationSymlinks"> & {
+  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, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+  overwrite?: boolean;
+};
+type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+  recursive?: boolean;
+  force?: boolean;
+  order?: "filesystem" | "sorted";
+  maxEntries?: number;
+  maxDepth?: number;
+  signal?: AbortSignal;
+};
+type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+  private?: boolean;
+};
+```
+
+Per-method option shapes. Each picks the `RootDefaults` keys that apply, plus method-specific extras.
+
+## `SymlinkPolicy` / `MutationSymlinkPolicy` / `HardlinkPolicy`
+
+```ts
+type SymlinkPolicy = "reject" | "follow-within-root" | "follow-parents-within-root";
+type MutationSymlinkPolicy = "reject" | "follow-parents-within-root";
+type HardlinkPolicy = "reject" | "allow";
+```
+
+`"reject"` is conservative; `"follow-within-root"` allows symlinks whose final target is still inside the root; `"allow"` (hardlinks only) is permissive. Defaults for read symlinks and hardlinks are `"reject"`; switch hardlinks to `"allow"` only when you intentionally accept hardlink aliases.
+
+`"follow-parents-within-root"` allows contained parent directory aliases while
+rejecting final symlinks. Mutation policy is opt-in and independent of read
+policy; omission preserves each mutation method's existing behavior.
+
+## `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.