@openclaw/openshell-sandbox 2026.9.4 → 2026.9.5

package/node_modules/@openclaw/fs-safe/dist/windows-path-alias.js

@@ -0,0 +1,153 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+const COLON = 0x3a;
+const FORWARD_SLASH = 0x2f;
+const BACKSLASH = 0x5c;
+const DOT = 0x2e;
+const QUESTION_MARK = 0x3f;
+function isAsciiLetter(code) {
+    return (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a);
+}
+function isSeparator(code) {
+    return code === FORWARD_SLASH || code === BACKSLASH;
+}
+function rootedDriveColonIndex(value) {
+    if (value.length >= 3 &&
+        isAsciiLetter(value.charCodeAt(0)) &&
+        value.charCodeAt(1) === COLON &&
+        isSeparator(value.charCodeAt(2))) {
+        return 1;
+    }
+    if (value.length >= 7 &&
+        isSeparator(value.charCodeAt(0)) &&
+        isSeparator(value.charCodeAt(1)) &&
+        (value.charCodeAt(2) === QUESTION_MARK || value.charCodeAt(2) === DOT) &&
+        isSeparator(value.charCodeAt(3)) &&
+        isAsciiLetter(value.charCodeAt(4)) &&
+        value.charCodeAt(5) === COLON &&
+        isSeparator(value.charCodeAt(6))) {
+        return 5;
+    }
+    return -1;
+}
+function isBareWindowsNamespaceDrive(value) {
+    return (value.length === 6 &&
+        isSeparator(value.charCodeAt(0)) &&
+        isSeparator(value.charCodeAt(1)) &&
+        (value.charCodeAt(2) === QUESTION_MARK || value.charCodeAt(2) === DOT) &&
+        isSeparator(value.charCodeAt(3)) &&
+        isAsciiLetter(value.charCodeAt(4)) &&
+        value.charCodeAt(5) === COLON);
+}
+/**
+ * Capture an ordinary Windows drive-relative path without normalizing its raw
+ * suffix. This is only for public APIs whose existing contract accepts such
+ * paths; callers must still run namespace-alias admission on the result.
+ */
+export function anchorWindowsDriveRelativePath(value) {
+    if (process.platform !== "win32" || path.isAbsolute(value))
+        return value;
+    if (value.length < 2 ||
+        !isAsciiLetter(value.charCodeAt(0)) ||
+        value.charCodeAt(1) !== COLON) {
+        return value;
+    }
+    const drive = value.slice(0, 2);
+    const base = path.resolve(drive);
+    return `${base}${path.sep}${value.slice(2)}`;
+}
+/**
+ * Resolve a path without letting Node erase the separator from an exact
+ * extended-length drive root such as `\\?\C:\`. Bare `\\?\C:` input remains
+ * unchanged so the surrounding alias admission rejects it.
+ */
+export function resolvePathPreservingWindowsRoot(value) {
+    if (value.length === 7 &&
+        process.platform === "win32" &&
+        rootedDriveColonIndex(value) === 5) {
+        return value.includes("/") ? value.replaceAll("/", "\\") : value;
+    }
+    const resolved = path.resolve(value);
+    return repairResolvedWindowsRoot(value, resolved);
+}
+/**
+ * Preserve a namespaced drive root after a caller has already resolved the
+ * input. This lets admission fast paths keep exactly one live path.resolve
+ * call while retaining the same root-repair behavior as the general helper.
+ */
+export function repairResolvedWindowsRoot(value, resolved) {
+    if (resolved.length === 6 &&
+        process.platform === "win32" &&
+        isBareWindowsNamespaceDrive(resolved) &&
+        !hasWindowsPathAlias(value, "filesystem")) {
+        return `${resolved}\\`;
+    }
+    return resolved;
+}
+/**
+ * Resolve path segments against a base while preserving a namespaced drive
+ * root when Node normalizes a legitimate rooted input back to that root.
+ * Raw bare namespace drives stay bare so admission checks still reject them.
+ */
+export function resolvePathFromBasePreservingWindowsRoot(base, ...segments) {
+    const resolved = path.resolve(base, ...segments);
+    if (resolved.length !== 6 ||
+        process.platform !== "win32" ||
+        !isBareWindowsNamespaceDrive(resolved)) {
+        return resolved;
+    }
+    if (hasWindowsPathAlias(base, "filesystem") ||
+        segments.some((segment) => hasWindowsPathAlias(segment, "filesystem"))) {
+        return resolved;
+    }
+    return `${resolved}\\`;
+}
+/**
+ * Adapt an admitted namespaced drive root for Node's Windows filesystem layer.
+ * Node removes the root separator from these paths during filesystem dispatch,
+ * so use the equivalent ordinary drive root for the operation. This is not an
+ * admission check: callers must validate attacker-controlled input first.
+ */
+export function pathForWindowsFilesystem(value) {
+    if (process.platform !== "win32" ||
+        rootedDriveColonIndex(value) !== 5) {
+        return value;
+    }
+    if (value.length === 7) {
+        return `${value[4]}:\\`;
+    }
+    const resolved = path.resolve(value);
+    if (isBareWindowsNamespaceDrive(resolved) &&
+        !hasWindowsPathAlias(value, "filesystem")) {
+        return `${resolved[4]}:\\`;
+    }
+    return value;
+}
+/** Returns true when a Windows pathname can address an alternate filesystem namespace. */
+export function hasWindowsPathAlias(value, kind, platform = process.platform) {
+    if (platform !== "win32")
+        return false;
+    const firstColon = value.indexOf(":");
+    if (firstColon === -1)
+        return false;
+    if (kind === "relative")
+        return true;
+    return firstColon !== rootedDriveColonIndex(value) || value.indexOf(":", firstColon + 1) !== -1;
+}
+export function assertNoWindowsPathAliasForPlatform(value, kind, message, platform) {
+    if (hasWindowsPathAlias(value, kind, platform)) {
+        throw new FsSafeError("invalid-path", message, {
+            details: { reason: "windows-path-alias" },
+        });
+    }
+}
+export function assertNoWindowsPathAlias(value, kind = "filesystem", message = "path uses a Windows filesystem namespace alias", platform = process.platform) {
+    if (hasWindowsPathAlias(value, kind, platform)) {
+        throw new FsSafeError("invalid-path", message, {
+            details: { reason: "windows-path-alias" },
+        });
+    }
+}
+export function isWindowsPathAliasError(error) {
+    return error instanceof FsSafeError && error.details?.reason === "windows-path-alias";
+}

package/node_modules/@openclaw/fs-safe/dist/write-file-handle.d.ts

@@ -0,0 +1,7 @@
+import type { FileHandle } from "node:fs/promises";
+export declare function writeAllToFile(target: FileHandle | number, data: string | Uint8Array, options?: {
+    encoding?: BufferEncoding;
+    position?: number;
+    assertBeforeMutation?: () => void;
+}): Promise<void>;
+//# sourceMappingURL=write-file-handle.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/write-file-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file-handle.d.ts","sourceRoot":"","sources":["../src/write-file-handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,wBAAsB,cAAc,CAClC,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAChG,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/node_modules/@openclaw/fs-safe/dist/write-file-handle.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import { FsSafeError } from "./errors.js";
+const WRITE_CHUNK_BYTES = 512 * 1024;
+export async function writeAllToFile(target, data, options = {}) {
+    const buffer = typeof data === "string" ? Buffer.from(data, options.encoding ?? "utf8") : data;
+    let offset = 0;
+    while (offset < buffer.byteLength) {
+        const length = Math.min(WRITE_CHUNK_BYTES, buffer.byteLength - offset);
+        const position = options.position === undefined ? null : options.position + offset;
+        options.assertBeforeMutation?.();
+        const written = typeof target === "number"
+            ? await new Promise((resolve, reject) => {
+                fs.write(target, buffer, offset, length, position, (error, bytesWritten) => {
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(bytesWritten);
+                });
+            })
+            : (await target.write(buffer, offset, length, position)).bytesWritten;
+        if (written <= 0) {
+            throw new FsSafeError("helper-failed", "file write made no progress");
+        }
+        offset += written;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/write-open-flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-open-flags.d.ts","sourceRoot":"","sources":["../src/write-open-flags.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAoB,GACjF,MAAM,CAIR;AAUD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}
+{"version":3,"file":"write-open-flags.d.ts","sourceRoot":"","sources":["../src/write-open-flags.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAG7B,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAoB,GACjF,MAAM,CAIR;AAUD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAOT"}

package/node_modules/@openclaw/fs-safe/dist/write-open-flags.js

@@ -1,5 +1,4 @@
 import fsSync from "node:fs";
-import fs from "node:fs/promises";
 import { hasNodeErrorCode } from "./path.js";
 export function resolveNonblockingWriteFlag(constants = fsSync.constants) {
     return process.platform !== "win32" && typeof constants.O_NONBLOCK === "number"
@@ -17,7 +16,7 @@ export async function isNonRegularWriteOpenError(error, filePath, flags) {
     if (!isNonblockingWriteEnxio(error, flags))
         return false;
     try {
-        return !(await fs.lstat(filePath)).isFile();
+        return !fsSync.lstatSync(filePath).isFile();
     }
     catch {
         return false;

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

@@ -32,6 +32,9 @@ The exports group into a handful of themes. Each documented helper has its own p
 | `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 +68,22 @@ 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. |
+| `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. |
+| `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 +91,39 @@ 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 the descriptor is closed. 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
@@ -115,9 +160,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 +184,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 +194,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

@@ -43,6 +43,7 @@ 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
+  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
@@ -55,6 +56,36 @@ type ExtractArchiveOptions = {
 };
 ```
 
+`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.
+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
@@ -95,6 +126,12 @@ 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.
 
+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
 `stripComponents`, filters, limits, and mode policy, then passes an explicit
@@ -102,7 +139,29 @@ 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 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 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.
+
+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.
 
 `stripComponents` removes leading nonempty, non-`.` path components after
 normalizing separators. For example, `./pkg/hello.txt` with
@@ -189,23 +248,34 @@ 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
+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.
+That helper retains per-copy durability and immediate postorder directory-mode
+finalization; the deferred pass described above belongs to `extractArchive()`.
 
 ### Limits
 
@@ -267,6 +337,11 @@ 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.
+
 ### Raw TAR framing
 
 Extraction and bounded reads admit the complete decoded TAR stream through the
@@ -319,7 +394,9 @@ 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
+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
@@ -522,8 +599,8 @@ 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
+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,
 and throws `ArchiveLimitError` if the requested entry's output exceeds
 `maxBytes`. ZIP output within that cap must match the declared uncompressed
@@ -538,6 +615,24 @@ 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.
+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 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.
+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