@openclaw/fs-safe 0.4.6 → 0.5.0

package/docs/durability.md

@@ -0,0 +1,299 @@
+---
+title: Directory durability
+description: "Pin directory identities, fsync publication metadata, and durably create nested directory paths."
+---
+
+# Directory durability
+
+`@openclaw/fs-safe/durability` provides the directory side of crash-safe file
+publication. Flushing a file does not guarantee that its containing directory
+entry reached storage; callers that promise durable create, link, rename, or
+unlink operations must also synchronize the affected directory.
+
+```ts
+import {
+  ensureDurableDirectory,
+  pinDirectory,
+} from "@openclaw/fs-safe/durability";
+
+const repository = await ensureDurableDirectory({
+  directoryPath: "/srv/backups/sqlite",
+  mode: 0o700,
+});
+
+const pinned = await pinDirectory(repository, { label: "backup repository" });
+try {
+  await publishSnapshot();
+  const outcome = await pinned.sync();
+  if (outcome.status === "unsupported") {
+    // Decide at the product boundary whether this platform can weaken the promise.
+  }
+} finally {
+  await pinned.close();
+}
+```
+
+## Outcomes and failure semantics
+
+`syncDirectory()` and `PinnedDirectory.sync()` return:
+
+```ts
+type DirectorySyncOutcome =
+  | { status: "synced" }
+  | { status: "unsupported"; code?: string };
+```
+
+POSIX synchronization failures propagate. Windows directory handles do not
+portably support `FlushFileBuffers`; the known unsupported error family is
+reported as `unsupported` after the pathname and pinned identity are checked
+again. Directory-open access failures and other Windows I/O failures still
+propagate.
+
+`syncDirectoryBestEffort()` and `syncDirectoryBestEffortSync()` intentionally
+discard both unsupported outcomes and failures. Use them only when the primary
+write remains useful without a crash-durability promise.
+
+## Pinned directories
+
+`pinDirectory()` rejects final symlinks and non-directories. On POSIX it opens
+with `O_DIRECTORY`, `O_NOFOLLOW`, and `O_NONBLOCK`, then compares the open
+descriptor, pathname identity, and canonical path. `assertCurrent()` repeats
+those checks. This prevents a pathname replacement from turning a later sync
+into proof for a different directory.
+
+Call `close()` in `finally`. Closing is idempotent; using a closed pin fails.
+
+## Durable directory creation
+
+`ensureDurableDirectory()` finds and pins the nearest existing ancestor,
+creates the requested path, opens every new directory segment, and synchronizes
+each new parent-to-child edge from the leaf upward. It returns the final
+directory receipt plus the aggregate parent-sync outcome.
+
+By default it uses fs-safe's guarded one-segment-at-a-time absolute-directory
+creator. Advanced callers can pass `create` when directory creation needs
+platform-specific ACLs or another product-owned policy. The callback owns the
+safety of its mutations and must create exactly `directoryPath`; fs-safe
+validates and pins every resulting segment before any synchronization is
+accepted.
+
+`expectedExistingIdentity` binds an existing target to an identity observed by
+the caller before a separate permission or policy check. A missing or replaced
+target fails with `FsSafeError("path-mismatch")`.
+
+## Exclusive file publication
+
+`publishFileExclusive()` materializes one file without clobbering an existing
+target. It pins the source with `O_NOFOLLOW`, optionally verifies
+`expectedSourceIdentity`, tries a hardlink first, then synchronizes the target
+parent directory.
+
+For example, a backup archive is complete before publication. If directory
+sync fails, keeping that complete file is more useful than conditionally
+deleting it by pathname:
+
+```ts
+import { FsSafeError } from "@openclaw/fs-safe/errors";
+import { publishFileExclusive } from "@openclaw/fs-safe/durability";
+
+try {
+  const result = await publishFileExclusive({
+    sourcePath: stagedArchive,
+    targetPath: finalArchive,
+    strategy: "link-or-copy",
+    onSyncFailure: "preserve",
+    parentReceipt: backupDirectory,
+  });
+  recordDurableBackup(result.identity, result.directorySync);
+} catch (error) {
+  if (
+    error instanceof FsSafeError &&
+    error.details?.phase === "directory-sync" &&
+    error.details.cleanup === "preserved"
+  ) {
+    recordCompleteButPossiblyNonDurableBackup(finalArchive, error.details);
+  } else {
+    throw error;
+  }
+}
+```
+
+### Strategies
+
+| Strategy | Behavior | Native requirement |
+|---|---|---|
+| `link-required` | Create a same-filesystem hardlink or propagate the failure. | No; guarded JS `link` fallback remains. |
+| `link-or-copy` | Try hardlink, then clone, Linux `copy_file_range`, then the JS byte loop for classified unsupported errors. | No; acceleration is optional. |
+| `rename-noreplace` | Atomically move the source without replacing an existing target. Success consumes `sourcePath`. | Yes. |
+
+`"link-required"` propagates an unsupported hardlink failure.
+`"link-or-copy"` falls back only for `EPERM`, `EXDEV`, `ENOTSUP`,
+`EOPNOTSUPP`, or `ENOSYS`; `isHardlinkFallbackError()` exposes that exact
+classifier. The fallback copies from the pinned source into a `wx` target,
+fsyncs it, and fences source and target identity and content before reporting
+success. `parentReceipt`, when supplied, must name the target's direct parent.
+
+With a native binding, the copy fallback first attempts a copy-on-write clone
+(`fclonefileat` on macOS, `FICLONE` on Linux), then Linux
+`copy_file_range`, and finally the existing JavaScript byte loop. Every route
+creates the target exclusively, normalizes its mode to `0o600`, and goes
+through the same post-copy identity and SHA-256 fencing. Hashing uses an async
+native task when available, so large verification reads do not occupy the
+JavaScript event loop.
+
+On a clone-capable filesystem, publication of a large file becomes mostly a
+metadata operation: data blocks are shared copy-on-write until either file is
+modified. Clone support is filesystem- and mount-dependent, so callers must
+not infer durability or physical independence from timing; an unsupported
+clone or `copy_file_range` transparently continues down the fallback chain.
+
+## Recoverable atomic-replace fallback
+
+`replaceFileAtomic()` normally publishes a synchronized sibling temp with an
+atomic rename. Some Windows filesystems and file owners reject that rename with
+`EPERM` or `EEXIST`; `copyFallbackOnPermissionError: true` permits a non-atomic
+copy fallback.
+
+Callers that cannot tolerate a torn in-place fallback can add:
+
+```ts
+await replaceFileAtomic({
+  filePath: statePath,
+  content: nextState,
+  syncTempFile: true,
+  syncParentDir: true,
+  copyFallbackOnPermissionError: true,
+  copyFallbackRestore: "restore-original",
+  maxRestoreBytes: 4 * 1024 * 1024,
+  destinationHardlinks: "reject",
+});
+```
+
+The existing regular-file destination is pinned before its link count is
+accepted. Its original bytes are read within `maxRestoreBytes`, then the new
+bytes are written and synchronized through the same descriptor. If a write or
+sync tears, fs-safe rewrites the snapshot and fsyncs it before throwing. Inspect
+`details.cleanup`: `"restored"` means the original bytes were put back and
+synchronized; `"restore-failed"` means the replacement and recovery both
+failed, so the destination must be treated as indeterminate. This is recovery
+from a live-process I/O failure, not a transaction or a substitute for an
+application backup protocol.
+
+## Streaming SHA-256
+
+`sha256File()` hashes either a pathname string or an already-open Node
+`FileHandle`. A backup verifier can pin the file itself, compare its size, and
+keep ownership of the handle:
+
+```ts
+import { open } from "node:fs/promises";
+import { sha256File } from "@openclaw/fs-safe/durability";
+
+const snapshot = await open(stagedArchive, "r");
+try {
+  const before = await snapshot.stat();
+  const hash = await sha256File(snapshot);
+  if (hash.bytes !== before.size || hash.digest !== manifest.sha256) {
+    throw new Error("staged backup does not match its manifest");
+  }
+} finally {
+  await snapshot.close();
+}
+```
+
+The result is `{ bytes, digest }`, where `digest` is lowercase hexadecimal.
+The handle overload never closes the caller's descriptor and uses positioned
+reads, so it does not alter the descriptor's current offset. The path overload
+rejects symbolic links and non-regular files, verifies the opened descriptor
+still names the requested path, and closes its own handle. POSIX opens are
+nonblocking, so a raced FIFO or device is rejected after descriptor inspection
+rather than waiting for a writer.
+
+When the optional binding is active, hashing runs as an async native task and
+does not occupy the JavaScript event loop with digest updates. With native mode
+`off`, or in `auto` when no binding loads, the fallback performs asynchronous
+positioned reads in 64 KiB chunks but updates Node's `Hash` on the JavaScript
+thread. Both paths stream constant-size buffers rather than loading the file
+into memory. Native mode `require` keeps its usual fail-closed loader semantics.
+
+If publication fails after this call created the target, it throws an
+`FsSafeError` with a `details` receipt:
+
+```ts
+type PublishFileExclusiveFailureDetails = {
+  phase:
+    | "hardlink-create" | "hardlink-verify"
+    | "copy-create" | "copy-verify"
+    | "rename-create" | "rename-verify"
+    | "directory-sync";
+  targetCreated: boolean;
+  targetIdentity?: { dev: number | bigint; ino: number | bigint };
+  cleanup: "removed" | "preserved" | "unknown";
+  directorySync?: { status: "failed"; code?: string };
+};
+```
+
+`"removed"` means the path still matched the identity created by this call and
+was unlinked (or was already absent). `"preserved"` means it was deliberately
+retained—for example after a successful no-replace rename—or the pathname had
+been replaced and therefore was not safe to remove. `"unknown"` means cleanup
+could not verify or remove the created identity. Callers that run a second
+application-level guard, such as SQLite snapshot validation, should branch on
+this receipt instead of inferring ownership from path existence. The original
+failure remains available as `cause`. Failures before target creation retain
+their existing error shape and do not claim a cleanup result.
+
+### Directory-sync failure policy
+
+`onSyncFailure` applies only after target creation and content/identity fencing
+have succeeded but synchronizing the containing directory throws:
+
+```ts
+type PublishFileExclusiveSyncFailurePolicy = "rollback" | "preserve";
+```
+
+A returned `{ status: "unsupported", code? }` is an explicit successful
+publication outcome, not a thrown sync failure, so this option does not rewrite
+or clean up that target.
+
+- `rollback` is the default. fs-safe removes the target only if its current
+  identity still matches the file created by this call. A replacement is never
+  removed. The error reports `cleanup: "removed"`, `"preserved"`, or
+  `"unknown"` and `directorySync: { status: "failed", code? }`.
+- `preserve` never attempts that unlink. The error reports
+  `targetCreated: true`, `cleanup: "preserved"`, the created identity, and the
+  failed directory-sync outcome. The file is complete and fenced, but its
+  directory entry is not proven crash-durable.
+
+Choose `rollback` when the pathname must mean “durably committed” and a failed
+commit should disappear from the live process view. Choose `preserve` when the
+payload itself remains valuable—backup archives are the common case—and the
+caller can record, retry, or independently validate durability. Neither choice
+can make a failed directory sync succeed: rollback deletion is also not proven
+durable, and a preserved name may disappear after a crash. Always use the
+typed receipt rather than inferring ownership from `exists()`.
+
+`rename-noreplace` always preserves its target after a successful rename,
+because removing it would discard the source's only remaining name; its typed
+failure receipt makes that explicit regardless of `onSyncFailure`.
+
+`"rename-noreplace"` requires the native helper and atomically moves the
+source to the target without replacement. A collision is reported as
+`EEXIST`, both files remain unchanged, and a successful call returns
+`method: "rename-noreplace"` after synchronizing the source and target parent
+directories. Unlike the link/copy strategies, success consumes `sourcePath`.
+
+## Scope
+
+These primitives establish path identity and filesystem synchronization. One
+`publishFileExclusive()` call is one no-clobber file materialization, not a
+retention policy, multi-file transaction, or application commit protocol. They
+do not decide application commit protocols, marker formats, permission policy,
+or whether an unsupported platform is acceptable. Keep those decisions at the
+owning product boundary.
+
+## See also
+
+- [Migrating to 0.5](migrating-to-0.5.md) — choosing a publication policy during upgrade.
+- [Native architecture](native.md) — clone/copy/hash mechanisms and fallback guarantees.
+- [Errors](errors.md) — typed operational failure handling.

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,10 +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. |
+| [`@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`. |
@@ -60,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