added fuse compliance testing

docs/BUGS.md

@@ -1585,3 +1585,47 @@ continue DB/client activity after teardown.
 handles, and ordered shutdown. Repeated mount/unmount tests should return thread
 counts to baseline and observe no post-unmount DB work.
 
+---
+
+## B45 — Truncate After a Queued Rewrite Replaces the Prefix With Zeros
+
+**Status:** Fixed and live-verified (2026-07-22)
+**Found by:** `scripts/fuse-acceptance.sh`
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, write-open scratch setup
+
+**Repro:** Write a file, immediately replace its contents, then run
+`truncate -s 4 file` before the queued replacement drains. Reading it returned
+four NUL bytes instead of the first four replacement bytes.
+
+**Cause:** A new write handle always treated the server revision as its base.
+When a newer complete revision was still queued locally, the handle's scratch
+file began sparse and zero-filled. Shrinking it preserved those scratch zeros,
+not the prefix of the locally authoritative queued revision.
+
+**Fix:** A write opened over a complete queued revision seeds its scratch file
+from that staged blob and marks the copied range authored. Stacking a write over
+an incomplete queued revision is refused rather than guessed. Live acceptance
+verified the exact rewrite-then-truncate sequence returns `b"a mu"`.
+
+---
+
+## B46 — Combined Cross-Directory Move and Rename Can Fail Out of Date
+
+**Status:** Fixed and live-verified (2026-07-22)
+**Found by:** `scripts/fuse-acceptance.sh`
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, `ProtonFs::rename`
+
+**Repro:** `mv source victim`, replacing an existing file, followed immediately
+by `mv victim dir/moved`. Proton accepted the move half of the second operation,
+then rejected its rename half with `InvalidRequirements` (HTTP 422, "out of
+date"), surfaced as `EIO`.
+
+**Cause:** Moving changes the node's encrypted-name requirements. The following
+link-details read can briefly observe the pre-move state, so the new name is
+signed against stale requirements.
+
+**Fix:** Retry only `InvalidRequirements` from the rename-after-move step with a
+short bounded backoff. Stable API failures are not retried. If every retry
+fails, adopt the already-completed move in inode state before returning `EIO`,
+so the local model never claims the node remains in its old parent. The full
+live suite subsequently passed the replacement and combined move/rename cases.

docs/TESTING.md

@@ -0,0 +1,55 @@
+# Testing
+
+The normal Rust suite exercises the metadata database, sync planner, offline
+queue, write staging, cache, and FUSE handler state without requiring a Proton
+account:
+
+```console
+cargo test --workspace
+cargo clippy --workspace --all-targets -- -D warnings
+```
+
+## Live FUSE acceptance suite
+
+Kernel behavior and remote convergence need a real mount. The live suite runs
+destructive POSIX operations only below a fresh `pdfs-acceptance-*` directory.
+It refuses paths that are not FUSE mounts and removes its directory on success,
+failure, or interruption.
+
+Use a dedicated test account without irreplaceable data:
+
+```console
+scripts/fuse-acceptance.sh /mnt/on-demand-testmount
+```
+
+Passing more paths runs the same filesystem suite independently against each.
+The first path must be the FUSE mount under test; later paths may be another
+FUSE mount or a normal local mirror filesystem:
+
+```console
+PDFS_ACCEPTANCE_SYNC_TIMEOUT=180 \
+  scripts/fuse-acceptance.sh /mnt/on-demand-testmount /mnt/testmount
+```
+
+If two paths really are views of the **same remote folder**, enable an
+additional byte-for-byte convergence check explicitly:
+
+```console
+PDFS_ACCEPTANCE_CONVERGENCE=1 \
+  scripts/fuse-acceptance.sh /mnt/first-view /mnt/second-view
+```
+
+Do not enable that flag merely because two sync folders belong to the same
+account. Their configured remote UIDs must be identical.
+
+The suite covers create/read/rewrite/truncate, multi-megabyte binary content,
+unaligned random writes, rename replacement, cross-directory moves, important
+POSIX error cases, open-then-unlink behavior, concurrent writers, directory
+enumeration, and optional cross-mount byte-for-byte convergence. A pass is
+strong evidence for those paths, not a blanket data-loss guarantee. Before a
+release, also run the recovery drills in `docs/RECOVERY.md` and inspect
+`docs/BUGS.md` for live-verification items.
+
+The runner accepts already-mounted paths instead of starting a daemon. This
+keeps authentication and keyring setup explicit and prevents it from silently
+reusing or replacing the normal application state directory.