@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,217 @@
+# 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).
+
+`ReplaceFileAtomicDestinationState` is also exported from that subpath. It is a
+readonly union of `{ state: "removed", path }` and
+`{ state: "writing" | "published", path, dev: bigint, ino: bigint }`. Both atomic
+replacement option types accept synchronous `assertBeforeMutation` and
+`onDestinationState` callbacks. See [authority and destination state](atomic.md#atomic-write-authority-and-destination-state).
+
+```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.

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

@@ -0,0 +1,283 @@
+# 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`.
+
+Each entry's `path` is absolute and retains the normalized spelling of the
+supplied root, including followed directory aliases. Paths do not switch to
+the canonical symlink target during descent.
+
+`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;
+};
+
+type AsyncWalkDirectoryOptions = Omit<WalkDirectoryOptions, "include" | "descend"> & {
+  include?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
+  descend?: (entry: WalkDirectoryEntry) => boolean | Promise<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.
+
+Before descending into a child directory, `skip` and `include` recheck whether
+that entry has become a symlink, including changes made while a filter waits.
+The explicitly supplied walk root may still be a symlink. This best-effort
+child check does not turn the standalone walker into a confinement boundary;
+use `Root.walk()` when root confinement is required.
+
+`include` controls which entries are returned. `descend` controls which directory entries are traversed. A skipped directory can still be returned if `include` accepts it.
+
+The asynchronous `walkDirectory()` accepts `AsyncWalkDirectoryOptions`. It resolves each `include` decision before calling `descend`, and resolves descent before reading the directory's children. Decisions run serially in the existing filesystem-order depth-first traversal. Both callbacks retain the supplied options object as their `this` receiver.
+
+Absent callbacks and primitive results keep the synchronous selection path. Object and function results are awaited directly, including promises and thenables. For JavaScript callers, nullish results retain the default `true`; other resolved values use their existing truthiness. Return booleans or promises of booleans for the typed API.
+
+```ts
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const scan = await walkDirectory("/safe/workspace", {
+  include: (entry) => entry.kind === "file",
+  descend: async (entry) => {
+    const marked = await fs.access(path.join(entry.path, "SKILL.md"))
+      .then(() => true, () => false);
+    return !marked;
+  },
+});
+```
+
+This prunes a directory after finding its marker without listing that directory's children. Callback throws and promise rejections reject the walk; they are not directory failures in `failedDirs`. Filtering still consumes the examined-entry budget. `WalkDirectoryOptions` and `walkDirectorySync()` remain synchronous; the async options do not add confinement or cancellation to the standalone walker.
+
+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" | "include"`, `order: "sorted" | "filesystem"`, and an `AbortSignal`. The default budget behavior yields
+one `kind: "truncated"` marker and ends; pass `limitBehavior: "throw"` for a
+typed `FsSafeError("too-large")` instead.
+
+For followed symlinks, both `kind` and `size` describe the resolved target.
+With `symlinkPolicy: "include"`, links retain `kind: "symlink"` and their own
+size. Targets are neither resolved nor visited; dangling and outside-root links
+are included. Filters receive these entries, and links consume the same entry
+budget as other names. A directory replaced by a symlink after observation
+fails with `path-mismatch` before descent, or produces a `directory-error`
+entry when `onDirectoryError` is `"skip-and-report"`.
+The starting directory retains existing Root path resolution; include mode
+controls the entries beneath that directory.
+
+```ts
+for await (const entry of capability.walk("", { symlinkPolicy: "include" })) {
+  if (entry.kind === "symlink") reportLink(entry.relativePath);
+}
+```
+
+Existing skip/follow calls keep their result types without a symlink variant.
+For explicitly annotated include-mode values, use `RootWalkOptions<"include">`
+and `RootWalkEntry<"include">`. `RootWalkSymlinkPolicy` describes all
+three policies when the policy is selected dynamically; the unparameterized
+entry and options types retain their previous shapes. Use
+`RootWalkOptions<RootWalkSymlinkPolicy>` for a dynamically selected policy.
+
+The caller's starting path retains Root home shorthand: `~` and `~/dir` expand
+the home directory when iteration starts and must resolve inside the Root.
+Home-started walks report actual Root-relative paths, such as `home/dir/file`,
+rather than `~/dir/file`. Use `./~/dir` to start at a literal `~` directory.
+An alias within a home-started path is reported under its admitted canonical
+target; ordinary non-home starting aliases retain their caller-supplied spelling.
+
+Entry names remain literal filesystem data, including a directory named `~`
+and its descendants. To reuse an entry path in another Root method without
+home-directory expansion, prefix it with `./`, as in
+`capability.open("./" + entry.relativePath)`.
+
+The default `order: "sorted"` visits each directory's names in lexicographic
+order before descending depth first. It reads and sorts all names in each
+visited directory. With `maxEntries`, it prepares small metadata batches capped
+by the remaining global entry budget. Every batch stops at the first directory
+or symlink, so recursive descent cannot spend a budget already used by later
+siblings. An early `break` may leave metadata from the current batch unused;
+the total still stays within `maxEntries`. Filtering requires metadata and
+consumes the entry budget, including entries skipped by the filter.
+
+Without `maxEntries`, sorted walks reuse a full directory metadata snapshot
+from the `Root.list()` owner. This preserves the existing fast complete-scan
+behavior and its snapshot semantics: changes made after a directory is listed
+do not alter its already-captured entries. Supply an entry budget or use
+filesystem order when metadata work must remain incremental. Sorted entries
+describe the observations captured in their directory snapshot or batch.
+
+Use `order: "filesystem"` when a wide directory must not be fully enumerated:
+
+```ts
+for await (const entry of capability.walk("", {
+  order: "filesystem",
+  maxEntries: 128,
+  symlinkPolicy: "skip",
+})) {
+  consume(entry);
+}
+```
+
+This order follows the filesystem's directory stream and is not deterministic.
+It reads one entry at a time, including one name of lookahead to distinguish an
+exactly exhausted budget from truncation. The lookahead does not request full
+entry metadata from fs-safe, and an early `break` does not prefetch later child
+metadata. If a filesystem does not supply directory-entry
+types, Node may classify that one extra entry with a synchronous `lstat`.
+Handles close on completion, truncation, cancellation, errors, or an
+early `break`. Both orders keep the same depth-first traversal, entry filtering,
+and truncation rules. Cancellation is checked between entries, with event-loop
+handoffs between budgeted sorted batches. Root and directory checks and admitted
+child metadata reads are synchronous; no mode can interrupt a filesystem
+syscall already in progress or the sorted mode's name sorting.
+
+If a thrown walk failure and directory close both fail, disposal throws a
+`SuppressedError` with the close failure in `error` and the original failure in
+`suppressed`, preserving both causes.
+
+`entryFilter` is evaluated for each resolved file, directory, or other entry.
+The `RootWalkEntryFilter` callback returns a `RootWalkEntryFilterResult`
+or a `Promise<RootWalkEntryFilterResult>`:
+
+```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"`.
+
+An asynchronous filter can inspect a marker before deciding whether to prune:
+
+```ts
+for await (const entry of capability.walk("", {
+  symlinkPolicy: "skip",
+  entryFilter: async (entry) => {
+    if (
+      entry.kind === "directory" &&
+      await capability.exists(`${entry.relativePath}/SKILL.md`)
+    ) {
+      return "skip-subtree";
+    }
+    return "include";
+  },
+})) {
+  consume(entry);
+}
+```
+
+Filters run serially outside metadata batches and retain the supplied options
+object as their `this` receiver. When an awaited filter resolves, the walk
+checks cancellation and revalidates the current listing directory and Root
+identities before using the decision. These checks do not refresh the entry's
+captured metadata or pin a later operation.
+
+Cancellation and iterator disposal wait for a pending filter to settle. The
+walk does not race the callback against the abort signal or close its directory
+while the callback is running; callbacks must settle their own work for
+cancellation to finish. Callback throws and promise rejections reject the walk
+through its normal cleanup path, even with `onDirectoryError: "skip-and-report"`.
+
+`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.
+This policy also applies when the directory or Root identity recheck after an
+awaited filter fails; callback failures themselves are not directory errors.
+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 through the Root boundary, pins
+its exact identity, and rechecks it and the Root identity around each metadata
+batch or individual filesystem-order observation. Sorted batches contain no
+await or caller code between their before/after checks. It tracks canonical
+directories to stop symlink cycles.
+Directory rechecks retain exact identities while using ordinary numeric metadata
+when it represents those identities without rounding. Large identities and
+Windows unknown-identity retries keep the bigint inspection path.
+Neither mode holds a descriptor for every path component, 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.