@openclaw/fs-safe 0.15.0 → 0.17.0

package/docs/advanced.md

@@ -19,7 +19,7 @@ import {
 
 ## What lives here
 
-The exports group into a handful of themes. Each documented helper has its own page; everything else is reference-only and tracked here.
+The exports group into a handful of themes. Documented helpers link to their contract below or a dedicated page; everything else is reference-only and tracked here.
 
 ### Path scopes and root paths
 
@@ -28,7 +28,8 @@ The exports group into a handful of themes. Each documented helper has its own p
 | `pathScope`, `PathScope`, `PathScopeOptions`, `PathScopeResolveOptions` | [path-scope.md](path-scope.md) | Absolute-path boundary helper with `Result`-shaped returns. |
 | `ensureDirectoryWithinRoot` | [path-scope.md](path-scope.md#ensuredir-rel-options) | Create a directory while enforcing the root boundary; same result contract as `pathScope().ensureDir()`. |
 | `resolvePathWithinRoot`, `resolvePathsWithinRoot` | – | Resolve one or many relative paths against a trusted root. |
-| `resolveExistingPathsWithinRoot`, `resolveStrictExistingPathsWithinRoot` | – | Same, but require the targets to exist. |
+| `resolveExistingPathsWithinRoot` | – | Validate existing regular files inside the root, while allowing missing paths. |
+| `resolveStrictExistingPathsWithinRoot` | – | Require every target to exist as a regular non-symlink file inside the root. |
 | `resolveWritablePathWithinRoot` | – | Resolve a write target inside a root. |
 | `resolveRootPath`, `resolveRootPathSync`, `ResolvedRootPath`, `ROOT_PATH_ALIAS_POLICIES`, `RootPathAliasPolicy` | – | Resolve a root directory honoring alias policy. |
 | `resolvePathViaExistingAncestorSync` | – | Walk to an existing ancestor for paths whose tail does not yet exist. |
@@ -68,8 +69,11 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | Export | Page | Notes |
 |---|---|---|
 | `readFileDescriptorBounded`, `readFileDescriptorBoundedSync`, `readFileHandleBounded` | – | Incremental whole-file reads for already-open descriptors/handles. They consume at most `maxBytes + 1`, do not close the input, and throw `FsSafeError("too-large")` on overflow. |
+| `createDirectory`, `createDirectorySync`, `createFileSync` | [Exclusive leaf creation](creation.md) | Create one exclusive entry under an existing trusted parent, optionally with private permissions; file creation returns an owned disposable descriptor. |
 | `readFileWindowFully`, `readFileWindowFullySync`, `ReadFileWindowOptions` | [positional-read.md](positional-read.md) | Fill a caller-owned buffer at an explicit file position, completing short reads and returning the EOF count without moving or closing the descriptor. |
+| `writeFileWindowFully`, `WriteFileWindowOptions` | [Borrowed-handle writes](#borrowed-handle-writes) | Write all supplied bytes at an explicit position or the current cursor, completing short writes with cancellation and per-write authority checks. |
 | `copyFileHandle`, `copyFileDescriptorSync`, `CopyFileHandleOptions` | [copy.md](copy.md#borrowed-filehandle-transfers) | Copy caller-owned regular files through async handles or sync descriptors from position zero with byte limits and synchronous callbacks; preserves cursors and leaves publication and cleanup to the caller. |
+| `sameFileContentsSync`, `SameFileContentsOptions` | [Exact file comparison](file-contents.md) | Compare borrowed regular-file descriptors byte for byte through EOF with bounded memory and an optional per-file byte limit, preserving both cursors and lifetimes. |
 | `overwriteFileHandle`, `OverwriteFileHandleOptions` | [in-place-write.md](in-place-write.md) | Overwrite a borrowed read/write handle with prefix-only preparation and best-effort rollback; preserves its inode, cursor, and caller-owned lifetime. |
 | `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `symlinks: "follow-parents-within-root"` for contained parent aliases or `"follow-within-root"` for final links too. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
@@ -149,6 +153,71 @@ component is followed by another segment, both helpers throw
 `FsSafeError("not-file")` before the platform can expose that state as POSIX
 `ENOTDIR` or Windows `ENOENT`.
 
+#### Borrowed-handle writes
+
+Use `writeFileWindowFully()` when you already own a writable file handle and
+need to complete a byte-window write, including positive short writes.
+
+```ts
+import { root } from "@openclaw/fs-safe";
+import { writeFileWindowFully } from "@openclaw/fs-safe/advanced";
+
+const workspace = await root("/srv/workspace");
+await using opened = await workspace.openWritable("record.bin", { writeMode: "update" });
+await writeFileWindowFully(opened.handle, Buffer.from([1, 2, 3]), 16);
+```
+
+```ts
+type WriteFileWindowOptions = {
+  signal?: AbortSignal;
+  assertBeforeMutation?: () => void;
+};
+
+function writeFileWindowFully(
+  handle: import("node:fs/promises").FileHandle,
+  bytes: Uint8Array,
+  position: number | null,
+  options?: WriteFileWindowOptions,
+): Promise<void>;
+```
+
+A numeric `position` writes at that offset without moving the handle's cursor.
+It and the exclusive window end (`position + bytes.byteLength`) must be
+non-negative safe integers; invalid ranges throw `RangeError` before mutation.
+Bounds come from the intrinsic byte view, ignoring shadowed metadata properties.
+Pass `null` to write at and advance the current cursor. Each syscall writes at
+most 512 KiB. A write that makes no progress throws
+`FsSafeError("helper-failed")`; filesystem errors propagate unchanged.
+Empty input still validates the range and checks cancellation, but performs no
+I/O and does not call `assertBeforeMutation`.
+
+The caller must supply a writable regular-file handle, opened **without append
+mode** for numeric positions. Some operating systems ignore positioned-write
+offsets on append handles, and this helper does not inspect file type or open
+flags. Opening, path admission, identity checks, and closing remain the caller's
+responsibility. Keep the handle open and the borrowed bytes unchanged, attached,
+and accessible until the promise settles; avoid concurrent I/O when it can change
+the intended contents or shared cursor. The helper does not acquire a lock.
+
+`assertBeforeMutation` runs synchronously immediately before every write,
+including short-write retries. A thrown value propagates unchanged; a Promise or
+thenable return rejects with `TypeError` before that write. The callback must not
+modify the payload or handle. It does not run as a final completion check; the
+caller owns any authority check before later publication or other mutations.
+
+`signal` is checked at admission, before and after each authority callback, and
+after each pending write settles. Cancellation waits for an in-flight write and
+then rejects with the signal's reason without starting another syscall. If that
+write fails, its filesystem error or zero-progress failure takes precedence over cancellation. Already
+written bytes remain changed; there is no rollback or hidden write after the
+promise settles.
+
+The helper neither truncates an existing suffix nor changes permissions,
+synchronizes, or closes the handle. Callers retain those responsibilities and
+any wider transaction policy. For complete replacement with best-effort
+rollback, use [`overwriteFileHandle()`](in-place-write.md); for root-bounded
+atomic replacement, use [`Root.write()`](writing.md).
+
 ### Local roots and file URLs
 
 | Export | Page | Notes |

package/docs/archive.md

@@ -3,11 +3,27 @@
 `@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`.
+
+The shared TAR parser reuses the already-validated owned path for ordinary
+members. Original header names and USTAR prefixes still undergo validation
+even when PAX or GNU metadata supplies an override; effective override paths
+retain their separate checks. Empty USTAR prefixes retain field decoding and
+padding checks; path validation applies to nonempty prefixes. Joining an
+admitted prefix and name with a separator preserves their checked components,
+so the parser does not repeat the same component validation on the joined path.
+
+`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";
@@ -23,6 +39,7 @@ await extractArchive({
   timeoutMs: 15_000,                  // hard budget; active destination mutation is joined
   stripComponents: 0,                 // tar-style strip-leading-dirs
   entryModes: "clamp",                // default; use "preserve" for archive rwx bits
+  entryUmask: 0,                      // default; remove these bits from final modes
   entryFilter: ({ path, kind, size }) => "extract",
   onFiltered: "reject-archive",        // default; opt into "skip-entry" explicitly
   limits: {
@@ -42,7 +59,7 @@ await extractArchive({
 type ExtractArchiveOptions = {
   archivePath: string;          // absolute path to the archive
   destDir: string;              // absolute destination directory; must already exist
-  timeoutMs: number;            // positive wall-clock budget; <= 0/non-finite disables it
+  timeoutMs: number;            // positive elapsed-time budget; <= 0/non-finite disables it
   durable?: boolean;            // false; opt into syncing published files and directories before completion
   kind?: ArchiveKind;           // "zip" | "tar" | "tar-zstd" | "tar-bzip2"
   stripComponents?: number;     // strip N leading dirs from entry paths
@@ -50,6 +67,7 @@ type ExtractArchiveOptions = {
   limits?: ArchiveExtractLimits;
   logger?: ArchiveLogger;       // { info?, warn? }
   entryModes?: "clamp" | "preserve";
+  entryUmask?: number;          // integer 0..0o777; defaults to 0
   entryFilter?: (entry: { path: string; kind: ArchiveEntryKind; size: number }) =>
     "extract" | "skip";
   onFiltered?: "reject-archive" | "skip-entry";
@@ -63,6 +81,12 @@ once, deepest first, and finally the destination directory. All work stays insid
 the extraction deadline; active syncs are joined before rejection. File sync
 failures use the same error surface as `Root.copyIn()`; directory I/O failures
 also reject, with the existing platform limitations on directory flushing.
+
+Deadline checks use a monotonic clock, including before queued mutations start
+and before reporting success. Synchronous caller code can delay the timer, but
+cannot permit the next operation after the budget expires. This does not
+interrupt a callback halfway through execution or replace its own thrown error;
+active destination mutations are still joined before timeout rejection.
 Files whose final mode prevents reading, including `0o000` and write-only files,
 sync once through the copy's retained descriptor during publication. Permissions
 are never widened to reopen them. Directory modes are finalized after the file
@@ -95,6 +119,15 @@ including a mode containing only stripped special bits, stays zero under
 directories; ZIP UNIX creator records with zero attributes are explicit zero,
 while non-UNIX ZIP records use the absent-metadata defaults.
 
+`entryUmask` removes permission bits after the selected mode policy: final modes
+are the policy result `& ~entryUmask`. It applies to files, explicit directories,
+and implicit parent directories, including existing destination directories.
+The destination root and private staging modes are unchanged. The default `0`
+preserves existing behavior; invalid masks reject before extraction begins.
+fs-safe neither reads nor changes the process umask. Pass
+`entryUmask: process.umask()` explicitly when that is the caller's policy.
+Windows retains the POSIX-mode limitations described below.
+
 TAR mode fields containing only NUL/ASCII-space padding use absent defaults.
 Both backends recognize GNU binary modes, including signed values,
 within JavaScript's safe-integer range before masking permission bits.
@@ -108,7 +141,7 @@ stay `0o600` and directories `0o700` until publication. Files receive their fina
 mode through the guarded copy's owned writer descriptor. Directories are pinned
 before descending and finalized after their children, including empty and
 restrictive directories. Explicit accepted directory modes win regardless of
-archive order; implicit parents receive `0o755`. Existing destination directories
+archive order; implicit parents receive `0o755 & ~entryUmask`. Existing destination directories
 also receive the requested final mode. They are never temporarily widened to
 allow child writes; insufficient write/search access still rejects.
 
@@ -146,6 +179,13 @@ between native and JavaScript paths rather than reimplementing it in Rust.
 
 ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless internal separator and dot-component equivalence is allowed only after validation; every raw and Unicode interpretation must also agree on whether its name ends in `/` or `\`. Ordinary legacy filename decoding remains backend-selected. Native ZIP extraction groups nearby metadata reads into at most two 4 KiB read-ahead buffers per admission pass; larger records retain separately bounded reads. Buffered record views remain stable across eviction, and cached work periodically yields for deadline checks.
 
+ZIP end-record admission searches the bounded comment window for signatures
+while retaining complete comment-length and ambiguity checks. Dense signature
+sequences fall back to the bounded byte scan.
+The separate `readZipCentralDirectoryEntryCount(buffer)` hint uses bounded
+reverse searches for comments and retains its latest-valid-record selection;
+it does not replace strict archive admission.
+
 ZIP admission establishes each entry's kind before callbacks: a high-word UNIX
 symlink type takes precedence regardless of creator, followed by the DOS directory
 bit, the exact UNIX directory type, or a terminal slash/backslash. Native manifests
@@ -177,6 +217,10 @@ decoded validation. Unicode Path admission is shared only when both the raw name
 and the complete Unicode fields match; different fields still verify their own
 CRC and interpretation. Shared backing memory is checked independently. Decoded
 name validation is not reused across entries or archives.
+UTF-8-flagged ASCII names in nonshared backing memory reuse their raw-path
+validation, and an identical decoded spelling reuses its canonical key. Shared
+name bytes still undergo independent decoding and validation; Unicode Path
+fields retain their own CRC and interpretation checks.
 
 `stripComponents` removes leading nonempty, non-`.` path components after
 normalizing separators. For example, `./pkg/hello.txt` with
@@ -188,12 +232,15 @@ 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
 spelling are preserved. Local PAX `path`, GNU long-name, and supported ZIP
 Unicode Path names use the same canonicalization.
+Callbacks follow physical archive order, including ZIP names that look like
+integer object keys. The public ZIP loader's `files` object retains ordinary
+JavaScript object enumeration and mutation behavior.
 
 Raw paths undergo traversal, absolute/drive-path, and NUL validation **before**
 canonicalization; normalization cannot turn an unsafe path into an accepted
@@ -368,14 +415,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
@@ -420,14 +469,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
@@ -524,7 +583,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`
 
@@ -590,7 +649,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
 ```
 
@@ -598,17 +657,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";
@@ -627,8 +687,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
@@ -641,7 +703,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.
@@ -652,12 +716,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

@@ -16,7 +16,7 @@ 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.
 
@@ -92,10 +92,13 @@ 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
+JavaScript permits `beforeRename` callbacks and filesystem adapters 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
+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
@@ -150,6 +153,14 @@ 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.
 
+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.
+
 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
@@ -349,7 +360,10 @@ 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`. Directory manifests retain an exact bigint device/inode receipt from
+`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
@@ -366,6 +380,11 @@ 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
 
@@ -404,6 +423,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

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.
@@ -117,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.

package/docs/copy.md

@@ -78,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