fs-safe 0.10.0

Highlights

• Faster ZIP and TAR reads: read archive members without temporary disk snapshots, reuse admitted native buffers, and reduce integrity-check and decompression overhead while retaining full validation.
• Directory copies with native acceleration: use copyTree to prefer or require APFS clones, Btrfs snapshots, or parallel ReFS/XFS reflinks, or choose portable byte copying for controlled, immutable templates and checkouts.
• Guarded file copies: copy from checked Root sources with exclusive publication, cancellation that waits for writes, and optional native cloning; copied data stays independent of its source.
• Faster Windows byte copies: reuse bounded buffers and parallelize directory copying, with native transfers between checked handles in automatic mode.
• Reuse buffers for file reads: new async and sync positional readers fill caller-owned buffers without changing the file's current offset; hashing gains byte limits and cancellation.
• Walk large directories incrementally: Root walks bound metadata work by the entry budget, with an opt-in filesystem-order stream for directories too wide to enumerate up front.
• Recheck live access authority: Root mutations can verify caller-owned leases or cancellation immediately before dispatch, and new symlink policies allow contained parent-directory aliases while rejecting final symlinks.

Compatibility and upgrade notes

• Ambiguous paths may now reject. Reads preserve actual symlink and parent traversal instead of normalizing it away; mutations reject ambiguous symlink/parent combinations. Use the new explicit parent-alias policies when that behavior is intended.
• Mutation failures are reported more accurately. Failed parent-directory checks after fallback moves and removals now reject instead of reporting success. Treat rejection after dispatch as a potentially completed mutation, not proof that nothing changed.
• Windows fallback writes honor durability settings. Root defaults and per-call overrides now apply to JavaScript write/create fallbacks. Use durable: false explicitly for reconstructible data when syncing is unnecessary.

Archive reads

• Retain admitted ZIP input buffers and parsed directories across native inspection and selected-member reads, removing disk staging and archive handoff copies. JavaScript ZIP reads also consume the admitted in-memory archive directly.
• Retain native TAR input and admitted member offsets. Plain TAR copies only the selected range after complete validation; gzip, zstd, and bzip2 replay bounded decompression with framing, trailer, padding, and limit checks intact. JavaScript TAR/gzip reads also avoid disk staging, with gzip output chunks matched to the WASM input window.
• Accelerate ZIP integrity checks with Node's native CRC32 on Node 22.2 and newer, retaining checksum validation and compatibility with earlier Node 22 versions. Reuse the strict UTF-8 decoder for TAR metadata without changing filename validation or BOM handling.
• Give each native archive pass its own abort signal so completed inspection cannot mask an extraction deadline.

File reads, hashing, and directory walks

• Add readFileWindowFully() and readFileWindowFullySync() to fill caller-owned buffers through short reads, stop at EOF, and preserve descriptor offsets and ownership. Async cancellation waits for the pending read to settle before the buffer can be reused.
• Bound speculative allocations for large or exhausted files and accelerate synchronous bounded reads of regular files up to 16 MiB without extra chunk copies; retain one-read async performance through the default Root byte budget.
• Add byte limits and cooperative cancellation to sha256File, preserving descriptor ownership and waiting for native work to stop before rejecting. Batch larger JavaScript hash reads in bounded buffers up to 256 KiB to reduce filesystem calls.
• Bound Root walk metadata batches by the global entry budget and stop batches at directories and symlinks before descent. Add order: "filesystem" for incremental directory streaming with bounded lookahead; sorted traversal remains the default, and unbounded sorted walks retain fast snapshots.
• Reduce walk overhead by sharing equivalent directory checks and synchronous entry classification, reusing joined paths, and avoiding an extra promise per async entry. Preserve both operation and close failures during disposal, and report a followed symlink target's size consistently in filters and returned metadata.
• Speed up POSIX containment and filename helpers while preserving traversal rejection, Unicode handling, reserved names, and collision-resistant install names.

File and directory copying

• Extend Root.copyIn with guarded Root sources, exclusive publication, settled cancellation, exact publication receipts, and optional native file cloning while keeping copied data independent. Share clone: "auto" | "always" | "never" with copyTree; Root keeps its "never" default, which uses ordinary reads and writes without clone or copy-offload calls.
• Add copyTree in @openclaw/fs-safe/copy with clone: "auto" (default), "always", and "never" policies. Automatic copying prefers native cloning and falls back to byte copying only when the binding or filesystem capability is unavailable, or cloning cannot cross filesystems; strict cloning never falls back, and ordinary copying avoids clone and copy-offload calls. Destinations must be absent, and cancellation waits for admitted writes to settle.
• Speed up Windows directory byte copies with bounded parallelism, reusable 1 MiB buffers, and native transfers between checked handles in automatic mode. Honor copy concurrency across portable backends and settle admitted writes before reporting failures or cancellation.
• Support APFS directory clones, Btrfs subvolume preparation and snapshots, and parallel ReFS/XFS reflinks through probeTreeClone and createCloneSource. Preserve XFS file and directory extended attributes and ACLs, and restore directory timestamps after APFS bulk cloning.
• Add batched readCloneFileMetadata for APFS clone IDs and file metadata. These are point-in-time observations, not authorization or proof that later contents remain unchanged.
• Document metadata and filesystem limits: APFS directory cloning does not guarantee descendant ACL preservation or inheritance, Btrfs snapshots omit nested subvolume contents, and ReFS rejects unsupported reparse points and alternate data streams. Portable copying does not promise ownership, ACL, extended-attribute, alternate-stream, or sparse-layout preservation. Callers retain responsibility for source immutability, permission policy, and recovery after a failed or aborted copy.

Root policies and path safety

• Add composed Root assertBeforeMutation callbacks that recheck live caller authority immediately before mutation dispatch, including each buffered-write chunk and direct file removal. Root-level and per-call checks both apply; refusal errors and owned cleanup are preserved across native and JavaScript writers.
• Add symlinks: "follow-parents-within-root" for reads and opt-in mutationSymlinks policies, following contained directory aliases while rejecting final symlinks at absolute root entry, open, and publication boundaries.
• Preserve checked canonical and raw traversal in Root, absolute-path, local-root, and openRootFile/openRootFileSync reads, including home expansion and parent components that cancel a missing prefix. Validation can no longer normalize away a rejected link or select a different in-root file; local requireFile reads retain final-symlink rejection.
• Pin Root directory identities as bigint values, reject indistinguishable numeric inode replacements, and fail closed after bounded retries when Windows root identity remains unknown. Require a verified opened identity before inheriting an existing write target's mode.
• Preserve Linux native directory-only open flags so the kernel rejects non-directories before FIFO blocking or truncation, while removing the redundant post-open stat.
• Expand leading home-directory prefixes before resolving parent segments, so ~/../file resolves against the home directory's parent; keep other tildes literal. Shorten only the home directory and its descendants in error messages, preserving similarly prefixed sibling paths.
• Resolve Windows ACL principal names such as constructor and __proto__ as real dictionary keys, preserving SID lookup and translated entries.
• Preserve Unicode Windows paths during fallback permission inspection by reading structured SID and access-mask facts instead of localized command output.

Writes, moves, and cleanup

• Check the complete encoded newline before Root append, avoiding duplicated or missing separators in UTF-16LE files on Windows and other platforms.
• Preserve unowned staging replacements after Windows fallback write or sync failures, and retain exact parent-directory identities so owned partial-file cleanup works even when Windows directory indexes exceed numeric precision.
• Report failed post-operation parent checks after fallback moves and removals, including moved source parents, instead of silently reporting success.
• Close publication descriptors when initial inspection fails and relinquish descriptor numbers before potentially failing closes, preventing cleanup from closing a reused descriptor.
• Keep move-fallback publication and cleanup tied to the initially admitted staging identity, preserve substituted paths after copy failures, and reject writes that make no progress.
• Preserve recreated temporary paths after exit cleanup observes the original name missing; absence no longer authorizes removal of a later replacement.
• Allow explicitly authorized filesystem-root descendants in Trash moves and keep reservation-directory names bounded for long source filenames.

Locks and durable queues

• Honor finite timeouts and retry delays above Node's single-timer limit by rearming bounded timers instead of expiring after approximately 1 ms.
• Keep zero-delay lock retries finite when a large backoff factor overflows, preserving retry and timeout budgets.
• Skip invalid delivered-marker names during durable queue batch loading, preserving malformed files while continuing to load valid pending entries.
• Read durable queue entries through the shared bounded buffer and admitted file-size hint, reducing filesystem calls and chunk copies while retaining exact identity and byte-limit checks.

Validation and maintenance

• Add a method-by-method benchmark with callable API coverage checks, native/fallback reports, and fixture setup outside measurement.
• Give the full documentation-build smoke test a bounded longer runtime on slow Windows runners. Validate retained native archive buffers across concurrent reads and forced garbage collection; use efficient byte comparisons in large-buffer coverage tests without relaxing timeouts.

Published packages

Package	Registry tarball	Verified integrity	Provenance
@openclaw/fs-safe-linux-x64-gnu@0.10.0	tgz	sha512-0860Rm/gfbVKoAVDr92mUVums0HL2l+UTKbEA07agxS0RDKZdCA1SQVTduyMBwirY0cqrMjzpygAIt5SJAtOKg==	verified attestation
@openclaw/fs-safe-linux-x64-musl@0.10.0	tgz	sha512-cTBNOKKp0LB3ZonavOxbpK5VHNsrZ0NlWf09GS8/KN+z0gNHyiSjJ2SQMgX8nwvjAV2OVr2JEaQJ3INzYML2fQ==	verified attestation
@openclaw/fs-safe-linux-arm64-gnu@0.10.0	tgz	sha512-oa4NA9HMJxl5Ub7Em7CdWUwS+XQJm2ICbBMHLxCIVhIS8zwikLqm+yWndArfMU5J5mgpaDXWhZ1pS7oe/Air1A==	verified attestation
@openclaw/fs-safe-linux-arm64-musl@0.10.0	tgz	sha512-wY4MbUNzH8BT8QRcby6riYw+GJzPddPiTzYj8eyebuta82VrB39ZpFyqQpsO4K9mqahbUnTxpbeYUUO34fRnHQ==	verified attestation
@openclaw/fs-safe-darwin-x64@0.10.0	tgz	sha512-CRpODRgQYkWWPr1uBZqZ21szrMAfreTOQf1Elwd1F8cxLJa783ynKDZAm/1r9xg6BGraLtGoLRctgaKx7Y6aEA==	verified attestation
@openclaw/fs-safe-darwin-arm64@0.10.0	tgz	sha512-WgBo6nRh/F+aQohBx1Txx1x9q5VaxrB7KcDu+550ju3rnQJ9NIgCWsDJNeIHBmkcokNaEfvZJZhxtfWiuOSa+w==	verified attestation
@openclaw/fs-safe-win32-x64-msvc@0.10.0	tgz	sha512-WlIJYtLumnWkZZ9pqoegri1DuOw+t9WaWZPzt83QVBS5HquyMRbJMw4RlPuwOgTE0X0vrv+g7GuFsOtmmg8g7w==	verified attestation
@openclaw/fs-safe@0.10.0	tgz	sha512-tZW2fR6TgLAYfsaYx+ewC4zoPLO6EicRfx7f6kke4N/jIb8ZkteBEq2cD4Y6jMeNgVM7YClVzQuzcaAIkan3Dg==	verified attestation

Release proof: GitHub Actions run.