@openclaw/fs-safe 0.5.1 → 0.5.3

package/docs/root.md

@@ -21,9 +21,10 @@ type RootDefaults = {
   hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
-  mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append
+  mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append; default true
   mode?: number;                   // file mode applied to new writes; per-call override available
-  nonBlockingRead?: boolean;       // schedule reads on a worker; useful for large files
+  nonBlockingRead?: boolean;       // compatibility hint; safe opens are already nonblocking where supported
+  renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
   symlinks?: "reject" | "follow-within-root"; // policy when a path component is a symlink
 };
 
@@ -83,6 +84,10 @@ await using opened = await fs.open("large.log");
 `containment: "best-effort"`. The field reports the mechanism used; see the
 [security model](security-model.md#containment-guarantees-by-platform).
 
+The read methods also accept an absolute spelling that already resolves inside
+the root. `readAbsolute()` and `reader()` make that intent explicit; an absolute
+path outside the root is still rejected.
+
 ### Writes
 
 ```ts
@@ -103,6 +108,14 @@ fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 
 `copyIn` is a one-shot ingest from a trusted absolute source path: it streams the source through the boundary, atomically renames into the root, and respects `maxBytes`.
 
+Root operations that choose a new destination reject a leading Windows
+drive-relative spelling such as `C:name` on every platform. This applies to
+`write`, `create`, `append`, `openWritable`, `mkdir`, `copyIn`, and the
+destination argument of `move`. In particular, `copyIn(path.basename(source),
+source)` can reject a legal POSIX basename such as `c:photo.png`; callers that
+derive portable destination names from host files must sanitize or map that
+basename first.
+
 `openWritable` opens a writable file with options `mode?: number` and `writeMode?: "replace" | "append" | "update"`. `replace` truncates existing files and is the default; `update` keeps existing contents. Use it for streaming output. Prefer `await using` for cleanup.
 
 All mutation methods accept `denyMutations?: { paths?: string[]; prefixes?: string[] }`. Entries must be absolute paths. `paths` blocks those exact paths; `prefixes` blocks those paths and their descendants. fs-safe preserves path strings exactly and canonicalizes through existing ancestors before comparing, so a symlinked ancestor to a denied location is still denied. Denied mutations throw `FsSafeError` with code `denied-path`. Use this for caller-specific sensitive paths, not as a replacement for the root boundary, symlink, or hardlink checks.
@@ -119,6 +132,12 @@ fs.resolve(rel)                  // absolute path inside the root, after canonic
 
 These do not pin a later operation. They are safe to expose to UIs and decision points; for the actual read or write, use the verb methods so the operation pins identity at the point of use.
 
+`resolve()` is the exception to the existing-object rule: because it selects a
+location for later use, it rejects a leading drive-relative spelling. Reads,
+`stat`, `exists`, `list`, `walk`, `remove`, and the source argument of `move`
+accept an existing POSIX filename such as `c:notes.txt`. For `move`, only the
+new destination name is subject to the portable guard.
+
 ## Native helper mode
 
 Create-only writes prefer the bundled native helper for fd-relative opens and
@@ -147,11 +166,14 @@ fs.defaults      // the RootDefaults you passed
 
 ## Failure semantics
 
-Every method throws `FsSafeError` with a `code`. Branch on `err.code`, not message text. Common codes:
+Boundary and policy failures throw `FsSafeError` with a `code`. Parsing callbacks
+and underlying filesystem operations can also surface `SyntaxError` or native
+`NodeJS.ErrnoException` values. Branch on `err.code`, not message text, after
+checking `err instanceof FsSafeError`. Common fs-safe codes:
 
 | Code | When it fires |
 |---|---|
-| `invalid-path` | The input path is malformed, including embedded NUL bytes. |
+| `invalid-path` | The input path is malformed, including embedded NUL bytes. Portable relative-path helpers and `FileStore` keys reject drive-relative segments; Root destination and resolution operations reject a leading drive-relative spelling such as `C:name`. |
 | `outside-workspace` | The input resolves outside the root, or contains a `..` segment that would escape it. |
 | `not-found` | The target does not exist (or its parent does not, with `mkdir: false`). |
 | `not-file` | A read or copy targeted a non-regular file (directory, FIFO, socket, …). |

package/docs/secret-file.md

@@ -23,7 +23,7 @@ import {
 | The file is a credential (token, key, password). | The file is application state. |
 | You want the parent directory created at `0o700` if missing. | You don't care about the parent directory mode. |
 | You want a hard size cap on reads (to defend against bogus input). | You're reading bounded JSON state. |
-| Mode `0o600` is mandatory, not just nice. | Mode is whatever umask gives you. |
+| Mode `0o600` and the private parent policy are mandatory. | Standalone `writeJson` also defaults to `0o600`, but it does not enforce the secret-directory ownership and permission policy. |
 
 ## Constants
 
@@ -39,7 +39,10 @@ The 16 KiB cap is intentionally aggressive — credentials should be small. If y
 
 ### `tryReadSecretFileSync(filePath, label, options?)`
 
-The lenient reader. Returns the trimmed secret string, or `undefined` when the path is missing or blank. Validation failures, unreadable files, oversized files, symlinks, and hardlinks throw `FsSafeError` so callers fail closed on suspicious credential state.
+The missing-is-optional reader. It returns the trimmed secret string, or
+`undefined` when the `filePath` argument is absent/blank or the target does not
+exist. An existing empty file is invalid and throws, as do unreadable,
+oversized, symlink, hardlink, and other validation failures.
 
 ```ts
 import { tryReadSecretFileSync } from "@openclaw/fs-safe/secret";
@@ -65,17 +68,31 @@ const token = readSecretFileSync("/var/lib/app/auth.token", "auth token");
 ```ts
 type SecretFileReadOptions = {
   maxBytes?: number;         // default DEFAULT_SECRET_FILE_MAX_BYTES (16 KiB)
-  rejectSymlink?: boolean;
+  rejectSymlink?: boolean;   // default false
   rejectHardlinks?: boolean; // default true
 };
 ```
 
-The reader trims the file content and rejects empty results. `rejectSymlink` blocks a symlink path before the pinned read. Hardlinks are rejected by default so another in-tree name cannot alias the credential; pass `rejectHardlinks: false` only when you explicitly trust that layout.
+The reader trims the file content and rejects empty results. Symlink paths are
+followed and pinned by default; set `rejectSymlink: true` when the pathname
+itself must not be an alias. Hardlinks are rejected by default so another
+in-tree name cannot alias the credential; pass `rejectHardlinks: false` only
+when you explicitly trust that layout.
+
+These readers do not enforce ownership or mode bits on an existing file. Their
+read contract covers pinned identity, file type, link policy, and byte bounds;
+the `0o600` guarantee belongs to the write helpers below. Use
+[`readSecureFile`](secure-file.md) when reading an externally managed
+credential must also fail on broad permissions or unexpected ownership.
 
 `readSecretFile()` and `tryReadSecretFile()` are asynchronous counterparts with
 the same pinned-handle validation, byte cap, trimming, error codes, and strict
 versus missing-is-undefined naming semantics.
 
+If an already validated descriptor fails while reading, both readers throw an
+operational `FsSafeError` with `code: "read-failed"`; inspect `cause` for the
+underlying Node filesystem code such as `EIO`.
+
 Use the async strict reader when a service cannot start safely without the
 credential:
 

package/docs/security-model.md

@@ -22,7 +22,8 @@ case since `5ddca80`. Exposure is limited to consumers that call
 You hand a `root()` boundary to a piece of code that takes caller-controlled relative paths. The library defends against a caller that:
 
 - supplies `..` traversal segments to escape the boundary
-- supplies an absolute path where a relative one is expected
+- supplies an absolute path outside a configured root, or to an API whose input
+  contract is strictly relative/portable
 - replaces a path component with a symlink between check and use (TOCTOU)
 - replaces the destination directory with a symlink right before a write
 - creates a hardlink that aliases an out-of-tree inode and asks you to read or replace it
@@ -44,7 +45,7 @@ If you need full sandboxing, run the worker under reduced privileges (uid, conta
 
 ### Path traversal and absolute paths
 
-Every relative path is resolved against the canonicalized real path of the root, then checked with `isPathInside`. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal that escapes, leading `/` (without `pathScope` opt-in), or any canonical result outside the root throws `outside-workspace`.
+Every path is resolved against the canonicalized real path of the root, then checked with `isPathInside`. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal, an absolute spelling, or any alias whose canonical result is outside the root throws `outside-workspace`; absolute spellings that remain inside the root are accepted.
 
 ### Symlinks (read side)
 
@@ -54,7 +55,20 @@ Per-call `symlinks: "follow-within-root"` allows symlinks whose final target is
 
 ### Symlinks (write side)
 
-Writes use a sibling-temp + rename helper that opens the parent directory by fd, then performs the rename `at` the parent fd. Replacing the parent directory with a symlink between the parent-fd open and the rename does not divert the write.
+With the native binding loaded, `write()`, `create()`, and `copyIn()` use a
+sibling temp file and create parents and publish the target relative to pinned
+directory descriptors. Replacement uses descriptor-relative rename just like
+no-replace publication, so replacing the parent pathname does not divert the
+mutation.
+
+The JavaScript fallback used by `off`, by `auto` when no binding loads, and by
+the explicit `renameIdentity: "verify-content-with-lock"` compatibility policy
+cannot provide that guarantee because Node exposes no `mkdirat` or `renameat`.
+It asserts directory identity around a pathname mutation and detects many
+swaps, but detection occurs after the kernel may already have followed a new
+parent symlink. A same-privilege peer with write access to the parent can
+therefore cause an out-of-root side effect before the operation throws. Use
+native `require` mode when concurrent hostile mutation is in scope.
 
 ### Hardlink aliasing
 
@@ -64,13 +78,15 @@ When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink >
 
 `resolve()`, `exists()`, `stat()`, and `list()` are explicitly advisory — they answer a question and return. To act on a path with operation-local identity checks, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. The containment table below states which opens are kernel-atomic and which remain best-effort.
 
+A `root()` handle also remembers the canonical root directory identity. Calls fail with `path-mismatch` if that canonical pathname is replaced, including advisory inspection and walking calls, rather than following a replacement root into another tree.
+
 ### Denied mutations
 
 `denyMutations` is an opt-in application policy for `root()` mutation methods. It blocks exact absolute paths with `paths` and whole subtrees with `prefixes`, merging root defaults with per-call entries so a call cannot clear root-level denies. This is not an OS permission boundary: code with access to `node:fs`, a shell, or another process with the same filesystem privileges can bypass it.
 
 ### Atomic writes
 
-`replaceFileAtomic` writes to a sibling temp file in the destination directory, optionally `fsync`s it, optionally `fsync`s the parent directory after rename, and atomically renames over the destination. On failure mid-write, the destination is either the old contents (rename never happened) or the new contents (rename succeeded). There is no half-written intermediate state visible at the destination path.
+`replaceFileAtomic` writes to a sibling temp file in the destination directory, optionally `fsync`s it, optionally `fsync`s the parent directory after rename, and atomically renames over the destination. On failure mid-write, the destination is either the old contents (rename never happened) or the new contents (rename succeeded). There is no half-written intermediate state visible at the destination path unless the caller explicitly enables `copyFallbackOnPermissionError`, whose default `copyFallbackRestore: "none"` contract may leave a partial destination after a failed in-place fallback.
 
 Within one process, async writes to the same target are queued so their temp-write/rename phases do not overlap. Cross-process writers still need an external protocol such as the sidecar lock helpers.
 
@@ -120,6 +136,7 @@ The public `OpenResult`, `ReadResult`, and `WritableOpenResult` expose `containm
 | Absolute paths are escape hatches | APIs that accept or return absolute paths exist for audit, ingest, and advanced composition. Prefer root-relative names in normal application flow. |
 | Not a mount boundary | `root()` keeps path traversal inside the directory tree and blocks known unsafe read device paths, but it does not make bind mounts or virtual filesystems safe to expose wholesale. |
 | Per-call, not per-session | Another process with the same privileges can still mutate the tree between calls, and best-effort mechanisms retain documented same-call race windows. Use one verb method to minimize the window and inspect its reported containment class. |
+| JavaScript mutations are detection-based | Without the native binding, Node pathname mutations retain a check-to-syscall race. A writable parent can be swapped so a create, rename, or removal affects an out-of-root path before the fallback detects identity drift. |
 | Hardlink rejection is best-effort | Link-count checks depend on platform metadata. Treat `hardlinks: "reject"` as a tripwire, not an authorization primitive. |
 | Mode bits are not a full policy engine | `replaceFileAtomic` and secret-file helpers set requested modes, but you should still set umask and inspect modes when policy requires it. |
 | Archive extraction is path safety, not content safety | Unsafe entry paths and links are rejected; malicious payload contents remain your application layer's problem. |

package/docs/sidecar-lock.md

@@ -96,6 +96,12 @@ type FileLockRetryOptions = {
 result is passed to `shouldReclaim` and `shouldRemoveStaleLock`, allowing PID,
 process-start, argv, or role schemas to remain application-owned.
 
+On Windows, a pathed `EPERM` from creating or opening the lock file can be a
+short teardown race after another holder unlinks it. The async lock retries that
+specific denial at most eight times. A parent-directory denial, a denial from a
+callback, or a ninth consecutive lock-file denial surfaces as the original
+`EPERM`; it is not converted to `file_lock_timeout`.
+
 ## Owner-scoped reentrancy
 
 Version 0.5 removes the unsound process-scoped `allowReentrant` boolean and
@@ -167,10 +173,10 @@ progress.
 ## Synchronous locks
 
 `acquireFileLockSync()` and `withFileLockSync()` mirror filesystem arbitration,
-retry, payload parsing, stale policy, guarded identity-conditioned reclaim,
-verification, and compromise monitoring. They do not use the async manager
-queue, support async callbacks, or provide same-process reentrancy. Retry waits
-block the calling thread; use the async API in request-serving code.
+retry, payload parsing, stale policy, owner-scoped reentrancy, guarded
+identity-conditioned reclaim, verification, and compromise monitoring. They do
+not use the async manager queue or support async callbacks. Retry waits block
+the calling thread; use the async API in request-serving code.
 
 Always release in a `finally`:
 
@@ -236,7 +242,11 @@ await locks.drain();
 
 ## Stale policy: `shouldReclaim`
 
-The default policy treats locks whose `createdAt` is older than `staleMs` as stale. Pass a custom callback when you want a richer notion of "is the holder still alive":
+The default policy treats locks whose valid `createdAt` is older than `staleMs`
+as stale. A valid current or future timestamp remains authoritative under
+filesystem clock skew; only absent or malformed timestamps fall back to the
+sidecar `mtime`. Pass a custom callback when you want a richer notion of "is the
+holder still alive":
 
 ```ts
 import { kill } from "node:process";

package/docs/temp.md

@@ -45,6 +45,11 @@ await runBuild(workspace.dir, inputPath);
 ```
 
 `write` writes at `mode` (default `0o600`); `writeText` and `writeJson` are convenience wrappers for the common scratch-file shapes; `copyIn` ingests an absolute source path through the same atomic-rename machinery as `Root.copyIn`. `read` is a small accessor that reads back any file you wrote into the workspace.
+Both the async and sync `read` methods throw `FsSafeError("not-file")` when the
+named leaf is a directory or another non-regular target, and preserve the
+`not-found`, `hardlink`, or `symlink` code for those stable target states.
+Operational filesystem read failures use `read-failed` with the Node error in
+`cause`.
 
 `store` is a `fileStore({ rootDir: workspace.dir, private: true })` handle. Use
 it when you want the richer store surface, including `writeStream`, `exists`,
@@ -157,11 +162,15 @@ type TempFile = {
   path: string;                            // absolute path; safe to write to
   dir: string;                             // the enclosing private workspace dir
   file(fileName?: string): string;          // resolve another file in the same dir
-  cleanup(): Promise<void>;                 // removes the private workspace dir
+  cleanup(): Promise<void>;                 // removes the original private workspace dir
   [Symbol.asyncDispose](): Promise<void>;   // alias of cleanup()
 };
 ```
 
+Cleanup captures the directory identity at creation time. If that path is
+renamed away and replaced, cleanup preserves the replacement rather than
+recursively deleting a directory it did not create.
+
 ### `withTempFile`
 
 Same shape with auto-cleanup:
@@ -239,13 +248,41 @@ const tempRoot = resolveSecureTempRoot({ fallbackPrefix: "my-app" });
 
 ```ts
 type ResolveSecureTempRootOptions = {
-  fallbackPrefix: string;   // base name for the per-user fallback dir
-  preferredDir?: string;    // optional preferred secure temp root
-  tmpdir?: () => string;    // override os.tmpdir()
+  fallbackPrefix: string;             // one portable path segment; invalid values throw
+  preferredDir?: string;              // preferred secure temp root
+  skipPreferredOnWindows?: boolean;
+  unsafeFallbackLabel?: string;       // text used in thrown errors
+  warningPrefix?: string;             // default "[fs-safe]"
+  warn?: (message: string) => void;    // default console.warn
+
+  // Platform/test adapters; production callers normally omit these.
+  platform?: NodeJS.Platform;
+  getuid?: () => number | undefined;
+  tmpdir?: () => string;
+  accessSync?: typeof import("node:fs").accessSync;
+  chmodSync?: typeof import("node:fs").chmodSync;
+  lstatSync?: (path: string) => {
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    mode?: number;
+    uid?: number;
+  };
+  mkdirSync?: (
+    path: string,
+    options: { recursive: boolean; mode?: number },
+  ) => void;
 };
 ```
 
-The directory name embeds the user's UID (POSIX) or username so multi-user systems don't collide. On unsupported platforms, falls back to `os.tmpdir()` directly with a `helper-unavailable` error code surfaced to callers that explicitly required the secure root.
+When `process.getuid()` is available, the fallback is
+`<tmpdir>/<fallbackPrefix>-<uid>`. Without a UID (including Windows), it is
+`<tmpdir>/<fallbackPrefix>`; no username is appended. The helper never returns
+the shared `os.tmpdir()` directory itself. It requires the selected path to be
+a writable, non-symlink directory and, when UID/mode facts are available,
+owned by the current user without group/world write bits. It creates or repairs
+the fallback to mode `0o700` where mode bits apply. If it cannot establish that
+state, it throws an ordinary `Error`; there is no native mode or
+`helper-unavailable` branch on this API.
 
 ## Common patterns
 

package/docs/test-hooks.md

@@ -37,6 +37,7 @@ type FsSafeTestHooks = {
   beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
   afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
   beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
+  beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
   beforeTrashMove?: (targetPath: string, destPath: string) => void;
   afterPublishTargetCreated?: (method, targetPath, identity) => Promise<void> | void;
   beforePublishDirectorySync?: (method, targetPath, identity) => Promise<void> | void;
@@ -54,6 +55,7 @@ type FsSafeTestHooks = {
 | `beforeRootFallbackMutation` | A guarded JS root fallback is about to mkdir, move, or remove. |
 | `afterPinnedWriteFallbackRename` | A fallback rename committed and post-commit identity checks have not run yet. |
 | `beforeSiblingTempWrite` | A sibling temp file exists and its writer is about to run. |
+| `beforeSidecarLockSnapshotOpen` | A sidecar lock was inspected and is about to be opened for a bounded snapshot read. |
 | `beforeTrashMove` | Trash handling is about to move the target. |
 | `afterPublishTargetCreated` | Exclusive publication created its target and final fences have not run yet. |
 | `beforePublishDirectorySync` | Publication verified the target and is about to sync its parent directory. |

package/docs/types.md

@@ -2,6 +2,8 @@
 
 The types most callers reach for. Shared data shapes are exported from `@openclaw/fs-safe/types`; method-specific option/result types live next to their subpath.
 
+For atomic replacement, `ReplaceFileAtomicFileSystem` and `ReplaceFileAtomicSyncFileSystem` are exported from `@openclaw/fs-safe/atomic`. Async adapters use `chmod()` on the `FileHandle` returned by their required `open()` operation. The synchronous type adds optional `fchmodSync(fd, mode)`; custom sync adapters that explicitly request `mode` or `preserveExistingMode` must implement it. See [Atomic writes](atomic.md#test-injection).
+
 ```ts
 import type {
   BasePathOptions,
@@ -16,15 +18,24 @@ import type {
 
 ```ts
 type PathStat = {
-  kind: "file" | "directory" | "symlink" | "fifo" | "socket" | "blockDevice" | "characterDevice" | "unknown";
-  size: number;       // bytes
-  mtimeMs: number;    // milliseconds since epoch
-  mode: number;       // POSIX mode bits
-  nlink: number;      // hardlink count
+  dev: number;
+  gid: number;
+  ino: number;
+  isDirectory: boolean;
+  isFile: boolean;
+  isSymbolicLink: boolean;
+  mode: number;
+  mtimeMs: number;
+  nlink: number;
+  size: number;
+  uid: number;
 };
 ```
 
-The shape returned by `Root.stat()`. A trimmed view of `node:fs.Stats` — only the fields the boundary cares about. Use `kind` instead of inspecting the various `is*` methods on a Node `Stats` object; it covers every case in one switchable string.
+The shape returned by `Root.stat()`. It is a serializable view of the identity,
+ownership, mode, size, timestamp, link count, and three file-kind facts the
+boundary uses. Unlike Node's `Stats`, `isFile`, `isDirectory`, and
+`isSymbolicLink` are boolean fields rather than methods.
 
 ## `DirEntry`
 
@@ -34,21 +45,23 @@ type DirEntry = PathStat & {
 };
 ```
 
-Returned by `Root.list(rel, { withFileTypes: true })`. Includes the same `kind`/`size`/etc as `PathStat`, plus the entry's `name`.
+Returned by `Root.list(rel, { withFileTypes: true })`. Includes every
+`PathStat` field plus the entry's `name`.
 
 ## `BasePathOptions`
 
 ```ts
 type BasePathOptions = {
-  fastPathMode?: FastPathMode;
+  rootDir: string;
+  relativePath: string;
 };
 
 type FastPathMode = "auto" | "never" | "require";
 ```
 
-Options shared by helpers that can take a "fast path" (use cheaper syscalls when the input is already absolute and clearly inside scope). The default is `"auto"` — let the helper pick. Force `"never"` in tests if you want to exercise the slow path. Force `"require"` if you need to assert that the fast path is taken (the helper throws if it can't).
-
-Most callers don't need to touch this.
+`BasePathOptions` is the shared root-plus-relative-path record. `FastPathMode`
+is retained as a public compatibility union; no current exported options record
+consumes it, so setting a fast-path policy is not part of the current API.
 
 ## `SafeEncoding`
 
@@ -83,13 +96,16 @@ type ReadResult = {
 ## `RootDefaults` / `RootOptions`
 
 ```ts
+type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
+
 type RootDefaults = {
   denyMutations?: DenyMutationPolicy;
   hardlinks?: "reject" | "allow";
   maxBytes?: number;
-  mkdir?: boolean;
+  mkdir?: boolean; // default true for mutation methods
   mode?: number;
   nonBlockingRead?: boolean;
+  renameIdentity?: RenameIdentityPolicy;
   symlinks?: "reject" | "follow-within-root";
 };
 
@@ -110,7 +126,7 @@ type RootOptions = {
 
 ```ts
 type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
-type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode"> & {
+type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode" | "renameIdentity"> & {
   encoding?: BufferEncoding;
   overwrite?: boolean;
 };
@@ -155,13 +171,14 @@ type FsSafeErrorCode =
   | "helper-unavailable" | "insecure-permissions" | "invalid-path"
   | "not-empty" | "not-file" | "not-found" | "not-owned"
   | "not-removable" | "outside-workspace" | "path-alias"
-  | "path-mismatch" | "permission-unverified" | "symlink"
+  | "path-mismatch" | "permission-unverified" | "read-failed" | "secret-exists"
+  | "store-reentrant-update" | "symlink"
   | "timeout" | "too-large" | "unsupported-platform";
 ```
 
 Closed union you switch on. See the [Errors](errors.md) reference for what each one means.
 
-`FsSafeError.category` is `"policy"` for unsafe input/target-state failures and `"operational"` for environment/runtime failures.
+`FsSafeError.category` is `"policy"` for unsafe input or target state rejected by a safety policy and `"operational"` for routine filesystem outcomes or environment/runtime failures. `not-found`, `not-empty`, `not-removable`, and `read-failed` are operational.
 
 ## See also
 

package/docs/writing.md

@@ -1,6 +1,11 @@
 # Writing
 
-The `Root` handle exposes a tight set of write verbs. Each one is atomic at the destination — no half-written intermediate state — and goes through the same boundary checks as reads.
+The `Root` handle exposes a tight set of mutation verbs. Replacement writes
+(`write`, `create`, `writeJson`, `createJson`, and `copyIn`) publish with a
+sibling-temp commit so no half-written replacement appears at the destination.
+`append` and `openWritable` intentionally modify an opened file in place;
+`move`, `remove`, and `mkdir` mutate directory entries rather than file bytes.
+Each verb applies the boundary checks appropriate to its operation.
 
 ```ts
 await fs.write("state.json", body);
@@ -13,16 +18,20 @@ await fs.remove("logs/yesterday.log");
 await fs.mkdir("snapshots/2026/05");
 ```
 
-## What every write does
+## What replacement writes do
 
 1. Resolve the relative target against the canonical root and reject anything that escapes (`outside-workspace`).
-2. If `mkdir: true`, create missing parent directories with the parent fd pinned.
-3. Pin or guard the parent directory for the selected mechanism. Native operations use a parent fd; guarded JavaScript verifies directory identity before and after mutation. Linux beneath opens are kernel-atomic, while macOS, Windows, and JavaScript routes retain the best-effort race boundaries in the [security model](security-model.md#containment-guarantees-by-platform).
+2. If `mkdir: true`, create missing parent directories relative to a pinned parent fd in the native path, or with per-component identity guards in the JavaScript fallback.
+3. Pin or guard the parent directory for the selected mechanism. Native operations use a parent fd; guarded JavaScript verifies directory identity before and after mutation. The JavaScript check cannot make the intervening pathname syscall atomic, so a same-privilege peer that can replace the parent may cause an out-of-root side effect before detection. Use native `require` mode for that threat model; see the [security model](security-model.md#symlinks-write-side).
 4. Write data to a sibling temp file in the same directory.
 5. Atomically rename the temp file over the destination.
 6. Stat the resulting fd and verify identity.
 
-A failure at any point either leaves the destination at its previous contents or surfaces an `FsSafeError` — never a partially-written file at the destination path.
+A failure before the final rename leaves the destination at its previous
+contents. A successful rename publishes the complete replacement. This
+old-or-new guarantee does not apply to `append()` or `openWritable()`, which
+write in place, or to lower-level atomic helpers when their explicitly
+non-atomic permission-error copy fallback is enabled.
 
 ## Denying mutations
 
@@ -53,7 +62,7 @@ await fs.write("state/last-run.json", JSON.stringify(run));
 await fs.write("notes/today.txt", "hello\n", { encoding: "utf8" });
 ```
 
-`data` accepts `string | Buffer`. `options` are `{ denyMutations?: DenyMutationPolicy; encoding?: BufferEncoding; mkdir?: boolean; mode?: number; overwrite?: boolean }`. `mode` sets the file's POSIX mode; if omitted, falls back to the `mode` from `RootDefaults` and then to umask. `overwrite` defaults to `true`; set it to `false` for the same no-clobber behavior as `create()`.
+`data` accepts `string | Buffer`. `options` are `{ denyMutations?: DenyMutationPolicy; encoding?: BufferEncoding; mkdir?: boolean; mode?: number; overwrite?: boolean; renameIdentity?: RenameIdentityPolicy }`. `mode` sets the file's POSIX mode. If neither the call nor `RootDefaults` supplies it, a replacement preserves the existing file mode and a new file uses `0o600`. `mkdir` and `overwrite` both default to `true`; set `overwrite: false` for the same no-clobber behavior as `create()`.
 
 ### `fs.create(rel, data, options?)`
 
@@ -79,10 +88,7 @@ await fs.writeJson("compact.json", state, { trailingNewline: false });
 Options:
 
 ```ts
-type RootWriteJsonOptions = {
-  encoding?: BufferEncoding;
-  mkdir?: boolean;
-  mode?: number;
+type RootWriteJsonOptions = RootWriteOptions & {
   replacer?: (this: any, key: string, value: any) => any | (number | string)[];
   space?: number | string;
   trailingNewline?: boolean; // default true
@@ -112,7 +118,9 @@ await fs.copyIn("inbox/upload.bin", "/tmp/incoming.bin", {
 });
 ```
 
-Options: `{ encoding?, mkdir?, maxBytes?, sourceHardlinks? }`. Use `sourceHardlinks: "reject"` to refuse if the source itself is a hardlinked alias.
+Options are `{ denyMutations?, maxBytes?, mkdir?, mode?, sourceHardlinks? }`.
+Use `sourceHardlinks: "reject"` to refuse if the source itself is a hardlinked
+alias. There is no encoding option: copying preserves source bytes.
 
 ### `fs.move(from, to, options?)`
 
@@ -167,7 +175,12 @@ try {
 }
 ```
 
-Options: `{ mkdir?, mode?, writeMode? }`, where `writeMode` is `"replace"` (default), `"append"`, or `"update"`. `replace` truncates existing files; `update` keeps existing contents. Streaming writes go directly to the destination — there is no atomic-rename step. If you need both streaming and atomicity, write to a sibling temp yourself and rename when done; the [`atomic`](atomic.md) helpers can do this for you.
+Options are `{ denyMutations?, mkdir?, mode?, writeMode? }`, where `writeMode`
+is `"replace"` (default), `"append"`, or `"update"`. `replace` truncates existing
+files; `update` keeps existing contents. Streaming writes go directly to the
+destination — there is no atomic-rename step. If you need both streaming and
+atomicity, write to a sibling temp yourself and rename when done; the
+[`atomic`](atomic.md) helpers can do this for you.
 
 ## Write defaults vs per-call options
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -29,6 +29,7 @@
     "dist/**/*.d.ts.map",
     "dist/native/**/*.node",
     "docs/**/*.md",
+    "docs/assets/readme-banner.jpg",
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",
@@ -128,12 +129,16 @@
     "prepack": "node scripts/prepack-build.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "test:coverage:collect": "vitest run --coverage --coverage.reporter=json --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.statements=0 --coverage.thresholds.branches=0",
+    "test:coverage:merge": "node scripts/merge-coverage.mjs",
     "test:security": "vitest run test/fs-safe.test.ts test/read-boundary-bypass.test.ts test/write-boundary-bypass.test.ts test/additional-boundary-bypass.test.ts test/adversarial-boundary-payloads.test.ts",
-    "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm test && node scripts/check-pack.mjs",
+    "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm docs:check && pnpm test && node scripts/check-pack.mjs",
+    "docs:check": "node scripts/check-doc-examples.mjs",
     "docs:site": "node scripts/build-docs-site.mjs",
     "native:build": "pnpm --filter @openclaw/fs-safe-native-build build",
     "native:test": "cargo test --manifest-path native/Cargo.toml",
     "pack:check": "pnpm build && node scripts/check-pack.mjs",
+    "public-api:update": "pnpm build && node scripts/check-pack.mjs --update-public-api",
     "package:smoke": "node scripts/check-release-packages.mjs --allow-host-only --output release-artifacts",
     "check:changed": "pnpm run check",
     "release:notes": "node scripts/release-notes.mjs",
@@ -148,11 +153,17 @@
     "tar": "7.5.22"
   },
   "devDependencies": {
-    "@napi-rs/cli": "3.8.1",
+    "@emnapi/runtime": "2.0.0-alpha.3",
+    "@napi-rs/cli": "3.8.2",
     "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "4.1.10",
+    "fast-check": "^4.9.0",
+    "istanbul-lib-coverage": "3.2.2",
+    "istanbul-lib-report": "3.0.1",
+    "istanbul-reports": "3.2.0",
+    "sigstore": "5.0.0",
     "typescript": "^7.0.2",
-    "vite": "8.2.0",
+    "vite": "8.2.1",
     "vitest": "^4.1.10"
   },
   "engines": {

package/dist/archive-file-io.d.ts

@@ -1,9 +0,0 @@
-import type { FileHandle } from "node:fs/promises";
-import type { ExtractionDeadline } from "./archive-deadline.js";
-export declare function writeFileHandleFully(params: {
-    handle: FileHandle;
-    buffer: Buffer;
-    bytes: number;
-    deadline: ExtractionDeadline;
-}): Promise<void>;
-//# sourceMappingURL=archive-file-io.d.ts.map

package/dist/archive-file-io.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"archive-file-io.d.ts","sourceRoot":"","sources":["../src/archive-file-io.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAchB"}

package/dist/archive-file-io.js

@@ -1,11 +0,0 @@
-export async function writeFileHandleFully(params) {
-    let offset = 0;
-    while (offset < params.bytes) {
-        params.deadline.check();
-        const { bytesWritten } = await params.handle.write(params.buffer, offset, params.bytes - offset);
-        if (bytesWritten <= 0) {
-            throw new Error("archive staging write made no progress");
-        }
-        offset += bytesWritten;
-    }
-}

package/dist/file-store-source.d.ts

@@ -1,5 +0,0 @@
-export declare function readFileStoreCopySource(params: {
-    sourcePath: string;
-    maxBytes?: number;
-}): Promise<Buffer>;
-//# sourceMappingURL=file-store-source.d.ts.map

package/dist/file-store-source.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"file-store-source.d.ts","sourceRoot":"","sources":["../src/file-store-source.ts"],"names":[],"mappings":"AAIA,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB"}