Expose invalidate_forest_cache through fula-flutter bindings (0.6.8): session-pinned forests serve stale cross-device listings

[ehsan6sha]

Problem

The encrypted client caches each bucket forest for the CLIENT LIFETIME: load_forest is a no-op once cached (verified: 0ms on second call via perf spans) and list_from_forest / get_object_flat read that memory. Any long-lived session therefore never sees another device''s uploads - listings, manifest reads AND downloads all resolve against the session-stale forest.

Real repro (FxFiles web, 2026-06-12): upload from desktop web -> a long-lived mobile web tab kept showing the old 2-file listing indefinitely (incognito on the same phone showed 3). The app''s SWR cache then re-stamped the stale listing as fresh because its live revalidation was actually a memory read. The same lifetime-pinning affects the NATIVE apps on long sessions.

The fix is already written - it just isn''t exposed

EncryptedClient::invalidate_forest_cache(&self, bucket) exists at crates/fula-client/src/encryption.rs:9015 (dirty-safe: keeps unsaved entries) plus invalidate_all_forest_caches at :9029. Neither is reachable from Dart: crates/fula-flutter/src/api/forest.rs exposes load/save/flush only.

Ask (0.6.8)

1. Add to crates/fula-flutter/src/api/forest.rs:
   • invalidate_forest_cache(client, bucket) -> guard read -> call through
   • optionally invalidate_all_forest_caches(client)
2. Release via the existing hash-consistent pipeline (FRB_CODEGEN_VERSION pinned 2.11.1, build-flutter-wasm job producing flutter-wasm-pkg.zip - same flow as v0.6.7).
3. Consider exposing the same in crates/fula-js for npm parity.

Consumer side (FxFiles, ready and waiting)

FulaApiService.invalidateForestCache(bucket) (FxFiles commit cfaa185) already drops the Dart-side memo and is called on every SWR revalidation/force path - it just needs the Rust call added once 0.6.8 lands. FxFiles currently ships an interim workaround (full client rebuild from stored credentials on Refresh/tab-resume/reconnect) that 0.6.8 makes cheap and per-bucket. Native apps can adopt the same call for their cloud-listing refreshes.

Acceptance

• After another client uploads to a bucket, invalidate_forest_cache(bucket) + list_from_forest on an existing client returns the new file (no client rebuild).
• A dirty (unsaved local changes) forest is NOT evicted - existing doc contract.

🤖 Generated with Claude Code

[ehsan6sha]

Verified: NOT addressed in 0.6.8 — fix incoming in 0.6.9

Checked against the 0.6.8 release (acb3fea, PR #35): that release fixed #34 (forest write amplification) entirely inside fula-crypto and never touched the binding crates. The state on main:

• EncryptedClient::invalidate_forest_cache (dirty-safe) and invalidate_all_forest_caches exist exactly as described, at crates/fula-client/src/encryption.rs:9015 / :9029, and are already exercised by SDK-internal integration tests (dir_index_v8_sharded_read.rs, get_object_flat_no_o_n_scan.rs).
• crates/fula-flutter/src/api/forest.rs exposes load/save/flush/has-pending only — no invalidate. Nothing in crates/fula-js either. Confirmed by grep: zero invalidate references in either binding crate.

So the issue stands: the escape hatch is real but unreachable from Dart/JS.

Also worth noting (relevant to the repro): the staleness this issue describes is about another device's writes. The 0.6.8 work added a related guarantee for the same client's conflict path — when a stale client writes, the 412 reconcile evicts and reloads the forest (tested in issue_34_two_client_interop.rs) — but pure readers never hit that path, so a read-only session stays pinned forever, exactly as reported.

Fix (lands as 0.6.9)

1. crates/fula-flutter/src/api/forest.rs: invalidate_forest_cache(client, bucket) + invalidate_all_forest_caches(client) — guard read → call through, per the issue's sketch.
2. Dart bindings regenerated with the pinned codegen (flutter_rust_bridge_codegen 2.11.1, matching the hash-consistent release pipeline) → invalidateForestCache / invalidateAllForestCaches on the Dart api/forest surface; flutter analyze clean.
3. npm parity: same two functions exported from crates/fula-js (invalidateForestCache, invalidateAllForestCaches), and the CI wasm job's .d.ts export check now guards them.

Acceptance tests (added, passing)

At the EncryptedClient layer (what both bindings delegate to), against a stateful conditional-PUT mock master — crates/fula-client/tests/issue_36_invalidate_forest_cache.rs:

• stale_listing_refreshes_after_invalidate_without_client_rebuild — device A lists 2 files; device B uploads a third; A's list_files_from_forest still returns 2 (pins the lifetime-pinning premise); invalidate_forest_cache + re-list on the same client instance returns 3 and the new file downloads byte-exactly. Acceptance bullet 1, verbatim.
• dirty_forest_is_not_evicted_by_invalidate — a deferred (unflushed) upload survives an invalidate (has_pending_forest_changes stays true, entry still listed); after flush_forest, invalidation takes effect and the reloaded forest still has the persisted file. Acceptance bullet 2.
• invalidate_all_drops_clean_forests_and_keeps_dirty_ones — bulk variant: clean bucket refreshes (sees the other device's file), dirty bucket keeps its pending entry.

Plus a bridge-level test (crates/fula-flutter/tests/issue_36_invalidate_bridge_test.rs) pinning that the functions are on the FRB-scanned crate::api surface and are safe no-ops on a client with no loaded forest — the "call it unconditionally from every SWR revalidation path" usage FxFiles wants.

🤖 Generated with Claude Code

[ehsan6sha]

Shipped in 0.6.9 — merged via #37 (4e39682)

Everything from the ask, plus one hardening fix the review surfaced:

Bindings (the ask):

• crates/fula-flutter/src/api/forest.rs: invalidate_forest_cache(client, bucket) + invalidate_all_forest_caches(client) — guard read → call through, as sketched.
• Dart regenerated with the pinned flutter_rust_bridge_codegen 2.11.1 (hash-consistent with the release pipeline): invalidateForestCache / invalidateAllForestCaches are on lib/src/api/forest.dart. flutter analyze clean.
• npm parity: same two exports in crates/fula-js, and the CI wasm job's .d.ts export check now guards both so parity can't silently regress.

Hardening (found during pre-merge review): the core invalidate_forest_cache had a TOCTOU window — a concurrent deferred put could dirty the entry between the is_dirty check and the remove(), and the eviction would silently drop the pending index entry. That window becomes reachable exactly when apps start calling this from refresh paths concurrent with uploads, so it's now atomic (DashMap::remove_if holds the shard lock across predicate + removal).

Acceptance, as specified (all passing):

• "After another client uploads, invalidate_forest_cache(bucket) + list_from_forest on an existing client returns the new file (no client rebuild)" — stale_listing_refreshes_after_invalidate_without_client_rebuild, which also pins the premise (without the call, the listing stays session-stale indefinitely) so a future auto-revalidation change will surface loudly.
• "A dirty (unsaved local changes) forest is NOT evicted" — dirty_forest_is_not_evicted_by_invalidate (pending entry + has_pending_forest_changes survive; after flush_forest, invalidation takes effect and the persisted file is still listed).
• Plus per-bucket isolation (invalidating bucket A never evicts bucket B) and the invalidate_all clean-dropped/dirty-kept split.
• Bridge level: functions are on the FRB-scanned surface and are safe idempotent no-ops on a client with no loaded forest — call them unconditionally from any SWR revalidation path.

CI: all 8 jobs green (Android aarch64/armv7/x86_64, iOS aarch64/x86_64, generate-bindings, full Rust workspace, wasm incl. the new export guards).

Version: 0.6.8 → 0.6.9 (workspace, fula-js + fula-flutter crates, fula_client pubspec/podspec, changelog). Release via the existing pipeline puts invalidateForestCache in FxFiles' hands — FulaApiService.invalidateForestCache (cfaa185) picks it up with no further app changes, retiring the full-client-rebuild workaround.

🤖 Generated with Claude Code