@openclaw/fs-safe 0.5.6 → 0.6.0

package/docs/contributing.md

@@ -46,23 +46,55 @@ pnpm check
 This runs the filesystem boundary checks, build, tests, and package
 tarball/import validation.
 
+### Native consumer installs
+
+After `pnpm build` and a fresh `pnpm native:build`, run `pnpm package:smoke`.
+It packs the real root and host binding, then runs root-only npm and the
+declared pnpm version against a disposable loopback registry. The root's exact
+optional dependencies stay unchanged. Each consumer lives outside the workspace
+with isolated configuration, caches, and stores; the registry never proxies to
+the Internet. The smoke verifies root integrity, consumer-local resolution,
+OS/CPU/libc selection, a native-required SHA-256 operation, and fresh-process
+`auto`/`off` fallbacks and `require` failures for missing bindings and omitted
+optionals. Omitted-optionals installs also verify that all public subpaths can
+be imported, without implying every operation remains available.
+
+Host-only smoke supplies the six foreign packages using their unchanged real
+manifests and clearly marked synthetic, non-executable payloads. Every foreign
+metadata/tarball endpoint is checked before installation, so a missing fixture
+cannot masquerade as successful platform filtering. These temporary fixtures
+never enter `packages/`, release artifacts, or the publish manifest. They prove
+installer filtering, not foreign native compilation or execution. Full release
+collection uses the actual seven collected native tarballs instead. Run it with
+`pnpm package:collect` after assembling all seven real bindings; missing targets
+fail collection. `pnpm package:collect --allow-host-only` exercises the same
+lifecycle boundary locally but proves only the host. Both collection commands
+require the pnpm lifecycle CLI path; direct `node` invocation is unsupported. Archive
+codecs and their dependencies are packed from the installed dependency graph.
+
+PR CI builds and executes four host targets: Linux x64 glibc, Linux x64 musl
+(Alpine), macOS arm64, and Windows x64. The root-only smoke runs on each. The
+seven-target source build matrix runs on release tags; packaging all seven is
+not execution proof for every architecture. The smoke writes manager versions,
+cases, and synthetic-fixture scope to `release-artifacts/consumer-proof.json`.
+
 ## Docs
 
-The docs site is rendered from `docs/*.md` by `scripts/build-docs-site.mjs`. Build locally to preview:
+The docs site is rendered recursively from Markdown files under `docs/` by `scripts/build-docs-site.mjs`. Build locally to preview:
 
 ```bash
-node scripts/build-docs-site.mjs
+pnpm docs:site
 open dist/docs-site/index.html
 ```
 
-The build validates internal links and embedded anchors. Broken links fail the build — fix them before pushing.
+The build validates internal links and embedded anchors. Broken links fail the build — fix them before pushing. Navigation must list every non-excluded Markdown page exactly once: missing, nonexistent, and duplicate entries fail before the build replaces existing site output. The builder and navigation tests share discovery and validation in `scripts/docs-site-navigation.mjs`.
 
 Adding a new doc page:
 
 1. Create `docs/<page>.md`. Use a leading `# Title` heading.
-2. Add the page to the appropriate section in `scripts/build-docs-site.mjs` (`sections` array near the top).
+2. Add the page to the appropriate section in `scripts/docs-site-navigation.mjs` (`sections` array near the top). Nested pages use slash-separated paths relative to `docs/`, such as `guides/example.md`.
 3. Cross-link from `docs/index.md` if it's a major surface.
-4. Re-run the local build.
+4. Run `pnpm test test/docs-site-navigation.test.ts` and re-run the local build.
 
 Internal links use relative `*.md` paths — the builder rewrites them to the rendered HTML. Code fences support GitHub-flavored markdown.
 
@@ -79,8 +111,14 @@ Small, focused PRs land faster. The general shape:
 
 Maintainers publish from a protected `vX.Y.Z` tag on `main` through
 `.github/workflows/release.yml`. The workflow requires the package version and a
-dated `CHANGELOG.md` section to match the tag, then publishes with npm trusted
-publishing and provenance before creating the GitHub release.
+dated `CHANGELOG.md` section to match the tag. It builds and publishes all seven
+platform packages before publishing `@openclaw/fs-safe`, verifies every registry
+artifact and provenance statement, and then creates the GitHub release.
+
+Each package needs its own npm trusted-publisher configuration for
+`openclaw/fs-safe` and `release.yml`. A new platform package must be created and
+configured on npm before the first tag that references it; npm trust is
+package-specific and cannot be bootstrapped by the tag workflow itself.
 
 External contributors do not need to do anything beyond getting the pull
 request merged. Maintainers must not publish locally or add npm automation

package/docs/durability.md

@@ -63,6 +63,12 @@ into proof for a different directory.
 
 Call `close()` in `finally`. Closing is idempotent; using a closed pin fails.
 
+These checks intentionally reject a moved or replaced pathname. For one file's
+abort cleanup through its original directory after a move, use the separate
+[retained-directory staging lifecycle](staged-file.md). Its cleanup authority
+does not weaken `pinDirectory().assertCurrent()` or `.sync()`, and namespace
+cleanup is not proof of crash durability.
+
 ## Durable directory creation
 
 `ensureDurableDirectory()` finds and pins the nearest existing ancestor,
@@ -204,10 +210,17 @@ try {
 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.
+rejects symbolic links and non-regular files, compares lossless bigint identities
+from the pre-open pathname inspection to the opened descriptor and from that
+descriptor to the current pathname, and closes its own handle. All identity
+checks complete before any JavaScript or native hashing. Each inspection allows
+one bounded retry for unknown Windows identity components, retaining known
+components and rejecting known differences immediately. Persistent unknown
+identity fails closed with `path-mismatch`, even for benign files: this trades
+availability for verifiable identity. Retries inspect the same descriptor or
+pathname without reopening the file and repeat the symlink and file-type checks.
+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

package/docs/errors.md

@@ -2,6 +2,15 @@
 
 Every failure that's the library's job to surface lands as an `FsSafeError` with a closed `code` union you can branch on. Catch by code, not by message text — messages may change, codes will not.
 
+Result-based APIs are an exception to throwing: [`pathScope().ensureDir()`](path-scope.md#ensuredir-rel-options)
+and `ensureDirectoryWithinRoot()` return operational failures as
+`{ ok: false, error: string, diagnostic: FsSafeError }`. The diagnostic uses
+`helper-failed` / `operational`, retains the exact native error in `cause`, and
+has the same message as `error`. Its display text names the native code/syscall
+when available but omits raw paths and native messages. Policy failures keep
+the string-only result without `diagnostic`; other `pathScope` methods do not
+gain this field. Directory preparation can partially complete before failing.
+
 Path and archive-entry details embedded in diagnostics escape control characters
 as `\\uXXXX` sequences. This keeps attacker-controlled names on one log line;
 the escaped message is for diagnosis, not for reconstructing the original path.
@@ -105,7 +114,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, missing/incompatible bundled binary, or `FS_SAFE_NATIVE_MODE=require`. `auto` falls back where possible; `require` fails closed. |
+| `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. |
 | `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, 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 legal POSIX drive-like names. |
 | `not-empty` | `remove()` on a non-empty directory. | Use `replaceDirectoryAtomic` or remove children first. |
@@ -125,6 +134,12 @@ type FsSafeErrorCode =
 | `too-large` | A read or bounded walk exceeded its configured budget. | Caller gave a too-permissive file or traversal limit. |
 | `unsupported-platform` | Reserved compatibility code for a platform-specific operation. | No current public helper emits this `FsSafeError` code. Platform-specific APIs currently return a typed unsupported result or use `helper-unavailable`; keep the union member when exhaustively switching across supported package versions. |
 
+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`.
+
 ## Branching
 
 ```ts

package/docs/index.md

@@ -39,6 +39,7 @@ await fs.remove("notes/archive/today.txt");
 
 - **First time?** [Install](install.md), then walk through the [Quickstart](quickstart.md). Five minutes from `pnpm add` to a working root.
 - **Upgrading from 0.4?** Follow [Migrating to 0.5](migrating-to-0.5.md) in order, including the archive clamp-default audit.
+- **Upgrading from 0.5?** Follow [Migrating to 0.6](migrating-to-0.6.md) to adopt platform-native optional packages.
 - **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.
@@ -51,7 +52,7 @@ await fs.remove("notes/archive/today.txt");
 |---|---|
 | [`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 helper policy](native-helper.md) | Choose `auto`, `off`, or `require` for platform-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. |
@@ -74,6 +75,7 @@ await fs.remove("notes/archive/today.txt");
 | [`@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. |
+| [Migrating to 0.6](migrating-to-0.6.md) | Installer-policy checklist for the platform-native package split. |
 
 ## Status
 

package/docs/install.md

@@ -85,19 +85,27 @@ Use the main entry for the common surface, or the focused subpaths when you want
 
 ## Runtime dependencies
 
-`@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.
+`@openclaw/fs-safe` lists `jszip` and `tar` as optional dependencies for JavaScript ZIP/TAR [archive extraction](archive.md). They are loaded lazily; the JavaScript archive fallback requires the corresponding codec and reports a missing-optional-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability.
 
-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.
+There are no peer dependencies. Exact-version optional packages carry the seven
+native targets and npm-compatible OS, CPU, and Linux libc filters install only
+the matching binary. Consumers do not run a 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 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.
 
-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.
+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.
 
 ## Native helper policy
 
-The bundled native binaries provide fd-relative open/link/mkdir primitives,
+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 bundled targets therefore
+JavaScript path. Platforms without one of the seven published targets therefore
 continue through the documented fallback in `auto` mode.
 
 ```ts
@@ -116,7 +124,7 @@ FS_SAFE_NATIVE_MODE=off      # auto | off | require
 
 `OPENCLAW_FS_SAFE_NATIVE_MODE` is also accepted.
 
-Disabling native loading keeps the public API working through Node path
+Disabling native loading keeps fallback-capable operations working through Node path
 operations guarded by lexical and canonical checks plus identity verification.
 Use `require` when native-backed operations must fail instead of falling back.
 The exact boundary is documented in [native helper policy](native-helper.md).

package/docs/migrating-to-0.5.md

@@ -8,8 +8,8 @@ description: "Ordered checklist for moving a 0.4 consumer from the Python helper
 Use this checklist from top to bottom. Version 0.5 replaces the Python worker,
 changes the default archive mode policy, and adds explicit contracts for
 publication, walking, locks, secrets, and native-only features. Nothing in this
-guide requires a Rust toolchain: all supported native binaries are prebuilt and
-bundled in `@openclaw/fs-safe`.
+guide requires a Rust toolchain: all supported native binaries are prebuilt.
+Current releases install the matching exact-version optional platform package.
 
 ## 1. Update the package and runtime
 
@@ -17,10 +17,10 @@ bundled in `@openclaw/fs-safe`.
 - Update `@openclaw/fs-safe` and regenerate every lock or shrinkwrap file your
   deployment consumes.
 - Keep optional dependencies enabled if you want JavaScript ZIP/TAR support.
-  Native loading no longer depends on optional packages because all seven
-  binaries ship in `@openclaw/fs-safe`. An install that omits optional packages
-  can still import fs-safe, but missing JS archive decoders fail with actionable
-  errors.
+  Native loading no longer depends on Python. Keep optional dependencies enabled
+  for the matching native package and JavaScript ZIP/TAR decoders. An install
+  that omits them can still import fs-safe, but native-only features and missing
+  JS archive decoders fail with actionable errors.
 
 If you call `resolveRootPath()` or `resolveRootPathSync()` directly, upgrade to
 0.5: versions through 0.4.7 could approve an in-root symlink traversal that
@@ -42,7 +42,7 @@ configureFsSafeNative({ mode: "auto" });
 | `configureFsSafePython({ mode })` | `configureFsSafeNative({ mode })` |
 | `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
 | `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
-| `pythonPath`, `FS_SAFE_PYTHON`, pinned-Python aliases | Nothing; bundled native binaries do not use an interpreter |
+| `pythonPath`, `FS_SAFE_PYTHON`, pinned-Python aliases | Nothing; prebuilt native binaries do not use an interpreter |
 
 The old names warn once and map `auto`, `off`, or `require` so a shipped 0.4
 deployment does not silently change policy. Interpreter paths are ignored and

package/docs/migrating-to-0.6.md

@@ -0,0 +1,43 @@
+---
+title: Migrating to 0.6
+description: "Upgrade checklist for the platform-native package split."
+---
+
+# Migrating from 0.5 to 0.6
+
+Version 0.6 moves native bindings out of the root `@openclaw/fs-safe` tarball
+and into exact-version platform packages. This removes unrelated operating
+system and architecture binaries from each installation.
+
+## Keep optional dependencies enabled for native mode
+
+Package managers select one binding by OS, CPU, and Linux libc. A normal
+install needs no command change:
+
+```bash
+pnpm add @openclaw/fs-safe
+```
+
+If a deployment currently installs 0.5 with `--omit=optional`, `--no-optional`,
+or an equivalent lockfile policy, change that policy before upgrading when it
+uses native mode `require` or any native-only feature. Version 0.5 kept its
+binding in the root tarball; version 0.6 intentionally does not.
+
+Omitting optional dependencies remains supported for fallback-capable APIs in
+`auto` mode. It disables native-only features such as zstd/bzip2 TAR handling,
+retained-directory staging, atomic `rename-noreplace`, and Windows private
+directory creation. Native mode `require` reports `helper-unavailable` when the
+matching package is absent or incompatible.
+
+## Deployment checklist
+
+1. Remove any option or policy that omits optional dependencies when native
+   support is required.
+2. Regenerate every lockfile or shrinkwrap file consumed by deployment.
+3. Verify that the lock contains the matching `@openclaw/fs-safe-*` package.
+4. Run a native-required operation on every deployed OS/libc target.
+5. Keep an `FS_SAFE_NATIVE_MODE=off` lane when the guarded JavaScript fallback
+   is part of the application contract.
+
+No Rust toolchain, postinstall build, or runtime download is introduced. See
+[Native helper policy](native-helper.md) for the exact fallback boundary.

package/docs/native-helper.md

@@ -1,11 +1,15 @@
 ---
 title: Native helper policy
-description: "How fs-safe loads its bundled native filesystem primitives and how auto, require, and off affect guarded fallbacks."
+description: "How fs-safe loads its platform-specific native filesystem primitives and how auto, require, and off affect guarded fallbacks."
 ---
 
 # Native helper policy
 
-`@openclaw/fs-safe` itself contains seven prebuilt binaries for Linux x64/arm64 (glibc or musl), macOS x64/arm64, and Windows x64. The loader selects `dist/native/<target>/fs-safe-native.node` without optional platform packages, downloads, postinstall scripts, or a consumer Rust build. Carrying every target makes the npm tarball larger, but every installation receives the same complete artifact.
+`@openclaw/fs-safe` declares seven exact-version optional packages for Linux
+x64/arm64 (glibc or musl), macOS x64/arm64, and Windows x64. Package-manager
+OS, CPU, and libc filters install only the matching package. The loader requires
+that package lazily, without runtime downloads, postinstall scripts, or a
+consumer Rust build.
 
 ```ts
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
@@ -21,15 +25,20 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 
 | Mode | Behavior |
 |---|---|
-| `auto` | Prefer native primitives when the current bundled binary loads; otherwise silently use the guarded JavaScript path. |
-| `off` | Do not load a bundled binary. Use the guarded JavaScript path deterministically. |
+| `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. |
 | `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
 
 Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
 
+[`stageFileInDirectory()`](staged-file.md) always requires native support on
+Linux/macOS and rejects before creation when off, unavailable, or missing the
+required capability. Windows is unsupported for this lifecycle. This does not
+change the mode policy of existing fallback-capable APIs.
+
 ## Native boundary
 
-The bundled native layer exposes policy-free filesystem mechanisms: beneath-root
+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, and Windows security descriptor calls. The TypeScript
 layer owns policy, retries, filters, budgets, modes, cleanup, error
@@ -89,3 +98,4 @@ consumer performs its 0.5 upgrade.
 - [File locks](sidecar-lock.md)
 - [Durability](durability.md)
 - [Migrating to 0.5](migrating-to-0.5.md)
+- [Migrating to 0.6](migrating-to-0.6.md)

package/docs/native.md

@@ -1,11 +1,11 @@
 ---
 title: Native architecture
-description: "The bundled native bindings, fd-relative beneath model, platform mechanisms, loader security, and JavaScript fallback contract."
+description: "The platform-specific native bindings, fd-relative beneath model, platform mechanisms, loader security, and JavaScript fallback contract."
 ---
 
 # Native architecture
 
-`@openclaw/fs-safe` bundles native bindings that supply mechanisms Node does
+`@openclaw/fs-safe` uses native bindings that supply mechanisms Node does
 not expose directly. The Rust layer is deliberately not a second policy engine.
 TypeScript owns trusted-root selection, path validation, archive filtering,
 budgets, modes, identity fencing, cleanup decisions, and error normalization.
@@ -14,8 +14,9 @@ platform syscall sequence that can preserve the boundary.
 
 Every operation that has an equivalent safe Node implementation keeps that
 guarded JavaScript path. Native loading is lazy; installs do not compile Rust,
-run postinstall code, or fetch binaries. The npm tarball carries all seven
-supported targets, so it is larger than a per-platform package by design.
+run postinstall code, or fetch binaries at runtime. Seven exact-version optional
+packages are filtered by OS, CPU, and Linux libc, so an installation receives
+only its matching prebuilt binding.
 Native-only formats and creation-time Windows DACL guarantees fail explicitly
 instead of substituting a weaker implementation.
 
@@ -86,9 +87,36 @@ workers rather than the JavaScript event loop.
 | `require` | Try once, cache the result | Throw `FsSafeError("helper-unavailable")` |
 | `off` | Never attempt a binding load | Always use guarded JavaScript |
 
-The one exception is functionality with no safe JavaScript implementation:
-zstd/bzip2 TAR and Windows private-directory creation fail with
-`helper-unavailable` when native support is absent or off.
+Features without a safe JavaScript implementation, including zstd/bzip2 TAR,
+Windows private-directory creation, and [retained-directory staging](staged-file.md),
+fail with `helper-unavailable` when native support is absent or off. Staging
+is currently Linux/macOS only and rejects Windows with `unsupported-platform`.
+
+The staged-file owner also serves POSIX native pinned writes, including streaming.
+Unpublished files remain at `0600`; requested modes are applied through the
+owned file descriptor only after rename and published-entry identity validation.
+Post-rename chmod or sync failures retain the publication receipt and final name.
+Its direct-child exclusive `openat` hands off the descriptor before any fallible
+post-open checks; non-following `statat` compares against that descriptor with
+exact native identities, and cleanup uses `unlinkat` in the retained parent.
+The separate checks and unlink are not atomic conditional deletion. Windows
+pinned writes and other fallback-capable APIs retain their existing mechanisms.
+Native writers share root and parent admission, but keep their platform identity
+checks and leaf ownership. POSIX coordinator disposal uses `SuppressedError` to
+retain both an operation failure and a disposal failure, including their receipts;
+stage preparation and cleanup keep their documented error mappings.
+Root replacement verification borrows the published descriptor after final mode
+application, while a private coordinator retains the staged owner until the
+asynchronous check finishes. The owner never escapes that coordinator; public
+staging methods and receipts expose no descriptor or verification callback.
+Verification failures preserve the published name, and disposal still retains
+both verification and cleanup errors when both fail.
+The private verification channel carries exact bigint identity from the original
+owned descriptor (or the content-accepted FUSE descriptor). Root compares it
+against exact fd and pathname metadata; legacy helper return facts and public
+read metadata behavior are unchanged. Missing Windows pathname identity still
+requires a guarded path reopen and comparison with the original retained file;
+that fallback does not apply to POSIX no-read modes.
 
 ## JavaScript fallback guarantees and delta
 
@@ -116,10 +144,10 @@ infer native loading from timing.
 Importing fs-safe never executes a child process. Linux libc selection uses
 the Node process report, conventional musl library filenames, and the ELF
 `PT_INTERP` field of `process.execPath`. If all probes are inconclusive, the
-loader conservatively attempts the bundled glibc binary and lets normal module
-loading fail into `auto` fallback. The loader requires only
-`dist/native/<target>/fs-safe-native.node`; it never probes optional packages,
-downloads code, or runs a postinstall step. A missing or incompatible binary
+loader conservatively attempts the glibc package and lets normal module loading
+fail into `auto` fallback. The loader requires only the package selected from
+the detected target; it never probes unrelated packages, downloads code, or
+runs a postinstall step. A missing or incompatible binary
 silently selects the JavaScript fallback in `auto`, throws typed
 `helper-unavailable` in `require`, and is never inspected in `off`. Tests reject
 `child_process`, `exec`, or `spawn` usage in the loader.
@@ -132,3 +160,4 @@ silently selects the JavaScript fallback in `auto`, throws typed
 - [Durability](durability.md)
 - [Permissions](permissions.md)
 - [Migrating to 0.5](migrating-to-0.5.md)
+- [Migrating to 0.6](migrating-to-0.6.md)

package/docs/path-scope.md

@@ -24,6 +24,8 @@ await sharp(photo.path).resize(800).toFile(/* … */);
 ## Signature
 
 ```ts
+import type { FsSafeError } from "@openclaw/fs-safe/errors";
+
 function pathScope(rootDir: string, options: PathScopeOptions): PathScope;
 
 type PathScopeOptions = {
@@ -36,6 +38,10 @@ type PathScopeResolveOptions = {
 
 type PathResult = { ok: true; path: string } | { ok: false; error: string };
 type PathsResult = { ok: true; paths: string[] } | { ok: false; error: string };
+// Illustrative result alias, not a named package export.
+type DirectoryResult =
+  | { ok: true; path: string }
+  | { ok: false; error: string; diagnostic?: FsSafeError };
 
 type PathScope = {
   rootDir: string;
@@ -45,7 +51,7 @@ type PathScope = {
   existing(requestedPaths: string[]): Promise<PathsResult>;
   files(requestedPaths: string[]): Promise<PathsResult>;
   writable(requestedPath: string, options?: PathScopeResolveOptions): Promise<PathResult>;
-  ensureDir(requestedPath: string, options?: PathScopeResolveOptions & { mode?: number }): Promise<PathResult>;
+  ensureDir(requestedPath: string, options?: PathScopeResolveOptions & { mode?: number }): Promise<DirectoryResult>;
 };
 ```
 
@@ -92,9 +98,29 @@ await fs.writeFile(t.path, body);
 
 Async. `mkdir -p` inside the scope. Walks each segment, refuses any symlink in the path, creates missing directories. Optional `mode` sets the directory mode.
 
+Failures remain nonthrowing results with `error: string`. Policy rejections
+(including traversal, NUL input, symlinks and non-directory segments) omit
+`diagnostic`. Operational failures from `lstat`, `realpath` or `mkdir` include
+an `FsSafeError` with `code: "helper-failed"`, `category: "operational"`, and
+the exact original error in `cause`, including its native `code`, `errno` and
+`syscall` when available. Only `ensureDir()` adds this diagnostic; other scope
+methods retain their existing result shapes.
+
+`error` equals `diagnostic.message` for operational failures, for example
+`"Could not prepare uploads directory: ENAMETOOLONG during lstat"`. Display
+text bounds and escapes the label and native code/syscall, without copying
+the requested path or native error message. Treat the raw cause as sensitive
+local diagnostic data, not as text to return to an untrusted caller. A failure
+can leave already-created parent directories; it does not roll them back or
+retry through an unchecked filesystem path.
+
 ```ts
 const dir = await uploads.ensureDir("inbox", { mode: 0o755 });
-if (!dir.ok) return reply(500, dir.error);
+if (!dir.ok) {
+  // Pass the cause only to an appropriately restricted local diagnostic sink.
+  if (dir.diagnostic) recordLocalFailure(dir.diagnostic.cause);
+  return reply(dir.diagnostic ? 500 : 400, dir.error);
+}
 ```
 
 ## Result type vs throwing

package/docs/permissions.md

@@ -75,10 +75,21 @@ Built-in PowerShell, `icacls.exe`, and `whoami.exe` invocations have a fixed
 30-second per-process deadline. A command failure or timeout returns an
 unverified result (`source: "unknown"`) so callers fail closed. Advanced callers
 that inject a custom `exec` implementation own that executor's deadline.
+Failed owner and ACL inspections retain `error` text and an optional
+`errorDetail: PermissionCommandFailure` with `command`, integer `durationMs`,
+`timedOut`, `exitCode`, `signal`, and `stderr`. The type is exported from both
+`@openclaw/fs-safe/permissions` and `@openclaw/fs-safe/advanced`. Built-in
+execution measures elapsed time; injected execFile-shaped failures receive
+best-effort command diagnostics. Plain errors have no `errorDetail`.
+Display reasons and stderr escape control characters and are limited to 400
+characters, including a trailing `…` when truncated. Diagnostics do not copy
+stdout or read target file contents. The separate `errorCause` retains the
+original exception for restricted local diagnosis; do not serialize or expose
+it as display text.
 The parser is on the advanced surface so tests and CLIs can process captured
 `icacls` output without spawning a process.
 
-When the bundled native binding is available, `inspectPathPermissions()`
+When the native binding is available, `inspectPathPermissions()`
 reads the owner and DACL directly with Windows security APIs. It classifies the
 current user, LocalSystem, and built-in Administrators as trusted and reports
 the world/group read/write facts consumed by secure reads. Descriptor forms it
@@ -128,7 +139,7 @@ Object-specific and other ACE layouts are not guessed: they are omitted,
 `complete` becomes false, and their numeric types appear in
 `unsupportedAceTypes`, allowing a security-sensitive caller to fail closed.
 Non-Windows systems return `{ status: "unsupported-platform", platform }`.
-Windows requires the bundled native binding; if it is unavailable or forced
+Windows requires the native binding; if it is unavailable or forced
 off, the call throws `FsSafeError("helper-unavailable")`. The existing coarse
 `inspectPathPermissions()` API still owns its compatibility fallback and trust
 classification.

package/docs/root.md

@@ -140,7 +140,7 @@ 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
+Create-only writes prefer the platform native helper for fd-relative opens and
 atomic no-replace rename. Operations without native wiring retain their guarded
 JavaScript implementations.
 

package/docs/secret-file.md

@@ -89,6 +89,14 @@ credential must also fail on broad permissions or unexpected ownership.
 the same pinned-handle validation, byte cap, trimming, error codes, and strict
 versus missing-is-undefined naming semantics.
 
+Both sync and async readers compare lossless bigint identities from the preview,
+opened descriptor, resolved target, and current input path before reading. An
+allowed symlink must still point to the opened file. On Windows, a zero device
+or inode is unverified: that inspection is retried once without reopening the
+file, preserving known identity components and link checks. Definite mismatches
+and persistent ambiguity fail with `path-mismatch`; optional reads do not treat
+these failures as missing files.
+
 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`.

package/docs/secure-file.md

@@ -28,6 +28,8 @@ The helper:
 
 On POSIX, unsafe permissions mean group/world writable, and group/world readable unless `permissions.allowReadableByOthers` is true. On Windows, the helper uses the ACL inspection helpers from [`permissions`](permissions.md) and refuses the read if ACLs cannot be verified.
 
+Descriptor, pathname, and realpath identity checks use lossless bigint stats internally. The returned `stat` remains a normal Node `Stats` object with numeric fields. A zero Windows device or inode is unverified, never a match: the helper re-inspects that identity once using the same descriptor or pathname, then rejects persistent ambiguity with `path-mismatch`. A definite mismatch rejects immediately; retries retain known identity components and still enforce symlink policy.
+
 ## Options
 
 ```ts
@@ -57,6 +59,8 @@ type SecureFileReadOptions = {
 
 `permissions.allowInsecure` is a migration escape hatch. Prefer fixing permissions and using [`formatPermissionRemediation`](permissions.md) to show the user what to run. `trust.allowNetworkPath` is off by default because UNC paths are remote authority, not local filesystem input. `inject` is for tests and platform adapters; production callers usually leave it unset.
 
+`permissions.allowInsecure` bypasses only permission checks. Neither it nor `inject.platform` changes filesystem identity verification, which always uses the actual process platform. `trust.allowSymlink` permits an alias but still requires its target and realpath to match the opened descriptor.
+
 ## Errors
 
 `readSecureFile()` throws `FsSafeError` with codes such as:
@@ -67,7 +71,7 @@ type SecureFileReadOptions = {
 | `not-found` | The path could not be stat'd before open. |
 | `not-file` | The opened target is not a regular file. |
 | `symlink` | The path is a symlink and `trust.allowSymlink` is false. |
-| `path-mismatch` | The path or realpath changed between open and verification. |
+| `path-mismatch` | The path or realpath changed between open and verification, or filesystem identity could not be verified after bounded re-inspection. |
 | `outside-workspace` | `realPath` is outside `trust.trustedDirs`. |
 | `permission-unverified` | Required mode/ACL checks could not be completed. |
 | `insecure-permissions` | Mode bits or ACLs grant broader access than allowed. |
@@ -75,6 +79,18 @@ type SecureFileReadOptions = {
 | `too-large` | File size or bytes read exceeded `maxBytes`. |
 | `timeout` | `timeoutMs` elapsed while reading. |
 
+Windows inspection failures remain operational `permission-unverified` errors
+and still refuse the read. Their message includes the underlying reason when
+available. `details` includes `ownerError` for owner-query failures and, when
+command diagnostics are available, `command`, `durationMs`, `timedOut`,
+`exitCode`, `signal`, and `stderr`. Reasons and stderr are control-character
+escaped and limited to 400 characters each (including a truncation marker).
+No stdout or target file contents are copied into these display diagnostics.
+The original inspection exception is retained as `cause`; built-in command
+errors also retain their original execFile exception in the cause chain.
+Treat causes as restricted local diagnostic data. No retries are performed,
+and verification order and rejection conditions are unchanged.
+
 ## See also
 
 - [Permissions](permissions.md) — standalone POSIX mode and Windows ACL checks.