@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -1,6 +1,6 @@
 # Atomic writes
 
-`@openclaw/fs-safe/atomic` re-exports the lower-level helpers that `root()`'s write methods are built on. Reach for them when you have an absolute path you trust and want sibling-temp + rename without setting up a `Root`, or when you need finer control over `fsync`, mode preservation, or pre-rename hooks.
+`@openclaw/fs-safe/atomic` re-exports the lower-level helpers that `root()`'s write methods are built on. Reach for them when you have a path you trust and want sibling-temp + rename without setting up a `Root`, or when you need finer control over `fsync`, mode preservation, or pre-rename hooks.
 
 ```ts
 import {
@@ -16,10 +16,18 @@ import {
 
 Write `content` to a sibling temp file in the destination directory, apply the parent-directory and final file modes through verified descriptors, optionally `fsync` the file descriptor, optionally `fsync` the parent directory after rename, then atomically rename over the destination. No permission change follows a caller-supplied pathname.
 
-On POSIX, the parent is opened with no-follow and directory-only flags, checked against its pre-open identity, and mode-adjusted through that descriptor. A replacement symlink is rejected rather than followed. If the directory cannot be opened for descriptor access, the operation fails closed instead of retrying by pathname. Windows does not enforce POSIX directory modes and Node cannot consistently open directory descriptors there, so `dirMode` is passed only to `mkdir`; no pathname `chmod` fallback is attempted.
+On POSIX, the parent is opened with no-follow and directory-only flags, checked against its exact pre-open device/inode identity, and mode-adjusted through that descriptor. A replacement symlink is rejected rather than followed. If the directory cannot be opened for descriptor access, the operation fails closed instead of retrying by pathname. Windows does not enforce POSIX directory modes and Node cannot consistently open directory descriptors there, so `dirMode` is passed only to `mkdir`; no pathname `chmod` fallback is attempted.
 
 Async replacements to the same destination are serialized inside the current process, so two overlapping `replaceFileAtomic()` calls do not interleave their temp-write/rename phases. Use a sidecar lock when multiple processes may write the same target.
 
+Relative paths retain their literal suffix so `.` and `..` keep Node's existing
+filesystem semantics. On Windows, an ordinary drive-relative destination such
+as `C:.\\state.json` is captured at entry by anchoring the drive's current
+directory without normalizing that suffix. The anchored absolute spelling is
+used for staging, locks, callbacks, publication, and cleanup. Any additional
+colon remains visible and is rejected as a filesystem namespace alias before
+I/O; malformed namespace-drive spellings remain rejected.
+
 ```ts
 import { replaceFileAtomic } from "@openclaw/fs-safe/atomic";
 
@@ -40,7 +48,7 @@ type ReplaceFileAtomicOptions = {
   content: string | Uint8Array;
   dirMode?: number;                 // parent-directory mode (POSIX; default 0o700)
   mode?: number;                    // new-file mode (default 0o600)
-  preserveExistingMode?: boolean;   // copy existing mode; default false
+  preserveExistingMode?: boolean;   // inherit existing regular-file rwx bits; default false
   tempPrefix?: string;              // default ".fs-safe-replace"
   renameMaxRetries?: number;        // EBUSY retries; default 0
   renameRetryBaseDelayMs?: number;  // exponential base; default 50
@@ -57,6 +65,17 @@ type ReplaceFileAtomicOptions = {
 };
 ```
 
+`preserveExistingMode` snapshots only the ordinary rwx bits (`0o777`) from an
+existing non-symlink regular destination. A final symlink fails with
+`FsSafeError("symlink")`; a directory or other non-regular destination fails
+with `FsSafeError("not-file")`. Set-user-ID, set-group-ID, and sticky bits are
+never inherited. Mode inheritance does not copy ownership, ACLs, extended
+attributes, or exact destination identity. Rename publication creates a new
+inode; an in-place copy fallback can retain metadata already attached to its
+pinned destination. The snapshot does not make replacement a compare-and-swap
+operation, so the destination parent must still be protected from untrusted
+concurrent namespace mutation.
+
 ### `beforeRename`
 
 Runs after the temp file is fully written and before the rename. Use it to take a backup snapshot, capture the about-to-be-replaced contents, or notify an observer. The helper retains the staged descriptor and exact bigint identity across the hook; replacing, deleting, hardlinking, or changing the temp entry to a non-regular file is rejected before publication:
@@ -73,14 +92,53 @@ await replaceFileAtomic({
 
 If `beforeRename` throws, the rename is skipped and the owned temp file is removed — the destination is unchanged. Cleanup unlinks only the exact admitted single-link file; a substitute observed at the temp name is preserved and removed from cleanup authority. The same identity is rechecked before every rename retry, when entering copy fallback, and at the final name after rename. A post-rename verification failure reports the race without rolling back or deleting the published name.
 
+JavaScript permits `beforeRename` callbacks and filesystem adapters to throw any value, including
+`undefined`, `null`, `false`, signed zero, `0n`, an empty string, and `NaN`.
+Atomic replacement preserves such operational failures when cleanup and close
+succeed, including rename and post-rename verification failures. Rename retry
+and copy-fallback classification reads the error code once without coercion;
+missing or unreadable codes preserve the original failure. A rejected call has
+no success receipt even if an adapter committed its rename before throwing. With
+`throwOnCleanupError: true`, an additional owned-temp cleanup failure keeps the
+existing cleanup wrapper whose `cause` is the original thrown value. A later
+descriptor-close failure is reported in an `AggregateError`, in operation/cleanup
+then close order. The default `throwOnCleanupError: false` omits only the cleanup
+failure: the temp stays registered for identity-checked process-exit cleanup, the
+descriptor is still closed, and a close failure remains reportable.
+
 Identity checks and pathname rename/unlink remain separate syscalls, not atomic conditional mutations. Use an approved writable parent plus cooperative locking or OS isolation when arbitrary concurrent namespace mutation is in scope.
 
-### FUSE mounts and unstable rename identity
+### FUSE, Windows exFAT/FAT32, and unstable rename identity
 
 Strict source-to-destination identity is the default. Some FUSE mounts assign a different inode to the destination during rename even without concurrency. Set `renameIdentity: "verify-content-with-lock"` to accept that boundary only when the re-opened no-follow destination has the exact requested SHA-256 content under an exclusive hashed sidecar lock in the destination parent. The newly accepted descriptor and identity remain pinned through parent sync and final verification. The synchronous helper provides the same policy with the synchronous lock implementation.
 
 This is the same explicit weaker contract available on `Root` writes: cooperating writers are serialized, stale locks fail closed, and mismatched content is rejected after publication without rollback. A same-authority actor that ignores the advisory lock can still substitute another file with identical bytes, so do not use this compatibility policy in directories writable by untrusted same-UID processes.
 
+Windows exFAT/FAT32 volumes can also change file identity during rename, depending
+on the source and destination names. The destination may already contain the
+requested bytes when strict verification reports `path-mismatch`. A short
+temporary name alone does not guarantee stable identity for a longer destination.
+For an application-controlled directory on such a volume, callers can explicitly
+select `renameIdentity: "verify-content-with-lock"` on `replaceFileAtomic` or
+`replaceFileAtomicSync`. Keep strict mode for directories that require the
+stronger identity contract; do not automatically retry every `path-mismatch`
+with the weaker policy. Staging names remain random, including custom prefixes.
+
+To verify the built package against an actual volume, run
+`node scripts/atomic-rename-compat-proof.mjs EXISTING_PARENT` after `pnpm build`.
+Use a trusted parent directory that no other process can rename or modify during
+the entire run, including cleanup; do not point the probe at a shared writable
+volume root. Cleanup checks the created directory's identity before recursive
+removal, but the check and removal are not atomic. The probe does not test safety
+against hostile concurrent namespace mutation.
+The probe creates and cleans up its own child directory and emits JSON without
+local paths. It compares default, strict, and locked policies in both async and
+sync calls, checks real rename identities and file contents, injects different-
+and identical-content substitutions, checks lock cleanup, and exercises custom
+prefix isolation and validation. Callback staging remains strict and can still
+report identity drift; the probe records that result separately. Filesystem type
+must be recorded independently; the probe does not infer it from a drive letter.
+
 ### `EPERM` and copy fallback
 
 On systems where `rename` fails with `EPERM`/`EEXIST`, pass
@@ -95,6 +153,28 @@ must not have aliases. The policy reads `nlink` from a pinned destination
 descriptor, not pathname metadata, before rename and rechecks it in the copy
 fallback.
 
+The asynchronous helper closes a successfully admitted hardlink-check pin
+best-effort, including synchronous adapter throws and rejected close promises.
+The synchronous helper reports a close failure after successful admission.
+
+Source and pinned destination admission compare exact bigint device/inode
+observations, so distinct identities that round to the same JavaScript number
+cannot authorize a copy. Unknown Windows identities get one bounded reinspection
+of the same descriptor or path; incomplete or inconsistent observations fail
+closed without reopening. Injected filesystem adapters must honor the
+`{ bigint: true }` stat option. Source admission reuses that exact pair instead
+of immediately repeating it with numeric metadata.
+
+Copy-source close is best-effort. A failed pinned-destination admission also
+preserves its selected failure when close fails. These cleanup rules include
+synchronous throws and rejected promises from custom asynchronous adapters.
+
+The best-effort parent-directory synchronization helper also ignores either form
+of close failure. Parent-directory mode admission and its close remain fail-closed.
+A compatibility-publication handle that was not adopted also receives one
+best-effort close, preserving the selected verification or previous-handle close
+failure. The retained owner's close failures remain reportable.
+
 The default `copyFallbackRestore: "none"` preserves the existing fallback
 contract: a failed copy can leave a partial destination. For state files where
 preserving the old bytes is more important, choose `"restore-original"` and set
@@ -104,12 +184,30 @@ that same descriptor, and synchronizes the result. Any write, mode, or sync
 failure triggers a byte-and-mode restore and another sync through the same
 descriptor.
 
+With `syncTempFile: false`, an exclusive-create copy fallback does not report
+success until its new destination writer closes successfully. This includes
+`"restore-original"` when the destination did not exist. A close rejection or throw is
+propagated exactly, including falsy values. The destination may already contain
+all or part of the replacement, so a close failure does not prove that the old
+destination survived or that the replacement was published. The outer atomic
+operation still attempts identity-bound cleanup of its owned source temp; an
+unverifiable or substituted temp remains preserved. If writing, mode adjustment,
+or another earlier operation also fails, that earlier value remains the reported
+failure and the destination close is attempted once. Successful synchronized
+fallbacks and in-place `"restore-original"` replacements retain their existing best-effort final-close
+handling.
+
 Restore failures are `FsSafeError("helper-failed")` values with typed
 `details.cleanup` set to `"restored"` or `"restore-failed"`. An original larger
 than `maxRestoreBytes` fails with `too-large` before mutation. A missing
 destination has no original to restore and follows the exclusive-create copy
 fallback.
 
+Restore snapshots use the pinned file's size as an allocation hint, with an
+initial allocation capped at 16 MiB plus the overflow byte. Reads continue
+through short reads and EOF, grow only as data arrives, and enforce the same
+`maxRestoreBytes` budget even if the destination grows after its size was read.
+
 ### Sync variant
 
 `replaceFileAtomicSync` accepts the same base options, a synchronous
@@ -119,7 +217,9 @@ synchronous boot paths or test setup code. It returns the same
 
 ## `replaceDirectoryAtomic`
 
-Atomically swap one directory's contents with another, using a temporary backup during the swap.
+Publish one staged directory at a target without overwriting a concurrently
+created entry. Despite the historical name, replacing an existing target is a
+guarded two-rename protocol, not an atomic directory exchange.
 
 ```ts
 import { replaceDirectoryAtomic } from "@openclaw/fs-safe/atomic";
@@ -130,13 +230,66 @@ await replaceDirectoryAtomic({
 });
 ```
 
-The helper renames `targetDir` to a generated backup path, renames `stagedDir → targetDir`, then removes the backup. If the second rename fails, it tries to restore the original target before rethrowing.
-Concurrent replacements of the same resolved target are serialized inside the
-current process so their backup, commit, and cleanup phases cannot interleave.
+Every publication requires the dedicated native identity-fenced,
+descriptor-relative no-replace rename capability and readable retained
+descriptors for the staged and target parents. Older bindings that expose only
+the legacy four-argument no-replace rename fail with `helper-unavailable`
+before target-parent creation or any other replacement effect. This applies
+when the parents are the same or different. There is no JavaScript rename
+fallback, and a cross-device rename still fails. Replacing an existing target
+additionally requires usable native bounded owned-tree cleanup and a readable
+retained descriptor for the original target.
+
+If the target is absent, the helper publishes `stagedDir → targetDir` with a
+single no-replace rename. If the target exists, it renames `targetDir` to a
+randomized sibling backup and then renames `stagedDir → targetDir`. The target
+name is temporarily absent between those two operations. A competing entry is
+never overwritten. Publication rollback is attempted only when the staged
+rename is known not to have committed and the target name is still absent; the
+rollback itself is no-replace, so a competitor is preserved and the backup is
+left for recovery.
+
+Exact staged-directory identity and parent checks run before and after each
+rename. On Windows, the native rename opens the source relative to the retained
+parent, compares that handle's exact volume and file-index identity with the
+pre-rename bigint receipt, and only then mutates it. POSIX does not provide a
+rename operation that also compares an expected source inode, so on POSIX a
+source-name substitution in the final check-to-rename gap can be moved briefly
+and then detected by the post-rename verification. Similarly, a successful
+rename can be followed by a verification error. Inspect the error's
+`details.publication` value rather than treating rejection as proof that
+publication did not happen.
+
+A Windows source-identity mismatch is rejected before mutation, reported
+publicly as `path-mismatch`, and treated as definitely uncommitted so an earlier
+backup can be rolled back. Other `path-mismatch`-shaped native errors are not
+assumed to be pre-commit failures; their publication outcome remains
+indeterminate and observed competitors are preserved.
+
+Any native rename error without explicit pre-dispatch provenance has an
+indeterminate outcome, including ordinary errno such as `ENOENT`, `EEXIST`,
+or `EACCES`: a remote filesystem may commit before losing its reply. The helper
+does not guess whether that rename committed or perform another rename or
+cleanup based on that guess; observed names are preserved for caller-directed
+recovery. An error `details.backupPath`, when present, is only the attempted or
+last-observed backup pathname. It does not prove that the path still exists or
+still names the original directory.
+
+After a verified commit, the original backup is removed through its retained
+directory identity and bounded native traversal. Cleanup failures reject after
+publication and can leave the backup. On POSIX, cleanup retains the
+[bounded final-entry unlink limitation](temp.md#private-temp-workspaces).
+
+Concurrent calls for the same resolved target are serialized inside the current
+process so their backup, publication, and cleanup phases cannot interleave.
+Other processes are not serialized; no-replace renames provide the competitor
+boundary. On Windows, ordinary drive-relative staged and target paths are
+anchored at entry before namespace-alias admission and resolution.
 `backupPrefix`, when supplied, is sanitized as one path prefix and cannot contain
 path separators or NUL bytes; the generated backup tail is randomized.
 
-Use it when callers must see a whole staged tree at the target path. For single-file replacement, `replaceFileAtomic` is the right tool.
+Use it when callers must publish a whole staged tree with these recovery
+semantics. For single-file replacement, `replaceFileAtomic` is the right tool.
 
 ## `writeTextAtomic`
 
@@ -182,6 +335,13 @@ directory mode. Staged file modes are applied through their still-open handles.
 If descriptor-bound mode application fails, the staged path is removed and the
 move fails before publication. A transient staged-path cleanup failure retains
 an identity-bound process-exit cleanup retry.
+The staging entry's initially admitted identity is checked before publication
+and cleanup; a later substituted entry is preserved. Regular files are admitted
+through their new descriptor. Node provides no creation descriptor for directories
+or symlinks, so their first identity comes from an immediate pathname observation.
+Replacement before that observation remains a best-effort detection gap: use a
+parent protected from concurrent untrusted mutation or OS isolation. A copy write
+that makes no progress rejects instead of looping indefinitely.
 On POSIX, staged directory modes are applied through no-follow directory
 descriptors; on Windows, Node cannot portably open those descriptors and no
 pathname `chmod` fallback is attempted, so directory modes remain subject to
@@ -200,6 +360,8 @@ await movePathWithCopyFallback({
 ```
 
 Use it when source and destination might live on different filesystems (containers, tmpfs, separate volumes).
+On Windows, ordinary drive-relative `from` and `to` paths are anchored at entry;
+publication receipts report the resulting absolute destination.
 The hardlink policy is captured when the move starts. Changing or reusing the
 options object later does not change the policy of an in-flight move.
 `sourceHardlinks: "reject"` performs a recursive preflight capped at 50,000
@@ -212,11 +374,31 @@ the preflight cap fails with `FsSafeError("too-large")`.
 If another writer changes source entries during the fallback, the staged copy
 throws `ESTALE` before commit when possible. If the destination has already
 been committed, cleanup still preserves the changed source entries and throws
-`ESTALE`. When allowed source names are hardlinks to the same inode, each owned
+`ESTALE`. Copied file and symlink manifests retain exact bigint identities and
+nanosecond timestamps, so rounded file IDs cannot authorize copying or removal
+of a different entry. Hardlink groups also use exact identities. Directory
+manifests retain an exact bigint device/inode receipt from
+copy admission. Each directory is rechecked after traversal, and the source root
+is checked again before publication. Cleanup checks the same receipt before
+removing children, then invokes mutation authority and rechecks the receipt and
+directory type immediately before removal. Unknown Windows identity
+components get at most one retry that retains known components; persistent
+ambiguity fails closed before further removal. A directory that disappeared or
+was replaced during child cleanup is reported as stale; an observed replacement
+is preserved. Unrelated children
+added to the original directory are preserved while unchanged copied children
+are still removed. These pathname checks remain best-effort: they cannot make
+the final identity check and removal atomic against another process.
+When allowed source names are hardlinks to the same inode, each owned
 unlink is verified through a remaining manifested alias and its exact resulting
 identity becomes the next cleanup receipt. This accounts for the operation's
 own link-count and ctime changes without suppressing unexpected external
 mutations.
+On Windows, opening a regular source may advance its ctime while all other
+fingerprint fields match. That exception applies only to opening; post-copy
+verification and cleanup retain their full fingerprint checks.
+Copied aliases share each verified open-time update. Changes observed between
+copies still reject instead of being mistaken for an owned open transition.
 
 ### Mutation authority and publication receipts
 
@@ -255,6 +437,11 @@ thenable, or any other value fails with a `TypeError`; rejected asynchronous
 results are consumed. Perform asynchronous policy checks before calling the
 helper and use the authority callback to recheck the current owner at each
 mutation boundary. All callbacks are captured before the first await.
+Copied source leaves are checked again immediately after authority returns and
+before unlink is submitted. Supplying any of the three callbacks also
+retains the original source-parent route and renews copied-directory ancestry
+before cleanup. Substituted entries are preserved; pathname checks and unlink
+remain a best-effort sequence, not atomic.
 
 `onDestinationPublished` runs exactly once after a successful rename resolves,
 before awaited post-rename directory checks or source cleanup. It receives a
@@ -289,7 +476,7 @@ preserves the existing move and source-identity behavior.
 
 | `Root` methods | `atomic` helpers |
 |---|---|
-| Take relative paths, bound to a `rootDir`. | Take absolute paths, no boundary. |
+| Take relative paths, bound to a `rootDir`. | Take trusted absolute or relative paths, no boundary. |
 | Throw `FsSafeError` with `code`. | Throw `FsSafeError` *or* the underlying `NodeJS.ErrnoException`, depending on failure point. |
 | Atomicity, mode, hooks, fsync are sane defaults. | Caller controls all of the above. |
 | `mkdir`, identity check, hardlink reject built in. | No root boundary; `movePathWithCopyFallback` has explicit `sourceHardlinks` policy, while other helpers expose their own narrower checks. |
@@ -324,7 +511,7 @@ type ReplaceFileAtomicSyncFileSystem = {
 };
 ```
 
-The async interface already requires `open()`, whose `FileHandle` supplies `chmod()`, so injecting `node:fs` or another conforming adapter needs no new async member. On POSIX, that `open()` must support no-follow directory descriptors as Node does. A custom synchronous filesystem that passes `mode`, `dirMode`, or `preserveExistingMode` must supply `fchmodSync`; omission fails before any file or directory is created and never falls back to a pathname `chmod`. Existing synchronous adapters that request none of those options may omit it; their parent is still opened and identity-checked through a no-follow directory descriptor. Injecting plain `node:fs` supports explicit file and directory modes. Older adapter literals may continue to include `chmod` or `chmodSync` for source compatibility, but those operations are ignored. Copy fallback applies the file mode through its pinned destination descriptor as well, preserving exact modes despite the process umask.
+The async interface already requires `open()`, whose `FileHandle` supplies `chmod()`, so injecting `node:fs` or another conforming adapter needs no new async member. The async temp owner consumes its retained handle before awaiting `close()` during publication handoff and terminal settlement: if a custom adapter releases the resource and then rejects, that rejection is reported without calling `close()` on the same retained handle again. If publication verification opened a replacement handle before the previous retained handle failed to close, the replacement receives one best-effort close attempt. On POSIX, `open()` must support no-follow directory descriptors as Node does. A custom synchronous filesystem that passes `mode`, `dirMode`, or `preserveExistingMode` must supply `fchmodSync`; omission fails before any file or directory is created and never falls back to a pathname `chmod`. Existing synchronous adapters that request none of those options may omit it; their parent is still opened and identity-checked through a no-follow directory descriptor. Injecting plain `node:fs` supports explicit file and directory modes. Older adapter literals may continue to include `chmod` or `chmodSync` for source compatibility, but those operations are ignored. Copy fallback applies the file mode through its pinned destination descriptor as well, preserving exact modes despite the process umask.
 
 ## See also
 

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

@@ -37,10 +37,14 @@ Set the process-global loading policy. Configure once at startup, before the fir
 
 | Mode | Behavior |
 |---|---|
-| `auto` | Default. Prefer the platform binding and use guarded JavaScript when it is unavailable. |
-| `off` | Do not load the binding; use guarded JavaScript deterministically. |
+| `auto` | Default. Prefer the platform binding and use supported fallbacks when it is unavailable. |
+| `off` | Do not load the binding; use supported fallbacks and reject native-only operations. |
 | `require` | Operations that need the binding raise `FsSafeError("helper-unavailable")` when it cannot load. |
 
+Fallbacks include guarded JavaScript, the bundled TAR/gzip WASM parser, and the
+[packaged Windows security scripts](install.md#windows-security-fallback).
+Windows command fallbacks remain subject to normal system execution policy.
+
 ## `getFsSafeNativeConfig()`
 
 ```ts
@@ -65,6 +69,7 @@ type FsSafeLockConfig = {
 Set process-wide defaults for sidecar lock options. This does **not** turn locking on globally; callers still need to pass `lock: true` or a lock options object for the specific JSON store/resource that needs cross-process coordination.
 
 `staleRecovery` defaults to `"fail-closed"`. The opt-in `"remove-if-unchanged"` mode requires caller approval and serializes the final snapshot check and unlink with an exclusive `.reclaim` guard. A reclaim guard left by a killed reclaimer fails closed and requires externally coordinated cleanup.
+`staleMs` must be non-negative and not `NaN`; `Infinity` disables age-based staleness.
 
 For a daemon that should wait briefly for normal contention but never delete a
 stale owner without per-lock approval:

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

@@ -19,10 +19,50 @@ manager version declared in `package.json`.
 pnpm build
 ```
 
-Runs TypeScript compilation and builds the portable Rust TAR parser for
-`wasm32-unknown-unknown`. Contributors need Rust (the native crate's declared
-minimum or newer) and `rustup target add wasm32-unknown-unknown`; Alpine's
-packaged toolchain uses `rust-wasm`. `pnpm archive:wasm` rebuilds just the parser.
+Runs TypeScript compilation and builds the portable Rust TAR parser and its
+bzip2/zstd codecs for `wasm32-unknown-unknown`. Contributors need Rust (the
+native crate's declared minimum or newer), `rustup target add
+wasm32-unknown-unknown`, and LLVM's WebAssembly-capable `clang` and `llvm-ar`.
+The system's native `ar` is not sufficient. `pnpm archive:wasm` rebuilds just
+the portable module.
+
+Linux, macOS, and Windows CI use the same pinned WASI SDK 34 LLVM toolchain;
+Alpine uses its versioned LLVM 22 packages alongside `rust-wasm`. For local
+builds, install LLVM through your package manager or use the official
+[WASI SDK](https://github.com/WebAssembly/wasi-sdk/releases/tag/wasi-sdk-34).
+On macOS, `brew install llvm` supplies the archiver missing from Apple's
+Command Line Tools. On Windows, install the LLVM distribution with both
+`clang.exe` and `llvm-ar.exe`. On Linux, install the matching `clang` and
+`llvm` packages; a GCC-only build toolchain cannot compile these WASM codecs.
+
+The build discovers tools on `PATH`, in `LLVM_PATH/bin`, in Homebrew's LLVM
+prefixes, and in Windows' standard LLVM installation. It also checks the
+versioned `clang-18` through `clang-21` and `llvm-ar-18` through `llvm-ar-21`
+executables. To select another installation explicitly, set
+`CC_wasm32_unknown_unknown` and `AR_wasm32_unknown_unknown` to its compiler
+and archiver. The corresponding hyphenated target variables and cc-rs's
+`TARGET_CC`/`TARGET_AR` or `CC`/`AR` overrides are also respected; an unusable
+explicit override fails with a builder diagnostic instead of being ignored.
+Windows build environment names are case-insensitive, including when worker
+processes uppercase them. The build normalizes only its copied child environment.
+Clang's implicit configuration is disabled for this target so the WASI SDK's
+default libc/sysroot cannot leak into the import-free module. These settings
+affect compilation only and do not become runtime dependencies.
+
+The build disables release LTO only in the WASM Cargo subprocess. An observed
+Rust 1.98.1 optimized-WASM-LTO allocation/free failure makes that necessary;
+the native release profile stays unchanged. The WASM linker strips debug
+sections to keep the bundled module small without stripping native binaries.
+The build verifies zero host
+imports and one unshared 32-bit memory with the existing 256 MiB maximum
+before copying the artifact. Allocator regression tests build a separate
+instrumented module with `pnpm archive:wasm:allocator-tests` under the Cargo
+target directory. That module is never copied to `dist/` or packaged. `pnpm
+check` and coverage collection build it explicitly before testing. After a
+fresh checkout, run that command before `pnpm test`, `pnpm test:coverage`, or
+focused `test/archive-codec-wasm-allocator.test.ts` runs; the tests fail if
+their prerequisite artifact is missing.
+
 The import-free asset lands at `dist/archive-parser.wasm`; source tests and
 compiled consumers both resolve that generated artifact. Run `pnpm build`
 before source tests in a fresh checkout. Do not commit `dist/` or built WASM.
@@ -42,6 +82,32 @@ Vitest. Tests live in `test/` and follow `*.test.ts`. Run a single file with:
 pnpm test test/archive.test.ts
 ```
 
+Guest filesystem tests and package smoke also need `python3` on Linux and
+macOS. They execute the exported source on synthetic files; Windows checks
+the import surface and leaves POSIX execution to the Linux/macOS lanes.
+After building on Linux, `node scripts/check-pack.mjs --guest-cross-device`
+also proves an installed-package directory move from temporary storage to
+`/dev/shm`; the command requires those locations to be different filesystems.
+
+With Bun 1.4.2 installed, build the host addon and run the native compatibility
+lane in real Bun workers, then exercise the built package with JIT disabled:
+
+```bash
+pnpm native:build
+pnpm test:bun:native
+bun --jitless scripts/bun-native-proof.mjs
+```
+
+Keep the Node/pnpm build toolchain above. CI runs the native compatibility lane
+on Linux, macOS, and Windows. The built-package proof checks `auto`/`require`,
+native-off loading policy, and a separate installation without the addon.
+
+`pnpm test:bun` runs the entire Node-oriented suite as a diagnostic. On released
+Bun, its explicit native-off and missing-helper cases include unsupported
+permission/path behavior described in [install](install.md#bun-runtime); this
+command is not a passing compatibility gate. Node CI retains every fallback
+assertion. Neither lane rewrites `off` to `auto` or marks defects as expected passes.
+
 Use `vi.mock` sparingly. Most tests should drive real disk operations in a `mkdtemp`-created scratch directory, asserting on observable behavior. The library has [test hooks](testing.md) for the rare cases where you need to inject a TOCTOU race deterministically.
 
 Vitest timeouts do not cancel filesystem promises. Shared fixtures with expensive
@@ -50,7 +116,10 @@ setup use `useSuiteFixture` from `test/helpers/suite-fixture.ts`: setup has a se
 removing directories. Run shared-state corpora sequentially with a deadline per
 payload. Keep child-process liveness limits separate from fixture preparation.
 The Windows CI slow-copy proof runs the real package-copy process-exit test with a
-six-second copy delay, retaining its four-second child deadline:
+16-second copy delay, a 10-second child deadline, a 15-second test deadline, and
+60-second setup and teardown hook budgets. Other hosts retain the ordinary
+six-second delay, four-second child deadline, five-second test deadline, and
+30-second hook budgets:
 
 ```bash
 pnpm build
@@ -68,6 +137,13 @@ pnpm check
 This runs the filesystem boundary checks, build, tests, and package
 tarball/import validation.
 
+### Method benchmarks
+
+`pnpm benchmark:methods` measures the callable library surface against synthetic
+fixtures and fails on uncovered exports or returned methods. See the
+[benchmark guide](https://github.com/openclaw/fs-safe/tree/main/benchmarks) for native/fallback runs, per-call
+timings, exclusions, and comparison methodology. Run `pnpm build` first.
+
 ### Real TAR producers
 
 After installing the freshly packed root (and optionally its freshly built host
@@ -81,6 +157,10 @@ pnpm archive:producer-smoke ./consumer require
 This uses a child bound to canonical cwd/device/inode running `/usr/bin/tar -czf - .`
 with unchanged stdout, and npm tar, on synthetic Unicode/newline/long-name files,
 then the installed package API for exact payload hashes and bounded reads.
+The consumer must be separate from the source checkout; package resolution must
+stay within its own `node_modules`, including pnpm's local `.pnpm` layout.
+Workspace self-resolution, upward resolution, and external package links reject
+before package imports or archive fixture creation.
 It also rejects a valid PAX override attached to an invalid raw UTF-8 field.
 The `require` command must resolve the freshly packed native binding; the
 `off` command uses the installed WASM asset. No live user files are read.
@@ -116,7 +196,9 @@ 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
+require the pnpm lifecycle CLI path; JavaScript CLIs run through Node and standalone
+`@pnpm/exe` binaries run directly. Shell/cmd shims and PATH fallback are not used;
+direct `node` invocation without lifecycle metadata 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