@openclaw/matrix 2026.9.6 → 2026.9.8

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

@@ -0,0 +1,240 @@
+# Errors
+
+Every failure that's the library's job to surface lands as an `FsSafeError` with a closed `code` union you can branch on. Catch by code, not by message text — messages may change, codes will not.
+
+Result-based APIs are an exception to throwing: [`pathScope().ensureDir()`](path-scope.md#ensuredir-rel-options)
+and `ensureDirectoryWithinRoot()` return operational failures as
+`{ ok: false, error: string, diagnostic: FsSafeError }`. The diagnostic uses
+`helper-failed` / `operational`, retains the exact native error in `cause`, and
+has the same message as `error`. Its display text names the native code/syscall
+when available but omits raw paths and native messages. Policy failures keep
+the string-only result without `diagnostic`; other `pathScope` methods do not
+gain this field. Directory preparation can partially complete before failing.
+
+Path and archive-entry details embedded in diagnostics escape control characters
+as `\\uXXXX` sequences. This keeps attacker-controlled names on one log line;
+the escaped message is for diagnosis, not for reconstructing the original path.
+
+```ts
+import { FsSafeError, type FsSafeErrorCode } from "@openclaw/fs-safe";
+```
+
+## Shape
+
+```ts
+class FsSafeError extends Error {
+  readonly name: "FsSafeError";
+  readonly code: FsSafeErrorCode;
+  readonly category: "policy" | "operational";
+  readonly details?: Readonly<Record<string, unknown>>;
+
+  constructor(
+    code: FsSafeErrorCode,
+    message: string,
+    options?: { cause?: unknown; details?: Readonly<Record<string, unknown>> },
+  );
+}
+```
+
+`cause` is available through the standard `Error` `cause` property when the failure was triggered by a `NodeJS.ErrnoException` (e.g. a wrapped `EACCES`). Inspect it for the original `code` / `errno` / `syscall` if you need finer-grained reporting.
+
+Guarded write preparation describes permission, read-only filesystem, and disk-space
+failures with messages such as `permission denied (EACCES)` or
+`no space left on device (ENOSPC)`. Other errno failures include their code in
+`filesystem write failed (EIO)`. These wrappers retain the existing `invalid-path`
+code and `policy` category for compatibility, along with the original `cause`;
+they do not expose native message text or paths. Already-classified `FsSafeError`
+instances and missing-path errors keep their existing classification.
+
+`details` is an operation-specific receipt, not an alternate error code. For
+example, `publishFileExclusive()` uses it to report the failing phase, created
+target identity, cleanup decision, and failed directory-sync outcome. Narrow
+by `code` and a documented details field before consuming it; do not assume all
+`FsSafeError` instances carry the same keys.
+
+`replaceFileAtomic({ copyFallbackRestore: "restore-original" })` reports a
+failed copy fallback with the exported `ReplaceFileAtomicRestoreFailureDetails`
+shape:
+
+```ts
+type ReplaceFileAtomicRestoreFailureDetails = {
+  cleanup: "restored" | "restore-failed";
+};
+```
+
+Both outcomes use `code: "helper-failed"`. `"restored"` means the original
+snapshot was written back and fsynced through the pinned destination handle.
+`"restore-failed"` means both the replacement and recovery failed; `cause` is
+an `AggregateError` containing both failures. A snapshot that exceeds
+`maxRestoreBytes` fails earlier with `too-large` and does not overwrite the
+destination.
+
+`category` separates caller-policy failures from operational failures:
+
+- `"policy"` — unsafe input or target state rejected by a safety policy, such as `outside-workspace`, `symlink`, `hardlink`, or `too-large`.
+- `"operational"` — routine filesystem outcomes or environment/runtime failures, such as `not-found`, `not-empty`, `not-removable`, helper startup, platform support, timeout, or unverifiable permissions.
+
+Routine absence or inability to remove a path does not by itself indicate a
+filesystem boundary violation. Branch on the specific code when the distinction
+between those operational outcomes matters.
+
+The operational set is exactly `helper-failed`, `helper-unavailable`,
+`not-empty`, `not-found`, `not-removable`, `permission-unverified`, `read-failed`,
+`timeout`, and `unsupported-platform`. Every other current `FsSafeErrorCode`, including
+`store-reentrant-update`, is categorized as `policy`.
+
+## Code union
+
+```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";
+```
+
+## Code reference
+
+| Code | When it fires | Common causes |
+|---|---|---|
+| `already-exists` | `create()`, `createJson()`, `move({ overwrite: false })`. | Target file or directory already at the destination. |
+| `denied-path` | A root mutation matched `denyMutations.paths` or `denyMutations.prefixes`. | Caller configured application-sensitive paths that must not be written, removed, moved, or created. |
+| `device-path` | A read/open target is a known unsafe device or process-fd path. | `/dev/zero`, `/dev/random`, `/dev/stdin`, `/dev/fd/*`, `/proc/*/fd/*`, or a Windows reserved device name. |
+| `hardlink` | Read or copy with `hardlinks: "reject"` saw `nlink > 1`. | File is hardlinked — possibly an alias of an out-of-tree inode. |
+| `helper-failed` | A native mechanism or multi-step operational helper failed. | Inspect `cause` and any operation-specific `details`; retrying may be unsafe if the operation partially completed. |
+| `helper-unavailable` | A required native binding or bounded primitive could not be loaded. | Unsupported platform, omitted/missing/incompatible platform package, `FS_SAFE_NATIVE_MODE=off`, or a no-clobber `Root.move()` without safe native parent admission. `auto` falls back only where a safe fallback exists. |
+| `insecure-permissions` | A secure file or path permission check found a mode/ACL that allows broader access than requested. | File or directory is group/world writable/readable; Windows ACL grants broad read. |
+| `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable; a FileStore key used a noncanonical spelling. | Noncanonical FileStore aliases, backslashes, or complete parent segments; a network path on Windows; a drive-relative segment in a portable relative path or store key; or a leading drive-relative spelling such as `C:name` used as a Root destination. Existing-object Root lookups retain broader confined path compatibility, including legal POSIX drive-like names. |
+| `not-empty` | Nonrecursive `remove()` on a non-empty directory, or new children appeared during recursive removal. | Use bounded `recursive: true` removal or coordinate concurrent writers. |
+| `not-file` | Read or copy targeted a non-regular file, or a path walk found a non-directory ancestor. | Target was a directory, FIFO, socket, device, or an existing file was followed by another segment. |
+| `not-found` | The target does not exist (or its parent does not, with `mkdir: false`). | Typical missing-file case. |
+| `not-owned` | A secure file owner check failed. | File is owned by another UID. |
+| `not-removable` | `remove()` couldn't inspect a directory stream or `unlink`/`rmdir` for a reason other than non-empty. | Permissions, device busy, immutable bit; the original filesystem error remains in `cause`. |
+| `outside-workspace` | Path resolves outside the configured root. | `..` traversal; absolute path outside the root; symlink resolved out. |
+| `path-alias` | A path alias check failed (e.g. canonical-real-path moved out of the root). | Symlink resolution lands outside the root. |
+| `path-mismatch` | Post-open identity check failed: the opened fd does not match the resolved path. | TOCTOU — something else swapped the path between resolve and open. |
+| `permission-unverified` | A secure file check could not verify required permissions. | Windows ACL inspection failed; POSIX ownership/mode was unavailable. |
+| `read-failed` | A validated file could not be read because of an operational filesystem or device failure. | I/O error, media failure, or another runtime read failure; inspect `cause`. |
+| `secret-exists` | `createSecretFileAtomic()` found an existing final path. | First-writer-wins secret creation lost a race or the credential was already initialized. |
+| `store-reentrant-update` | A `JsonStore.update()` callback called `update()` or `updateOr()` for the same canonical store before returning. | Reentrant mutation would deadlock or lose an update; return the complete next value from the outer callback. |
+| `symlink` | Path component is a symlink, policy is `reject`. | Caller followed a symlink they shouldn't have, or `symlinks: "reject"` is set. |
+| `timeout` | An operation with a wall-clock budget overran. | Secure file read or timed operation exceeded `timeoutMs`. |
+| `too-large` | A read, bounded walk, or recursive removal exceeded its configured budget. | Review the expected file or tree size before increasing the limit; recursive removal may have completed earlier entries. |
+| `unsupported-platform` | The platform or filesystem cannot perform the requested operation. | `createCloneSource` and `copyTree({ clone: "always" })` require native cloning support. The default `copyTree({ clone: "auto" })` selects portable byte copying when cloning is unavailable; unsupported source contents or metadata still fail. See [directory copying](copy.md) for backend limits and fallback behavior. |
+
+Secret writes reject invalid `mode` / `dirMode` values with `invalid-path` before directory creation. Existing secret directories with a mode different from the requested `dirMode` report `insecure-permissions` without chmod; a created directory whose descriptor ownership no longer matches its initializing effective user reports `not-owned`.
+
+Pathname `sha256File()` and `sha256FileSync()` also report `path-mismatch` when
+pre-open, descriptor, or current-path identity remains unknown after one bounded
+Windows retry, even if the file is benign. Neither reopens to recover identity.
+Preview symlinks report `symlink`, preview or descriptor non-files report
+`not-file`, and a current-path symlink or non-file reports `path-mismatch`.
+
+## Branching
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe";
+
+try {
+  await fs.write("../escape.txt", "x");
+} catch (err) {
+  if (!(err instanceof FsSafeError)) throw err;
+  switch (err.code) {
+    case "outside-workspace":
+      return reply(400, "path escapes workspace");
+    case "already-exists":
+      return reply(409, "exists");
+    case "too-large":
+      return reply(413, "too large");
+    case "not-found":
+      return reply(404, "missing");
+    case "symlink":
+    case "device-path":
+    case "hardlink":
+    case "path-mismatch":
+    case "path-alias":
+      return reply(400, "unsafe path");
+    default:
+      throw err;
+  }
+}
+```
+
+The `default` above deliberately rethrows unknown codes, so it remains safe as
+the union grows. If you want the compiler to flag every newly added code, end
+an exhaustive switch with a `never` assertion instead of a general `default`.
+
+## Distinguishing from `NodeJS.ErrnoException`
+
+Some failures bubble up as native Node errors (e.g. `EACCES`, `EPERM`, `EISDIR`, `EBUSY`) when they don't map cleanly to a library code. Inspect both:
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe";
+
+try {
+  await op();
+} catch (err) {
+  if (err instanceof FsSafeError) {
+    handleFsSafe(err);
+    return;
+  }
+  const code = (err as NodeJS.ErrnoException).code;
+  if (code === "EACCES" || code === "EPERM") {
+    handleAccess();
+    return;
+  }
+  throw err;
+}
+```
+
+A common pattern is to wrap your domain code in a single try/catch that maps both shapes to your application's typed error format.
+
+On Windows, access-denied failures from native root/open filesystem operations
+use `EPERM` to match Node/libuv and the JavaScript fallback. Security-descriptor
+inspection has its own failure surface. Older fs-safe versions could report
+`EACCES` for the same root/open condition, so consumers spanning versions
+should accept both codes.
+
+## Specialty errors
+
+A handful of helpers throw their own typed errors instead of `FsSafeError`:
+
+- `JsonFileReadError` — thrown by [`readJson`](json.md). Carries `cause` so you can distinguish missing (`ENOENT`) from invalid (`SyntaxError`).
+- `ArchiveLimitError` — thrown by [`extractArchive`](archive.md) when an archive size, entry count, path depth, metadata, or extracted-byte budget is exceeded. The `code` field uses the string values exposed by `ARCHIVE_LIMIT_ERROR_CODE` (for example `archive-entry-path-components-exceeds-limit`).
+- `ArchiveSecurityError` — thrown by extraction when entry policy or destination safety fails. Entry codes are `entry-path`, `entry-link`, and `entry-filtered`; destination codes cover non-directory, symlink, and symlink-traversal failures.
+
+These are exported from their respective subpaths.
+
+## Why `FsSafeError`?
+
+Two reasons it isn't a richer hierarchy of subclasses:
+
+1. **Switch on `code`, don't `instanceof` a tree.** `code` is a closed string union the TypeScript compiler can exhaust-check. Subclasses make `instanceof` ladders that drift over time.
+2. **One catch handler.** Library callers often want a single "is this an `fs-safe` failure?" gate before deciding what to do — `instanceof FsSafeError` plus a switch is the cleanest expression of that.
+
+## See also
+
+- [`root()`](root.md) — every method documents the codes it can throw.
+- [Reading](reading.md) — read-path codes.
+- [Writing](writing.md) — write-path codes.
+- [Archive extraction](archive.md) — `ArchiveLimitError` and `ArchiveSecurityError`.

package/node_modules/@openclaw/fs-safe/docs/file-contents.md

@@ -0,0 +1,68 @@
+# Exact file comparison
+
+`sameFileContentsSync()` compares the bytes of two already-open regular files,
+starting at offset zero. It uses bounded buffers and completes positive short
+reads independently on each descriptor. A `true` result requires matching bytes
+and observed EOF on both inputs; a difference can return `false` immediately.
+
+```ts
+import fs from "node:fs";
+import { sameFileContentsSync } from "@openclaw/fs-safe/advanced";
+
+const source = fs.openSync("/trusted/source.sqlite", "r");
+try {
+  const copy = fs.openSync("/trusted/copy.sqlite", "r");
+  try {
+    console.log(sameFileContentsSync(source, copy, { maxBytes: 256 * 1024 * 1024 }));
+  } finally {
+    fs.closeSync(copy);
+  }
+} finally {
+  fs.closeSync(source);
+}
+```
+
+## Signature
+
+```ts
+type SameFileContentsOptions = { maxBytes?: number };
+
+function sameFileContentsSync(
+  leftFd: number,
+  rightFd: number,
+  options?: SameFileContentsOptions,
+): boolean;
+```
+
+Both descriptors must be open regular files. Nonregular inputs throw
+`FsSafeError("not-file")`; underlying filesystem errors propagate unchanged.
+Passing the same descriptor twice is allowed, but does not bypass validation,
+the byte limit, or reads. File sizes are checked against the limit, but are not
+used as proof that contents match or that EOF has been reached.
+
+## Bounds and ownership
+
+`maxBytes` is a limit for each file, not their combined size. It accepts a
+non-negative safe integer or `Infinity`; omission imposes no caller-selected
+limit. Invalid limits throw `RangeError` before filesystem work. Comparisons
+cannot exceed `Number.MAX_SAFE_INTEGER` bytes because positions must remain
+exactly representable.
+
+A reported file size above the limit throws `FsSafeError("too-large")` before
+reading. At the limit, the comparison reads at most one additional byte from
+each input to prove EOF; any observed overflow throws the same error. A
+matching prefix is never reported as complete equality. An early mismatch
+does not scan the remaining bytes or promise to detect later errors or growth.
+A zero-byte limit admits two empty files. Memory use is at most two 1 MiB
+payload buffers, regardless of file size.
+
+The operation neither changes the descriptors' current offsets nor closes
+them, including on failure. It performs no writes, hashing, pathname lookup,
+or identity comparison. Callers retain path admission, hardlink policy,
+descriptor lifetime, and any before/after mutation-fingerprint checks. A
+comparison is not a snapshot of concurrently modified files; applications
+requiring stable contents must retain their existing coordination and checks.
+
+Use [`readFileWindowFullySync()`](positional-read.md) for a selected byte
+window and [bounded descriptor reads](advanced.md#files-and-identity) when the
+caller needs the file contents in memory.

package/node_modules/@openclaw/fs-safe/docs/file-store.md

@@ -0,0 +1,369 @@
+# File store
+
+`fileStore` is exported from `@openclaw/fs-safe/store`. It is a managed wrapper around `root()` for the common "store files under a directory at known modes, prune old ones, hand back absolute paths" pattern. Useful for caches, ingest staging, generated artifacts, anywhere the consumer wants object-style access plus stream and copy primitives.
+
+```ts
+import {
+  fileStore,
+  type FileStore,
+  type FileStoreOptions,
+  type FileStoreWriteOptions,
+  type FileStorePruneOptions,
+} from "@openclaw/fs-safe/store";
+```
+
+## When to reach for it
+
+- You want a single directory holding files written by your code, with consistent mode bits and atomic placement.
+- You want a `FileStore.write(rel, data)` / `read(rel)` / `pruneExpired(...)` interface.
+- You want to feed a stream into the store with a byte cap.
+- You don't need the full `Root` surface (move, list, mkdir, …); the store can hand you a real `Root` via `.root()` when you do.
+
+## Factory: `fileStore(options)`
+
+```ts
+const cache = fileStore({
+  rootDir: "/var/cache/app",
+  mode: 0o600,        // file mode for writes (default 0o600)
+  dirMode: 0o700,     // mode for parent directories created on demand (default 0o700)
+  maxBytes: 64 * 1024 * 1024, // optional: refuse writes/reads larger than this
+  private: true,      // use secret-file atomic writes for private state
+  durable: true,      // sync file and parent directory (default true)
+});
+```
+
+| `FileStoreOptions` option | Default | Purpose |
+|---|---|---|
+| `rootDir` | Required | Store directory. |
+| `private` | `false` | Use the secret-file atomic path. |
+| `mode` / `dirMode` | `0o600` / `0o700` | File and parent-directory modes. |
+| `maxBytes` | Unset | Store read/write byte limit. |
+| `durable` | `true` | Sync the written file and its parent directory; see method support below. |
+
+Store and per-call `maxBytes` values must be non-negative safe integers or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` disables the cap. An omitted or explicitly `undefined` per-call value preserves the store-level limit. The same rule applies to buffer writes, streams, copies, async reads, and synchronous reads/writes.
+
+Use `private: true` for credentials, auth profiles, tokens, and other private
+state. Private mode keeps the same `FileStore` shape but routes writes through
+the secret-file atomic path, refusing symlink parent components and re-asserting
+mode after rename.
+
+Returns a `FileStore`:
+
+```ts
+type FileStore = {
+  readonly rootDir: string;
+  path(relativePath: string): string;
+  root(): Promise<Root>;
+  write(rel, data: string | Uint8Array, options?): Promise<string>;
+  writeStream(rel, stream: Readable, options?): Promise<string>;
+  copyIn(rel, sourcePath: string, options?): Promise<string>;
+  open(rel, options?): Promise<OpenResult>;
+  read(rel, options?): Promise<ReadResult>;
+  readBytes(rel, options?): Promise<Buffer>;
+  readText(rel, options?): Promise<string>;
+  readTextIfExists(rel, options?): Promise<string | null>;
+  readJson<T = unknown>(rel, options?): Promise<T>;
+  readJsonIfExists<T = unknown>(rel, options?): Promise<T | null>;
+  writeText(rel, data: string | Uint8Array, options?): Promise<string>;
+  writeJson(rel, data: unknown, options?): Promise<string>;
+  json<T = unknown>(rel, options?): JsonStore<T>;
+  remove(rel): Promise<void>;
+  exists(rel): Promise<boolean>;
+  pruneExpired(options: FileStorePruneOptions): Promise<void>;
+};
+```
+
+`path()` returns the absolute path the store would use, after asserting it stays inside `rootDir`. Useful for logging or for handing to other libraries.
+
+Every `relativePath` is a portable store key. The same lexical policy applies
+to every keyed async and sync method, including reads, `exists`, `remove`,
+`path()`, and `json()` construction, with either `private: false` or `true`.
+Keys must use their exact canonical spelling; the store never trims, normalizes,
+or converts one caller-supplied key onto another:
+
+- Keys are nonempty NFC Unicode strings without surrounding whitespace or NUL.
+- Segments are separated by a single forward slash. Empty segments, repeated or
+  trailing slashes, and complete `.` or `..` segments are rejected, including
+  `./b`, `a/./b`, and `a/../b`.
+- Every backslash is rejected on every platform, including a literal POSIX
+  `a\b` filename. POSIX and Windows absolute, rooted, UNC, and extended paths
+  are rejected.
+- Windows drive-relative segments such as `C:name` or `C:` are rejected
+  anywhere in a key, including `a/C:name`.
+- On Windows, every other colon is rejected too, preventing a key from naming
+  an NTFS alternate stream or directory-index alias. POSIX keeps accepting
+  ordinary colon-bearing segments that are not drive-relative spellings.
+- No segment may end in an ASCII dot or space.
+
+Violations report `invalid-path` when key validation is reached. Ordinary nested
+keys, NFC Unicode such as `café/日本語.txt`, `.hidden`, `a..b`, and internal spaces
+such as `internal space/a b.txt` are accepted. On POSIX, colons elsewhere, such
+as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid;
+Windows rejects that spelling as stream syntax.
+
+Keys such as `~` and `~/state.json` name literal entries inside the store; they
+do not expand the user's home directory. Reads, writes, removal, and pruning
+all use that literal identity. The `Root` returned by `root()` retains its own
+home-expansion behavior.
+
+Validation retains each method's operation order. Async reads, `exists`, and
+`remove` open the root first: if the root is missing, strict methods report
+`not-found` and `readTextIfExists` / `readJsonIfExists` return `null`, even for an
+invalid key. With an existing root, those same invalid keys report `invalid-path`.
+Private `copyIn` checks and reads its source before validating the destination
+key, and `writeJson` serializes its value before validating the key. Key rejection
+therefore does not imply that no filesystem access or serialization occurred.
+
+`root()` returns a [`Root`](root.md) handle for the same directory when you need the full surface (move, list, mkdir). It's a fresh handle per call and is safe to call frequently.
+
+## Writes
+
+Writes use guarded sibling-temp publication: apply file and directory modes,
+then rename into place. By default, the file and parent directory are synced
+where supported by the platform and writer.
+
+`durable: false` keeps the sibling-temp replace/rename behavior but skips the
+temp-file and parent-directory `fsync` calls. Use it only for reconstructible
+metadata where lower latency matters more than crash-durability. Per-call
+`durable` overrides the store option, which defaults to `true`; an omitted or
+`undefined` override preserves the store default. Modes, path confinement,
+and publication identity checks are unchanged.
+
+Synchronous writes retain their original write-only descriptor through rename
+and publication checks, using exact bigint file identities. When Windows cannot
+report a pathname's identity, verification reopens the name only to compare its
+descriptor with the retained writer; it never reads file contents. A substituted
+file is rejected even if its bytes match, and a post-publication failure leaves
+the published entry intact for caller-owned recovery. Ordinary write-only and
+mode-000 outputs do not require a readable descriptor when pathname metadata is
+available.
+
+If a synchronous write operation and its final temp-descriptor close both fail,
+the store reports them in operation-then-close order in an `AggregateError`.
+This ordering and the original JavaScript thrown value are preserved even when
+that value is `undefined` or otherwise falsy. An unsuccessful best-effort temp
+unlink remains registered for identity-checked process-exit cleanup; it does not
+prevent the close attempt or replace either reportable failure.
+
+If an opaque pathname cannot be reopened because of an ACL denial or sharing
+restriction, the synchronous writer intentionally rejects with `path-mismatch`:
+its exact publication identity cannot be verified. There is no equal-content
+fallback. The published entry remains present, so callers must inspect or
+recover that outcome instead of assuming the write did not occur.
+
+Synchronous directory creation retains exact bigint receipts for the store root
+and every parent component. On POSIX, an existing or newly created directory
+whose complete requested mode differs is reopened without following the final
+name, checked against its receipt and parent chain, and finalized through that
+descriptor. A concurrent root or parent replacement is rejected without
+applying the mode to the replacement. Directories already at the requested mode
+skip the descriptor and mode operation. Windows retains its bounded `mkdir`
+mode request and identity checks without relying on directory descriptors or a
+pathname `chmod`, because Node does not enforce POSIX directory modes there.
+
+Node does not expose a portable, `fchmod`-capable search-only directory
+descriptor on Linux. If a mismatched existing directory, or one created under
+an owner-read-removing umask, cannot be opened for reading, the synchronous
+store therefore fails closed with `permission-unverified`; it never falls back
+to pathname `chmod`. On supported macOS x64/arm64 hosts it also tries an
+`O_SEARCH` descriptor, so owner-searchable directories can still be repaired.
+Directories with neither usable read nor search access remain fail-closed.
+
+| Method | Durability support |
+|---|---|
+| `write`, `writeText`, `writeJson` (async and sync) | Per-call option overrides store default. |
+| `writeStream`, `copyIn` (either private mode) | Per-call option overrides store default. |
+| JSON `write`, `update`, `updateOr` | JSON handle option overrides file-store default. |
+
+### `write(rel, data, options?)`
+
+```ts
+const path = await cache.write("entries/2026/05/05.json", JSON.stringify(entry));
+```
+
+Buffer or string. Returns the final absolute path. Throws `too-large` if `data.byteLength` exceeds `maxBytes`.
+
+### `writeText(rel, data, options?)` / `writeJson(rel, data, options?)`
+
+Convenience wrappers over `write`. `writeJson` pretty-prints with a trailing newline by default and accepts `{ trailingNewline: false }` when the exact bytes matter.
+
+### `json<T>(rel, options?)`
+
+Returns a typed single-file JSON state helper for a file under this store. It
+inherits the store's root, mode, max-size, durability, and private-write policy, then adds
+`readOr`, `readRequired`, `update`, `updateOr`, and optional sidecar locking:
+
+```ts
+const state = cache.json<State>("state/settings.json", { lock: true });
+await state.updateOr(defaultState, (current) => ({ ...current, enabled: true }));
+```
+
+Use this when one JSON file owns one piece of state. `jsonStore({ filePath })`
+is the absolute-path convenience wrapper for the same primitive.
+
+Pass `{ durable: false }` or `{ durable: true }` to `json()` to override the
+parent store's durability for all mutations of that JSON handle.
+
+### `writeStream(rel, stream, options?)`
+
+```ts
+import { Readable } from "node:stream";
+const path = await cache.writeStream("downloads/blob.bin", Readable.from(remoteFetch));
+```
+
+Streams into a sibling temp with a running byte budget. Aborts the source stream with `too-large` if `maxBytes` is exceeded mid-stream — partial writes are cleaned up.
+
+Streams honor `durable` in both private modes. Non-private streams stage their
+input and forward the resolved durability option to Root `copyIn` for publication.
+
+### `copyIn(rel, sourcePath, options?)`
+
+```ts
+const path = await cache.copyIn("ingest/upload.bin", "/tmp/upload.bin");
+```
+
+One-shot ingest from an absolute source path. Source is checked for symlink/non-regular before copy. Same mode rules as `write`.
+
+`copyIn` honors per-call and store-level `durable` values in both private modes,
+with the same precedence as `write`.
+
+### `FileStoreWriteOptions`
+
+Per-call overrides for the store-level defaults:
+
+Writes capture byte limits, modes, and durability before asynchronous work or
+stream consumption. JSON writes capture those fields and the trailing-newline
+setting before serialization. Later mutation cannot change those captured values.
+Accessors run on the original options object. Ordinary writes retain content
+conversion and byte-limit validation before reading modes and durability.
+The legacy non-private stream `tempPrefix` accessor still runs after staging;
+it does not control the publication policy.
+
+```ts
+type FileStoreWriteOptions = {
+  durable?: boolean;   // store default, otherwise true
+  dirMode?: number;
+  mode?: number;
+  maxBytes?: number;
+  tempPrefix?: string;  // override the default "." + basename
+};
+```
+
+| `FileStoreWriteOptions` option | Default |
+|---|---|
+| `durable` | Store option, otherwise `true`. |
+| `dirMode` / `mode` | Store directory/file modes. |
+| `maxBytes` | Store byte limit. |
+| `tempPrefix` | Writer-specific temporary prefix. |
+
+The same durability precedence applies to `fileStoreSync().write`,
+`writeText`, and `writeJson`. The synchronous store has no `writeStream` or
+`copyIn` methods.
+
+## Reads
+
+`open`, `read`, `readBytes`, `readText`, and `readJson` delegate to a fresh `Root` with `hardlinks: "reject"` and the store's `maxBytes`. Same return shapes as `Root`.
+Async and sync reads both report `not-file` when the key names a directory;
+stable hardlinks and symlinks retain `hardlink` and `symlink`. The `IfExists`
+methods return their nullish result only for `not-found`. Operational filesystem
+read failures use `read-failed` with the Node error retained in `cause`.
+
+## `remove(rel)` / `exists(rel)`
+
+Forward to the underlying `Root`. `remove` unlinks files and `rmdir`s empty directories; non-empty dirs throw `not-empty`.
+
+## `pruneExpired(options)`
+
+Walk the store and delete files older than `options.ttlMs`:
+
+```ts
+await cache.pruneExpired({
+  ttlMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+  recursive: true,
+  pruneEmptyDirs: true,
+});
+```
+
+Options:
+
+```ts
+type FileStorePruneOptions = {
+  ttlMs: number;
+  recursive?: boolean;       // default false (top-level only)
+  maxDepth?: number;         // bound recursion explicitly
+  pruneEmptyDirs?: boolean;  // also remove dirs that became empty (only with recursive/maxDepth)
+};
+```
+
+Symlinks are skipped. The walk is best-effort — failures on individual entries don't abort the whole prune. Compares against `mtimeMs`.
+
+Pruning rechecks that a selected entry is still a regular file and still expired
+immediately before guarded removal. Fresh replacements and in-place timestamp
+refreshes are preserved; replacements that are themselves expired remain
+eligible. This does not require read permission. The existing best-effort
+external-process race window after dispatch still applies.
+
+Empty-directory pruning likewise rechecks that the selected entry is still a
+directory immediately before guarded removal. File and symlink replacements
+are preserved, and a directory that becomes nonempty is left in place.
+
+## Difference from `Root`
+
+| `FileStore` | `Root` |
+|---|---|
+| Object-style with mode+dirMode baked in. | Method-style boundary; mode is per-call or per-default. |
+| `writeStream` with built-in byte budget. | Manual via `openWritable()`. |
+| `writeText` / `writeJson` return the final absolute path. | `Root.write` / `writeJson` return void. |
+| `copyIn` returns the final absolute path. | `Root.copyIn` returns void. |
+| `pruneExpired` walks by `mtime`. | No prune helper. |
+| Reads delegate via `Root` internally. | The boundary itself. |
+
+If you need richer ops (move, list, append, mkdir), call `store.root()` to get a `Root` and use that.
+
+`FileStore` owns portable key identity; `Root` owns filesystem confinement.
+Existing-object Root lookups intentionally retain broader confined path
+compatibility, including in-root absolute paths and parent-segment spellings,
+and literal backslashes on POSIX. FileStore rejects those spellings even when
+Root could resolve them safely inside the directory. This key policy does not
+change Root's containment checks or the absolute-path `jsonStore({ filePath })`
+contract.
+
+## Common patterns
+
+### Cache with TTL prune
+
+```ts
+const cache = fileStore({ rootDir: "/var/cache/app", maxBytes: 16 * 1024 * 1024 });
+
+await cache.writeStream(`${id}.bin`, fetchStream(id));
+
+// Background prune every hour
+setInterval(() => cache.pruneExpired({ ttlMs: 24 * 60 * 60 * 1000 }), 60 * 60 * 1000);
+```
+
+### Ingest pipeline
+
+```ts
+const ingest = fileStore({ rootDir: "/srv/ingest", mode: 0o644 });
+
+for (const upload of uploads) {
+  const dest = await ingest.copyIn(`raw/${upload.id}`, upload.tempPath, {
+    maxBytes: 200 * 1024 * 1024,
+  });
+  await enqueueProcess(dest);
+}
+```
+
+### Drop down to `Root` for moves
+
+```ts
+const root = await store.root();
+await root.move(`pending/${id}`, `done/${id}`);
+```
+
+## See also
+
+- [`root()`](root.md) — the boundary `FileStore` is built on; reach for it when you need move/list/append.
+- [JSON store](json-store.md) — the JSON-state-file equivalent of this surface.
+- [Atomic writes](atomic.md) — lower-level sibling-temp publication helpers.
+- [Temp workspaces](temp.md) — private scratch directories backed by `FileStore`.