@openclaw/fs-safe 0.14.0 → 0.16.0

package/docs/archive.md

@@ -3,11 +3,19 @@
 `@openclaw/fs-safe/archive` extracts ZIP and TAR archives behind one API, with traversal checks, blocked-link-type rejection, and entry-count and byte budgets. When the native binding is available for the current platform, Rust streams ZIP, TAR, gzip, zstd, and bzip2 while TypeScript remains the sole policy owner; every accepted output is created fd-relative in a private staging root. Extraction then merges through the same safe-open boundary used by direct writes — a symlinked entry can't trick the merge into following an out-of-tree path.
 
 TAR admission uses one Rust core compiled into both the native binding and a
-bundled, import-free WebAssembly module. The guarded JavaScript fallback uses
-that module for TAR/gzip and optional `jszip` for ZIP. TAR needs no optional
-parser dependency, runtime download, install script, or consumer Rust toolchain.
-Installs omitting optional dependencies can import every public subpath and use
-TAR/gzip in `auto` or `off`; ZIP fallback still requires `jszip`.
+bundled, import-free WebAssembly module. In `off`, or `auto` when the native
+binding is unavailable, extraction and bounded entry reads use that module for
+plain TAR, gzip, zstd, and bzip2. Zstd and bzip2 use bundled WASM builds of the
+same codec implementations used by native; gzip uses Node's built-in decoder.
+These TAR routes work with all optional dependencies omitted and need no
+runtime interpreter, download, install script, or consumer compiler toolchain.
+ZIP fallback still requires optional `jszip`.
+
+`auto` prefers an available native binding; a native operation failure is
+terminal and never retries through WASM. `require` rejects a missing binding
+with `FsSafeError("helper-unavailable")`, including for zstd/bzip2 suffix
+resolution. The separate `inspectTarArchive()` API still accepts only plain TAR
+and gzip.
 
 ```ts
 import { extractArchive, resolveArchiveKind } from "@openclaw/fs-safe/archive";
@@ -124,7 +132,12 @@ Readable directories do not depend on procfs. A Linux search-only directory
 needing a mode change requires accessible, genuine procfs; unavailable or
 untrusted authority rejects explicitly instead of silently accepting a wrong
 mode. Other unsupported search-only routes also fail closed. Windows retains
-its existing bounded lack of POSIX mode enforcement.
+its existing bounded lack of POSIX mode enforcement. Best-effort mode handling
+applies only to the mode change itself: an authority or deadline check that
+fails immediately before dispatch still propagates, including a custom
+one-shot structural check. A check failure observed immediately after dispatch
+is retained while post-dispatch authority verification and final mode inspection
+settle, then propagated with its exact JavaScript value, including falsy values.
 
 Extraction and TAR inspection first copy the admitted source into a private
 staging file. This copy reuses at most 512 KiB of scratch space, reduced for
@@ -148,14 +161,24 @@ must agree with this kind, physical index, size, known path, and UNIX-creator mo
 before extraction or any member read. Bounded ZIP reads retain this metadata from
 their single admission pass without another input copy or scan.
 
-Portable ZIP preflight, extraction, and reads also check the decoded kind against
-admission. Unsupported JSZip metadata rejects with `ArchiveFormatError` before
-filters, including UNIX-only directory attributes without a terminal slash or DOS
-directory bit, backslash-only directory names without directory attributes, and
-non-UNIX creators whose high-word symlink mode JSZip does not expose. Symlinks that
-the decoder represents faithfully remain subject to the existing filter and
-blocked-link policy. UNIX creator metadata and permission defaults remain as
-described above.
+Portable ZIP preflight, extraction, and reads bind every decoder insertion to
+its admitted physical record before JSZip can coerce its type or discard its
+payload. Names, physical order, original directory/permission metadata,
+compression method, compressed and decoded sizes, and CRC must agree. The
+private loader then applies the admitted kind, preserving UNIX-only directory
+attributes, backslash-only directories, and high-word symlinks from any creator.
+Symlinks remain subject to the existing filter and blocked-link policy.
+UNIX socket and block-device type bits do not turn regular-file payloads into
+empty directories. Directory and symlink callbacks receive their physical
+declared sizes; directory bodies are not published as files. Unsupported
+link-like types remain visible as `other` and are safely omitted when accepted.
+UNIX creator metadata and permission defaults remain as described above.
+
+The loader adapter belongs to one private JSZip instance and is removed after
+loading, including failure. Public preflight still returns ordinary JSZip entry
+objects, with directory keys ending in `/` and recognizable symlink type bits.
+Compressed data is retained even for declared-zero entries, so an empty-size
+claim cannot bypass payload-size or CRC verification during extraction or reads.
 
 Within one ZIP entry, identical local and central name bytes reuse the same
 decoded validation. Unicode Path admission is shared only when both the raw names
@@ -173,7 +196,7 @@ collision checks, writes, and mode application agree.
 
 An `entryFilter` sees the validated **canonical effective archive path before
 stripping**, entry kind, and declared size. On every JavaScript and native
-ZIP/TAR backend (including gzip and native zstd/bzip2), backslashes become `/`,
+ZIP/TAR backend (including gzip, zstd, and bzip2), backslashes become `/`,
 empty and `.` components are removed, and trailing separators are removed from
 directory paths. For example, `./pkg//state\cache/value` is presented as
 `pkg/state/cache/value`, even with `stripComponents: 1`. Case and Unicode
@@ -269,11 +292,23 @@ A failure before publication preserves a pre-existing file, and rejection does
 not grant authority to delete a substituted file or alias. Failed extraction does not
 restore overwritten contents. Active destination mutations and their guarded
 cleanup still finish before rejection; no later destination mutation begins.
+Portable ZIP output is not eligible for publication until its stream closes or
+the defensive `FileHandle` close succeeds. If that fallback close rejects,
+`extractArchive()` propagates the error and publishes no entry from the staged
+tree. Cleanup retains its best-effort `FileHandle` close; it does not transfer
+the descriptor to a raw or native closer.
 New directories whose finalization was never reached can retain their
 private working mode after failure. Failure cleanup closes retained descriptors;
 it does not run a cleanup chmod sweep or roll back the archive. The public merge
 helper still derives modes from its external source tree and must be able to
 read that source; it never chmods an unreadable external source to admit it.
+It retains the source root and each active child directory's exact identity
+through traversal and copy verification. Each source file is opened once,
+admitted against that root and its earlier exact identity observation, and
+copied from the admitted descriptor; public file modes use that descriptor's
+ordinary permission bits. Replacing a source ancestor or leaf rejects the
+merge before replacement bytes can be published. These checks do not provide
+a snapshot against writes to the same source inode.
 That helper retains per-copy durability and immediate postorder directory-mode
 finalization; the deferred pass described above belongs to `extractArchive()`.
 
@@ -341,14 +376,16 @@ Native gzip, zstd, and bzip2 readers check cancellation before refilling
 compressed input and before each decoded read, including buffered output. These checks
 apply to file extraction and in-memory member reads; they cannot interrupt an
 already-running filesystem read or a decoder step using already-buffered input.
+Portable zstd/bzip2 decoding checks cancellation between bounded codec steps and
+periodically yields to the event loop, including while consuming output-free
+members. An individual WASM call cannot be interrupted. Teardown joins the input,
+parser, and any Node decoder streams before disposing their shared WASM state.
 
 ### Raw TAR framing
 
 Extraction and bounded reads admit the complete decoded TAR stream through the
-shared Rust core. This applies to plain TAR,
-gzip, and native-supported zstd/bzip2, without changing native-mode availability
-or fallback policy. The native and WASM builds enforce the same
-framing rules:
+shared Rust core. This applies to plain TAR, gzip, zstd, and bzip2 on native and
+fallback paths. The native and WASM builds enforce the same framing rules:
 
 - Every nonzero header must have a valid unsigned octal checksum, delimited
   within its field. Checksum validation precedes metadata allocation and member
@@ -393,14 +430,24 @@ returning selected bytes. Unrequested, filtered, and stripped members cannot
 bypass validation. Decompression remains streaming; no complete decoded archive
 is retained in memory or written to a decoded spool.
 
-The WASM transport has a fixed 64 KiB input buffer, one pending member event,
-and a 256 MiB maximum linear memory per isolated parser instance. JavaScript
-gzip decoding emits chunks of at most 64 KiB for both staged files and buffered
-inputs, matching that input window. Metadata is
-bounded before allocation; allocation failure rejects. Stream backpressure
-bounds queued chunks, and completion/error destroys the instance's parser
-state. The manifest retains the existing charged budget below; linear memory
-is an additional execution resource bound, not a new public limit option.
+The WASM transport has fixed 64 KiB input/output windows, one pending member
+event, and a 256 MiB maximum linear memory per isolated session. The parser and
+portable zstd/bzip2 decoder share that session and memory ceiling. JavaScript
+gzip decoding also emits chunks of at most 64 KiB for both staged files and
+buffered inputs. Metadata is bounded before allocation; codec allocation
+failure rejects. Stream backpressure bounds queued chunks, and completion or
+error releases the session's parser and decoder state after stream teardown.
+The manifest retains the existing charged budget below; linear memory is an
+additional execution resource bound, not a new public limit option.
+
+Portable zstd/bzip2 decoding consumes every concatenated member through physical
+EOF and verifies container integrity, including available checksums. Zstd
+skippable frames are consumed without becoming TAR data. Truncated members and
+trailing non-container bytes reject with `ArchiveFormatError` before filters,
+publication, or selected bytes are returned. Decoded TAR EOF and byte-budget
+checks still apply across member boundaries; a second TAR after EOF is not
+silently ignored. The gzip-only compressed-padding policy above does not extend
+to zstd/bzip2 containers.
 
 The raw meter enforces `maxEntries` before consuming each logical member's body,
 including members later skipped by filtering or stripping. PAX/GNU metadata
@@ -497,7 +544,7 @@ parsers from disagreeing about a member's type.
 `K` validates encoding and NUL structure without authorizing link creation.
 Normal link/filter policy still governs the described member. Canonical
 pre-strip filter paths, decoded-stream ceilings, and physical EOF checks apply
-to plain/gzip TAR and native zstd/bzip2 alike.
+to plain/gzip TAR and zstd/bzip2 alike.
 
 ## `inspectTarArchive`
 
@@ -563,7 +610,7 @@ import { resolveArchiveKind, type ArchiveKind } from "@openclaw/fs-safe/archive"
 
 const kind = resolveArchiveKind("upload.zip"); // "zip"
 const tar = resolveArchiveKind("upload.tar.gz"); // "tar"
-const zstd = resolveArchiveKind("upload.tar.zst"); // "tar-zstd" when native is available
+const zstd = resolveArchiveKind("upload.tar.zst"); // "tar-zstd" in auto/off; require checks native
 const unknown = resolveArchiveKind("upload.bin"); // null
 ```
 
@@ -571,17 +618,18 @@ Recognizes:
 
 - `*.zip` → `"zip"`
 - `*.tar`, `*.tar.gz`, `*.tgz` → `"tar"`
-- `*.tar.zst`, `*.tar.zstd`, `*.tzst` → `"tar-zstd"` (native only)
-- `*.tar.bz2`, `*.tbz2`, `*.tbz` → `"tar-bzip2"` (native only)
+- `*.tar.zst`, `*.tar.zstd`, `*.tzst` → `"tar-zstd"`
+- `*.tar.bz2`, `*.tbz2`, `*.tbz` → `"tar-bzip2"`
 
 Returns `null` for unknown extensions; check the result before calling
-`extractArchive` if the filename is caller-controlled. A recognized zstd or
-bzip2 TAR extension with no native binding throws the typed
-`FsSafeError("helper-unavailable")` with installation guidance. This includes
-`mode: "off"`; those two formats have no JavaScript fallback.
+`extractArchive` if the filename is caller-controlled. Recognized zstd and bzip2
+TAR extensions resolve in `auto` and `off` even without a native binding, using
+the bundled codecs for subsequent extraction or reads. Explicit `require`
+still checks native availability during suffix resolution and throws
+`FsSafeError("helper-unavailable")` when the binding cannot load.
 
-For a service whose input contract requires zstd, configure native mode before
-the first archive call so a packaging mistake fails at the boundary:
+For a deployment that requires native archive processing, configure native mode
+before the first archive call so a missing binding fails at the boundary:
 
 ```ts
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
@@ -600,8 +648,10 @@ await extractArchive({
 
 `readArchiveEntry(archivePath, entryPath, { maxBytes, kind? })` reads one
 regular-file entry into a bounded `Buffer` without extracting a tree. It reads
-the input through an identity-checked descriptor, rejects link, directory, and duplicate
-entries, verifies ZIP CRC and declared size,
+the input through an identity-checked descriptor, rejects a requested link or
+directory, and rejects duplicate entry names anywhere in the archive. Unrequested
+links and directories do not prevent reading a regular file; no links are followed
+or created. It verifies ZIP CRC and declared size,
 and throws `ArchiveLimitError` if the requested entry's output exceeds
 `maxBytes`. ZIP output within that cap must match the declared uncompressed
 size exactly; either a shorter or longer payload throws
@@ -614,7 +664,9 @@ plus the 768 MiB decoded ceiling derived from default extracted/archive byte
 limits. It does not apply payload budgets to unrequested members. ZIP
 inputs retain the archive subpath's 256 MiB compressed-input ceiling.
 With a native binding it uses the same Rust decoders as extraction, including
-zstd and bzip2 TAR. Without native it retains the JS ZIP/TAR/gzip implementation.
+zstd and bzip2 TAR. Without native, the guarded fallback uses bundled WASM for
+TAR admission and zstd/bzip2 decoding, Node gunzip for gzip, and optional JSZip
+for ZIP. Native `require` still rejects an unavailable binding.
 Archive member reads retain their private in-memory input without a disk
 snapshot. JavaScript ZIP member reads reuse their completed physical admission
 when loading the decoder, which still checks its decoded names and entry count.
@@ -625,12 +677,11 @@ allocation without another copy where external buffers are supported.
 Native TAR retains the fully admitted member offsets alongside the same input
 allocation. Plain TAR copies only the selected payload range after full archive
 validation. Gzip, zstd, and bzip2 replay bounded decompression and still validate
-all framing, trailers, and physical padding before returning. The JavaScript
-TAR/gzip fallback copies each input window into WASM once, consuming member
-events at offsets within that window. After full admission, plain TAR copies the
-selected range directly from its private snapshot; gzip still replays bounded
-decompression through the parser. WASM transport and selected output still
-require copies.
+all framing, trailers, and physical padding before returning. The fallback also
+retains admitted member offsets. After full admission, plain TAR copies the
+selected range directly from its private snapshot; gzip, zstd, and bzip2 replay
+bounded decompression through the same parser. WASM transport and selected
+output use owned copies, so reusable codec windows cannot escape to callers.
 Returned buffers own their bytes, so changing a result cannot modify an archive
 reader or retain an unrelated part of the input through its backing ArrayBuffer.
 

package/docs/atomic.md

@@ -92,6 +92,17 @@ 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 to throw any value, including
+`undefined`, `null`, `false`, signed zero, `0n`, an empty string, and `NaN`.
+Once such an operation failure reaches temp-owner settlement, atomic replacement
+preserves that value when cleanup and close succeed. 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, Windows exFAT/FAT32, and unstable rename identity
@@ -148,6 +159,19 @@ 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
@@ -168,7 +192,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";
@@ -179,15 +205,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.
-On Windows, ordinary drive-relative staged and target paths are anchored at
-entry before namespace-alias admission and resolution.
+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`
 
@@ -396,7 +473,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/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

package/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.

package/docs/copy.md

@@ -66,6 +66,8 @@ On Windows, automatic byte copying uses the native binding when available to tra
 
 On Linux, automatic byte copying also uses the native binding when available. It reads in chunks up to 1 MiB, using smaller buffers for smaller source-size hints, and leaves leading and trailing zero-filled portions of each chunk unwritten in the new file, avoiding their allocation on filesystems that support sparse files. A final size update preserves trailing holes and all-zero files. This path uses reads and writes, without cloning or copy offload; it still reads the full logical contents and does not promise identical sparse extent layout. `clone: "never"` retains the JavaScript byte-copy path.
 
+Tree-copy cleanup attempts every acquired close once, even when another close fails. Portable file handles close output before input; completed directories close their pinned source before target; the public wrapper then closes its source before the destination parent. A copy, identity, metadata, native-clone, or cancellation failure already observed at one of those scopes remains the reported value instead of being replaced by cleanup. If that scope otherwise succeeded, its first close failure is reported unchanged. Concurrent siblings have no global structural close order: the first observed sibling failure stops new work while admitted work settles. Portable copying records caller cancellation when it occurs, so a later abort during cleanup cannot replace an earlier copy failure.
+
 Clones preserve file contents, empty directories, timestamps, executable modes where supported, and literal symbolic links. Editing a clone does not modify its source. Unsupported filesystem operations fail; callers may choose their own copy or checkout fallback after the failed operation has settled.
 
 Native Windows byte copies can store large zero-filled chunks as sparse ranges when the destination is initially empty and its filesystem supports sparse files. This still reads every source byte and creates an independent copy.
@@ -76,6 +78,8 @@ XFS and ZFS preserve regular-file and directory modes, timestamps, extended attr
 
 `readCloneFileMetadata(files)` asynchronously reads APFS data-stream identities and file metadata in one native batch. Results correspond to input order; missing or unsupported entries return `undefined`. The returned `CloneFileMetadata` includes clone ID, device/inode, size, mode, ownership, and timestamps. These are point-in-time observations, not authorization or proof that later reads remain unchanged. Consumers such as Git index adapters must validate their own content and timestamp invariants. The reader does not follow leaf symbolic links.
 
+All input paths must be absolute and valid before native availability is checked. On platforms other than macOS, `auto` and `off` can return one `undefined` per path without the addon, matching native's unsupported result. On macOS, `off` or an unavailable addon still rejects with `helper-unavailable`; JavaScript cannot supply APFS clone IDs. Explicit `require` mode rejects an unavailable addon on every platform, including for an empty batch. Errors from a loaded native helper remain terminal.
+
 ## Borrowed FileHandle transfers
 
 `copyFileHandle` from `@openclaw/fs-safe/advanced` copies bytes between two
@@ -137,6 +141,37 @@ descriptor inspection does not prove that the source remained unchanged while
 copying. Keep existing source-fingerprint and publication checks around the
 transfer when building snapshot operations.
 
+### Synchronous descriptor transfers
+
+`copyFileDescriptorSync(sourceFd, targetFd, options?)` provides the same
+zero-origin byte transfer for borrowed numeric descriptors. It shares
+`CopyFileHandleOptions` and returns the copied byte count synchronously:
+
+```ts
+import { copyFileDescriptorSync } from "@openclaw/fs-safe/advanced";
+
+const bytes = copyFileDescriptorSync(sourceFd, targetFd, {
+  maxBytes: expectedSize,
+  assertBeforeMutation: assertSnapshotOwnerCurrent,
+});
+```
+
+The same regular-file and exact-identity admission, byte limits, short-I/O
+handling, cursor preservation, and caller-owned cleanup apply. The target must
+be opened without append mode, and both descriptors must remain open and free
+of concurrent I/O, including inside callbacks. Neither helper makes a mutable
+source into a consistent snapshot or truncates an existing destination suffix.
+
+The synchronous helper snapshots the four options once and invokes both
+callbacks with no receiver (`this` is `undefined` in strict callbacks).
+`onChunk` receives a borrowed view that must be consumed immediately without
+retaining or mutating it. Both callbacks must finish synchronously; thenables
+throw `TypeError` before the current write. Cancellation is cooperative: a
+pre-aborted signal or an abort triggered by a callback stops the transfer before
+the next write. Timers cannot interrupt synchronous filesystem calls while the
+event loop is blocked. Authority runs before every partial write; an abort
+triggered by that assertion prevents the same write.
+
 ## Ownership and cancellation
 
 These are low-level operations on caller-owned absolute paths, not Root-relative methods. The source and destination parent must be real directories. The library pins their descriptors and verifies their identities; it does not establish the caller's authorization to use them. Keep the source immutable for the operation, including writes through other aliases, and keep the destination namespace under the caller's control. Literal symlinks in the cloned contents are preserved rather than followed or sanitized.
@@ -145,6 +180,8 @@ An already aborted signal prevents dispatch. In-flight cancellation stops cancel
 
 Completion is not a crash-durability guarantee. The API is suitable for reconstructible templates and checkouts; it does not sync every file or replace application-level publication and recovery rules.
 
+A close-only rejection reports descriptor settlement, not whether bytes reached stable storage. The destination can already be complete when a close fails, just as other failed or cancelled calls can leave caller-owned output. Inspect or remove that output only after the copying promise settles and under the same source and destination authority assumptions.
+
 Byte copying retains fractional file and directory access/modification timestamps to the precision supported by Node's timestamp APIs and the destination filesystem. This includes dates before 1970 on Unix. On Windows, [Node's unsigned stat seconds](https://github.com/nodejs/node/blob/v26.8.2/src/node_file-inl.h#L93-L104) can report pre-1970 timestamps as dates about 136 years later; byte copying inherits that upstream limitation.
 
 ## Platform tests and benchmarks