@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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,10 +28,14 @@ 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. |
+| `resolvePathPrefixSync`, `ResolvedPathPrefix` | [path-prefix.md](path-prefix.md) | Follow physical symlink targets and return a canonical existing prefix with the raw missing suffix; propagate uncertain resolution failures. |
+| `probePathCaseInsensitiveSync`, `ProbePathCaseOptions` | [path-case.md](path-case.md) | Observe local ASCII-case behavior with explicit read-only mode and owned temporary-probe cleanup. |
+| `probePathSuffixAliasesSync`, `ProbePathSuffixAliasesOptions` | [path-suffix-aliases.md](path-suffix-aliases.md) | Observe selected missing suffix aliases with bounded temporary directory probes; ambiguity, dynamic budget exhaustion, or incomplete cleanup returns `undefined`. |
 
 `ensureDirectoryWithinRoot({ rootDir, requestedPath, scopeLabel, defaultDirName?, mode? })`
 returns `{ ok: true, path }` or `{ ok: false, error: string, diagnostic?: FsSafeError }`.
@@ -65,13 +69,25 @@ 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. |
-| `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `rejectSymlinks: false` for explicit in-root following. |
+| `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. |
 | `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. |
 | `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |
 
+`pathExists()` and `pathExistsSync()` intentionally retain ordinary `stat`
+semantics and are not caller-path admission boundaries. Validate an untrusted
+path with the boundary appropriate to the operation before using these
+existence probes.
+
 `openRootFile()` and `openRootFileSync()` compare exact bigint identities before
 open, on the retained descriptor, and on the current resolved path. Their `stat`
 receipts remain numeric. Custom `ioFs` adapters must honor `{ bigint: true }` for
@@ -79,6 +95,41 @@ receipts remain numeric. Custom `ioFs` adapters must honor `{ bigint: true }` fo
 Windows identities receive one re-inspection without reopening, then fail
 validation if still unknown.
 
+On Windows, these existing-object readers retain their historical support for a
+leading drive-relative spelling such as `C:existing.txt`: it is anchored to that
+drive before confinement and namespace admission. Additional colons remain in
+the anchored spelling, so alternate-stream and directory-index aliases are still
+rejected before opening.
+
+These adapters also capture the canonical root directory's exact bigint identity
+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 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.
+This is an operation-local detection fence, not atomic confinement against a peer
+that can keep racing pathname bindings.
+
+The explicit `symlinks` policy takes precedence over the existing `rejectSymlinks`
+boolean. Without `symlinks`, `rejectSymlinks: false` retains its existing behavior
+of following contained links, and omission still rejects all symlink components.
+
+The bounded descriptor helpers cap their initial speculative allocation at
+16 MiB plus the overflow-probe byte, even when a file reports a much larger
+size. Regular files up to that size can return from one read without copying
+chunks; larger files and short reads continue incrementally under the same
+byte limit. Continuation buffers grow only after filling with actual bytes,
+up to the byte budget plus its probe; file-size hints cannot force that growth.
+Unknown-size inputs start with at most 64 KiB. This avoids per-chunk copies and
+a final concatenation when a file exceeds the initial allocation.
+Regular files that report a size of zero, such as virtual files, continue through
+positive short reads until actual EOF or byte-limit overflow.
+
 The bounded descriptor helpers start at the descriptor's current offset and
 leave ownership with the caller. They are intended for the second half of a
 safe read: first open and validate the path using the boundary appropriate to
@@ -104,6 +155,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 |
@@ -115,9 +231,9 @@ component is followed by another segment, both helpers throw
 
 | Export | Page | Notes |
 |---|---|---|
-| `safeDirName`, `safePathSegmentHashed`, `resolveSafeInstallDir`, `assertCanonicalPathWithinBase` | [install-path.md](install-path.md) | Build install-target directories from caller-supplied identifiers. |
+| `safeDirName`, `safePathSegmentHashed`, `safePathSegmentHashedV2`, `resolveSafeInstallDir`, `assertCanonicalPathWithinBase` | [install-path.md](install-path.md) | Build install-target directories; use V2 for untrusted identifier mappings. |
 | `sanitizeUntrustedFileName` | [filename.md](filename.md) | Coerce an untrusted string into a safe filename. |
-| `resolveHomeRelativePath` | – | Expand `~`-prefixed paths. |
+| `resolveHomeRelativePath` | – | Expand a leading `~` before resolving `.` and `..`; tildes inside relative paths stay literal. |
 
 ### Temp targets and sibling-temp writes
 
@@ -139,7 +255,7 @@ component is followed by another segment, both helpers throw
 | Export | Page | Notes |
 |---|---|---|
 | `createAsyncLock` | – | In-process async lock (separate from cross-process file locks). |
-| `withTimeout` | [timing.md](timing.md) | Wrap a promise with a timeout that raises `FsSafeError("timeout")`. |
+| `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. |
 
 ## Stability
@@ -149,5 +265,5 @@ Items in this surface can change shape between minor versions if a higher-level
 ## Related pages
 
 - [Root API](root.md) — built on top of these helpers.
-- [Errors](errors.md) — every helper here surfaces failures as `FsSafeError`.
+- [Errors](errors.md) — shared filesystem error codes; generic timing helpers retain their documented error types.
 - [Security model](security-model.md) — what the underlying boundary checks promise.

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,19 +59,57 @@ 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
   tarGzip?: boolean;            // when archive is .tar.gz/.tgz
   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";
 };
 ```
 
+`durable` defaults to `false`. Private staging never fsyncs, and publication copies
+defer opted-in durability until the complete merge succeeds. With `durable: true`, the final pass syncs each
+published file once (at most eight concurrently), then each published directory
+once, deepest first, and finally the destination directory. All work stays inside
+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
+pass, with a descriptor pinned before chmod for syncing restrictive directories.
+Existing inaccessible directories are never widened; an existing search-only
+directory must become readable in its final mode if no readable sync descriptor
+can be acquired before chmod.
+
+The default suits extractions into temporary or reconstructible locations.
+It skips all file and directory syncs while preserving atomic file publication,
+mode enforcement, identity checks, and containment checks. Successful `durable: true`
+extraction syncs file contents and directory entries before returning; failures
+can leave a partially published tree as described below.
+
+For a crash-safe install workflow, extract with the default into a scratch
+directory, then apply the caller's durability policy: sync the staged files and
+directories before publishing with [`replaceDirectoryAtomic`](atomic.md#replacedirectoryatomic),
+and sync the affected parent directories afterward. The directory swap alone
+does not sync the staged tree. Alternatively, pass `durable: true` when extracted
+files must be on stable storage before the extraction call returns, subject to
+the platform's flushing guarantees. A plain fsync on macOS does not flush the
+drive cache.
+
 `entryModes` defaults to `"clamp"`: directories become `0o755`; files become
 `0o644`, or `0o755` when the archived owner-execute bit is set. `"preserve"`
 keeps archived read/write/execute bits. Both policies strip setuid, setgid, and
@@ -64,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.
@@ -77,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.
 
@@ -93,7 +157,18 @@ 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
+small inputs and capped by the archive byte limit plus one overflow-probe byte.
+Each read stays within the remaining budget plus that probe; deadline checks
+surround reads, and short writes finish before the buffer is reused.
 
 Native extraction is deliberately split into two phases. Rust first reports an
 entry manifest without creating paths. TypeScript validates paths, applies
@@ -102,7 +177,50 @@ accepted-entry plan back to Rust. Rust owns raw-stream admission, decompression,
 and fd-relative `mkdirBeneath`/exclusive-open writes. This keeps filter policy identical
 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 separator and dot-component equivalence is allowed only after validation. Ordinary legacy filename decoding remains backend-selected.
+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
+must agree with this kind, physical index, size, known path, and UNIX-creator mode
+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 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
+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
@@ -114,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
@@ -189,23 +310,46 @@ omitted and do not consume output payload budgets. The shared core admits these
 record and are then cleared; local PAX on unsupported types and GNU sparse
 `S` records retain their existing fail-closed format policy.
 
-If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). Archive inputs must remain regular files from preview through descriptor admission; POSIX opens are no-follow and nonblocking, so a FIFO swap cannot stall before deadline checks resume. A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline. Non-mutating work rejects promptly when the budget expires. If a live destination mutation is already in flight, rejection waits only for that mutation and any rollback to finish; no later destination mutation can begin.
+If `kind` is omitted, the helper calls `resolveArchiveKind(archivePath)` and throws if the extension is not recognized. Pass `kind` explicitly when the archive name doesn't carry the type (e.g. content-addressed names). Archive inputs must remain regular files from preview through descriptor admission; POSIX opens are no-follow and nonblocking, so a FIFO swap cannot stall before deadline checks resume. On Windows, archive source and destination filesystem paths reject NTFS alternate-stream and directory-index namespace spellings such as `file:stream` and `dir::$INDEX_ALLOCATION`; ordinary colon-bearing POSIX names remain valid. A positive finite `timeoutMs` is a wall-clock budget; zero, negative, `NaN`, and infinity disable the deadline. Non-mutating work rejects promptly when the budget expires. If a live destination mutation is already in flight, rejection waits only for that mutation and any rollback to finish; no later destination mutation can begin.
+
+Extraction captures the destination's lossless filesystem identity before any
+entry filter runs and retains that capability through final publication. If a
+filter or concurrent actor renames or replaces the destination, extraction
+rejects with `destination-symlink-traversal` before publishing into the
+replacement. This check uses bigint device and inode identities so large native
+identifiers cannot compare equal after JavaScript number rounding.
 
 The destination merge is nontransactional: each file is published atomically,
 but completed files and directories can remain when a later copy, post-copy
 check, mode application, or deadline fails. This also applies to
-`mergeExtractedTreeIntoDestination()`. Guarded `Root.copyIn()` owns cleanup for
-its operation; the archive merge does not unlink the current destination name
-on error because it has no publication receipt proving ownership. 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
+`mergeExtractedTreeIntoDestination()`. Guarded `Root.copyIn()` owns unpublished
+stage cleanup and preserves completed publications. The archive merge never
+acquires rollback authority over the current destination name. Replacing a
+source path after publication rejects the merge with `path-mismatch` while
+preserving the admitted bytes already published, or any later destination edit.
+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.
-New directories whose postorder finalization was never reached can retain their
+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 final chmod sweep or roll back the archive. The public merge
+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()`.
 
 ### Limits
 
@@ -267,13 +411,20 @@ codes remain `"destination-not-directory"`, `"destination-symlink"`, and
 - **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget for non-mutating work. Extraction is aborted on overrun; if a destination mutation is already in flight, that mutation and rollback are joined before rejection so archive-controlled publication cannot continue afterward.
 - **Metadata bombs:** a streaming pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before buffering their bodies. It understands octal and base-256 fixed sizes and validates bounded local PAX bodies before using their size overrides for member framing. Original archive bytes remain unchanged.
 
+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
@@ -318,12 +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. 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
@@ -420,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`
 
@@ -486,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
 ```
 
@@ -494,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";
@@ -522,9 +686,11 @@ await extractArchive({
 ## `readArchiveEntry`
 
 `readArchiveEntry(archivePath, entryPath, { maxBytes, kind? })` reads one
-regular-file entry into a bounded `Buffer` without extracting a tree. It pins
-and privately stages the archive input, rejects link, directory, and duplicate
-entries, verifies ZIP CRC and declared size,
+regular-file entry into a bounded `Buffer` without extracting a tree. It reads
+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
@@ -537,7 +703,26 @@ 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.
+The native ZIP reader retains the private allocation and parsed directory across worker-thread
+inspection and reading without an extra archive-byte copy.
+Decompression still allocates its bounded output; Node receives that native
+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 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.
 
 Requested paths and effective member names use extraction's canonical pre-strip
 identity: backslashes become `/`, and repeated separators and `.` components