Migrating from 0.5 to 0.6

Version 0.6 moves native bindings out of the root @openclaw/fs-safe tarball and into exact-version platform packages. This removes unrelated operating system and architecture binaries from each installation.

#Keep optional dependencies enabled for native mode

Package managers select one binding by OS, CPU, and Linux libc. A normal install needs no command change:

pnpm add @openclaw/fs-safe

If a deployment currently installs 0.5 with --omit=optional, --no-optional, or an equivalent lockfile policy, change that policy before upgrading when it uses native mode require or any native-only feature. Version 0.5 kept its binding in the root tarball; version 0.6 intentionally does not.

Omitting optional dependencies remains supported for fallback-capable APIs in auto mode. It disables native-only features such as retained-directory staging and atomic rename-noreplace. Native mode require reports helper-unavailable when the matching package is absent or incompatible. Zstd/bzip2 TAR extraction and bounded reads required the binding in version 0.6; current versions also support bundled WASM codecs in auto and off through the same guarded TAR pipeline. ZIP fallback still requires optional JSZip. Windows private-directory creation required the binding in version 0.6; current releases also support packaged Windows security helper in auto and off mode while preserving the creation-time protected DACL.

#Deployment checklist

Remove any option or policy that omits optional dependencies when native

support is required.

Regenerate every lockfile or shrinkwrap file consumed by deployment.
Verify that the lock contains the matching @openclaw/fs-safe-* package.
Run a native-required operation on every deployed OS/libc target.
Keep an FS_SAFE_NATIVE_MODE=off lane when the guarded JavaScript fallback

is part of the application contract.

No Rust toolchain, postinstall build, or runtime download is introduced. See Native helper policy for the exact fallback boundary.