Keep prepared search readers warm and verify abrupt indexing recovery

docs/BUILDING.md

@@ -201,10 +201,13 @@ signing/notarization requires Apple tooling and credentials. See the
 
 ### Windows archive for source installations
 
-After staging the CPU worker and media helpers, build an embedded-frontend
+Stage the normal hardware-detecting worker and media helpers, then build an embedded-frontend
 desktop binary and collect its runtime files:
 
 ```powershell
+python tools/embeddinggemma2/build_runtime.py --backend auto --jobs 2
+python tools/embeddinggemma2/stage_runtime.py --backend auto
+python tools/media-runtime/provision.py --stage
 Set-Location apps/desktop
 npm run tauri -- build --no-bundle
 Set-Location ../..
@@ -223,6 +226,10 @@ using CPU and OS capabilities, and
 the verified Vulkan loader DLL and its license; GPU availability is detected at
 runtime, with CPU fallback. The SDK is used only to compile the app.
 All runtime DLLs are listed by size and SHA-256 in `runtime-libraries.json`.
+Packaging also verifies the original pinned decoder ZIP and compares staged
+FFmpeg/FFprobe, notices and manifest against it. Keep that verified archive in
+`.searchi/media-runtime` while preparing the package; changed staged helpers
+or notices are rejected before replacing a previous archive.
 Staging and packaging reject missing or changed listed dependencies before
 replacing output. CPU-only VM smoke tests can also omit optimized modules to
 exercise the packaged baseline; this does not certify older physical hardware.
@@ -250,6 +257,7 @@ need both verified model files. See [semantic bounds and evidence](SEMANTIC.md)
 for current corpus, localization, and performance limitations. Keep signing keys,
 repository tokens, and model credentials outside source control.
 FFmpeg provisioning supports manifest-pinned Windows/Linux x86-64 and ARM64 artifacts;
-only Windows x86-64 has executed here. macOS decoder packaging remains a gate.
+Windows and Linux x86-64 startup and CPU decoding have executed here;
+other architectures and macOS decoder packaging remain gates.
 See [media runtime provenance](../tools/media-runtime/README.md) and
 [measured media limitations](MEDIA-QUALITY.md).

docs/PERFORMANCE.md

@@ -166,3 +166,19 @@ include the active VM-contention caveat: native photo inference and other work
 may overlap. This is an absolute small-corpus comparison, not an old-baseline
 regression claim or proof of model/media tracing overhead. The extra cost
 supports keeping detailed mode optional rather than claiming it is free.
+
+## Prepared-reader publication
+
+The desktop shares a bounded process-local prepared ANN between indexing and
+its retained query service. The graph is registered before SQL activation and
+matched by canonical database, dimensions, generation, policy and checksum.
+`semantic.prepared_graph_lookup` measures that handoff; a successful handoff
+sets `semantic.ann_load` cache_hit to one, without blob read/checksum/deserialization.
+The query model and real-vector LRU remain warm. Eligibility refresh and query
+inference still have costs and are measured independently.
+
+The actual CPU regression checks both a repeated cached query and an unseen
+query after publication; the unseen input must record query_cache_hit zero.
+See [RECOVERY-AND-HANDOFF.md](RECOVERY-AND-HANDOFF.md). Its single-document
+request times do not establish representative-corpus p95, native first input
+or foreground priority during indexing. Shared CPU admission remains open.

docs/RECOVERY-AND-HANDOFF.md

@@ -0,0 +1,100 @@
+# Process recovery and prepared-reader handoff
+
+2026-10-13 development validation. Production release gates remain open.
+
+## Abrupt process termination
+
+`crates/searchi-cli/tests/crash_recovery.rs` invokes the real installed-layout
+CLI adapter with verified Google EmbeddingGemma 2 assets, one CPU thread and
+actual FFmpeg helpers. It creates two document/code source groups and a
+65-second PCM WAV with three normal audio windows. It polls SQLite for both
+completed document groups plus a committed, unowned chunk belonging to the
+running media task, then terminates only its owned process tree.
+
+Windows uses PID-scoped `taskkill /T /F`; Unix assigns a dedicated process group
+and kills that group. Cleanup does not kill processes by name and does not panic
+during test unwinding. No user app/settings/index is used.
+
+Assertions verify that the previous active generation and completed vector
+bytes remain intact. Restart resumes the same generation, makes zero document
+encoder calls, re-encodes all three windows of the unfinished audio source,
+and publishes five unique chunks without leaked partial vectors. A real
+Google CodeRetrieval query checks the current source line citation.
+
+Windows and native Linux actual runs passed in 157.86 s and 233.65 s. These are suite elapsed times with compiler
+contention, not a search benchmark. Power loss, arbitrary batch boundaries and
+all crash scenarios are not established by one process-termination case.
+
+## Prepared graphs and warmed query model
+
+The desktop already used separate background and query model workers, but
+publication could send the next foreground request through blob reading,
+SHA verification and ANN deserialization. It also withdrew readiness and
+repeated query warmup while holding the retained session mutex.
+
+The publisher now shares its immutable prepared `Arc<usearch::Index>` before
+SQL activation through a process-local `PreparedGraphs` handle. That handle
+binds to the canonical database and vector dimension; entries match generation,
+full policy fingerprint and persisted ANN checksum. At most two registry entries
+are retained. Failed SQL activation removes only its unpublished entry; readers
+retain their own Arc when an old registry entry is evicted.
+
+The desktop query worker keeps its model and query-vector LRU ready throughout
+publication. Detailed traces include `semantic.prepared_graph_lookup`; the new
+active graph is a cache hit instead of foreground blob loading. Existing source
+eligibility, strict filtering and generation snapshot checks still apply.
+
+Storage regressions cover identity/dimension/checksum mismatches, bounded
+eviction, retained-reader lifetime and SQL activation rejection/retry. The real
+Google CPU test drops the background worker, searches the updated document and
+asserts no blob-read/checksum/deserialization spans. It verifies both a retained
+query-vector hit and an unseen query with actual neural inference.
+
+Windows one-document fixture: retained query 4.389 ms, unseen query 111.086 ms,
+29.05 s suite elapsed. These measure the shared engine request in debug mode,
+not native UI first input, application startup, a representative corpus or p95.
+The same native Linux fixture passed: retained query 2.107 ms, unseen query
+79.614 ms, suite 21.98 s. Different cache/contention conditions prevent treating
+these numbers as Windows-versus-Linux comparative performance.
+
+## Windows package media provenance
+
+The packager now verifies the pinned original decoder ZIP size and checksum,
+then compares the staged manifest, helpers and notices with bounded archive
+members. Valid PE headers and a freshly recorded package checksum are not
+accepted as decoder provenance. Fifteen packaging tests cover changed helpers,
+notices, manifests, archive members and changes during ZIP writing; failure
+preserves the previous output. Media staging was refreshed from the verified
+cached archive before packaging.
+
+Current embedded-frontend Windows release built successfully. Its 145,265,448-byte unsigned ZIP
+contains 39 verified files; optimized and baseline-only packaged CPU inference
+and decoder startup passed. Archive SHA-256:
+`cf7953827be90255f182932fe53c16faf76701098d2636c8860b6ed4e0eb6ec4`.
+Both worker smoke tests request auto with the GPU provider disabled only in the
+child process. Actual GPU, native UI interaction and clean-machine installation
+are not certified by those smoke tests.
+
+## Remaining performance/release work
+
+Background and query workers still receive independent thread budgets; shared
+CPU admission and foreground priority are open. Publication no longer charges
+foreground graph deserialization, but eligibility refresh, indexing I/O and
+CPU contention need representative measurements. Native compositor/input timing,
+large-corpus p95, older CPUs, actual GPU/device-loss, power-loss durability,
+installers/upgrades/signatures and macOS packaging remain open.
+
+## Executed checks
+
+- Windows and native Linux workspace tests: 106 passed each, 18 ignored.
+- Windows native desktop unit suite: 17 passed.
+- Strict Windows/Linux workspace and Windows desktop Clippy plus both formatting checks passed.
+- Real Google CPU process-kill and prepared-reader regressions passed on both OSes.
+- Windows packager tests: 15 passed. Current embedded-frontend release build,
+  archive integrity, packaged optimized/baseline CPU inference and decoder startup
+  passed; no accelerator was used.
+
+The prepared graph handle is process-local: foreign CLI/MCP index writers cannot
+share its native Arc. Cold CLI initialization and cross-process reader refresh
+remain separate costs. Representative concurrent-indexing/foreground measurements
+and shared CPU thread admission remain the next performance milestone.

docs/ROADMAP.md

@@ -30,7 +30,7 @@ Status: implementation started; no production release yet. Windows VM tests use
 - [ ] Versioned embeddings, ANN index, exact-match priority and hybrid fusion.
 - [ ] English/German relevance corpus and measured top-10 recall.
 - [ ] Atomic model/index replacement and resumable persistent work queues.
-- [ ] Completed-source manifests with title/model/window policy keys and
+- [x] Completed-source manifests with title/model/window policy keys and
   citation remapping; reuse only verified complete document/media groups.
 - [ ] Durable generation tasks, crash resume and final corpus reconciliation;
   see [incremental semantic design](INCREMENTAL-SEMANTIC.md).
@@ -100,7 +100,7 @@ Status: implementation started; no production release yet. Windows VM tests use
   Warm p95 alone does not satisfy the first-use requirement.
 - [ ] Test migrations, interrupted work, invalid documents, inaccessible/offline roots and cloud placeholders.
 - [ ] Automated native build matrix and documented supported cross-compilation paths.
-- [x] Native Linux headless workspace tests: 104 passed, 16 explicitly ignored.
+- [x] Native Linux headless workspace tests: 106 passed, 18 explicitly ignored.
 - [x] Native Linux Google text/code/media reference parity and service
   lifecycle/rebuild recovery: seven genuine CPU integration tests passed.
 - [x] Unsigned Linux x86-64 headless archive: verify extracted checksums/modes,
@@ -136,6 +136,9 @@ Audit and measured priorities: [EMBEDDINGGEMMA2-AUDIT.md](EMBEDDINGGEMMA2-AUDIT.
   paired repeated-query/filter-change results with unchanged retrieval evidence.
 - [x] Bounded provider-scoped actual-query vector LRU with accurate cache traces;
   preserve filtering, source freshness, failures and actual warmup probes.
+- [x] Bounded shared prepared-ANN handoff before SQL activation; retain query
+  model/LRU and readiness across publication. Actual CPU first new query has
+  no foreground graph load; [recovery/handoff evidence](RECOVERY-AND-HANDOFF.md).
 - [x] Reduce semantic settle delay to 120 ms and retain old ready generation
   during rebuilding; test initial-generation and activation readiness boundaries.
 - [x] Bound whole IPC write/read deadlines and recover from a nonreading helper;
@@ -153,7 +156,10 @@ Audit and measured priorities: [EMBEDDINGGEMMA2-AUDIT.md](EMBEDDINGGEMMA2-AUDIT.
   on normal rescans; stale/missing agent excerpts fail closed.
 - [x] Actual Google CPU same-metadata text mutation before/during inference:
   reject publication, rescan without metadata workarounds and reuse unaffected vectors.
-- [ ] Process-kill/concurrent deletion/media mutation, component-policy reuse and
+- [x] Abrupt owned CLI termination after a committed partial audio chunk;
+  resume completed documents and reencode unfinished media without duplicates.
+  Process termination does not prove power-loss durability.
+- [ ] Concurrent deletion/media mutation, component-policy reuse and
   indexing/foreground measurements.
   See [INCREMENTAL-SEMANTIC.md](INCREMENTAL-SEMANTIC.md).
 - [ ] Benchmark genuine token-budgeted multi-sequence batching and isolation.