@openclaw/signal 2026.9.5 → 2026.9.6

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

@@ -0,0 +1,222 @@
+# Install
+
+`fs-safe` is published to npm as `@openclaw/fs-safe`. It targets Node 22 or newer, ships ESM only, and works on macOS, Linux, and Windows.
+
+## Package managers
+
+```bash
+pnpm add @openclaw/fs-safe
+```
+
+```bash
+npm install @openclaw/fs-safe
+```
+
+```bash
+yarn add @openclaw/fs-safe
+```
+
+```bash
+bun add @openclaw/fs-safe
+```
+
+## Node version
+
+Minimum **Node 22**. The package uses `fs.promises`, `fs.constants.O_NOFOLLOW` where available, and `node:stream/promises`. Earlier Node releases will fail at import time.
+
+Verify the runtime:
+
+```bash
+node --version
+# v22.0.0 or newer
+```
+
+## Bun runtime
+
+Bun 1.4.2 can run the same public APIs and load the matching native package.
+On macOS and Linux, fs-safe uses its Rust N-API addon to call the system
+`realpath` implementation for native resolution. Ordinary resolution follows
+Node's component walk, including lexical normalization of expanded symlink
+targets, in Rust, with a 1,024-link expansion limit that returns `ELOOP` for
+excessive or cyclic expansion. This works around Bun path-resolution defects that
+otherwise reject restrictive permissions and confuse literal POSIX backslashes
+with directory separators. The OS still resolves symlinks and canonical file
+names; fs-safe retains its confinement and file-identity checks.
+
+This works with `bun --jitless` and needs no runtime FFI or JIT. Use native mode
+`auto` or `require` with the matching addon installed. `FS_SAFE_NATIVE_MODE=off`
+still disables all addon loading; `auto` without the addon falls back to Bun's
+resolver. Those configurations retain Bun 1.4.2's limitations with restrictive
+permissions, sockets, literal backslashes, and symlink/parent traversal. Use
+Node if you need full compatibility without the addon. On Bun POSIX, `require`
+also rejects canonicalization when the addon or its canonicalizer is unavailable.
+
+Node and Windows use their existing runtime canonicalizers. On Windows, Bun's
+recursive directory creation receives an absolute spelling that preserves raw
+path components, working around its rejection of existing relative `.` and `..`
+directories. Windows native descriptor-relative operations require Bun to expose
+the paired libuv descriptor bridge from its host executable; a missing or partial
+bridge fails explicitly with `ENOTSUP`. Public paths and caller-supplied filesystem
+adapters remain unchanged.
+
+The upstream fix is tracked in [Bun #42374](https://github.com/oven-sh/bun/pull/42374).
+The adapter can be removed when the supported Bun baseline includes that fix.
+Run native compatibility checks with `pnpm test:bun:native` after building the
+package and addon. See [contributing](contributing.md) for the Node/pnpm toolchain
+and the broader diagnostic suite.
+
+## TypeScript
+
+Types ship with the package — no `@types/openclaw__fs-safe` needed. The `exports` map in `package.json` provides typed entries for every subpath:
+
+```ts
+import { root, FsSafeError } from "@openclaw/fs-safe";
+import { writeJson } from "@openclaw/fs-safe/json";
+import { extractArchive } from "@openclaw/fs-safe/archive";
+```
+
+A working `tsconfig.json` for consumers:
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "node18",
+    "moduleResolution": "node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+## Subpath exports
+
+Use the main entry for the common surface, or the focused subpaths when you want a leaner import or to depend on a narrower contract:
+
+| Subpath | Contents |
+|---|---|
+| `@openclaw/fs-safe` | Common root, config, output, lock, native-mode, and error exports. |
+| `@openclaw/fs-safe/root` | `root()`, `Root`, `RootDefaults`, and root-walk types. |
+| `@openclaw/fs-safe/config` | Process-global native helper and lock defaults. |
+| `@openclaw/fs-safe/path` | `isPathInside`, `safeRealpathSync`, `isWithinDir`, error helpers. |
+| `@openclaw/fs-safe/output` | Guarded staging/finalization for libraries that require an absolute output path. |
+| `@openclaw/fs-safe/json` | `tryReadJson`, `readJson`, `readJsonIfExists`, `writeJson`, sync variants. |
+| `@openclaw/fs-safe/store` | `fileStore()`, `fileStoreSync()`, and `jsonStore<T>()`. |
+| `@openclaw/fs-safe/secret` | Secret file read/write helpers. |
+| `@openclaw/fs-safe/atomic` | `replaceFileAtomic`, `writeTextAtomic`, `replaceDirectoryAtomic`, `movePathWithCopyFallback`. |
+| `@openclaw/fs-safe/durability` | Pinned directories, strict sync, durable directory creation, exclusive publication, and streaming SHA-256. |
+| `@openclaw/fs-safe/temp` | `tempWorkspace`, `withTempWorkspace`, sync variants, `resolveSecureTempRoot`. |
+| `@openclaw/fs-safe/secure-file` | `readSecureFile` for pinned absolute file reads with permissions checks. |
+| `@openclaw/fs-safe/file-lock` | `acquireFileLock`, `withFileLock`, `createFileLockManager`, and related lock types. |
+| `@openclaw/fs-safe/permissions` | POSIX mode helpers, Windows ACL inspection/remediation, raw owner/ACE facts, and private-directory creation. |
+| `@openclaw/fs-safe/walk` | `walkDirectory`, `walkDirectorySync`, related types. Budget-bounded, not root-bounded. |
+| `@openclaw/fs-safe/archive` | `extractArchive`, `readArchiveEntry`, kind resolution, policy types, limits, and preflight helpers. |
+| `@openclaw/fs-safe/advanced` | Lower-level composition helpers: path scopes, root-file open, install paths, local-root readers, temp-file targets, sibling-temp writes, regular-file helpers, `pathExists`, `withTimeout`, and related advanced types. This surface is less stable than the focused public subpaths. |
+| `@openclaw/fs-safe/errors` | `FsSafeError`, `FsSafeErrorCode`. |
+| `@openclaw/fs-safe/types` | Shared types: `DirEntry`, `PathStat`, `BasePathOptions`, … |
+| `@openclaw/fs-safe/test-hooks` | Test-only hooks for injecting races. Active under `NODE_ENV=test`. |
+
+## Runtime dependencies
+
+`@openclaw/fs-safe` bundles an import-free WASM build of its Rust TAR parser and zstd/bzip2 codecs for guarded [archive extraction and bounded entry reads](archive.md). Plain TAR, gzip, zstd, and bzip2 work in `off` and missing-native `auto`, including installs with all optional dependencies omitted; gzip uses Node's built-in decoder. These archive fallbacks need no runtime interpreter, download, or consumer compiler. ZIP fallback uses lazily loaded optional `jszip` and reports a missing-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability. Native `require` remains strict, and an available native operation's failure never triggers a WASM retry.
+
+There are no peer dependencies. Exact-version optional packages carry the seven
+native targets and npm-compatible OS, CPU, and Linux libc filters install only
+the matching binary. Consumers do not run a Rust build, download code at
+runtime, or execute a postinstall step. Omitting optional dependencies keeps
+fallback-capable operations working in `auto` or `off`. Native-only
+features, including strict owned-tree temp cleanup, retained-directory staging,
+and atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
+remain unavailable. Operations without a safe fallback fail with `helper-unavailable`
+when the matching package is absent, incompatible, or disabled.
+
+Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
+before deploying with native mode `require` or native-only features.
+
+### Windows security fallback
+
+Windows raw owner/DACL inspection, private-directory creation, and secure-file
+reads work without the addon in `auto` or `off` mode when system Windows
+PowerShell and its .NET `Add-Type` compilation support are available. The package
+ships a readable, fixed `.ps1` driver and adjacent `.cs` source and invokes the
+driver with Windows PowerShell `-File`. Paths are passed as data. The fallback
+does not generate helper scripts at runtime or use an encoded launcher.
+The driver addresses built-in commands by module name and limits module
+discovery to PowerShell's bundled system modules, avoiding broad command
+discovery scans during each helper startup.
+
+Normal PowerShell execution policy and Microsoft Defender policy must permit
+the packaged scripts, including their use of `Add-Type`. The package does not
+bypass restrictions, change policies, or add exclusions. Unsupported or
+disallowed command execution fails closed.
+
+The fallback preserves private DACLs at creation and inspects the same open
+handle that supplies secure-file bytes. Each capability emits a path-free
+`FS_SAFE_NATIVE_FALLBACK` warning once per process; each call adds PowerShell
+startup and compilation overhead. Execution or compilation failure also fails
+closed. Native `require` still rejects a missing binding or capability, and an
+available native operation's error never triggers a command retry. See
+[Permissions](permissions.md) and [Secure file reads](secure-file.md).
+
+## Native helper policy
+
+The platform native binaries provide fd-relative open/link/mkdir primitives,
+atomic no-replace rename, and file identity checks. The default is `auto`: use
+the matching binary when it loads, otherwise use the guarded JavaScript path
+where a safe fallback exists. Native-only operations fail with
+`helper-unavailable`.
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "auto" });    // default
+configureFsSafeNative({ mode: "off" });     // disable the addon; reject native-only operations
+configureFsSafeNative({ mode: "require" }); // fail closed if unavailable
+```
+
+Environment variables are read at runtime:
+
+```bash
+FS_SAFE_NATIVE_MODE=off      # auto | off | require
+```
+
+`OPENCLAW_FS_SAFE_NATIVE_MODE` is also accepted.
+
+Disabling native loading keeps fallback-capable operations working through Node path
+operations guarded by lexical and canonical checks plus identity verification.
+Use `require` when native-backed operations must fail instead of falling back.
+Temp workspaces retain compatible JavaScript quarantine cleanup in `auto` and
+`off`. Set `cleanupSafety: "require-bounded"` to reject before child creation
+unless native no-replace quarantine and descriptor-bounded tree removal are
+available. See the [temp workspace contract](temp.md#private-temp-workspaces). The exact boundary
+for other operations is documented in [native helper policy](native-helper.md).
+
+## Verify the install
+
+```ts
+import { root, FsSafeError } from "@openclaw/fs-safe";
+import os from "node:os";
+import path from "node:path";
+
+const dir = path.join(os.tmpdir(), "fs-safe-smoke");
+await import("node:fs/promises").then((fs) => fs.mkdir(dir, { recursive: true }));
+
+const fs = await root(dir);
+await fs.write("hello.txt", "ok\n");
+console.log(await fs.readText("hello.txt"));
+
+try {
+  await fs.write("../escape.txt", "x");
+} catch (err) {
+  if (err instanceof FsSafeError) console.log("blocked:", err.code);
+}
+```
+
+If the script prints `ok` followed by `blocked: outside-workspace`, your install is healthy.
+
+## Next
+
+- [Quickstart](quickstart.md) — write, read, atomic, temp.
+- [Security model](security-model.md) — what the boundary defends against.
+- [Errors](errors.md) — the closed code union you'll be catching.

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

@@ -0,0 +1,240 @@
+# JSON store
+
+`jsonStore` is exported from `@openclaw/fs-safe/store`. It is the single-path
+convenience wrapper for `fileStore(...).json(...)`: a small read-modify-write
+handle around a single JSON file. It bakes in atomic writes, explicit fallback
+reads, and optional cross-process locking via
+[`acquireFileLock`](sidecar-lock.md).
+
+```ts
+import { jsonStore } from "@openclaw/fs-safe/store";
+
+const settings = jsonStore<{ theme: "light" | "dark"; volume: number }>({
+  filePath: "/var/lib/app/settings.json",
+});
+
+const current = await settings.readOr({ theme: "dark", volume: 0.7 });
+await settings.write({ ...current, volume: 1 });
+await settings.updateOr({ theme: "dark", volume: 0.7 }, (prev) => ({ ...prev, theme: "light" }));
+```
+
+If you already have a store/root context, prefer binding the JSON file from that
+store:
+
+```ts
+import { fileStore } from "@openclaw/fs-safe/store";
+
+const files = fileStore({ rootDir: "/var/lib/app", private: true });
+const settings = files.json<Settings>("settings.json", { lock: true });
+```
+
+## When to reach for it
+
+- You have a single JSON state file and want `read / readOr / readRequired / write / update` semantics.
+- You want every write atomic at file mode `0o600` and parents at `0o700` by default.
+- You want optional cross-process locking with one boolean.
+
+For ad-hoc read/write of multiple JSON files, use the standalone helpers in
+[`json`](json.md). For object-style storage of many files at known modes, use
+[`fileStore`](file-store.md) and bind JSON files with `store.json(rel)`.
+
+## Factory: `jsonStore<T>(options)`
+
+```ts
+type JsonStoreOptions<T> = {
+  filePath: string;
+  dirMode?: number;                                // default 0o700
+  mode?: number;                                   // default 0o600
+  durable?: boolean;                              // default true
+  trailingNewline?: boolean;                       // default true
+  lock?: boolean | JsonStoreLockOptions;           // false / undefined = no lock
+};
+
+type JsonStoreLockOptions = {
+  staleMs?: number;     // default 30_000
+  timeoutMs?: number;   // default 30_000
+  retry?: FileLockRetryOptions;
+  staleRecovery?: "fail-closed" | "remove-if-unchanged";
+  managerKey?: string;  // default `fs-safe.json-store:<filePath>`
+};
+
+type JsonStore<T> = {
+  readonly filePath: string;
+  read(): Promise<T | undefined>;
+  readOr(fallback: T): Promise<T>;
+  readRequired(): Promise<T>;
+  write(value: T): Promise<void>;
+  update(run: (current: T | undefined) => T | Promise<T>): Promise<T>;
+  updateOr(fallback: T, run: (current: T) => T | Promise<T>): Promise<T>;
+};
+```
+
+`jsonStore({ filePath })` resolves `rootDir = dirname(filePath)` and calls
+`fileStore({ rootDir, private: true }).json(basename(filePath), options)`.
+On Windows, the factory rejects NTFS alternate-stream and directory-index
+namespace spellings before preparing its private parent. An ordinary
+drive-relative path is anchored at entry and `store.filePath` exposes the
+resulting absolute path; ordinary colon-bearing POSIX paths remain valid.
+
+`durable: false` keeps 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. The default
+is `true`, subject to platform sync support. This store-level policy applies
+to `write`, `update`, and `updateOr`; these methods have no per-call options.
+For `fileStore(...).json(rel, options)`, `options.durable` overrides the parent
+file store's durability, while omission or `undefined` inherits it. Modes,
+identity checks, mutation serialization, and sidecar locking are unchanged.
+
+Each `write`, `update`, or `updateOr` invocation captures the retained options'
+`durable` and `trailingNewline` values before queueing, locking, reading, or
+calling the updater. Changes to those options affect later invocations only,
+including when a mutation is waiting behind another operation.
+
+The store does **not** validate the parsed value against `T` at runtime — the cast is unchecked. Wrap with a schema (zod/valibot) if the file might be hand-edited or written by another process you don't control.
+
+## `read()`
+
+Returns the parsed contents, or `undefined` if the file does not exist. Invalid JSON throws (via [`readJsonIfExists`](json.md)).
+
+```ts
+const state = await store.read();
+```
+
+## `readOr(fallback)`
+
+Returns the parsed contents or the per-call fallback. Object fallbacks are cloned so callers can safely mutate the returned value:
+
+```ts
+const state = await store.readOr(defaultState);
+```
+
+## `readRequired()`
+
+Strict disk read. Throws when the file is missing or invalid:
+
+```ts
+const state = await store.readRequired();
+```
+
+## `write(value)`
+
+Atomic JSON write at `mode` (default `0o600`), creating parent dirs at `dirMode` (default `0o700`) if needed. When `lock: true` is set, takes the sidecar lock for the duration of the write.
+
+```ts
+await store.write({ ...state, lastSeen: Date.now() });
+```
+
+## `update(run)`
+
+Read, transform, write — under the lock if locking is enabled. Returns the new value:
+
+```ts
+const next = await store.update((prev) => ({ count: (prev?.count ?? 0) + 1 }));
+```
+
+`run` is async-friendly. The whole `read → run → write` sequence is serialized
+by canonical file path inside the process. With locking enabled, the sidecar
+lock is acquired inside that queue, so concurrent updaters from different
+processes serialize cleanly too.
+
+Do not call `write()`, `update()`, or `updateOr()` for the same file from inside
+an update callback. That nested mutation cannot run until the outer update
+finishes, so `jsonStore` rejects it immediately with
+`FsSafeError("store-reentrant-update")`. Return the complete next value from the
+outer callback instead. The check follows Node async context, including promise
+and `queueMicrotask` boundaries.
+
+Use `update(run)` when missing state is part of your model. Use `updateOr(fallback, run)` when the missing-file case should start from a concrete value and you want to merge into defaults:
+
+```ts
+const next = await store.updateOr({ count: 0 }, (prev) => ({ count: prev.count + 1 }));
+```
+
+## Locking
+
+Set `lock: true` for default behavior, or pass an options object to tune:
+
+```ts
+const counter = jsonStore<{ count: number }>({
+  filePath: "/var/lib/app/counter.json",
+  lock: {
+    staleMs: 60_000,
+    timeoutMs: 10_000,
+    staleRecovery: "fail-closed",
+    retry: { retries: 30, minTimeout: 100, maxTimeout: 5_000, randomize: true },
+  },
+});
+```
+
+When `lock` is falsy, writes and updates still serialize inside this process by
+canonical file path, including across separate `jsonStore` handles. They offer
+no concurrency guarantees if another process also writes to the file.
+
+Process-wide lock defaults from `configureFsSafeLocks()` apply only after locking is explicitly enabled. They do not make JSON stores lock by default.
+
+JSON store locks fail closed on stale sidecars by default. Opt-in `staleRecovery: "remove-if-unchanged"` requires caller approval and uses the same exclusive reclaim guard as the low-level sidecar-lock API.
+
+The default `managerKey` namespaces the `FileLockManager` per absolute file
+path. The JSON-store queue is independent of the manager key, so separate
+handles and custom lock-manager namespaces still cannot overlap mutations of
+the same canonical file path inside one process.
+
+## Common patterns
+
+### Per-feature settings file
+
+```ts
+type Settings = { theme: "light" | "dark"; muted: boolean };
+
+const settings = jsonStore<Settings>({
+  filePath: path.join(homedir(), ".myapp/settings.json"),
+});
+
+// Read on boot
+applySettings(await settings.readOr({ theme: "dark", muted: false }));
+
+// Toggle on UI action
+await settings.update((prev) => {
+  const current = prev ?? { theme: "dark", muted: false };
+  return { ...current, muted: !current.muted };
+});
+```
+
+### Cross-process counter
+
+```ts
+const counter = jsonStore<{ count: number }>({
+  filePath: "/var/lib/app/counter.json",
+  lock: true,
+});
+
+const { count } = await counter.updateOr({ count: 0 }, (prev) => ({ count: prev.count + 1 }));
+console.log("now at", count);
+```
+
+### Migration on boot
+
+```ts
+const config = jsonStore<Config>({ filePath });
+const current = await config.readOr(defaultConfig);
+if (current.version !== CURRENT_VERSION) {
+  await config.write(migrate(current));
+}
+```
+
+## Difference from raw `writeJson` / `readJsonIfExists`
+
+| `jsonStore` | Raw helpers |
+|---|---|
+| Read-modify-write in one call (`update`). | Compose `readJsonIfExists` + `writeJson` yourself. |
+| Optional cross-process lock with one flag. | Manage `withFileLock` yourself. |
+| Explicit `readOr` / `updateOr` fallbacks. | Caller handles `null` and clones. |
+| Mode/dirMode locked per store. | Per-call. |
+
+`jsonStore` is the right shape when one file owns one piece of state and many call sites read or update it. For one-off writes, the raw helpers are leaner.
+
+## See also
+
+- [JSON files](json.md) — the standalone helpers `jsonStore` is built on.
+- [File lock](sidecar-lock.md) — the cross-process lock used when `lock: true`.
+- [File store](file-store.md) — the multi-file equivalent of this surface.

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

@@ -0,0 +1,225 @@
+# JSON files
+
+`@openclaw/fs-safe/json` is the standalone JSON surface: strict and lenient read variants plus atomic JSON writes.
+
+```ts
+import {
+  tryReadJson,
+  readJson,
+  readJsonIfExists,
+  readJsonSync,
+  tryReadJsonSync,
+  readRootJsonSync,
+  readRootJsonObjectSync,
+  readRootStructuredFileSync,
+  writeJson,
+  writeJsonSync,
+  JsonFileReadError,
+} from "@openclaw/fs-safe/json";
+```
+
+## Three reads, three failure shapes
+
+Same input, three distinct contracts — pick the one whose error story matches your call site:
+
+```ts
+await readJson<T>("./manifest.json");      // throws JsonFileReadError on missing or invalid
+await readJsonIfExists<T>("./cache.json"); // returns null on missing; throws on invalid
+await tryReadJson<T>("./optional.json");   // returns null on missing or invalid
+```
+
+| Helper | Missing file | Invalid JSON |
+|---|---|---|
+| `readJson` | throws | throws |
+| `readJsonIfExists` | `null` | throws |
+| `tryReadJson` | `null` | `null` |
+
+Use `readJson` when missing-or-malformed is a programmer error you want to surface immediately. Use `readJsonIfExists` when "file not there" is normal but malformed bytes should still page someone. Use `tryReadJson` when neither outcome should crash the caller.
+
+`JsonFileReadError` carries `cause` so you can inspect whether the underlying failure was an `ENOENT`, a `SyntaxError`, or something else.
+
+On Windows, filesystem path inputs reject NTFS alternate-stream and
+directory-index namespace spellings such as `file:stream` and
+`dir::$INDEX_ALLOCATION`; ordinary colon-bearing POSIX names remain valid.
+Standalone JSON writers preserve their released support for an ordinary
+drive-relative destination by anchoring its leading drive designator at entry
+without normalizing the remaining suffix. Any additional colon is still
+rejected before filesystem access.
+Strict standalone readers retain `JsonFileReadError` and expose the
+`invalid-path` rejection as its cause, lenient `tryReadJson*` calls return
+`null`, and root-bounded readers report an `open`/`validation` failure.
+
+## Reading
+
+### `readJson<T>(filePath, options?)`
+
+Async strict reader. Throws `JsonFileReadError` on missing or invalid input. The cast is unchecked — validate the shape with your own schema (zod, valibot, …) if it came from an untrusted source.
+
+```ts
+const manifest = await readJson<Manifest>("./manifest.json");
+const smallManifest = await readJson<Manifest>("./manifest.json", {
+  maxBytes: 256 * 1024,
+});
+```
+
+All standalone readers accept `{ maxBytes?: number }`. When set, the read is
+incremental and consumes no more than `maxBytes + 1` bytes before rejecting, so
+file growth after the initial stat cannot cause an unbounded allocation.
+
+### `readJsonIfExists<T>(filePath, options?)`
+
+Async semi-lenient reader. Returns `null` if the file is missing; throws `JsonFileReadError` if the file exists but cannot be parsed.
+
+```ts
+const cache = (await readJsonIfExists<Cache>("./cache.json")) ?? freshCache();
+```
+
+### `tryReadJson<T>(filePath, options?)`
+
+Async lenient reader. Returns `null` for any failure (missing, unreadable, invalid). The "no fuss" sibling.
+
+```ts
+const optional = (await tryReadJson<Settings>("./settings.json")) ?? defaults;
+```
+
+### `readJsonSync<T>(filePath, options?)`
+
+Synchronous strict reader. Throws `JsonFileReadError` on missing or invalid input, matching the async `readJson` contract.
+
+### `tryReadJsonSync<T>(pathname, options?)`
+
+Synchronous, generic, lenient. Returns `T | null`. Useful in boot paths where you want a typed result without async.
+
+## Root-bounded structured reads
+
+Use the root-bounded readers when you already have a trusted root directory and
+a caller-controlled relative path, but you only need one synchronous structured
+read instead of a full `root()` handle.
+
+```ts
+const result = readRootJsonObjectSync({
+  rootDir: "/safe/workspace",
+  relativePath: "plugin/openclaw.plugin.json",
+  boundaryLabel: "plugin manifest",
+  maxBytes: 256 * 1024,
+});
+
+if (!result.ok) {
+  // reason is "open", "parse", or "invalid"
+  throw new Error(result.reason);
+}
+
+console.log(result.value);
+```
+
+`readRootJsonSync()` parses any JSON value. `readRootJsonObjectSync()` only
+accepts objects. `readRootStructuredFileSync()` accepts a custom parser and
+validator so callers can layer JSON5, TOML, YAML, or domain-specific validation
+without making `fs-safe` depend on those formats.
+
+## Writing
+
+### `writeJson(filePath, value, options?)`
+
+Async atomic JSON write. `JSON.stringify(value, null, 2)` + sibling-temp + rename. Defaults to file mode `0o600`.
+
+```ts
+await writeJson("./state.json", state, { trailingNewline: true });
+```
+
+Options:
+
+```ts
+type WriteJsonOptions = {
+  mode?: number;             // file mode (default 0o600)
+  dirMode?: number;          // mode for parent dirs created on demand
+  trailingNewline?: boolean; // append "\n" if missing (default false)
+  durable?: boolean;         // default true; false skips temp/parent fsync
+};
+```
+
+`durable: false` preserves atomic temp-file replacement but skips the temp-file
+and parent-directory `fsync` calls. Use it only for reconstructible JSON state
+where lower latency matters more than crash-durability.
+
+### `writeJsonSync(pathname, data)`
+
+Synchronous variant. It pretty-prints with two spaces, appends a newline,
+creates parents at `0o700`, writes at `0o600`, and synchronizes the parent
+directory best-effort. A retained staging descriptor carries the exact bigint
+identity through rename and file-mode tightening. Publication and cleanup never
+adopt a substituted temporary file: a changed identity, type or link count rejects
+the write and leaves the replacement untouched. A swap detected after publication
+also rejects without deleting or changing the replacement. It has no options bag. On `EPERM`/`EEXIST`, its legacy
+compatibility path removes the existing destination and retries the staged-file
+rename, so that fallback is temporarily non-atomic while retaining the staged
+file's `0600` mode; use the async `writeJson()`/`replaceFileAtomic()` surfaces
+when fallback policy must be explicit.
+
+Its private sibling temporary name is independent of the destination basename,
+so staging does not lengthen a valid destination filename.
+
+```ts
+writeJsonSync("./prefs.json", { theme: "dark" });
+```
+
+For atomic text writes, use [`writeTextAtomic`](atomic.md) from `@openclaw/fs-safe/atomic`. For in-process serialization, use `createAsyncLock` from the advanced surface, or prefer [`jsonStore`](json-store.md) when you want a JSON-specific read-modify-write helper.
+
+## Common patterns
+
+### Read-modify-write
+
+```ts
+const state = (await readJsonIfExists<State>("./state.json")) ?? initialState();
+state.lastRun = Date.now();
+await writeJson("./state.json", state, { mode: 0o600, dirMode: 0o700 });
+```
+
+### Atomic with secure mode
+
+For credentials or other sensitive JSON, write at mode `0o600`:
+
+```ts
+await writeJson("./auth.json", token, { mode: 0o600, dirMode: 0o700 });
+```
+
+For higher-assurance secrets, prefer the dedicated [secret-file helpers](secret-file.md) — they create the parent directory at `0o700` if missing.
+
+### Strict load on boot
+
+```ts
+let manifest: Manifest;
+try {
+  manifest = await readJson<Manifest>("./manifest.json");
+} catch (err) {
+  if (err instanceof JsonFileReadError) {
+    console.error("manifest unreadable:", err.cause);
+    process.exit(1);
+  }
+  throw err;
+}
+```
+
+### Concurrent readers, single writer
+
+```ts
+const state = await readJsonIfExists<State>("./state.json");
+// missing returns null; malformed JSON still throws
+```
+
+## Error reference
+
+| Throw / return | When |
+|---|---|
+| `null` from `tryReadJson` / `tryReadJsonSync` | Any read or parse failure. |
+| `null` from `readJsonIfExists` | File is missing; invalid or unreadable input still throws. |
+| `JsonFileReadError` | `readJson` or `readJsonIfExists` saw unreadable or invalid input. Inspect `cause`. |
+| Native `NodeJS.ErrnoException` | Lower-level fs errors not wrapped. |
+
+## See also
+
+- [JSON store](json-store.md) — a single-file state wrapper with explicit per-call fallback (`readOr` / `updateOr`) and optional sidecar locking.
+- [Atomic writes](atomic.md) — lower-level sibling-temp replacement helpers.
+- [Secret files](secret-file.md) — JSON-or-text writes with mode 0600 in mode 0700 dirs.
+- [Private file-store mode](private-file-store.md) — root-bounded JSON+text state stores.
+- [File lock](sidecar-lock.md) — cross-process coordination.