@openclaw/fs-safe 0.8.4 → 0.8.6

package/CHANGELOG.md

@@ -1,23 +1,64 @@
 # Changelog
 
-## Unreleased
+## 0.8.6 - 2026-09-07
+
+**Highlights:** Clearer guidance for atomic writes on Windows exFAT, with a repeatable filesystem compatibility probe.
+
+- Document the existing opt-in locked rename policy for Windows exFAT/FAT32 and add a built-package probe for identity drift, substitution handling, and temporary-prefix isolation; require a trusted, quiescent probe parent and verify its cleanup identity. Thanks @dongsheng123132.
+- Refresh the native zstd decoder to 0.14.0 and compatible Rust and JavaScript development dependencies, and update the pnpm setup action to 6.1.0.
+
+## 0.8.5 - 2026-09-07
+
+### Highlights
+
+- **Strict moves stay strict:** a move started with hardlink rejection keeps that policy throughout asynchronous preparation and copying, even when the caller reuses or changes its options object.
+
+### Safe moves
+
+- Preserve the admitted `sourceHardlinks` policy through staged-copy fallback. A late hardlink is still rejected before destination publication, with the source and its alias preserved, instead of being accepted after an in-flight options change.
+- Document when move policy is captured and how it relates to the existing per-mutation authority checks and destination-publication receipts.
 
 ## 0.8.4 - 2026-09-07
 
+### Highlights
+
+- **Faster reads and writes:** metadata checks avoid unnecessary event-loop round-trips while data I/O stays asynchronous; reconstructible data can explicitly opt out of fsync with `durable: false`.
+- **Inspect TARs without extracting:** the new bounded archive inspection API uses the same native/WASM admission and canonical planner as extraction.
+
+### Filesystem performance and durability
+
+- Run metadata checks inside async operations synchronously (microseconds each), cutting event-loop round-trips per read/write while data I/O remains asynchronous and native canonical path spelling is preserved, including Windows short paths.
+- Add `durable` to Root write/create/writeJson/createJson/append options and Root defaults; `durable: false` skips file and parent fsync for reconstructible data (default unchanged: durable).
+
+### Archive inspection and compatibility
+
 - Add bounded `inspectTarArchive` with complete native/WASM admission and the same canonical extraction planner, preserving effective member identities without materializing an output tree.
 - Preserve inherited and getter-backed extraction options on the WASM TAR path, matching native and ZIP handling for destinations, filters, stripping, and modes.
+
+### Validation
+
 - Apply the existing filesystem-test worker cap locally as well as in CI, and drain archive publication fixtures before resetting hooks or cleaning restricted directories after timeouts.
-- Add `durable` to Root write/create/writeJson/createJson/append options and Root defaults; `durable: false` skips file and parent fsync for reconstructible data (default unchanged: durable).
-- Run metadata checks inside async operations synchronously (microseconds each), cutting event-loop round-trips per read/write while data I/O remains asynchronous and native canonical path spelling is preserved, including Windows short paths.
 
 ## 0.8.3 - 2026-09-06
 
+### Highlights
+
+- **Safer cancellable moves:** callers can guard every source removal and retain an exact destination-publication receipt for recovery after later failures, including Windows and cross-device fallbacks.
+- **Less filesystem overhead:** reads and writes make fewer calls while preserving their existing boundary and identity checks.
+
+### Move authority and recovery
+
 - Add optional synchronous move authority checks before renames and each copied-source removal, plus an exact bigint destination-publication receipt for caller-owned recovery after later failure; retain cross-device and Windows `EPERM` copy fallbacks and the existing `Promise<void>` contract.
 
-- Simplify internals without changing public behavior: remove unused string/home helpers, `resolveUserPath`, `createBoundedReadStream`, `sidecarLockPayloadIsStale`, and `tarManifestEntryCost`; share filesystem utilities and merge private modules.
+### Filesystem performance and durability
+
 - Reduce filesystem calls per read and write while retaining boundary, hardlink, hook, retry, and post-mutation identity checks.
 - Skip native publication's extra mode-only file fsync for modes that retain owner read/write when staging permissions have not widened; after a crash, a file may retain staged `0o600` instead of the wider requested mode, while restrictive modes retain the extra fsync.
+
+### Tooling and maintenance
+
 - Add 1 MiB read/write and existing-mode inheritance benchmarks, with native-mode metadata and per-case iteration counts.
+- Simplify internals without changing public behavior: remove unused string/home helpers, `resolveUserPath`, `createBoundedReadStream`, `sidecarLockPayloadIsStale`, and `tarManifestEntryCost`; share filesystem utilities and merge private modules.
 
 ## 0.8.2 - 2026-09-05
 

package/dist/move-path.js

@@ -289,7 +289,7 @@ export async function movePathWithCopyFallback(options) {
     const unregisterStaged = registerTempPathForExit(staged, { recursive: true });
     try {
         const manifest = await copyEntryWithManifest(sourcePath, staged, {
-            sourceHardlinks: options.sourceHardlinks ?? "allow",
+            sourceHardlinks: rejectHardlinks ? "reject" : "allow",
             ...(rejectHardlinks ? { budget: { discovered: 1 } } : {}),
         }, sourceIdentity);
         const cleanupState = createCleanupCopiedEntryState(sourcePath, manifest);

package/docs/atomic.md

@@ -75,12 +75,37 @@ If `beforeRename` throws, the rename is skipped and the owned temp file is remov
 
 Identity checks and pathname rename/unlink remain separate syscalls, not atomic conditional mutations. Use an approved writable parent plus cooperative locking or OS isolation when arbitrary concurrent namespace mutation is in scope.
 
-### FUSE mounts and unstable rename identity
+### FUSE, Windows exFAT/FAT32, and unstable rename identity
 
 Strict source-to-destination identity is the default. Some FUSE mounts assign a different inode to the destination during rename even without concurrency. Set `renameIdentity: "verify-content-with-lock"` to accept that boundary only when the re-opened no-follow destination has the exact requested SHA-256 content under an exclusive hashed sidecar lock in the destination parent. The newly accepted descriptor and identity remain pinned through parent sync and final verification. The synchronous helper provides the same policy with the synchronous lock implementation.
 
 This is the same explicit weaker contract available on `Root` writes: cooperating writers are serialized, stale locks fail closed, and mismatched content is rejected after publication without rollback. A same-authority actor that ignores the advisory lock can still substitute another file with identical bytes, so do not use this compatibility policy in directories writable by untrusted same-UID processes.
 
+Windows exFAT/FAT32 volumes can also change file identity during rename, depending
+on the source and destination names. The destination may already contain the
+requested bytes when strict verification reports `path-mismatch`. A short
+temporary name alone does not guarantee stable identity for a longer destination.
+For an application-controlled directory on such a volume, callers can explicitly
+select `renameIdentity: "verify-content-with-lock"` on `replaceFileAtomic` or
+`replaceFileAtomicSync`. Keep strict mode for directories that require the
+stronger identity contract; do not automatically retry every `path-mismatch`
+with the weaker policy. Staging names remain random, including custom prefixes.
+
+To verify the built package against an actual volume, run
+`node scripts/atomic-rename-compat-proof.mjs EXISTING_PARENT` after `pnpm build`.
+Use a trusted parent directory that no other process can rename or modify during
+the entire run, including cleanup; do not point the probe at a shared writable
+volume root. Cleanup checks the created directory's identity before recursive
+removal, but the check and removal are not atomic. The probe does not test safety
+against hostile concurrent namespace mutation.
+The probe creates and cleans up its own child directory and emits JSON without
+local paths. It compares default, strict, and locked policies in both async and
+sync calls, checks real rename identities and file contents, injects different-
+and identical-content substitutions, checks lock cleanup, and exercises custom
+prefix isolation and validation. Callback staging remains strict and can still
+report identity drift; the probe records that result separately. Filesystem type
+must be recorded independently; the probe does not infer it from a drive letter.
+
 ### `EPERM` and copy fallback
 
 On systems where `rename` fails with `EPERM`/`EEXIST`, pass
@@ -200,6 +225,8 @@ await movePathWithCopyFallback({
 ```
 
 Use it when source and destination might live on different filesystems (containers, tmpfs, separate volumes).
+The hardlink policy is captured when the move starts. Changing or reusing the
+options object later does not change the policy of an in-flight move.
 `sourceHardlinks: "reject"` performs a recursive preflight capped at 50,000
 entries before any mutation. Because link count and rename cannot be one atomic
 portable operation, this mode always commits a fresh inode/tree through the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -156,13 +156,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.8.4",
-    "@openclaw/fs-safe-darwin-x64": "0.8.4",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.4",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.8.4",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.8.4",
-    "@openclaw/fs-safe-linux-x64-musl": "0.8.4",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.8.4",
+    "@openclaw/fs-safe-darwin-arm64": "0.8.6",
+    "@openclaw/fs-safe-darwin-x64": "0.8.6",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.6",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.8.6",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.8.6",
+    "@openclaw/fs-safe-linux-x64-musl": "0.8.6",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.8.6",
     "jszip": "^3.10.1"
   },
   "devDependencies": {