Add flush(), so a RAG index survives the process (#492)

[DenisovAV]

Fixes #492 (first finding).

flutter_gemma_rag_qdrant never called EdgeShard.flush(), so points added through addDocument stayed in the shard's in-RAM segment: an index built in one session was gone in the next, and the corpus was embedded again on every launch.

@think2execute measured it on two Android devices and named the missing piece precisely — the next open fails with Failed to load ID tracker mappings. That was exactly the right place to look:

file	before flush()	after
mutable_id_tracker.mappings	absent	420 bytes
mutable_id_tracker.versions	absent	160 bytes

Everything else — vector storage, payload storage, segment.json — is on disk well before that.

close() persisted already, since unloading writes too, but that only covers a store the app closes cleanly. An Android app the system kills in the background never gets there, and there was no way to persist without giving up the store.

What flush() means per backend

flush() joins the VectorStoreRepository contract rather than only the qdrant class — a caller holding the interface, which is what FlutterGemma.initialize hands back, would otherwise need a backend type-check to ask for durability. It is also exposed as FlutterGemma.rag.flush(), without which the facade every app uses could not reach the fix at all.

• qdrant — required. This is flutter_gemma_rag_qdrant: EdgeShard.flush() is never called, so an index does not survive the process #492.
• SQLite, native — a genuine no-op: the connection is in autocommit and never opens a transaction.
• SQLite, web — the interesting one, and not a no-op. The VFS Flutter web gets is IndexedDB (OPFS needs a dedicated worker), whose xSync does nothing and whose writes are asynchronous by design. So the store keeps the VFS reference and drains it, and close() drains too.

Why web is documented rather than worked around

On sqlite3 >= 3.4.0 that drain is partial: flush() returns without awaiting a batch already in flight. Upstream commit 11be8acb ("Optimize indexeddb flush on idle") replaced a marker queued behind the running batch with a bare _startWorkingIfNeeded, whose body is skipped while _isWorking is true. 3.3.4 still had the marker; the doc comment still promises to await. It is an unintended regression, and no upstream issue reports it yet.

The two alternatives were both worse:

• Capping sqlite3 <3.4.0 — drift 2.35.0 requires ^3.4.0 and sqlite_async ^3.5.0. A cap turns our durability gap into a hard resolution failure for the most common consumer.
• Owning the drain (writeAutomatically: false + a debounce timer) — needs a 3.4 floor anyway, since the option does not exist on 3.3.x; the timer manufactures exactly the interleaving that makes flush() return early; and it widens today's loss window for every web caller that never calls flush().

The exposure being documented is bounded: the VFS streams writes into IndexedDB continuously, so what an early return misses is the batch in flight, not the index. Reported upstream as simolus3/sqlite3.dart#408, with a fix in simolus3/sqlite3.dart#409 that keeps their idle optimisation and restores the marker only while a batch is running. When it ships, raising the floor makes our flush() a true fence with no code change here.

Other findings from review, all fixed

• close() settled its fields in a finally after the await, so isInitialized reported true over a closed database and a flush() in that window reached a closing VFS.
• A re-initialize overwrote the VFS field without draining the old one, orphaning its queued pages.
• flush()'s guard returned early when a failed re-initialize had left the previous run's VFS holding unwritten pages.
• _rethrow's final throw e escaped raw, so anything neither an EdgeException nor a UniffiInternalError crossed all twelve wrapper methods and the store's translation to VectorStoreException never fired.
• The OPFS comment named the wrong mechanism — durability comes from SQLite calling xSync on commit, not from the write having reached storage.
• The class dartdoc had attached itself to a private enum inserted above it.
• Core's bump is marked breaking for custom implementations, matching how 1.8.0 marked the same shape of change.

Verified

• Mutation-checked: dropping the flush() call fails three tests, including the black-box one.
• A black-box test reproduces flutter_gemma_rag_qdrant: EdgeShard.flush() is never called, so an index does not survive the process #492 in one process — a copy of the shard taken before the flush reopens empty and silent, after it carries every document. It pins the contract's outcome rather than this engine's file names.
• The id-tracker assertion now asserts the segment directory exists first, so it cannot pass on a store that never wrote.
• flutter_gemma_rag_qdrant 115/115, flutter_gemma_rag_sqlite 121/121, flutter_gemma 710/710, flutter analyze packages/ clean.
• The example's sqlite3 dev-dep moves to ^3.5.2 while the package keeps ^3.3.0: the example resolves separately from the workspace and was pinning 3.3.3, so the web suite was exercising a flush() consumers do not get.

Not covered

The web path still has no automated test — it needs a browser, and the existing web suite runs under flutter drive. The IndexedDB behaviour here is argued from the VFS's own source plus a headless-Chrome measurement from review, not from a test in this repo.

The second finding in #492 — one device failing to reopen an intact shard — is not ours: it is qdrant/qdrant#10307, a zero-length POSIX_FADV_NOREUSE returning ENOENT on F2FS kernels with the memory-donation patch. Fix is qdrant/qdrant#10365, approved and waiting on CI.