Indexing: generalize the single-volume indexer into a per-volume registry (M1, no behavior change)

Replaces the one hardwired `INDEXING: Mutex<IndexPhase>` global with `INDEX_REGISTRY: Mutex<HashMap<VolumeId, IndexInstance>>`, where each `IndexInstance` bundles a volume's `{phase, read_pool, pending_sizes}`. This is the structural foundation for indexing SMB shares and MTP devices (later milestones); M1 lands the refactor in isolation with the local disk (`root`) still the only registered volume, so externally observable behavior is byte-identical.

- **Per-volume lifecycle, keyed independently.** Every invariant the single-volume design held now holds per volume id: single-writer-per-DB, lock-first reservation (`(absent) -> Initializing` claimed atomically per volume before building the heavy `IndexManager`), drop-the-guard-before-`mgr.shutdown()`'s 5 s drain, and reads via `ReadPool` never under the lifecycle lock. Two volumes can't corrupt each other; two starts for the same volume still can't race (the `UNIQUE(parent_id, name_folded)` safety net is unchanged).
- **Disabled is the absence of a key** — there's no `IndexPhase::Disabled` variant; stop/clear remove the instance after the drain.
- **Reads route by volume id.** `get_read_pool_for(vid)` / `get_pending_sizes_for(vid)` route root to the `READ_POOL`/`PENDING_SIZES` globals (the same `Arc` the root instance holds, so they can't drift — kept as globals because search reads them hot and the tests install them directly) and non-root to the registry instance. Enrichment, verification, and IPC dir-stats thread the listing's `volume_id` where they have it.
- **The `should_exclude` early-return in `enrichment.rs` is reframed to "skip if no index is registered for this volume"** (`get_read_pool_for` returns `None`). In M1 only `root` has a pool, so every non-root listing still early-returns exactly as before — same set of listings skipped, new reason. For `root` the local-path `should_exclude` check is also retained so a root-volume listing navigated under `/Volumes`, `/mnt`, or `/proc` still skips (no "Parent path not found" log-spam on network mounts).
- **IPC surface unchanged.** `#[tauri::command]` signatures and `bindings.ts` are byte-identical: path-based commands resolve the volume internally (M1: always `root`, with a `TODO(M2/M4)` for `/Volumes/<share>` and `mtp-*` virtual-path mapping); the scan/status/clear commands pass `ROOT_VOLUME_ID`.

Tests: added `state.rs::tests` for the registry (skip-vs-route gate tracks registration; two volume ids reserve/release independently and route to distinct pools). The existing `integration_tests.rs` enrichment/`ReadPool`/dir-stats/FDA regression tests pass with their assertions unchanged; the `IndexPhase` lifecycle harness tests were ported mechanically to the registry (same assertion intent — "phase Disabled" becomes "instance absent"). Full `pnpm check rust` green (clippy clean, `bindings-fresh` confirms the IPC surface, 2863 + 38 tests on macOS and the Linux Docker lane).

Left for later milestones (TODOs in-code): the memory watchdog still stops only `root` (M2 makes it a global budget), and `volume_id_for_local_path` maps everything to `root` until SMB/MTP backends register (M2/M4).

Author: vdavid

apps/desktop/src-tauri/src/commands/file_system/write_ops.rs

@@ -32,7 +32,7 @@ pub async fn create_directory(
     // Synthetic diff only works for volumes backed by the local filesystem.
     // Protocol-only volumes (MTP) handle UI updates through their own event systems.
     if should_emit_synthetic_diff(volume_id.as_deref()) {
-        emit_synthetic_entry_diff(&new_path, &PathBuf::from(&expanded_path));
+        emit_synthetic_entry_diff(volume_id.as_deref(), &new_path, &PathBuf::from(&expanded_path));
     }
     Ok(new_path.to_string_lossy().to_string())
 }
@@ -43,7 +43,7 @@ pub async fn create_file(volume_id: Option<String>, parent_path: String, name: S
     let (new_path, expanded_path) = create_file_core(volume_id.clone(), &parent_path, &name).await?;
 
     if should_emit_synthetic_diff(volume_id.as_deref()) {
-        emit_synthetic_entry_diff(&new_path, &PathBuf::from(&expanded_path));
+        emit_synthetic_entry_diff(volume_id.as_deref(), &new_path, &PathBuf::from(&expanded_path));
     }
     Ok(new_path.to_string_lossy().to_string())
 }
@@ -364,7 +364,7 @@ fn should_emit_synthetic_diff(volume_id: Option<&str>) -> bool {
 ///
 /// Best-effort: if any step fails (stat, cache lookup, etc.) we log a warning
 /// and return. The watcher will pick up the change later.
-fn emit_synthetic_entry_diff(entry_path: &Path, parent_path: &Path) {
+fn emit_synthetic_entry_diff(volume_id: Option<&str>, entry_path: &Path, parent_path: &Path) {
     use crate::file_system::listing::diff_emitter::enqueue_diff;
     use crate::file_system::listing::reading::get_single_entry;
     use crate::file_system::listing::{find_listings_for_path, insert_entry_sorted};
@@ -379,8 +379,10 @@ fn emit_synthetic_entry_diff(entry_path: &Path, parent_path: &Path) {
         }
     };
 
-    // 2. Enrich with index data
-    crate::indexing::enrich_entries_with_index(std::slice::from_mut(&mut entry));
+    // 2. Enrich with index data. `None` means the local filesystem (`root`); this
+    // path only runs for local-FS volumes (`should_emit_synthetic_diff`).
+    let volume_id = volume_id.unwrap_or(crate::indexing::ROOT_VOLUME_ID);
+    crate::indexing::enrich_entries_with_index_on_volume(volume_id, std::slice::from_mut(&mut entry));
 
     // 3. Find affected listings
     let listings = find_listings_for_path(parent_path);

apps/desktop/src-tauri/src/commands/indexing.rs

@@ -4,14 +4,19 @@
 
 use tauri::AppHandle;
 
-use crate::indexing::{self, IndexDebugStatusResponse, IndexStatusResponse, store::DirStats};
+use crate::indexing::{self, IndexDebugStatusResponse, IndexStatusResponse, ROOT_VOLUME_ID, store::DirStats};
+
+// IPC stays path-based and single-volume in M1: the index-status, scan, and
+// clear commands all act on the local-disk `root` index. The backend resolves
+// the volume internally (here, the constant `root`), so the frontend and
+// `bindings.ts` are unchanged. M2+ will widen these to carry a volume.
 
 #[tauri::command]
 #[specta::specta]
 pub async fn start_drive_index(app: AppHandle) -> Result<(), String> {
-    if indexing::is_active() {
+    if indexing::is_active(ROOT_VOLUME_ID) {
         // Already running: force a fresh full scan (for example, from the debug "Start scan" button)
-        indexing::force_scan()
+        indexing::force_scan(ROOT_VOLUME_ID)
     } else {
         indexing::start_indexing(&app)
     }
@@ -20,13 +25,13 @@ pub async fn start_drive_index(app: AppHandle) -> Result<(), String> {
 #[tauri::command]
 #[specta::specta]
 pub async fn stop_drive_index() -> Result<(), String> {
-    indexing::stop_scan()
+    indexing::stop_scan(ROOT_VOLUME_ID)
 }
 
 #[tauri::command]
 #[specta::specta]
 pub async fn get_index_status() -> Result<IndexStatusResponse, String> {
-    indexing::get_status()
+    indexing::get_status(ROOT_VOLUME_ID)
 }
 
 #[tauri::command]
@@ -44,26 +49,26 @@ pub async fn get_dir_stats_batch(paths: Vec<String>) -> Result<Vec<Option<DirSta
 #[tauri::command]
 #[specta::specta]
 pub async fn clear_drive_index() -> Result<(), String> {
-    indexing::clear_index()
+    indexing::clear_index(ROOT_VOLUME_ID)
 }
 
 /// Extended debug status for the debug window (dev only).
 #[tauri::command]
 #[specta::specta]
 pub async fn get_index_debug_status() -> Result<IndexDebugStatusResponse, String> {
-    indexing::get_debug_status()
+    indexing::get_debug_status(ROOT_VOLUME_ID)
 }
 
 /// Toggle drive indexing on/off based on the user's setting.
 #[tauri::command]
 #[specta::specta]
 pub async fn set_indexing_enabled(app: AppHandle, enabled: bool) -> Result<(), String> {
     if enabled {
-        if !indexing::is_active() {
+        if !indexing::is_active(ROOT_VOLUME_ID) {
             indexing::start_indexing(&app)?;
         }
     } else {
-        indexing::stop_indexing()?;
+        indexing::stop_indexing(ROOT_VOLUME_ID)?;
     }
     Ok(())
 }
@@ -105,7 +110,7 @@ pub async fn start_indexing_after_fda_decision(app: AppHandle) -> Result<(), Str
     #[cfg(any(target_os = "macos", target_os = "linux"))]
     crate::mtp::start_mtp_watcher(&app);
 
-    if indexing::is_active() {
+    if indexing::is_active(ROOT_VOLUME_ID) {
         return Ok(());
     }
     indexing::start_indexing(&app)

apps/desktop/src-tauri/src/file_system/listing/caching.rs

@@ -428,7 +428,7 @@ pub fn notify_directory_changed(volume_id: &str, parent_path: &Path, change: Dir
     match change {
         DirectoryChange::Added(entry) => {
             let mut entry = entry;
-            crate::indexing::enrich_entries_with_index(std::slice::from_mut(&mut entry));
+            crate::indexing::enrich_entries_with_index_on_volume(volume_id, std::slice::from_mut(&mut entry));
             for (listing_id, ..) in &listings {
                 notify_added(listing_id, entry.clone());
             }
@@ -441,14 +441,14 @@ pub fn notify_directory_changed(volume_id: &str, parent_path: &Path, change: Dir
         }
         DirectoryChange::Modified(entry) => {
             let mut entry = entry;
-            crate::indexing::enrich_entries_with_index(std::slice::from_mut(&mut entry));
+            crate::indexing::enrich_entries_with_index_on_volume(volume_id, std::slice::from_mut(&mut entry));
             for (listing_id, ..) in &listings {
                 notify_modified(listing_id, entry.clone());
             }
         }
         DirectoryChange::Renamed { old_name, new_entry } => {
             let mut new_entry = new_entry;
-            crate::indexing::enrich_entries_with_index(std::slice::from_mut(&mut new_entry));
+            crate::indexing::enrich_entries_with_index_on_volume(volume_id, std::slice::from_mut(&mut new_entry));
             let old_path = parent_path.join(&old_name);
             for (listing_id, ..) in &listings {
                 notify_removed(listing_id, &old_path);
@@ -600,7 +600,7 @@ async fn notify_full_refresh(
         }
     };
 
-    crate::indexing::enrich_entries_with_index(&mut new_entries);
+    crate::indexing::enrich_entries_with_index_on_volume(&volume_id, &mut new_entries);
 
     for (listing_id, sort_by, sort_order, dir_sort_mode) in &listings {
         // Re-sort to match this listing's sort params

apps/desktop/src-tauri/src/file_system/listing/mod.rs

@@ -29,8 +29,8 @@ pub use operations::{get_files_at_indices, get_paths_at_indices};
 
 // Internal re-exports for file_system module internals (pub(crate) for crate-internal use)
 pub(crate) use caching::{
-    ModifyResult, find_listings_for_path, get_listing_path, get_listing_volume_id_and_path, has_entry,
-    increment_sequence, insert_entry_sorted, remove_entry_by_path, start_orphan_listing_reaper, update_entry_sorted,
+    ModifyResult, find_listings_for_path, get_listing_volume_id_and_path, has_entry, increment_sequence,
+    insert_entry_sorted, remove_entry_by_path, start_orphan_listing_reaper, update_entry_sorted,
 };
 // Notification API for volume mutations
 #[cfg(any(target_os = "macos", target_os = "linux"))]

apps/desktop/src-tauri/src/file_system/listing/operations.rs

@@ -77,8 +77,8 @@ pub async fn list_directory_start_with_volume(
     // Enrich directory entries with index data (recursive_size etc.) before sorting,
     // so that sort-by-size works correctly for directories.
     let mut all_entries = all_entries;
-    crate::indexing::enrich_entries_with_index(&mut all_entries);
-    crate::indexing::trigger_verification(&path.to_string_lossy());
+    crate::indexing::enrich_entries_with_index_on_volume(volume_id, &mut all_entries);
+    crate::indexing::trigger_verification(volume_id, &path.to_string_lossy());
 
     // Sort the entries
     sort_entries(&mut all_entries, sort_by, sort_order, dir_sort_mode);
@@ -369,7 +369,8 @@ pub fn resort_listing(
     };
 
     // Refresh index data before re-sorting (cache entries may not have fresh sizes)
-    crate::indexing::enrich_entries_with_index(&mut listing.entries);
+    let volume_id = listing.volume_id.clone();
+    crate::indexing::enrich_entries_with_index_on_volume(&volume_id, &mut listing.entries);
 
     // Re-sort the entries
     sort_entries(&mut listing.entries, sort_by, sort_order, dir_sort_mode);
@@ -421,7 +422,7 @@ pub(crate) fn update_listing_entries(listing_id: &str, entries: Vec<FileEntry>)
     {
         listing.touch();
         let mut entries = entries;
-        crate::indexing::enrich_entries_with_index(&mut entries);
+        crate::indexing::enrich_entries_with_index_on_volume(&listing.volume_id, &mut entries);
         sort_entries(
             &mut entries,
             listing.sort_by,
@@ -585,7 +586,8 @@ pub fn get_listing_stats(
 pub fn refresh_listing_index_sizes(listing_id: &str) -> Result<(), String> {
     let mut cache = LISTING_CACHE.write().map_err(|_| "Failed to acquire cache lock")?;
     if let Some(listing) = cache.get_mut(listing_id) {
-        crate::indexing::enrich_entries_with_index(&mut listing.entries);
+        let volume_id = listing.volume_id.clone();
+        crate::indexing::enrich_entries_with_index_on_volume(&volume_id, &mut listing.entries);
     }
     Ok(())
 }

apps/desktop/src-tauri/src/file_system/listing/streaming.rs

@@ -473,9 +473,9 @@ pub(crate) async fn read_directory_with_progress(
     // Enrich directory entries with index data (recursive_size etc.) before sorting,
     // so that sort-by-size works correctly for directories.
     let enrich_start = std::time::Instant::now();
-    crate::indexing::enrich_entries_with_index(&mut entries);
+    crate::indexing::enrich_entries_with_index_on_volume(volume_id, &mut entries);
     let enrich_ms = enrich_start.elapsed().as_millis();
-    crate::indexing::trigger_verification(&path.to_string_lossy());
+    crate::indexing::trigger_verification(volume_id, &path.to_string_lossy());
 
     // Sort entries
     benchmark::log_event("sort START");

apps/desktop/src-tauri/src/file_system/watcher.rs

@@ -19,8 +19,8 @@ use tauri::AppHandle;
 use tauri_specta::Event as _;
 
 use crate::file_system::listing::{
-    FileEntry, ModifyResult, get_listing_entries, get_listing_path, get_single_entry, has_entry, insert_entry_sorted,
-    list_directory_core, remove_entry_by_path, update_entry_sorted, update_listing_entries,
+    FileEntry, ModifyResult, get_listing_entries, get_listing_volume_id_and_path, get_single_entry, has_entry,
+    insert_entry_sorted, list_directory_core, remove_entry_by_path, update_entry_sorted, update_listing_entries,
 };
 
 /// Default debounce duration in milliseconds (used if not configured)
@@ -204,8 +204,8 @@ fn handle_directory_change_incremental(listing_id: &str, events: Vec<DebouncedEv
         return;
     }
 
-    // Get watched directory path from the cache (without cloning all entries)
-    let Some(dir_path) = get_listing_path(listing_id) else {
+    // Get watched directory path + volume from the cache (without cloning all entries)
+    let Some((volume_id, dir_path)) = get_listing_volume_id_and_path(listing_id) else {
         return;
     };
 
@@ -256,10 +256,10 @@ fn handle_directory_change_incremental(listing_id: &str, events: Vec<DebouncedEv
 
     // Enrich new/modified entries with index data
     for entry in &mut adds {
-        crate::indexing::enrich_entries_with_index(std::slice::from_mut(entry));
+        crate::indexing::enrich_entries_with_index_on_volume(&volume_id, std::slice::from_mut(entry));
     }
     for entry in &mut modifies {
-        crate::indexing::enrich_entries_with_index(std::slice::from_mut(entry));
+        crate::indexing::enrich_entries_with_index_on_volume(&volume_id, std::slice::from_mut(entry));
     }
 
     // Apply changes: removes first (indices refer to OLD listing), then adds, then modifies.
@@ -443,7 +443,7 @@ pub async fn handle_directory_change(listing_id: &str) {
         if let Ok(cache) = LISTING_CACHE.read()
             && let Some(listing) = cache.get(listing_id)
         {
-            crate::indexing::enrich_entries_with_index(&mut new_entries);
+            crate::indexing::enrich_entries_with_index_on_volume(&listing.volume_id, &mut new_entries);
             sort_entries(
                 &mut new_entries,
                 listing.sort_by,

apps/desktop/src-tauri/src/indexing/CLAUDE.md

@@ -5,7 +5,8 @@ size aggregates so listings can show directory sizes.
 
 ## Module map
 
-- **Lifecycle / state**: `state.rs` (`IndexPhase` machine, `INDEXING` mutex, public API), `manager.rs` (coordinator).
+- **Lifecycle / state**: `state.rs` (`IndexPhase` machine, the per-volume `INDEX_REGISTRY`, public API), `manager.rs`
+  (per-volume coordinator).
 - **Write path**: `writer/` (single writer thread + write connection; `mod.rs` = protocol + loop, `entries.rs` /
   `delta.rs` / `aggregation.rs` / `maintenance.rs` = handlers), `scanner.rs` (jwalk walk), `aggregator.rs` (dir-stats),
   `reconciler.rs` + `event_loop.rs` (replay + live FSEvents).
@@ -16,39 +17,45 @@ size aggregates so listings can show directory sizes.
 
 ## Must-knows (invariants and guardrails)
 
-- **Single-writer thread.** All writes go through one writer thread via a bounded `sync_channel` (backpressure on full).
-  Reads use a `ReadPool` of thread-local WAL connections, NOT the `INDEXING` mutex (which guards only lifecycle
-  transitions); don't move read paths (enrichment, verification, IPC dir-stats) back under it. `stop_indexing` and
-  `clear_index` must drop the guard BEFORE `mgr.shutdown()`'s 5 s drain.
+- **Per-volume registry.** `INDEX_REGISTRY: Mutex<HashMap<VolumeId, IndexInstance{phase, read_pool, pending_sizes}>>` is
+  the authority for which volumes are indexed; an absent key = disabled (no `Disabled` phase). Every invariant below
+  holds PER volume id; in M1 only `root` is registered, so behavior is byte-identical to single-volume. Reads route by
+  volume id (`get_read_pool_for`); enrichment SKIPS when it returns `None` ("no index registered", replacing the old
+  `should_exclude` early-return, so non-root listings skip with zero DB work). Root's pool/tracker stay in the
+  `READ_POOL`/`PENDING_SIZES` globals (same `Arc` the root instance holds). DETAILS § registry.
+- **Single-writer thread, per DB; reads off the lock.** Writes go through one writer thread (bounded `sync_channel`,
+  backpressure on full). Reads use the per-volume `ReadPool` (thread-local WAL conns), NOT the registry mutex (lifecycle
+  only); don't move read paths back under it. `stop_indexing` / `clear_index` take/remove the instance under the lock,
+  then drop the guard BEFORE `mgr.shutdown()`'s 5 s drain.
 - **`platform_case` collation must be registered on every connection.** It isn't persisted, so the `sqlite3` CLI fails
   on any query touching `name`; use `index-query`.
-- **Don't drop `UNIQUE (parent_id, name_folded)`**: it's the data-safety net against two writers racing on one DB
-  (seen once as a 1.83 TB ghost size). Don't drop `name_folded` either; without it the composite-index rebuild takes
-  ~25 min on macOS.
+- **Don't drop `UNIQUE (parent_id, name_folded)`** (data-safety net against two writers racing on one DB; seen once as a
+  1.83 TB ghost size) **nor `name_folded`** (without it the composite-index rebuild takes ~25 min on macOS).
 - **Scanner uses `INSERT OR IGNORE`, not `INSERT OR REPLACE`.** REPLACE reassigns IDs (orphaning children) and is
-  catastrophically slow on a populated DB. `start_scan` truncates `entries` + `dir_stats` before every scan, and the
+  catastrophically slow on a populated DB. `start_scan` truncates `entries` + `dir_stats` before every scan; the
   accumulator counts only rows that landed (per-row OR-IGNORE flags), never bytes a row lost.
-- **Mid-scan partial aggregation must BORROW the accumulator maps read-only, never consume/mutate them**, and its
-  empty-maps no-op must stay SQL-free (a late partial pass legitimately lands after the final aggregation cleared the
-  maps). Either violation silently ships wrong sizes. Keep `try_send` non-blocking, and fire partial passes only from
-  the full-scan progress loop (its death scopes them to the scan window).
+- **Mid-scan partial aggregation must BORROW the accumulator maps read-only** (never consume/mutate), and its empty-maps
+  no-op must stay SQL-free (a late pass legitimately lands after the final aggregation cleared the maps) — either
+  violation silently ships wrong sizes. Keep `try_send` non-blocking; fire passes only from the full-scan progress loop.
 - **The index is a disposable cache.** Schema-version mismatch drops + rebuilds; corruption heals by rescan; no online
   migrations or user-facing DB errors. Bounded buffers make dropping events then rescanning safe.
-- **An interrupted scan must heal to a fresh rescan**, via two cooperating writes: `start_scan` clears
-  `scan_completed_at` before truncating, and the completion handler writes meta only when `!was_cancelled`. Gate only
-  the meta writes on it, never the reconcile/live transition.
-- **`start_indexing` is lock-first**: claim `Disabled -> Initializing` atomically BEFORE building the heavy
-  `IndexManager`, else two near-simultaneous starts spawn writer threads racing on one DB.
+- **An interrupted scan heals to a fresh rescan** via two cooperating writes: `start_scan` clears `scan_completed_at`
+  before truncating; the completion handler writes meta only when `!was_cancelled`. Gate only the meta writes, never the
+  reconcile/live transition.
+- **`start_indexing` is lock-first, per volume**: claim `(absent) -> Initializing` for that volume id atomically BEFORE
+  building the heavy `IndexManager`, else two starts for the SAME volume race writer threads on one DB. Different volumes
+  start freely.
 - **Reconciler/event loops hold a READ connection** (`open_read_connection`), never a write one: write-mode pragmas can
-  `SQLITE_BUSY` and silently kill live indexing for the session.
-- **Defer indexer auto-start until FDA is decided** (`should_auto_start_indexing`): a first-launch scan from `/` opens
-  TCC-protected dirs and stacks native popups over the FDA modal.
+  `SQLITE_BUSY` and silently kill live indexing.
+- **Defer `root` auto-start until FDA is decided** (`should_auto_start_indexing`): a first-launch scan from `/` stacks
+  TCC popups over the FDA modal. FDA gates ONLY `root` — future SMB/MTP starts must not route through it (not
+  TCC-protected).
 - **macOS: the writer thread (and any thread calling ObjC/Cocoa) must wrap work in `objc2::rc::autoreleasepool`** or
-  autoreleased `NSData` / `NSInvocation` objects leak (multi-GB over hours).
-- **Spawn indexing tasks with `tauri::async_runtime::spawn`, not `tokio::spawn`**: indexing can start from the sync
-  `setup()` hook, where `tokio::spawn` panics (no runtime).
+  autoreleased `NSData` / `NSInvocation` leak (multi-GB over hours).
+- **Spawn indexing tasks with `tauri::async_runtime::spawn`, not `tokio::spawn`** (indexing can start from the sync
+  `setup()` hook, where `tokio::spawn` panics).
 - **`IndexWriter` owns the shared `Arc<AtomicI64>` ID counter.** Don't allocate IDs from `MAX(id)` on a read connection:
-  uncommitted channel inserts make it stale and double-assign IDs.
+  uncommitted channel inserts make it stale and double-assign.
 - **FSEvents `item_removed` must be stat-verified before deleting** (atomic swaps and coalesced events deliver false
   removals); upsert instead when the path exists.