@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/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,15 +69,19 @@ 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. |
-| `copyFileHandle`, `CopyFileHandleOptions` | [copy.md](copy.md#borrowed-filehandle-transfers) | Copy caller-owned regular-file handles from position zero with byte limits, settled cancellation, and a synchronous source observer; preserves cursors and leaves publication and cleanup to the caller. |
+| `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. |
+| `retainFileInDirectory`, `RetainedFile`, related receipt/result types | [Retained Windows files](retained-file.md) | Existing-file native handle custody and explicit removal; local NTFS, producer authority required, no persistence guarantee. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `readDirectoryIdentity`, `assertDirectoryIdentitySync`, `DirectoryIdentity` | [directory-identity.md](directory-identity.md) | Observe exact bigint directory identity and synchronously check a caller-selected path, optionally retaining its canonical path. |
 | `pathExists`, `pathExistsSync` | – | Boolean existence check that does not throw on `ENOENT`. |
-| `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks. |
+| `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks, inspecting raw segments before `..` normalization. A `..` may undo an inspected real directory, but cannot leave the root or undo an allowed root-child symlink. Raw paths outside the root that normalize inside are rejected. |
 | `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |
 
 `pathExists()` and `pathExistsSync()` intentionally retain ordinary `stat`
@@ -102,7 +107,9 @@ before component traversal. Immediately before transferring descriptor ownership
 they check that root, freshly canonicalize the consumed pathname, admit the fresh
 spelling under the captured root, compare a no-follow canonical-leaf observation
 with the retained descriptor, and check the root again. Boundary or identity drift
-is a validation failure and the descriptor is closed. A custom `ioFs` supplies
+is a validation failure and triggers one descriptor-close attempt. If cleanup also
+fails, the selected admission failure result is preserved. Successful opens transfer
+descriptor ownership to the caller. A custom `ioFs` supplies
 these observations; the built-in adapter uses fs-safe's native realpath wrapper.
 On Windows, the built-in adapter binds native root spelling before traversal,
 including supplied `rootRealPath`, and returns that spelling in its root receipt.
@@ -149,6 +156,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 |
@@ -169,6 +241,7 @@ component is followed by another segment, both helpers throw
 | Export | Page | Notes |
 |---|---|---|
 | `stageFileInDirectory`, `StagedFile`, `StagedFileReceipt`, `PublishedFileReceipt`, `StagedFilePublication`, `StagedFileCleanupReceipt`, `StagedFileFailureDetails` | [staged-file.md](staged-file.md) | Native-required Linux/macOS lifecycle retaining the original directory for abort cleanup. |
+| `retainSymlinkInDirectory`, `StagedSymlink`, `StagedSymlinkExpected`, `StagedSymlinkReceipt`, `PublishedSymlinkReceipt`, `StagedSymlinkPublication`, `StagedSymlinkRemoval`, `StagedSymlinkCleanupReceipt`, `StagedSymlinkFailureDetails` | [staged-symlink.md](staged-symlink.md) | Native-required retained symlink identity, no-replace publication and explicit recovery; never same-target ownership adoption. |
 | `tempFile`, `withTempFile`, `TempFile`, `buildRandomTempFilePath`, `sanitizeTempFileName` | [temp.md](temp.md) | One-file temp primitive; prefer `tempWorkspace` from `@openclaw/fs-safe/temp` for the stable surface. |
 | `writeSiblingTempFile`, `writeViaSiblingTempPath`, `WriteSiblingTempFileOptions`, `WriteSiblingTempFileResult` | – | Callback-produced file staging: verified sibling publication or private-workspace copy through a root. |
 
@@ -185,7 +258,7 @@ component is followed by another segment, both helpers throw
 |---|---|---|
 | `createAsyncLock` | – | In-process async lock (separate from cross-process file locks). |
 | `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `Error` by default, or an error supplied by `createError`. |
-| `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. |
+| `movePathToTrash`, `MovePathToTrashOptions` | – | Best-effort move to the platform trash. Allowed roots constrain the real parent of the moved entry, including symlinks; the referent is not moved. Parent identity is rechecked before mutation. |
 
 ## Stability
 

package/node_modules/@openclaw/fs-safe/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.
 
@@ -124,7 +157,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
@@ -141,6 +179,19 @@ 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 preflight and bounded reads apply extraction's case-insensitive NFC collision
+policy to the complete archive, including entries that extraction would strip
+or skip. Known UTF-8 and Unicode Path names are checked during physical admission;
+legacy names retain backend-selected decoding and undergo the same collision
+check before callbacks or selected bytes are returned.
+
+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
@@ -148,20 +199,42 @@ 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.
+Extraction and bounded reads retain the admitted CRC and size independently of
+mutable decoder objects, so later decoder changes cannot redefine the expected
+payload integrity. Public preflight archives retain ordinary JSZip mutation
+and entry-reading behavior.
+Portable bounded reads select the admitted canonical name and reject a selected
+decoder entry that no longer belongs to that archive and name before reading its
+payload. Extraction retains the admitted names and physical order independently
+of later changes to the decoder's public `files` object.
 
 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
 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
@@ -173,12 +246,17 @@ 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.
+A leading `~` is a literal archive entry name and is never expanded to the
+user's home directory during extraction, publication, or durability checks.
+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
@@ -269,11 +347,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 +431,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 +485,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 +599,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 +665,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 +673,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 +703,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 +719,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 +732,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.