@openclaw/feishu 2026.9.6 → 2026.9.7

package/node_modules/@openclaw/fs-safe/docs/mutation-policy-proof.md

@@ -0,0 +1,69 @@
+# 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 stage creation for a missing destination, before publishing a
+complete stage to that still-missing destination, and before publishing to an
+existing symlink-selected destination. Missing destinations must remain absent at
+every authority callback and after refusal. The workers verify alias binding,
+destination preservation, complete single-link stages, 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. In native-require mode, the compatibility route loads
+the addon to publish its retained sidecar lock through `Root.create`; the payload
+writer remains JS. The receipt does not mislabel this as native payload
+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/node_modules/@openclaw/fs-safe/docs/native-helper.md

@@ -0,0 +1,193 @@
+---
+title: Native helper policy
+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` 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";
+
+configureFsSafeNative({ mode: "auto" });    // default
+configureFsSafeNative({ mode: "off" });     // disable the addon; reject native-only operations
+configureFsSafeNative({ mode: "require" }); // fail closed when the binding is unavailable
+```
+
+The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_SAFE_NATIVE_MODE`. Accepted values are `auto`, `off`, `require`, `true`, `false`, `on`, `never`, `required`, `1`, and `0`.
+
+## Modes
+
+| Mode | Behavior |
+|---|---|
+| `auto` | Prefer native primitives when the current platform package loads; otherwise use supported fallbacks and reject native-only operations. |
+| `off` | Do not load a native package. Use supported fallbacks 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. |
+
+Plain TAR, gzip, zstd, and bzip2 extraction and bounded entry reads use a bundled,
+import-free WASM build of the same Rust TAR parser when native support is absent
+or disabled. Zstd/bzip2 codecs are bundled alongside the parser; gzip uses Node's
+built-in decoder. These archive fallbacks require no runtime interpreter or
+download. `off` disables the optional native filesystem helper, not the bundled
+WASM. `auto` prefers native and does not retry a native operation failure through
+WASM; `require` still rejects an unavailable native binding. ZIP fallback still
+requires optional `jszip`. `inspectTarArchive()` remains limited to plain TAR
+and gzip.
+
+Windows security operations can use the package's readable PowerShell/C# scripts
+in `auto` and `off`, subject to the [Windows security fallback prerequisites](install.md#windows-security-fallback).
+
+On Bun macOS/Linux, the [runtime path adapter](install.md#bun-runtime) uses the
+same Rust addon for system canonicalization in `auto` and `require`. No JIT is
+needed. With `off` or a missing addon in `auto`, Bun's own resolver retains its
+path and permission limitations. Canonicalization in `require` fails with
+`helper-unavailable` if the addon or its canonicalizer is missing, including
+when admitting a temp workspace. Containment and identity checks stay intact.
+
+Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
+
+Native-created descriptors retain their originating native close operation through
+normal and error cleanup, including later mode changes. Node-created roots and
+directory handles keep Node's close operation, and borrowed handles keep their
+caller-owned lifetime. This preserves Node worker-thread descriptor tracking
+without unmanaged-descriptor warnings. A helper missing native close support is
+unavailable before descriptor allocation.
+
+Close retained native resources and let in-flight operations finish before
+forcibly terminating a worker. Native-created descriptors are not registered
+with Node's automatic worker-exit cleanup; `Worker.terminate()` can leave them
+open until process exit. The native close operation handles explicit cleanup,
+not forced worker termination.
+
+[`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)
+remain available in every mode. Their default compatible cleanup uses guarded
+JavaScript quarantine when owned native tree removal is unavailable.
+`cleanupSafety: "require-bounded"` instead rejects before child creation unless
+no-replace quarantine plus descriptor-relative owned-tree removal are available.
+On Linux, admission probes the exact `openat2` child-directory flags, including
+`RESOLVE_NO_XDEV`, at runtime. An unavailable or denied probe selects compatible
+JavaScript cleanup even in global `require` mode; `require-bounded` rejects before
+child creation.
+Already-created strict workspaces retain their binding
+and descriptors across later mode changes.
+
+[`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 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
+layer owns policy, retries, filters, budgets, modes, cleanup, error
+normalization, and the decision to fall back.
+
+- Linux uses `openat2` with `RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS`, `renameat`, and `renameat2(RENAME_NOREPLACE)`. Without `openat2`, beneath opens use the [no-follow component walk](native.md#linux-without-openat2) with exact identity checks and report `best-effort`. Direct-child no-replace renames borrow already-retained parent descriptors; deeper relative paths retain the guarded reopen. Owned-tree cleanup still requires `openat2` with `RESOLVE_NO_XDEV` and fails closed when unavailable.
+- 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. Direct-child no-replace renames borrow already-retained parents without another `F_GETPATH`; deeper paths retain the guarded reopen. 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, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer. The dedicated retained-directory `renameNoReplaceWithIdentity` primitive compares its required exact source receipt with the handle opened for rename before mutation. Its internal mismatch status is normalized to public `path-mismatch`; the legacy four-argument `renameNoReplace` export and its other callers are unchanged. Owned trees are deleted 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. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
+
+Linux root lookups reject negative descriptor sentinels before borrowing a handle or resolving a relative path; they never substitute the process working directory for an admitted root. Public Root operations already supply retained, admitted handles.
+
+On Linux and macOS, native asynchronous file-copy admission rejects negative source and parent descriptors before creating a stage, preserving source-before-parent error ordering. Callers must keep nonnegative source and parent descriptors open until the operation settles.
+
+Low-level Unix query, hash, copy, clone, staging, and owned-tree cleanup calls also reject negative descriptors before using them, preserving each operation's path-validation, cancellation, and cleanup order. Descriptor-relative mutations never accept a working-directory sentinel as a retained capability. On modern macOS, beneath opens reject negative roots with `EBADF` before calling `openat`, rather than returning `EIO` after an OS failure or working-directory operation. This check does not establish the validity of arbitrary nonnegative integers: callers must supply live descriptors and retain them until synchronous calls return or asynchronous operations settle.
+
+`replaceDirectoryAtomic()` requires `renameNoReplaceWithIdentity` before it
+creates a missing target parent. On POSIX the dedicated entry point keeps the
+existing pre-dispatch exact receipt fence but dispatches direct-child names
+through the retained parents without another receipt, duplicate, reopen, or
+macOS `F_GETPATH`; the documented final source-name substitution window remains
+there. Deeper names retain guarded parent traversal.
+
+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. In native `auto` or `off` mode, a missing
+binding or capability can use a packaged PowerShell script that inspects the
+borrowed handle. Raw owner/DACL inspection and private-directory creation also support
+this fallback, subject to the [Windows security fallback prerequisites](install.md#windows-security-fallback).
+Each capability emits a path-free warning once per process and adds PowerShell
+startup and compilation overhead per call. Native `require` rejects missing
+capabilities, and native operation failures remain terminal. 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.
+If a same-privilege peer can replace a writable parent after its identity guard
+but before Node resolves a pathname mutation, the mutation can land outside the
+intended root before the post-operation guard throws. Native `require` ensures the addon is present, but does not require a
+`kernel-atomic` resolver; inspect containment and use OS isolation when that
+concurrent attacker is part of the threat model.
+
+`openBeneath()` returns `{ fd, containment }`. `containment` is
+`"kernel-atomic"` for Linux `openat2` and `"best-effort"` for the Linux fallback, macOS and
+Windows. Public JavaScript root open/read/writable results also expose the
+field and report `"best-effort"`; the label reports mechanism, not policy.
+
+## Migration from the Python helper
+
+Version 0.5 removes the Python worker and interpreter-path selection. The mode
+contract is unchanged, so migrate startup configuration directly:
+
+| Python helper configuration | Native replacement |
+|---|---|
+| `configureFsSafePython({ mode: "auto" })` | `configureFsSafeNative({ mode: "auto" })` |
+| `configureFsSafePython({ mode: "off" })` | `configureFsSafeNative({ mode: "off" })` |
+| `configureFsSafePython({ mode: "require" })` | `configureFsSafeNative({ mode: "require" })` |
+| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
+| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
+| `pythonPath`, `FS_SAFE_PYTHON`, and the OpenClaw interpreter-path aliases | Remove; prebuilt bindings do not use an interpreter path |
+
+In 0.5, `configureFsSafePython` and the legacy Python environment names
+remain only as an upgrade bridge. On the first config read they emit one
+`DeprecationWarning` with code `FS_SAFE_PYTHON_DEPRECATED`, state the mapped
+native mode, and then apply that mode. A legacy interpreter path without an
+explicit mode maps to `auto` and the path itself is ignored. Native config has
+the normal precedence over legacy environment config.
+
+There is no silent alias and no Python execution fallback. The bridge exists
+only to make shipped 0.4 configuration visible and predictable while the
+consumer performs its 0.5 upgrade.
+
+## Related pages
+
+- [Config](config.md)
+- [Security model](security-model.md)
+- [Writing](writing.md)
+- [File locks](sidecar-lock.md)
+- [Durability](durability.md)
+- [Migrating to 0.5](migrating-to-0.5.md)
+- [Migrating to 0.6](migrating-to-0.6.md)
+
+### Retained existing Windows file
+
+The maintained Windows helper supports the public
+[`retainFileInDirectory`](retained-file.md) lifecycle on fixed local NTFS.
+Private native handles, exact identity/generation checks, writable-section
+admission and explicit close results stay behind that public API. Older helpers
+without this capability are unsupported; there is no pathname deletion fallback.
+No Windows namespace persistence barrier is provided.

package/node_modules/@openclaw/fs-safe/docs/native.md

@@ -0,0 +1,351 @@
+---
+title: Native architecture
+description: "The platform-specific native bindings, fd-relative beneath model, platform mechanisms, loader security, and JavaScript fallback contract."
+---
+
+# Native architecture
+
+`@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.
+Rust receives already-decided relative operations and performs the smallest
+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 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 fail explicitly
+instead of substituting a weaker implementation.
+
+## The beneath model
+
+A trusted directory descriptor is the capability. Native operations accept
+that descriptor plus a validated relative path and never reconstruct authority
+from a process working directory. Newly created files use exclusive creation,
+and TypeScript compares descriptor, pathname, and expected identities before
+accepting results.
+
+Conceptually, a caller grants authority to an already-open root—not to a path
+string that can be reinterpreted later:
+
+```text
+validated Root handle
+  └─ relative components (untrusted)
+       └─ open/link/mkdir beneath the handle
+            └─ compare descriptor + pathname + expected identity
+```
+
+The TypeScript layer validates and decides. The native layer never decides
+whether a path, archive entry, mode, owner, or cleanup policy is acceptable.
+
+- Linux uses `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`, fd-relative
+  `mkdirat`/`linkat`/`renameat`/`renameat2`, `FICLONE`, and `copy_file_range`.
+  Without `openat2`, beneath opens use the [guarded fallback](#linux-without-openat2).
+- macOS 15.4 and newer first use `openat(O_RESOLVE_BENEATH)`; older kernels walk
+  components with `openat(O_NOFOLLOW)` and restart in-root symlinks from the
+  pinned root. Both routes apply an `F_GETPATH` post-open containment detector,
+  but directory rename races mean the result remains `best-effort`, not
+  race-atomic. macOS uses `renameatx_np(RENAME_EXCL)` and permits
+  `fclonefileat` in an owned, non-shared parent. The clone is normalized inside
+  a private staging directory: flags, ACLs, extended attributes, and broad mode
+  bits are cleared before no-replace publication. Clone admission obtains mode,
+  owner, exact identity, flags, and ACL state together from the retained descriptor;
+  immutable receipts are compared across the private staging operation and against
+  fresh no-follow pathname identity reads. Any extended entry on the target parent
+  or private staging directory is rejected before cloning bytes. The payload's
+  cleared ACL and normalized descriptor facts are verified before publication and
+  again, with a fresh published-name identity fence, before its descriptor is
+  returned. Unsupported admission before payload
+  creation or an unsupported clone syscall may still select the documented
+  ordinary-copy path. After the clone creates bytes, normalization and security
+  verification failures report terminal `EIO`, retaining the original error
+  detail; successful cleanup does not make them eligible for ordinary-copy retry.
+  Cleanup failures remain secondary diagnostics, and already-terminal publication
+  errors such as `EEXIST` retain their status.
+- Windows uses handle-relative `NtCreateFile` with `OBJ_DONT_REPARSE` and
+  `FILE_OPEN_REPARSE_POINT`, then explicitly rejects reparse points. Rename and
+  hardlink operations stay rooted in already-open handles. Owner/DACL reads
+  use `GetSecurityInfo`; private directories receive their protected DACL in
+  an exclusive, handle-relative `NtCreateFile` call. Their created handles remain
+  open through ACL and pathname-association checks and own any failure cleanup.
+  N-API descriptors cross into and out of
+  this layer only through the host executable's paired libuv descriptor bridge;
+  missing or partial exports fail with `ENOTSUP` instead of trying a raw HANDLE
+  or add-on CRT descriptor namespace.
+
+The internal macOS `inspectDarwinAcl(fd)` capability reports `absent`, `empty`,
+or `present` for the opened object's extended ACL. It synchronously borrows the
+caller's descriptor, preserving its file position and POSIX record locks, and
+never reopens a pathname. Keep the descriptor open until inspection returns.
+Darwin's `acl_get_entry` returns
+zero for an entry; end-of-list is accepted only for the first entry of a valid,
+privately owned empty ACL. Unsupported, malformed, and failed inspection is not
+reported as absence. These facts do not classify individual ACE permissions or
+prove volume ownership enforcement; each caller applies its own security policy.
+
+## Linux without openat2
+
+Linux kernels before 5.6 and containers whose seccomp policy denies `openat2`
+can keep native mode `auto` or `require`. The addon caches one harmless
+`openat2(".")` capability probe per process. `ENOSYS`, or `EPERM` on that probe,
+selects the native `openat` fallback. An `EPERM`/`EACCES` from an application
+operation is still a permission error and never triggers a retry. Install
+syscall filters before the first native operation; a later `ENOSYS` fails with
+`ENOTSUP`, rather than changing the cached mechanism during a call.
+
+The fallback inspects components with `O_PATH | O_NOFOLLOW`, follows relative
+symlink targets using a stack of retained directory descriptors, and rejects
+absolute targets or `..` past the retained root with `EXDEV`. It permits at most
+40 link expansions (`ELOOP` beyond that limit). Final `O_NOFOLLOW` and exclusive
+creation retain their syscall semantics, including opening the link itself with
+`O_PATH | O_NOFOLLOW` and creating through a dangling in-root relative link.
+Exact device/inode/type identities are checked before and after the final
+no-follow open; followed links also retain their descriptors and have their
+named identities and target strings rechecked. Detected replacements fail with
+`EXDEV`, including changes to directories left behind by a link's `..` target.
+
+The fallback also honors `nosymfollow` mount restrictions on retained links.
+Two conservative restrictions remain: the fallback refuses to follow **any
+procfs symlink** with `ELOOP`, including ordinary links such as `/proc/mounts`.
+Userspace metadata cannot distinguish these from procfs magic links, which
+`RESOLVE_NO_MAGICLINKS` must never follow. Opening a final link itself with
+`O_PATH | O_NOFOLLOW` remains allowed. In a sticky, world-writable directory,
+the fallback refuses all symlink following with `EACCES`, even when the calling
+thread or directory owner owns the link, or `fs.protected_symlinks=0`. This
+preserves Linux's protected-symlink restriction without assuming the thread's
+filesystem UID or treating equal mapped `stat` UIDs as proof of equal kernel
+owners (distinct unmapped owners can both appear as the overflow UID).
+
+Public Root policy and canonical-path admission, hardlink rejection, pinned-file checks, and mutation
+identity fences remain in place. `openBeneath()` reports `best-effort`: these
+identity samples detect replacements but cannot make a multi-component walk
+atomic against a hostile process renaming directories between samples. This
+is the same documented containment class as the macOS and JavaScript paths;
+applications requiring atomic beneath resolution must check the result or use
+OS isolation. Rejection after a mutating open does not promise rollback.
+
+Nested no-clobber `Root.move()` still admits both parents and uses
+`renameat2(RENAME_NOREPLACE)`. Existing destinations are never overwritten.
+That separate syscall/filesystem capability remains required; if unavailable,
+the operation fails with `helper-unavailable`. Turning native mode `off` still
+disables no-clobber moves because Node has no equivalent atomic rename API.
+
+Bounded owned-tree cleanup deliberately has no `openat` fallback:
+`RESOLVE_NO_XDEV` rejects bind mounts even when device numbers match, which
+ordinary identity checks cannot reproduce. `cleanupSafety: "require-bounded"`
+fails before workspace creation with `helper-unavailable`; low-level cleanup
+opens report `ENOTSUP`. Compatible cleanup retains its documented behavior.
+Low-level `O_TMPFILE` anonymous opens also fail before creation with `ENOTSUP`
+in the fallback, because named-entry identity checks cannot verify an unnamed
+file. Public staged-write APIs use exclusive named files and remain available.
+
+For tests, set `FS_SAFE_TEST_NO_OPENAT2=1` before starting Node to force the
+fallback (including bounded-cleanup refusal). It is read only at the first
+capability probe. It has no effect on macOS or Windows.
+See [Linux fallback testing](testing.md#linux-openat2-fallback).
+
+## Archives
+
+Native ZIP and TAR entry reads retain a private, unpooled input Buffer in
+the async reader. ZIP reuses its parsed directory; TAR retains admitted member
+offsets. TypeScript validates and selects the requested member before reading. The internal binding borrows that allocation: it must never be
+mutated or detached while the reader or a read task exists. The public API only
+accepts a pathname and owns this buffer exclusively. An N-API reference keeps
+the bytes alive; a mutex serializes access to the retained ZIP cursor. Plain
+TAR copies only the selected range after complete admission, while gzip, zstd,
+and bzip2 replay bounded decompression and validate the full physical stream.
+Concurrent TAR reads share immutable input and own separate decoder state.
+Each output owns a new vector, which N-API transfers to Node without a second
+payload copy on runtimes supporting external buffers. No entry-read path
+requires temporary-file staging. Extraction retains its private staged input.
+
+Rust streams ZIP and TAR payloads, including gzip, zstd, and bzip2. It first
+returns a bounded manifest. TypeScript applies the shared path, filter, strip,
+mode, and byte policies and returns an index-bound extraction plan. Rust then
+creates only those planned entries beneath a private staging descriptor.
+
+The `fs-safe-archive-core` Rust workspace crate owns TAR framing, paths, types,
+mode decoding, GNU metadata, and byte-counted local PAX records. The native
+binding and bundled WASM module compile the same source. No `tar::Archive` or
+Node TAR parser reinterprets admitted identities or sizes. Executors replay
+admitted payload ranges after complete bounded admission; native writes retain
+the platform's descriptor-relative primitives, while fallback writes retain
+the guarded Node staging/publication boundary. ZIP behavior is unchanged.
+`maxMetaEntryBytes` bounds bodies before allocation; unsupported global/old
+metadata and sparse forms fail closed. See [bounded local PAX support](archive.md#bounded-local-pax-support).
+
+The bundled module also compiles the same zstd and bzip2 codec implementations
+used by native. In `off` or missing-native `auto`, those decoders feed the shared
+TAR parser through fixed 64 KiB windows in one import-free WASM session with a
+256 MiB linear-memory ceiling. Gzip retains Node's built-in decoder. Complete
+container and TAR admission precedes policy evaluation and guarded publication;
+concatenated compressed members and zstd skippable frames are consumed through
+physical EOF. No runtime command, interpreter, download, or consumer compilation
+is needed for these archive routes. `require` stays strict, and available native
+operation failures do not retry through WASM. Public `inspectTarArchive()` still
+accepts only plain TAR/gzip; ZIP fallback still requires optional JSZip.
+
+Every raw pass receives only TypeScript's resolved `maxEntries`,
+`maxMetaEntryBytes`, and `maxDecodedBytes`. Shared resolution caps metadata and
+decoded byte fields at JavaScript's safe-integer maximum and entry counts at
+`2^32 - 1` before backend selection. Large finite limits remain accepted;
+native conversion mirrors those caps and rejects malformed non-finite or
+negative direct-call values before casting. Logical member headers count
+before filtering/stripping; metadata records do not. `maxEntryBytes` and
+`maxExtractedBytes` remain exclusively in TypeScript's accepted-plan builder,
+after strip/filter policy, and are absent from the raw meter's interface.
+Bounded reads use the default count/metadata/decoded bounds; public `maxBytes`
+bounds only the requested output. TypeScript derives the internal decoded cap
+by safely adding `maxExtractedBytes` and `maxArchiveBytes`, clamped to the safe
+integer maximum. Every native pass receives that same cap and charges headers,
+metadata, bodies, padding, EOF blocks, and trailing zeros. It rejects overflow
+with `archive-decoded-size-exceeds-limit`; no ratio policy is implied.
+Extraction and entry reads drain the metered reader through physical EOF after
+admitted-range replay. Trailing framing or decoded-limit failures propagate before
+directory modes are finalized, staging is published, or selected bytes return.
+Native gzip uses the existing flate2 member decoder with an explicit bounded
+member/padding transition; JavaScript retains Node gunzip and validates its
+unconsumed compressed suffix. Only all-zero physical padding after a complete
+validated trailer is accepted, still within the original archive-byte budget.
+Native reads stop at framing boundaries so a rejected header does not request
+its body from the decoder; codec buffering can still read ahead internally.
+Inspection finishes the complete bounded framing pass before returning its manifest. Directory
+and link bodies, missing two-block EOF, and nonzero trailers reject on both
+backends, as detailed in [raw TAR framing](archive.md#raw-tar-framing). Raw and
+padded sizes above JavaScript's safe-integer maximum reject as invalid framing
+before applying member budgets, including when local PAX overrides the size.
+
+## Publication and hashing
+
+Exclusive publication tries a hardlink, then a copy-on-write clone, Linux
+`copy_file_range`, and finally the existing asynchronous JavaScript byte loop.
+All routes preserve `wx` semantics and the same source/target identity and
+SHA-256 fencing. Native hashing and Linux whole-file copying run on N-API async
+workers rather than the JavaScript event loop.
+
+Linux range copying confirms every zero-byte result with a positioned source
+read at the current transfer offset, including after earlier calls copied data.
+If readable bytes remain, automatic Root copying resumes its byte loop from
+that offset; exclusive publication removes its partial target before retrying
+the guarded byte-copy fallback. EOF checks preserve descriptor cursors and do
+not bypass the byte limit.
+
+## Mode semantics
+
+| Mode | Native loading | Fallback |
+|---|---|---|
+| `auto` | Try once, cache the result | Use guarded JavaScript when safe; reject native-only operations |
+| `require` | Try once, cache the result | Throw `FsSafeError("helper-unavailable")` |
+| `off` | Never attempt a binding load | Use guarded JavaScript when safe; reject native-only operations |
+
+`sha256FileSync()` is a synchronous Node implementation in all three modes and
+does not load the binding. Use asynchronous `sha256File()` for native hashing
+and cancellation that can respond while JavaScript callbacks run.
+
+Features without a safe fallback, including no-clobber
+`Root.move()` 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`.
+
+Windows raw owner/DACL inspection, private-directory creation, and secure-file
+descriptor inspection can use a package-shipped, readable `.ps1` driver and
+adjacent `.cs` source in `auto` or `off` mode when their binding or capability is
+unavailable. System Windows PowerShell runs the fixed driver with `-File`;
+paths remain data, with no runtime-generated helper script or encoded launcher.
+The [Windows security fallback prerequisites](install.md#windows-security-fallback)
+apply, and unsupported or disallowed command execution fails closed. This route
+preserves raw ACL facts, private DACLs at creation, and descriptor-bound secure
+reads, and emits a path-free `FS_SAFE_NATIVE_FALLBACK` warning once per capability
+per process. Each call adds PowerShell startup and compilation overhead.
+`require` rejects missing capabilities without a command, and an available native operation's
+failure never triggers this fallback. See [Permissions](permissions.md) and
+[Secure file reads](secure-file.md) for error and platform contracts.
+
+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
+
+Policy-bound parent creation can refresh exact directory facts through the
+retained POSIX descriptor. The optional native observer compares descriptor and
+no-follow pathname metadata and verifies the descriptor's canonical path before
+and after the observation. Ordinary paths can share that observation within one
+synchronous admission phase; callbacks, mutations, and later phases require fresh
+evidence. Unsupported helpers retain the guarded pathname checks. Policy and
+denied-path decisions remain in TypeScript.
+
+Public policy does not change with the selected mechanism: traversal and link
+rejection, archive filters/limits/modes, exclusive target creation, source and
+target identity fencing, publication cleanup receipts, and secret/lock policy
+remain TypeScript-owned. What changes is the syscall strength or availability:
+
+The table compares underlying mechanisms. On Node, public `Root.open()`,
+`Root.read()`, and `Root.openWritable()` use guarded Node file opens and report
+`containment: "best-effort"` in every native mode. `require` checks availability
+when an operation requests native support; it does not upgrade those results.
+See [Root containment guarantees](security-model.md#containment-guarantees-by-platform).
+
+| Capability | Native path | Guarded JavaScript path |
+|---|---|---|
+| Native beneath opens and Root mutations | Descriptor-relative beneath operations. Pinned writes create parents and publish both replacement and no-replace targets relative to open directory descriptors. No-clobber `Root.move()` admits both parents and uses the native no-replace rename. Native `openBeneath()` reports `kernel-atomic` with Linux `openat2` and `best-effort` with the guarded Linux fallback, macOS, and Windows. macOS uses `O_RESOLVE_BENEATH` when available plus an `F_GETPATH` detector, while Windows rejects reparse traversal in the object-manager call. | Reports `best-effort`: component-wise alias checks, no-follow opens where Node exposes them, private temp/rename, and post-operation identity verification. No-clobber `Root.move()` is unsupported because a check followed by a replacing rename is unsafe. A same-privilege peer can replace a writable parent after a guard assertion but before Node resolves another pathname mutation; the mutation may land outside the intended root before the post-check detects it. |
+| ZIP/TAR/gzip | Rust streaming decode and fd-relative output creation. | Optional JSZip or bundled WASM TAR into guarded private staging, then the same guarded merge policy. |
+| Zstd/bzip2 TAR | Rust streaming decode and fd-relative output creation. | Bundled WASM codecs feed the shared Rust TAR parser, then guarded private staging and the same merge policy; no optional codec dependency. |
+| Publication copy | Clone, Linux `copy_file_range`, async native SHA-256. | Exclusive `wx` byte loop and Node SHA-256 with the same content/identity fences. |
+| `rename-noreplace` | Atomic platform no-replace rename. | Unsupported; no emulation by check-then-rename. |
+| Windows DACL read | Direct `GetSecurityInfo`; the public facts API exposes ordered basic allow/deny ACE SIDs, masks, and decoded flags without trust policy. Secure-file reads query the borrowed open descriptor and compare its 32-bit volume serial and 64-bit file-index projection with Node's bigint receipt. | The packaged PowerShell/C# bridge preserves raw facts and inspects the borrowed descriptor for secure reads, with the same Node identity comparison; its command failures reject. Structured .NET pathname reporting retains its separate compatibility query. |
+| Windows private directory | Creation-time protected DACL. | The packaged PowerShell/C# bridge applies the protected DACL at creation and retains exact handles through identity validation and failure cleanup. Command failures reject. |
+
+Use `off` in CI to keep the fallback contract exercised. Use `require` when a
+deployment depends on the stronger mechanism or a native-only feature; do not
+infer native loading from timing.
+
+## Loader security
+
+Importing fs-safe never executes a child process. Linux libc selection uses
+the Node process report, then the ELF `PT_INTERP` field of `process.execPath`,
+then conventional musl library filenames. An installed compatibility loader
+does not override the running executable's interpreter. If all probes are inconclusive, the
+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.
+
+## Related pages
+
+- [Native helper policy](native-helper.md)
+- [Security model](security-model.md)
+- [Archive extraction](archive.md)
+- [Durability](durability.md)
+- [Permissions](permissions.md)
+- [Migrating to 0.5](migrating-to-0.5.md)
+- [Migrating to 0.6](migrating-to-0.6.md)