@openclaw/fs-safe 0.11.0 → 0.13.0

package/docs/errors.md

@@ -38,6 +38,14 @@ class FsSafeError extends Error {
 
 `cause` is available through the standard `Error` `cause` property when the failure was triggered by a `NodeJS.ErrnoException` (e.g. a wrapped `EACCES`). Inspect it for the original `code` / `errno` / `syscall` if you need finer-grained reporting.
 
+Guarded write preparation describes permission, read-only filesystem, and disk-space
+failures with messages such as `permission denied (EACCES)` or
+`no space left on device (ENOSPC)`. Other errno failures include their code in
+`filesystem write failed (EIO)`. These wrappers retain the existing `invalid-path`
+code and `policy` category for compatibility, along with the original `cause`;
+they do not expose native message text or paths. Already-classified `FsSafeError`
+instances and missing-path errors keep their existing classification.
+
 `details` is an operation-specific receipt, not an alternate error code. For
 example, `publishFileExclusive()` uses it to report the failing phase, created
 target identity, cleanup decision, and failed directory-sync outcome. Narrow
@@ -114,7 +122,7 @@ type FsSafeErrorCode =
 | `device-path` | A read/open target is a known unsafe device or process-fd path. | `/dev/zero`, `/dev/random`, `/dev/stdin`, `/dev/fd/*`, `/proc/*/fd/*`, or a Windows reserved device name. |
 | `hardlink` | Read or copy with `hardlinks: "reject"` saw `nlink > 1`. | File is hardlinked — possibly an alias of an out-of-tree inode. |
 | `helper-failed` | A native mechanism or multi-step operational helper failed. | Inspect `cause` and any operation-specific `details`; retrying may be unsafe if the operation partially completed. |
-| `helper-unavailable` | Required native binding could not be loaded. | Unsupported platform, omitted/missing/incompatible platform package, or `FS_SAFE_NATIVE_MODE=require`. `auto` falls back where possible; `require` fails closed. |
+| `helper-unavailable` | A required native binding or bounded primitive could not be loaded. | Unsupported platform, omitted/missing/incompatible platform package, `FS_SAFE_NATIVE_MODE=off`, or a no-clobber `Root.move()` without safe native parent admission. `auto` falls back only where a safe fallback exists. |
 | `insecure-permissions` | A secure file or path permission check found a mode/ACL that allows broader access than requested. | File or directory is group/world writable/readable; Windows ACL grants broad read. |
 | `invalid-path` | Input was empty, contained NUL, was an unparseable URL, or otherwise unusable; a FileStore key used a noncanonical spelling. | Noncanonical FileStore aliases, backslashes, or complete parent segments; a network path on Windows; a drive-relative segment in a portable relative path or store key; or a leading drive-relative spelling such as `C:name` used as a Root destination. Existing-object Root lookups retain broader confined path compatibility, including legal POSIX drive-like names. |
 | `not-empty` | Nonrecursive `remove()` on a non-empty directory, or new children appeared during recursive removal. | Use bounded `recursive: true` removal or coordinate concurrent writers. |
@@ -136,11 +144,11 @@ type FsSafeErrorCode =
 
 Secret writes reject invalid `mode` / `dirMode` values with `invalid-path` before directory creation. Existing secret directories with a mode different from the requested `dirMode` report `insecure-permissions` without chmod; a created directory whose descriptor ownership no longer matches its initializing effective user reports `not-owned`.
 
-Pathname `sha256File()` also reports `path-mismatch` when pre-open, descriptor,
-or current-path identity remains unknown after one bounded Windows retry, even
-if the file is benign. It never reopens to recover identity. Preview symlinks
-report `symlink`, preview or descriptor non-files report `not-file`, and a
-current-path symlink or non-file reports `path-mismatch`.
+Pathname `sha256File()` and `sha256FileSync()` also report `path-mismatch` when
+pre-open, descriptor, or current-path identity remains unknown after one bounded
+Windows retry, even if the file is benign. Neither reopens to recover identity.
+Preview symlinks report `symlink`, preview or descriptor non-files report
+`not-file`, and a current-path symlink or non-file reports `path-mismatch`.
 
 ## Branching
 

package/docs/file-store.md

@@ -90,13 +90,16 @@ or converts one caller-supplied key onto another:
   are rejected.
 - Windows drive-relative segments such as `C:name` or `C:` are rejected
   anywhere in a key, including `a/C:name`.
+- On Windows, every other colon is rejected too, preventing a key from naming
+  an NTFS alternate stream or directory-index alias. POSIX keeps accepting
+  ordinary colon-bearing segments that are not drive-relative spellings.
 - No segment may end in an ASCII dot or space.
 
 Violations report `invalid-path` when key validation is reached. Ordinary nested
 keys, NFC Unicode such as `café/日本語.txt`, `.hidden`, `a..b`, and internal spaces
-such as `internal space/a b.txt` are accepted. Colons elsewhere, such as the
-timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid; filesystem
-success still depends on the platform and the underlying Root policies.
+such as `internal space/a b.txt` are accepted. On POSIX, colons elsewhere, such
+as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid;
+Windows rejects that spelling as stream syntax.
 
 Validation retains each method's operation order. Async reads, `exists`, and
 `remove` open the root first: if the root is missing, strict methods report
@@ -136,6 +139,24 @@ its exact publication identity cannot be verified. There is no equal-content
 fallback. The published entry remains present, so callers must inspect or
 recover that outcome instead of assuming the write did not occur.
 
+Synchronous directory creation retains exact bigint receipts for the store root
+and every parent component. On POSIX, an existing or newly created directory
+whose complete requested mode differs is reopened without following the final
+name, checked against its receipt and parent chain, and finalized through that
+descriptor. A concurrent root or parent replacement is rejected without
+applying the mode to the replacement. Directories already at the requested mode
+skip the descriptor and mode operation. Windows retains its bounded `mkdir`
+mode request and identity checks without relying on directory descriptors or a
+pathname `chmod`, because Node does not enforce POSIX directory modes there.
+
+Node does not expose a portable, `fchmod`-capable search-only directory
+descriptor on Linux. If a mismatched existing directory, or one created under
+an owner-read-removing umask, cannot be opened for reading, the synchronous
+store therefore fails closed with `permission-unverified`; it never falls back
+to pathname `chmod`. On supported macOS x64/arm64 hosts it also tries an
+`O_SEARCH` descriptor, so owner-searchable directories can still be repaired.
+Directories with neither usable read nor search access remain fail-closed.
+
 | Method | Durability support |
 |---|---|
 | `write`, `writeText`, `writeJson` (async and sync) | Per-call option overrides store default. |
@@ -256,6 +277,12 @@ type FileStorePruneOptions = {
 
 Symlinks are skipped. The walk is best-effort — failures on individual entries don't abort the whole prune. Compares against `mtimeMs`.
 
+Pruning rechecks that a selected entry is still a regular file and still expired
+immediately before guarded removal. Fresh replacements and in-place timestamp
+refreshes are preserved; replacements that are themselves expired remain
+eligible. This does not require read permission. The existing best-effort
+external-process race window after dispatch still applies.
+
 ## Difference from `Root`
 
 | `FileStore` | `Root` |

package/docs/filename.md

@@ -1,6 +1,6 @@
 # Filenames
 
-`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one traversal-free path segment. Use it as a thin first pass before storing user-supplied names; pair with [`safeDirName`](install-path.md#safedirname) when you need stricter directory-name handling.
+`sanitizeUntrustedFileName(name, fallback)` reduces a filename string from an untrusted source to one traversal-free path segment. Use it as a thin first pass before storing user-supplied names; use [`safePathSegmentHashedV2`](install-path.md#safepathsegmenthashedv2) when mapping untrusted install IDs to separate directory names.
 
 ```ts
 import { sanitizeUntrustedFileName } from "@openclaw/fs-safe/advanced";
@@ -17,15 +17,27 @@ function sanitizeUntrustedFileName(fileName: string, fallbackName: string): stri
 
 ## What it does
 
-In order:
+The primary name goes through this pipeline first:
 
-1. **Trim** whitespace. If the result is empty, return `fallbackName`.
+1. **Trim** whitespace. An empty result is unusable.
 2. **Strip path components.** Apply `path.posix.basename` then `path.win32.basename` so neither `foo/bar.txt` nor `foo\bar.txt` survives — only the final segment remains.
 3. **Strip non-portable characters.** C0/C1 controls (`0x00`–`0x1f`, `0x7f`–`0x9f`) and the Windows-invalid set `< > : " / \\ | ? *` are removed on every platform.
 4. **Trim again.**
-5. If the result is empty, `"."`, or `".."`, return `fallbackName`.
-6. **Suffix Windows reserved basenames.** Compare the part before the first `.` case-insensitively with the Windows device-name set, including `CON`, `PRN`, `AUX`, `NUL`, `CLOCK$`, `CONIN$`, `CONOUT$`, `COM1..9`, `LPT1..9`, and their superscript `¹`, `²`, and `³` variants. Windows-ignored spaces and dots at the end of that basename do not disguise a device name. A match gains `_` before its extension, preserving the original case and extension on every platform.
-7. **Truncate.** If the cleaned segment is longer than 200 UTF-16 code units, take up to the first 200 without splitting a valid Unicode surrogate pair.
+5. An empty result, `"."`, or `".."` is unusable.
+6. **Truncate.** If the cleaned segment is longer than 200 UTF-16 code units, take up to the first 200 without splitting a valid Unicode surrogate pair.
+7. **Make the final name device-safe.** Compare the part before the first `.` case-insensitively with the Windows device-name set, including `CON`, `PRN`, `AUX`, `NUL`, `CLOCK$`, `CONIN$`, `CONOUT$`, `COM1..9`, `LPT1..9`, and their superscript `¹`, `²`, and `³` variants. Windows-ignored spaces and dots at the end of that basename do not disguise a device name. A match gains `_` before its extension on every platform. If the suffix would exceed 200 code units, the unsuffixed tail is shortened first, so truncation cannot recreate a device name.
+
+Only when the primary name is unusable does `fallbackName` go through the same
+nonrecursive pipeline. A safe fallback is preserved exactly; path components,
+controls, reserved device names, and overlong fallback names receive the same
+treatment as the primary name. If both candidates are unusable, the function
+returns the fixed safe literal `"file"`.
+
+If truncation itself exposes a reserved-device basename after Windows ignores
+trailing spaces or dots, the result is shortened once more and receives the
+same underscore suffix. A name that reaches the sanitization branch therefore
+remains at most 200 UTF-16 code units and is never a Windows reserved-device
+alias. Fallback names pass through the same checks before they can be returned.
 
 That's it. The function stays intentionally small: it removes traversal and
 the most obvious cross-platform device and character hazards, but it is not a
@@ -41,6 +53,8 @@ sanitizeUntrustedFileName("a\u0000b\tc", "upload");       // "abc"
 sanitizeUntrustedFileName("   ", "fallback");              // "fallback"
 sanitizeUntrustedFileName(".", "fallback");                // "fallback"
 sanitizeUntrustedFileName("..", "fallback");               // "fallback"
+sanitizeUntrustedFileName("<>", "../../etc/passwd");       // "passwd"
+sanitizeUntrustedFileName("<>", "../..");                  // "file"
 sanitizeUntrustedFileName("CON", "fallback");              // "CON_"
 sanitizeUntrustedFileName("nul.txt", "fallback");          // "nul_.txt"
 sanitizeUntrustedFileName("aux.c", "fallback");            // "aux_.c"
@@ -92,5 +106,5 @@ await fs.write(`uploads/${safe}`, body); // fs is a Root() handle; rejects trave
 
 ## See also
 
-- [Install path helpers](install-path.md) — `safeDirName`, `safePathSegmentHashed` for directory-segment sanitization.
+- [Install path helpers](install-path.md) — legacy directory-segment sanitizers and `safePathSegmentHashedV2` for untrusted install IDs.
 - [`root()`](root.md) — the boundary you'll write into after sanitizing.

package/docs/guest.md

@@ -113,6 +113,11 @@ prefixes and use short random suffixes independent of the destination basename,
 so legal names near the filesystem's component limit also work for writes and
 cross-device moves.
 
+Cross-device symlink moves create the new link in a private destination-side
+staging directory before atomically replacing the destination. Link creation or
+publication failure preserves the existing destination and source link; ordinary
+failure cleanup removes the staging directory.
+
 Cross-device directory moves build a copy manifest and check it during source
 cleanup. Source changes can leave the published destination and some or all
 of the source. Regular-file and symlink move fallbacks unlink the source

package/docs/install-path.md

@@ -8,6 +8,7 @@ import {
   resolveSafeInstallDir,
   safeDirName,
   safePathSegmentHashed,
+  safePathSegmentHashedV2,
 } from "@openclaw/fs-safe/advanced";
 ```
 
@@ -22,7 +23,7 @@ function resolveSafeInstallDir(params: {
 }): { ok: true; path: string } | { ok: false; error: string };
 ```
 
-Computes the absolute install directory for `id` under `baseDir`, after running `id` through `nameEncoder` (`safeDirName` by default). Verifies the result stays inside `baseDir` — anything that would escape returns `{ ok: false, error: invalidNameMessage }`.
+Computes the absolute install directory for `id` under `baseDir`, after running `id` through `nameEncoder` (`safeDirName` by default). Verifies the result stays inside `baseDir` — anything that would escape returns `{ ok: false, error: invalidNameMessage }`. On Windows, contained alternate-stream and filesystem-namespace aliases are rejected with the same result.
 
 ```ts
 const r = resolveSafeInstallDir({
@@ -35,14 +36,17 @@ if (!r.ok) return reply(400, r.error);
 await fs.mkdir(r.path, { recursive: true });
 ```
 
-For ids whose default-sanitized form might collide (e.g. `"foo/bar"` and `"foo\\bar"` both map to `"foo__bar"`), pass `nameEncoder: safePathSegmentHashed` to append a content hash:
+For untrusted IDs that must occupy separate install directories, pass
+`nameEncoder: safePathSegmentHashedV2`. The default `safeDirName` and legacy
+`safePathSegmentHashed` can map distinct IDs to the same directory; the boundary
+check does not establish which ID owns an existing directory.
 
 ```ts
 const r = resolveSafeInstallDir({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   id: untrustedId,
   invalidNameMessage: "invalid plugin name",
-  nameEncoder: safePathSegmentHashed,
+  nameEncoder: safePathSegmentHashedV2,
 });
 ```
 
@@ -60,7 +64,7 @@ function assertCanonicalPathWithinBase(params: {
 }): Promise<void>;
 ```
 
-Throws if the candidate resolves outside `baseDir` after `realpath`. The `boundaryLabel` is included in the error message ("Invalid path: must stay within {boundaryLabel}").
+Throws if the candidate resolves outside `baseDir` after `realpath`. On Windows it also throws for alternate-stream or filesystem-namespace aliases in the base, candidate, or canonical path. The `boundaryLabel` is included in the containment-shaped error message ("Invalid path: must stay within {boundaryLabel}").
 
 ```ts
 await assertCanonicalPathWithinBase({
@@ -87,11 +91,48 @@ safeDirName("");                       // ""
 
 `safeDirName` does *not* try to be exhaustive about Windows-reserved names or special characters. It is purely a separator-stripping pass — `resolveSafeInstallDir` adds the boundary check on top so an `"../../etc"` input cannot escape `baseDir`.
 
-For stricter sanitization, use `safePathSegmentHashed`.
+Use `safePathSegmentHashedV2` when distinct untrusted IDs need separate names.
+
+### `safePathSegmentHashedV2`
+
+```ts
+function safePathSegmentHashedV2(input: string): string;
+```
+
+Hashes every trimmed ID, including ordinary short names, into `id-v2-` followed
+by 64 lowercase hexadecimal SHA-256 digits. The result is always 70 ASCII bytes,
+contains no separators, and avoids Windows device names and ignored suffixes.
+There is no readable prefix to truncate and no unchanged-name branch. Distinct
+trimmed IDs, including an ID that looks like an encoded output, remain distinct
+unless their full SHA-256 digests collide. The lowercase ASCII output also
+preserves that distinction on case-insensitive and Unicode-normalizing volumes.
+
+The stable V2 digest recipe is SHA-256 of the UTF-8 bytes of
+`"@openclaw/fs-safe:install-path:v2\0"`, followed by the UTF-16LE bytes of
+`input.trim()`, without a byte-order mark. The NUL-terminated prefix separates
+this use of SHA-256 from other hash domains. UTF-16LE preserves exact JavaScript
+code units, including lone surrogates. Inputs are not case-folded or Unicode
+normalized. Surrounding whitespace, as removed by JavaScript `String.trim()`,
+is the only intentional equivalence; internal whitespace remains significant.
+
+```ts
+const segment = safePathSegmentHashedV2("plugin/v1"); // id-v2-<64 hex digits>
+safePathSegmentHashedV2(" plugin/v1 ") === segment;  // true
+safePathSegmentHashedV2("Plugin/v1") === segment;    // false
+```
+
+This encoder computes a name; it does not authorize access or prove ownership
+of a directory. Store the original trimmed ID in application-owned metadata and
+verify it before reusing an existing install directory. Keep each install tree
+on one encoding version. Switching to V2 changes existing paths: use a new base
+directory or explicitly migrate directories after verifying their recorded IDs.
+Do not silently fall back to a legacy path when the V2 path is missing.
 
 ### `safePathSegmentHashed`
 
-Returns a directory-safe segment **plus** a short content hash when sanitization changed the input or when the safe form is too long. Use this when input collisions matter:
+Legacy readable encoding retained for path compatibility. It appends a short
+content hash when sanitization changed the input or when the safe form is too
+long; ordinary short names remain unchanged. Use V2 for new untrusted-ID mappings.
 
 ```ts
 safePathSegmentHashed("plugin-v1");                  // "plugin-v1"  (unchanged short input)
@@ -104,31 +145,35 @@ safePathSegmentHashed(".");                          // "skill-cdb4ee2aea"
 
 The sanitization is more aggressive than `safeDirName`: any character not in `[A-Za-z0-9._-]` becomes `-`, runs of `-` collapse, leading and trailing `-` are stripped, the empty/`.`/`..` fallback is `"skill"`. Long results are truncated to 50 chars before the hash is appended.
 
-The suffix is the first 10 hex characters of `sha256(trimmedInput)`. It makes
-collisions between distinct trimmed inputs unlikely, but it is a 40-bit
-identifier rather than a mathematical uniqueness guarantee. Inputs that differ
-only by surrounding whitespace intentionally map to the same output.
+The suffix is the first 10 hex characters of `sha256(trimmedInput)`. This is a
+40-bit identifier, and the hash is not applied to every ID: short generated
+outputs overlap with accepted literal inputs. Case variants can also share a
+directory on case-insensitive filesystems. Distinct IDs can therefore alias
+without a hash collision. Do not use this legacy encoder as an identity or
+authorization boundary for untrusted IDs. Inputs that differ only by surrounding
+whitespace intentionally map to the same output. Its output and the default
+encoder selected by `resolveSafeInstallDir` remain unchanged for compatibility.
 
 ## Common patterns
 
 ### Install a plugin
 
 ```ts
-import { resolveSafeInstallDir, assertCanonicalPathWithinBase, safePathSegmentHashed } from "@openclaw/fs-safe/advanced";
+import { resolveSafeInstallDir, assertCanonicalPathWithinBase, safePathSegmentHashedV2 } from "@openclaw/fs-safe/advanced";
 import { extractArchive } from "@openclaw/fs-safe/archive";
 import fs from "node:fs/promises";
 
 const r = resolveSafeInstallDir({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   id: untrustedName,
   invalidNameMessage: "invalid plugin name",
-  nameEncoder: safePathSegmentHashed,
+  nameEncoder: safePathSegmentHashedV2,
 });
 if (!r.ok) return reply(400, r.error);
 
 await fs.mkdir(r.path, { recursive: true, mode: 0o755 });
 await assertCanonicalPathWithinBase({
-  baseDir: "/srv/plugins",
+  baseDir: "/srv/plugins-v2",
   candidatePath: r.path,
   boundaryLabel: "plugin install dir",
 });
@@ -148,6 +193,7 @@ const snap = resolveSafeInstallDir({
   baseDir: "/srv/snapshots",
   id: `${runId}-${version}`,
   invalidNameMessage: "invalid snapshot id",
+  nameEncoder: safePathSegmentHashedV2,
 });
 if (!snap.ok) throw new Error(snap.error);
 await fs.mkdir(snap.path, { recursive: true });

package/docs/install.md

@@ -54,7 +54,10 @@ also rejects canonicalization when the addon or its canonicalizer is unavailable
 Node and Windows use their existing runtime canonicalizers. On Windows, Bun's
 recursive directory creation receives an absolute spelling that preserves raw
 path components, working around its rejection of existing relative `.` and `..`
-directories. Public paths and caller-supplied filesystem adapters remain unchanged.
+directories. Windows native descriptor-relative operations require Bun to expose
+the paired libuv descriptor bridge from its host executable; a missing or partial
+bridge fails explicitly with `ENOTSUP`. Public paths and caller-supplied filesystem
+adapters remain unchanged.
 
 The upstream fix is tracked in [Bun #42374](https://github.com/oven-sh/bun/pull/42374).
 The adapter can be removed when the supported Bun baseline includes that fix.
@@ -124,9 +127,10 @@ the matching binary. Consumers do not run a native build, download code at
 runtime, or execute a postinstall step. Omitting optional dependencies keeps
 non-archive fallback-capable operations working in `auto` or `off`. Native-only
 features, including strict owned-tree temp cleanup, retained-directory staging,
-atomic `rename-noreplace`, zstd/bzip2 TAR handling, and Windows private-directory
-creation, remain unavailable. Operations needing the binding in `require` mode fail with
-`helper-unavailable` when the matching package is absent or incompatible.
+atomic `rename-noreplace` (including the default no-clobber `Root.move()`),
+zstd/bzip2 TAR handling, and Windows private-directory creation, remain
+unavailable. Operations without a safe fallback fail with `helper-unavailable`
+when the matching package is absent, incompatible, or disabled.
 
 Upgrading an existing 0.5 consumer? Follow [Migrating to 0.6](migrating-to-0.6.md)
 before deploying with native mode `require` or native-only features.
@@ -135,15 +139,15 @@ before deploying with native mode `require` or native-only features.
 
 The platform native binaries provide fd-relative open/link/mkdir primitives,
 atomic no-replace rename, and file identity checks. The default is `auto`: use
-the matching binary when it loads, otherwise silently keep the guarded
-JavaScript path. Platforms without one of the seven published targets therefore
-continue through the documented fallback in `auto` mode.
+the matching binary when it loads, otherwise use the guarded JavaScript path
+where a safe fallback exists. Native-only operations fail with
+`helper-unavailable`.
 
 ```ts
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
 configureFsSafeNative({ mode: "auto" });    // default
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript; reject native-only operations
 configureFsSafeNative({ mode: "require" }); // fail closed if unavailable
 ```
 

package/docs/json-store.md

@@ -1,6 +1,6 @@
 # JSON store
 
-`jsonStore` is exported from `@openclaw/fs-safe/store`. It is the absolute-path
+`jsonStore` is exported from `@openclaw/fs-safe/store`. It is the single-path
 convenience wrapper for `fileStore(...).json(...)`: a small read-modify-write
 handle around a single JSON file. It bakes in atomic writes, explicit fallback
 reads, and optional cross-process locking via
@@ -71,6 +71,10 @@ type JsonStore<T> = {
 
 `jsonStore({ filePath })` resolves `rootDir = dirname(filePath)` and calls
 `fileStore({ rootDir, private: true }).json(basename(filePath), options)`.
+On Windows, the factory rejects NTFS alternate-stream and directory-index
+namespace spellings before preparing its private parent. An ordinary
+drive-relative path is anchored at entry and `store.filePath` exposes the
+resulting absolute path; ordinary colon-bearing POSIX paths remain valid.
 
 `durable: false` keeps sibling-temp replace/rename behavior but skips the
 temp-file and parent-directory `fsync` calls. Use it only for reconstructible

package/docs/json.md

@@ -38,6 +38,17 @@ Use `readJson` when missing-or-malformed is a programmer error you want to surfa
 
 `JsonFileReadError` carries `cause` so you can inspect whether the underlying failure was an `ENOENT`, a `SyntaxError`, or something else.
 
+On Windows, filesystem path inputs reject NTFS alternate-stream and
+directory-index namespace spellings such as `file:stream` and
+`dir::$INDEX_ALLOCATION`; ordinary colon-bearing POSIX names remain valid.
+Standalone JSON writers preserve their released support for an ordinary
+drive-relative destination by anchoring its leading drive designator at entry
+without normalizing the remaining suffix. Any additional colon is still
+rejected before filesystem access.
+Strict standalone readers retain `JsonFileReadError` and expose the
+`invalid-path` rejection as its cause, lenient `tryReadJson*` calls return
+`null`, and root-bounded readers report an `open`/`validation` failure.
+
 ## Reading
 
 ### `readJson<T>(filePath, options?)`

package/docs/mutation-policy-proof.md

@@ -0,0 +1,65 @@
+# Hosted mutation-policy proof
+
+The `mutation policy public behavior proof` workflow builds the exact event-head
+package and host addon on Node 24 Linux, macOS, and Windows. Each case executes in
+a fresh process, uses a private temporary fixture, and emits only a bounded,
+canonical receipt. POSIX workers require both real and effective non-root UIDs.
+
+Receipt schema `fs-safe-mutation-policy-proof-v2` deliberately does not describe
+final directory emptiness as a mutation-dispatch count. Root replacement records
+the unchanged contents of the original and replacement parent; denied redirect
+records rejection and unchanged denied/displaced parents. The existing JS mkdir
+counters name their exact child or next component. None counts native syscalls
+or excludes transient mutations that leave no final trace.
+
+## Additional hosted cases
+
+Each POSIX write/create/copy worker, under both native-off and native-require,
+performs an eligible success control, an exact deeper-parent denial after an
+earlier parent is created, a denied redirect after preflight, and a stale-parent
+replacement at the public pre-mkdir authority boundary. Exact directory listings
+and sentinels verify that denied/current/displaced parents contain no prohibited
+child, target, or stage. Copy sources must retain their original bytes.
+
+Redirect injection uses the existing public `@openclaw/fs-safe/test-hooks` subpath
+from `dist`, not a mocked native binding. Only these isolated workers enable
+`NODE_ENV=test`. The exact target and single hook visit are required. The hook is
+after policy preflight but before parent admission; it must not be described as
+a post-parent-admission hook. Stale replacement instead uses the public authority
+callback after child-create policy admission, with an existing sentinel parent
+and a still-missing child. Both implementation files that enforce the following
+freshness check are hash-bound. No unchecked callback ordinal chooses a fault.
+
+Representative POSIX `Root.write` workers refuse authority before the first mkdir,
+after one parent has been created and before the next mkdir, before staging, and
+immediately before publication. Epoch selection uses actual fixture state. The
+publication refusal requires a real single-link, caller-owned mode-0600 stage
+containing the complete payload while the destination still contains its original
+sentinel. The same rejection object must escape, no callback may follow refusal,
+and the owned stage must be gone before fixture teardown.
+
+Windows workers exercise buffer `Root.write` through a stable final-file symlink,
+then refuse before staging a newly created placeholder, before publishing over a
+new placeholder, and before publishing to an existing symlink-selected destination.
+They verify alias binding, destination preservation, observed placeholder/stage
+states, and cleanup before fixture teardown. The default native-off and explicit
+`verify-content-with-lock` native-require configurations both select the existing
+Windows JS buffer writer. The compatibility route is expected not to load the
+addon; the receipt does not mislabel this as native publication or evidence that
+content-verification fallback or lock contention was exercised.
+
+## Bounds and interpretation
+
+The receipt remains below 32 KiB, each worker has a 15-second process timeout and
+4-KiB stdout limit, and the proof step has a six-minute outer timeout. Worker I/O
+and cleanup retain their existing deadlines. The canonical pending/failed receipt
+is preserved if setup, a worker, provenance validation, or emission fails.
+Source, built modules, the public test seam, harness helper, contract tests, and
+host addon are hashed and checked again after workers.
+
+These are deterministic representative observations, not an exhaustive race proof
+or syscall audit. Existing hash-bound internal tests remain complementary for
+other awaited-admission, receipt-refresh, and observation-failure interleavings.
+Windows root replacement and POSIX-specific pinned routes are not claimed on
+Windows. Hosted CI and exact artifact inspection are required before relying on
+new receipts; the proof supplies no performance release clearance.

package/docs/native-helper.md

@@ -15,7 +15,7 @@ consumer Rust build.
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 
 configureFsSafeNative({ mode: "auto" });    // default
-configureFsSafeNative({ mode: "off" });     // guarded JavaScript only
+configureFsSafeNative({ mode: "off" });     // guarded JavaScript; reject native-only operations
 configureFsSafeNative({ mode: "require" }); // fail closed when the binding is unavailable
 ```
 
@@ -25,8 +25,8 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 
 | Mode | Behavior |
 |---|---|
-| `auto` | Prefer native primitives when the current platform package loads; otherwise silently use the guarded JavaScript path. |
-| `off` | Do not load a native package. Use the guarded JavaScript path deterministically. |
+| `auto` | Prefer native primitives when the current platform package loads; otherwise use guarded JavaScript where a safe fallback exists and reject native-only operations. |
+| `off` | Do not load a native package. Use guarded JavaScript where safe and reject native-only operations deterministically. |
 | `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
 
 TAR/gzip in the guarded JavaScript path uses a bundled, import-free WASM build
@@ -62,6 +62,20 @@ change the mode policy of existing fallback-capable APIs.
 
 ## Native boundary
 
+The internal Darwin descriptor ACL inspector requires its matching native
+capability in both `auto` and `require`; `off`, a missing package, or an older
+binding without `inspectDarwinAcl` rejects with `helper-unavailable`. Inspection
+failure or malformed facts reject with `permission-unverified`; there is no
+mode-bit or pathname fallback for this capability. Clone admission uses a fused
+descriptor-bound metadata and ACL observation, then compares immutable receipts
+with fresh no-follow pathname identity fences; pathnames never authorize ACL
+state. The payload ACL-clear readback is part of that fused observation. Once
+a clone payload exists, normalization and verification failures become terminal
+`EIO` errors (with the underlying status and detail retained), not capability
+signals that permit an ordinary-copy retry. Checked cleanup cannot undo that
+terminal classification.
+This addition does not change other APIs' native-mode or permission contracts.
+
 The native layer exposes policy-free filesystem mechanisms: beneath-root
 open/mkdir/link, replace and no-replace rename, identity reads, archive decode/execution,
 clone/copy/hash workers, POSIX canonicalization, and Windows security descriptor calls. The TypeScript
@@ -70,12 +84,17 @@ normalization, and the decision to fall back.
 
 - Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Owned-tree cleanup enumerates and unlinks through retained directory descriptors and rejects device crossings.
 - 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. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
-- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed.
-
-Native primitives back create-only and replacing 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)
+- Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer, and deletes owned trees through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table.
+
+Native primitives back create-only and replacing pinned writes, no-clobber
+`Root.move()`, async sidecar creation, guarded publication, archive acceleration,
+and direct Windows ACL operations. Windows secure-file reads require
+descriptor-bound owner/DACL facts from the current helper; they do not use the
+standalone pathname inspector's command fallback. No-clobber moves fail with
+`helper-unavailable` when descriptor-relative parent admission or the atomic
+no-replace rename is unavailable; they never use a check followed by a replacing
+rename. Equivalent JavaScript paths remain available for documented
+fallback-capable features. See [Native architecture](native.md#javascript-fallback-guarantees-and-delta)
 for the exact difference.
 
 The guarded JavaScript mutation path is detection-based, not containment-atomic.