@openclaw/fs-safe 0.4.7 → 0.5.1

package/docs/errors.md

@@ -13,13 +13,41 @@ 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 });
+  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.
 
+`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, such as `outside-workspace`, `symlink`, `hardlink`, or `too-large`.
@@ -46,6 +74,7 @@ type FsSafeErrorCode =
   | "path-alias"
   | "path-mismatch"
   | "permission-unverified"
+  | "secret-exists"
   | "symlink"
   | "timeout"
   | "too-large"
@@ -60,8 +89,8 @@ type FsSafeErrorCode =
 | `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` | Internal POSIX helper failed after startup. | Inspect `cause`; retrying may be unsafe if the operation may have partially completed. |
-| `helper-unavailable` | Persistent Python helper was disabled or could not be spawned. | `FS_SAFE_PYTHON_MODE=off`, Python missing in PATH, restricted sandbox. `auto` falls back where possible; `require` fails closed. |
+| `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` | Required native binding could not be loaded. | Unsupported platform, missing/incompatible bundled binary, or `FS_SAFE_NATIVE_MODE=require`. `auto` falls back where possible; `require` fails closed. |
 | `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. | Caller didn't validate input; input was a network path on Windows. |
 | `not-empty` | `remove()` on a non-empty directory. | Use `replaceDirectoryAtomic` or remove children first. |
@@ -73,9 +102,10 @@ type FsSafeErrorCode =
 | `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. |
+| `secret-exists` | `createSecretFileAtomic()` found an existing final path. | First-writer-wins secret creation lost a race or the credential was already initialized. |
 | `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` | Read exceeded `maxBytes`. | Caller gave a too-permissive file or didn't size-cap correctly. |
+| `too-large` | A read or bounded walk exceeded its configured budget. | Caller gave a too-permissive file or traversal limit. |
 | `unsupported-platform` | The requested operation is not supported on the current platform. | E.g. POSIX-only helper invoked on Windows. |
 
 ## Branching
@@ -139,8 +169,8 @@ A common pattern is to wrap your domain code in a single try/catch that maps bot
 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, or extracted-byte budget is exceeded. The `code` field uses `ARCHIVE_LIMIT_ERROR_CODE` constants (e.g. `"ARCHIVE_SIZE_EXCEEDS_LIMIT"`).
-- `ArchiveSecurityError` — thrown by extraction when an entry path violates safety rules (traversal, drive prefix, blocked link type). The `code` field uses `ArchiveSecurityErrorCode` values.
+- `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.
 

package/docs/index.md

@@ -38,7 +38,8 @@ await fs.remove("notes/archive/today.txt");
 ## Pick your path
 
 - **First time?** [Install](install.md), then walk through the [Quickstart](quickstart.md). Five minutes from `pnpm add` to a working root.
-- **Designing a workspace feature.** Read the [Security model](security-model.md) before you trust the boundary, the [Python helper policy](python-helper.md) before you pick deployment defaults, and the [Errors](errors.md) reference so you know what to catch.
+- **Upgrading from 0.4?** Follow [Migrating to 0.5](migrating-to-0.5.md) in order, including the archive clamp-default audit.
+- **Designing a workspace feature.** Read the [Security model](security-model.md) before you trust the boundary, the [native helper policy](native-helper.md) before you pick deployment defaults, and the [Errors](errors.md) reference so you know what to catch.
 - **Replacing ad-hoc atomic writes.** Jump to [Atomic writes](atomic.md) or, for keyed JSON state, [JSON files](json.md).
 - **Extracting an upload.** Start at [Archive extraction](archive.md) — handles ZIP and TAR with traversal, link, count, and byte limits.
 - **Running an agent in a sandbox.** [Private temp workspaces](temp.md) plus [secret files](secret-file.md) cover the common scratch-and-credentials shape.
@@ -48,11 +49,12 @@ await fs.remove("notes/archive/today.txt");
 
 | Surface | Use it for |
 |---|---|
-| [`root()`](root.md) | One boundary for read/write/move/remove inside a trusted directory. |
-| [`@openclaw/fs-safe/config`](config.md) | Process-global Python helper and lock-option defaults. |
-| [Python helper policy](python-helper.md) | Choose `auto`, `off`, or `require` for POSIX fd-relative hardening. |
+| [`root()`](root.md) | One boundary for read/write/move/remove and bounded recursive walking inside a trusted directory. |
+| [`@openclaw/fs-safe/config`](config.md) | Process-global native helper and lock-option defaults. |
+| [Native helper policy](native-helper.md) | Choose `auto`, `off`, or `require` for bundled native primitives. |
+| [Native architecture](native.md) | Understand the thin syscall layer, beneath model, platform mechanisms, and fallback boundary. |
 | [`replaceFileAtomic`](atomic.md) | Sibling-temp + rename, fsync hooks, mode preservation, copy fallback. |
-| [Directory durability](durability.md) | Pinned directory identities, explicit sync outcomes, and durable nested-directory creation. |
+| [`@openclaw/fs-safe/durability`](durability.md) | Pinned directory identities, durable creation, exclusive publication, streaming SHA-256, provenance receipts, and sync-failure policy. |
 | [`writeExternalFileWithinRoot`](output.md) | Stage external-library file output in private temp storage, then finalize under a root. |
 | [`writeJson` / `readJson*`](json.md) | JSON state files with strict and lenient read variants. |
 | [`@openclaw/fs-safe/store`](store.md) | Overview of `fileStore`, `fileStoreSync`, and `jsonStore`. |
@@ -61,15 +63,16 @@ await fs.remove("notes/archive/today.txt");
 | [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for private JSON/text state at 0600 under 0700 dirs. |
 | [`tempWorkspace`](temp.md) | 0700 scratch dir with auto-cleanup. |
 | [`readSecureFile`](secure-file.md) | Absolute file reads with fd pinning, permissions, owner, size, and timeout checks. |
-| [`walkDirectory`](walk.md) | Budget-bounded recursive directory scan with symlink policy and filters. |
-| [`extractArchive`](archive.md) | ZIP/TAR extraction with size, count, link, and traversal limits. |
+| [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
+| [`extractArchive`](archive.md) | Policy-driven ZIP/TAR extraction with clamp/filter, metadata/path-depth, link, count, and byte limits. |
 | [Secret files](secret-file.md) | Mode-0600 credentials with size and TOCTOU defense. |
-| [Permissions](permissions.md) | POSIX mode and Windows ACL inspection/remediation helpers. |
+| [Permissions](permissions.md) | POSIX mode helpers plus Windows ACL inspection, raw owner/ACE facts, remediation, and private-directory creation. |
 | [`acquireFileLock`](sidecar-lock.md) | Cross-process file lock with retry and fail-closed stale-lock handling. |
 | [`FsSafeError`](errors.md) | Closed code union (with `policy` / `operational` category) you can branch on. |
 | [`pathScope()`](path-scope.md) | Lower-level absolute-path boundary helper; lives behind `@openclaw/fs-safe/advanced`. |
 | [`@openclaw/fs-safe/advanced`](advanced.md) | Directory of lower-level composition helpers (path scopes, regular-file I/O, install paths, sibling-temp writes, …). |
 | [`@openclaw/fs-safe/test-hooks`](test-hooks.md) | Test-only injection hooks for reproducing open/lstat races. |
+| [Migrating to 0.5](migrating-to-0.5.md) | End-to-end checklist for Python removal and 0.4 API behavior changes. |
 
 ## Status
 

package/docs/install.md

@@ -62,20 +62,22 @@ Use the main entry for the common surface, or the focused subpaths when you want
 
 | Subpath | Contents |
 |---|---|
-| `@openclaw/fs-safe` | Small common surface: `root`, root types, and errors. |
-| `@openclaw/fs-safe/root` | `root()`, `Root`, `RootDefaults`, related types. |
-| `@openclaw/fs-safe/config` | Process-global Python helper configuration. |
+| `@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 and Windows ACL inspection/remediation helpers. |
+| `@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`, `resolveArchiveKind`, limits, preflight helpers. |
+| `@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`, … |
@@ -85,40 +87,39 @@ Use the main entry for the common surface, or the focused subpaths when you want
 
 `@openclaw/fs-safe` lists `jszip` and `tar` as optional dependencies for [archive extraction](archive.md). They are loaded lazily and only required when ZIP/TAR helpers run. Installs that omit optional dependencies can still import and use every non-archive subpath; archive calls fail with a clear missing-optional-dependency message.
 
-There are no peer dependencies and no native build step.
+There are no peer dependencies. The single npm package bundles all seven native binaries, so consumers do not run a native build, download platform code, or execute a postinstall step. Shipping every target increases the tarball size compared with per-platform packages, intentionally trading bandwidth for deterministic installation.
 
-## Python helper policy
+Upgrading an existing consumer? Follow [Migrating to 0.5](migrating-to-0.5.md)
+before choosing a native mode or accepting the new archive clamp default.
 
-On POSIX, `root()` uses one persistent Python helper process for the
-fd-relative operations Node does not expose cleanly. The default is `auto`: use
-the helper when it starts, fall back to Node-only behavior when it is disabled
-or unavailable.
+## Native helper policy
+
+The bundled 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 silently keep the guarded
+JavaScript path. Platforms without one of the seven bundled targets therefore
+continue through the documented fallback in `auto` mode.
 
 ```ts
-import { configureFsSafePython } from "@openclaw/fs-safe/config";
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
-configureFsSafePython({ mode: "auto" });    // default
-configureFsSafePython({ mode: "off" });     // never spawn Python
-configureFsSafePython({ mode: "require" }); // fail closed if unavailable
+configureFsSafeNative({ mode: "auto" });    // default
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "require" }); // fail closed if unavailable
 ```
 
 Environment variables are read at runtime:
 
 ```bash
-FS_SAFE_PYTHON_MODE=off      # auto | off | require
-FS_SAFE_PYTHON=/usr/bin/python3
+FS_SAFE_NATIVE_MODE=off      # auto | off | require
 ```
 
-OpenClaw compatibility aliases are also accepted:
-`OPENCLAW_FS_SAFE_PYTHON_MODE`, `OPENCLAW_FS_SAFE_PYTHON`,
-`OPENCLAW_PINNED_PYTHON`, and `OPENCLAW_PINNED_WRITE_PYTHON`.
+`OPENCLAW_FS_SAFE_NATIVE_MODE` is also accepted.
 
-Disabling Python keeps the public API working, but downgrades POSIX mutation
-hardening from fd-relative syscalls to Node path operations guarded by lexical
-and canonical checks plus identity verification. Use `require` for
-security-sensitive deployments where that downgrade should be a startup/runtime
-failure instead of a fallback. The full tradeoff is documented in
-[Python helper policy](python-helper.md).
+Disabling native loading keeps the public API 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.
+The exact boundary is documented in [native helper policy](native-helper.md).
 
 ## Verify the install
 

package/docs/json-store.md

@@ -113,7 +113,17 @@ Read, transform, write — under the lock if locking is enabled. Returns the new
 const next = await store.update((prev) => ({ count: (prev?.count ?? 0) + 1 }));
 ```
 
-`run` is async-friendly. The whole `read → run → write` sequence runs inside one `withLock` call, so concurrent updaters from different processes serialize cleanly.
+`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:
 
@@ -137,13 +147,18 @@ const counter = jsonStore<{ count: number }>({
 });
 ```
 
-When `lock` is falsy, `read` / `write` / `update` are unlocked. The `update` shape is still useful — it gives you a single function for the read-modify-write pattern — but it offers no concurrency guarantees if other processes also write to the file.
+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 in-process `FileLockManager` per absolute file path, so two `jsonStore` calls on the same file share lock state automatically.
+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
 

package/docs/migrating-to-0.5.md

@@ -0,0 +1,196 @@
+---
+title: Migrating to 0.5
+description: "Ordered checklist for moving a 0.4 consumer from the Python helper to native mode and adopting the 0.5 API contracts."
+---
+
+# Migrating from 0.4 to 0.5
+
+Use this checklist from top to bottom. Version 0.5 replaces the Python worker,
+changes the default archive mode policy, and adds explicit contracts for
+publication, walking, locks, secrets, and native-only features. Nothing in this
+guide requires a Rust toolchain: all supported native binaries are prebuilt and
+bundled in `@openclaw/fs-safe`.
+
+## 1. Update the package and runtime
+
+- Run on Node.js 22 or newer.
+- Update `@openclaw/fs-safe` and regenerate every lock or shrinkwrap file your
+  deployment consumes.
+- Keep optional dependencies enabled if you want JavaScript ZIP/TAR support.
+  Native loading no longer depends on optional packages because all seven
+  binaries ship in `@openclaw/fs-safe`. An install that omits optional packages
+  can still import fs-safe, but missing JS archive decoders fail with actionable
+  errors.
+
+If you call `resolveRootPath()` or `resolveRootPathSync()` directly, upgrade to
+0.5: versions through 0.4.7 could approve an in-root symlink traversal that
+resolved outside the root. `root()` handles were not affected. See the
+[affected versions and exposure](security-model.md#affected-versions-exposure).
+
+## 2. Replace Python helper configuration
+
+Change startup configuration before the first filesystem operation:
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "auto" });
+```
+
+| Remove from 0.4 | Use in 0.5 |
+|---|---|
+| `configureFsSafePython({ mode })` | `configureFsSafeNative({ mode })` |
+| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
+| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
+| `pythonPath`, `FS_SAFE_PYTHON`, pinned-Python aliases | Nothing; bundled native binaries do not use an interpreter |
+
+The old names warn once and map `auto`, `off`, or `require` so a shipped 0.4
+deployment does not silently change policy. Interpreter paths are ignored and
+Python is never spawned. Treat that warning as an upgrade diagnostic, not as a
+second supported helper path.
+
+Choose the production mode deliberately:
+
+- `auto` keeps guarded JavaScript fallbacks when a binding is unavailable.
+- `off` makes fallback testing deterministic.
+- `require` fails with `helper-unavailable` instead of weakening an operation
+  that expected native support.
+
+See [Native helper policy](native-helper.md) and
+[Native architecture](native.md).
+
+## 3. Audit every archive call
+
+The 0.5 default is `entryModes: "clamp"`. Directories become `0o755`; files
+become `0o644` or `0o755` when owner-execute was archived. Set
+`entryModes: "preserve"` explicitly only if your 0.4 consumer intentionally
+relied on archived rwx bits. Setuid, setgid, sticky bits, and archived ownership
+are never restored.
+
+```ts
+await extractArchive({
+  archivePath: uploadPath,
+  destDir: restoreRoot,
+  timeoutMs: 30_000,
+  entryModes: "clamp",
+  entryFilter: (entry) =>
+    entry.path.startsWith("snapshot/cache/") ? "skip" : "extract",
+  onFiltered: "skip-entry",
+  limits: {
+    maxArchiveBytes: 256 * 1024 * 1024,
+    maxEntries: 50_000,
+    maxExtractedBytes: 512 * 1024 * 1024,
+    maxEntryBytes: 256 * 1024 * 1024,
+    maxMetaEntryBytes: 1024 * 1024,
+    maxEntryPathComponents: 64,
+  },
+});
+```
+
+Returning `"skip"` rejects the archive unless `onFiltered: "skip-entry"` is
+explicit. Zstd and bzip2 TAR are native-only; ZIP, TAR, and gzip retain guarded
+JavaScript implementations. Catch `ArchiveLimitError` by its code, including
+`archive-entry-path-components-exceeds-limit` for deep implicit-directory
+attacks. See [Archive extraction](archive.md).
+
+## 4. Pick a publication failure policy
+
+`publishFileExclusive()` never replaces an existing target. Choose a strategy
+and decide what a post-create directory-sync failure means to your application:
+
+```ts
+await publishFileExclusive({
+  sourcePath: stagedArchive,
+  targetPath: finalArchive,
+  strategy: "link-or-copy",
+  onSyncFailure: "preserve",
+});
+```
+
+`rollback` is the default: an unchanged target created by this call is removed
+when directory sync throws. `preserve` keeps a complete but possibly
+non-durable target and reports `cleanup: "preserved"` plus
+`directorySync: { status: "failed", code? }` in the typed error. Backup
+archives commonly need `preserve`; transactional protocols that expose only
+durably committed names usually want `rollback`. See
+[Directory durability](durability.md).
+
+## 5. Replace recursive scans with an explicit walk policy
+
+Use `Root.walk()` for caller-controlled relative paths. Every examined entry
+consumes the budget even when filtered:
+
+```ts
+for await (const entry of workspace.walk("memory", {
+  maxDepth: 12,
+  maxEntries: 50_000,
+  symlinkPolicy: "skip",
+  entryFilter: (entry) =>
+    entry.kind === "directory" && entry.relativePath.endsWith("/.git")
+      ? "skip-subtree"
+      : "include",
+  onDirectoryError: "skip-and-report",
+})) {
+  if (entry.kind === "directory-error") {
+    reportIncompleteSubtree(entry.relativePath, entry.error);
+    continue;
+  }
+  indexEntry(entry);
+}
+```
+
+The default directory-error policy remains `throw`. See
+[Directory walking](walk.md).
+
+## 6. Adopt the focused concurrency and secret APIs
+
+- Use `acquireFileLockSync()` only in synchronous boot or migration code; retry
+  waits block the thread. Request-serving paths should use `withFileLock()`.
+- Remove the `allowReentrant` boolean from async file-lock options. If a logical
+  holder intentionally nests acquisition, pass the same operation-scoped
+  `reentrantOwner` string to each acquisition; different or missing owners
+  contend normally. Never replace the boolean with a process-wide constant.
+  Locked and unlocked `jsonStore` mutations serialize by canonical file path
+  and do not opt into lock reentrancy; nested same-file mutations from an update
+  callback fail with `store-reentrant-update`, so return the complete value from
+  the outer callback instead.
+- Use `createSecretFileAtomic()` for first-writer-wins credentials and catch
+  `secret-exists`; use `writeSecretFileAtomic()` only when replacement is the
+  intended protocol.
+- Async `readSecretFile()` is strict; `tryReadSecretFile()` returns `undefined`
+  only for missing or blank content and still rejects suspicious files.
+- Check `tempWorkspace.cleanup()` results when ownership matters;
+  `identity-mismatch` deliberately preserves a replacement path.
+
+See [File locks](sidecar-lock.md), [Secret files](secret-file.md), and
+[Temp workspaces](temp.md).
+
+## 7. Gate native-only features
+
+`createPrivateDirectory()` is Windows-only and native-only because a pathname
+fallback cannot promise the same creation-time DACL. Zstd/bzip2 extraction and
+`strategy: "rename-noreplace"` are also native-only. Test the unavailable path
+instead of assuming installation always succeeds.
+
+## 8. Run both behavior families in CI
+
+For each consumer workflow that matters:
+
+1. Run once with `FS_SAFE_NATIVE_MODE=auto` on every supported OS.
+2. Run once with `FS_SAFE_NATIVE_MODE=off` to prove the JavaScript fallback.
+3. Run native-required or native-only cases with `FS_SAFE_NATIVE_MODE=require`.
+4. Exercise archive traversal/link/depth limits, publication sync failure, and
+   partial-walk reporting with production-shaped fixtures.
+
+For downstream staging and backup consumers:
+
+- [ ] Replace private whole-file hashing with `sha256File(path | FileHandle)`
+      from `durability`; native mode keeps digest work off the event loop and
+      the JavaScript fallback remains streaming.
+- [ ] If Windows trust policy depends on exact principals, consume
+      `readOwnerAndDacl()` from `permissions`, reject incomplete/null/remote
+      descriptors as your policy requires, skip inherit-only ACEs where
+      appropriate, and apply the application's own SID allowlist.
+
+The [Testing](testing.md) page documents the test hooks and mode setup used by
+fs-safe itself.

package/docs/native-helper.md

@@ -0,0 +1,85 @@
+---
+title: Native helper policy
+description: "How fs-safe loads its bundled native filesystem primitives and how auto, require, and off affect guarded fallbacks."
+---
+
+# Native helper policy
+
+`@openclaw/fs-safe` itself contains seven prebuilt binaries for Linux x64/arm64 (glibc or musl), macOS x64/arm64, and Windows x64. The loader selects `dist/native/<target>/fs-safe-native.node` without optional platform packages, downloads, postinstall scripts, or a consumer Rust build. Carrying every target makes the npm tarball larger, but every installation receives the same complete artifact.
+
+```ts
+import { configureFsSafeNative } from "@openclaw/fs-safe/config";
+
+configureFsSafeNative({ mode: "auto" });    // default
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "require" }); // fail closed when the binding is unavailable
+```
+
+The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_SAFE_NATIVE_MODE`. Accepted values are `auto`, `off`, `require`, `true`, `false`, `on`, `never`, `required`, `1`, and `0`.
+
+## Modes
+
+| Mode | Behavior |
+|---|---|
+| `auto` | Prefer native primitives when the current bundled binary loads; otherwise silently use the guarded JavaScript path. |
+| `off` | Do not load a bundled binary. Use the guarded JavaScript path deterministically. |
+| `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
+
+Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
+
+## Native boundary
+
+The bundled native layer exposes policy-free filesystem mechanisms: beneath-root
+open/mkdir/link, no-replace rename, identity reads, archive decode/execution,
+clone/copy/hash workers, and Windows security descriptor calls. The TypeScript
+layer owns policy, retries, filters, budgets, modes, cleanup, error
+normalization, and the decision to fall back.
+
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS` and `renameat2(RENAME_NOREPLACE)`.
+- macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. No-replace publication uses `renameatx_np(RENAME_EXCL)`.
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points, and uses `FileRenameInfoEx` with replacement disabled.
+
+Native primitives back create-only pinned writes, async sidecar creation,
+guarded publication, archive acceleration, and direct Windows ACL operations.
+Equivalent JavaScript paths remain available for documented fallback-capable
+features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
+for the exact difference.
+
+`openBeneath()` returns `{ fd, containment }`. `containment` is
+`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for macOS and
+Windows. Public JavaScript root open/read/writable results also expose the
+field and report `"best-effort"`; the label reports mechanism, not policy.
+
+## Migration from the Python helper
+
+Version 0.5 removes the Python worker and interpreter-path selection. The mode
+contract is unchanged, so migrate startup configuration directly:
+
+| Python helper configuration | Native replacement |
+|---|---|
+| `configureFsSafePython({ mode: "auto" })` | `configureFsSafeNative({ mode: "auto" })` |
+| `configureFsSafePython({ mode: "off" })` | `configureFsSafeNative({ mode: "off" })` |
+| `configureFsSafePython({ mode: "require" })` | `configureFsSafeNative({ mode: "require" })` |
+| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
+| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
+| `pythonPath`, `FS_SAFE_PYTHON`, and the OpenClaw interpreter-path aliases | Remove; prebuilt bindings do not use an interpreter path |
+
+In 0.5, `configureFsSafePython` and the legacy Python environment names
+remain only as an upgrade bridge. On the first config read they emit one
+`DeprecationWarning` with code `FS_SAFE_PYTHON_DEPRECATED`, state the mapped
+native mode, and then apply that mode. A legacy interpreter path without an
+explicit mode maps to `auto` and the path itself is ignored. Native config has
+the normal precedence over legacy environment config.
+
+There is no silent alias and no Python execution fallback. The bridge exists
+only to make shipped 0.4 configuration visible and predictable while the
+consumer performs its 0.5 upgrade.
+
+## Related pages
+
+- [Config](config.md)
+- [Security model](security-model.md)
+- [Writing](writing.md)
+- [File locks](sidecar-lock.md)
+- [Durability](durability.md)
+- [Migrating to 0.5](migrating-to-0.5.md)