Selection: Rust backend (M5)

- New `selection/` module mirroring `search/` but narrower (no scope, no system-dir exclusion).
- `selection/history.rs`: persistent recent-selections store at `{app_data_dir}/selection-history.json`. Atomic write, schema-versioned (v1), canonical-key dedupe over `mode|normalized_query|filters|case_sensitive`, cap eviction (default 1000, 0 disables). Re-exports `HistoryMode` and `HistoryFilters` from `search::history` so the wire shape stays in sync.
- `selection/ai/{prompt,parser,query_builder}.rs`: cloud-only LLM pipeline. Key-value response (`pattern`, `kind`, `size_min`, `size_max`, `modified_after`, `modified_before`, `note`, `label`). The prompt grounds the model in a sample of the focused folder's filenames so "every rymd file" → `*rymd*`.
- `commands/selection.rs`: 6 IPC commands wired through specta (`translate_selection_query`, `get_recent_selections`, `add_recent_selection`, `remove_recent_selection`, `clear_recent_selections`, `apply_recent_selections_max_count`). `translate_selection_query` hard-errors when the AI provider isn't `cloud`.
- Settings registry + applier wire `selection.recentSelections.maxCount` (default 1000, range 0-10000) with live-apply.
- 62 Rust unit tests for history + AI pipeline (canonical key, dedupe, cap, schema-version quarantine, prompt assembly, parser edge cases, builder filter combinations).
- 11 IPC contract tests under `lib/ipc/selection.test.ts` pin the wire shape for destructive `clear_recent_selections` and cross-window `apply_recent_selections_max_count`.
- 6 `#[ignore]`-gated real-OpenAI eval tests (`selection::ai::real_llm_eval_test`) confirm the prompt + parser produce parseable results across 6 representative intents. All 6 pass against `gpt-4o-mini`.
- Bindings regenerated; `bindings-fresh` green. Full default check suite green for Rust + new TS tests; pre-existing svelte-check/eslint failures in `query-ui/QueryDialog.*` and `search-state.svelte.ts` belong to M4 frontend work, not this commit.
- Docs: new `selection/CLAUDE.md`, `search/CLAUDE.md` updated to call out the shared history types, `docs/architecture.md` adds a `selection/` row.

Author: vdavid

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

@@ -22,6 +22,7 @@ pub mod network;
 pub mod rename;
 pub mod restricted_paths;
 pub mod search;
+pub mod selection;
 pub mod settings;
 pub mod smb_diagnostics;
 pub mod sync_status; // Has both macOS and non-macOS implementations

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

@@ -0,0 +1,161 @@
+//! IPC commands for the Selection dialog (M5).
+//!
+//! Thin wrappers around `crate::selection`. The selection AI translation is
+//! cloud-only: small local models can't reliably handle a 200+-name folder sample
+//! plus the structured prompt and response. `translate_selection_query` returns a
+//! hard error when the configured provider isn't `cloud` so the UI can toast the
+//! reason; the frontend hides the AI chip when the provider isn't cloud so we
+//! never reach this path in normal use.
+
+use genai::chat::ChatOptions;
+
+use crate::ai::client::AiBackend;
+use crate::ai::manager::BackendResolution;
+
+use crate::selection::ai::{self, SelectionTranslateResult, query_builder};
+use crate::selection::history::{self, SelectionHistoryEntry};
+
+/// Resolves the AI backend, requiring a cloud provider.
+///
+/// Mirrors `commands::search::resolve_ai_backend` but adds the cloud-only gate. The
+/// frontend hides the AI chip when `ai.provider !== 'cloud'`; this gate is the
+/// belt-and-braces check so a misconfigured frontend (or an MCP caller in the
+/// future) can't drive the local model with a prompt it can't handle.
+fn resolve_cloud_ai_backend() -> Result<AiBackend, String> {
+    let provider = crate::ai::manager::get_provider();
+    if provider != "cloud" {
+        return Err("AI selection needs a cloud provider. Set one in Settings > AI.".to_string());
+    }
+    match crate::ai::manager::resolve_backend() {
+        BackendResolution::Ready(b) => Ok(b),
+        BackendResolution::Off => Err("AI is not configured. Enable a cloud provider in settings.".to_string()),
+        BackendResolution::NotConfigured(reason) => Err(reason.to_string()),
+        BackendResolution::UnknownProvider(p) => Err(format!("Unknown AI provider: {p}")),
+    }
+}
+
+/// Translates a natural-language selection request into a glob/regex plus optional
+/// size and date filters.
+///
+/// The `sample_names` argument is the focused folder's filename listing (already
+/// sampled on the frontend; see `lib/selection-dialog/folder-sampler.ts` for the
+/// sampling strategy). It grounds the prompt in what's actually in the folder.
+#[tauri::command]
+#[specta::specta]
+pub async fn translate_selection_query(
+    prompt: String,
+    sample_names: Vec<String>,
+) -> Result<SelectionTranslateResult, String> {
+    let backend = resolve_cloud_ai_backend()?;
+    let system_prompt = ai::build_classification_prompt(&sample_names);
+
+    log::debug!(
+        target: "selection::ai",
+        "translate_selection_query: prompt={prompt:?}, sample_count={}, system_prompt_chars={}",
+        sample_names.len(),
+        system_prompt.len()
+    );
+
+    let options = ChatOptions::default()
+        .with_temperature(0.2)
+        .with_max_tokens(300)
+        .with_top_p(0.9);
+
+    let t0 = std::time::Instant::now();
+    let response = crate::ai::client::chat_completion(&backend, &system_prompt, &prompt, &options)
+        .await
+        .map_err(|e| {
+            log::warn!(
+                target: "selection::ai",
+                "chat_completion failed after {:.1}s for prompt={prompt:?}: {e}",
+                t0.elapsed().as_secs_f64()
+            );
+            format!("{e}")
+        })?;
+
+    log::info!(
+        target: "selection::ai",
+        "translate_selection_query: response {} chars in {:.1}s",
+        response.len(),
+        t0.elapsed().as_secs_f64()
+    );
+    log::debug!(target: "selection::ai", "translate_selection_query raw response: {response:?}");
+
+    let parsed = ai::parse_selection_response(&response);
+    Ok(query_builder::build_selection_translate_result(&parsed))
+}
+
+// ============================================================================
+// Recent selections (history) IPC
+// ============================================================================
+
+/// Returns the persisted recent-selections entries (newest first). `limit = None`
+/// returns all.
+#[tauri::command]
+#[specta::specta]
+pub fn get_recent_selections(limit: Option<u32>) -> Vec<SelectionHistoryEntry> {
+    history::list_entries(limit.map(|n| n as usize))
+}
+
+/// Adds a recent-selection entry. Dedupes against existing entries by canonical
+/// key, moves the matching one to the top, and trims to `max_count`.
+#[tauri::command]
+#[specta::specta]
+pub fn add_recent_selection(
+    app: tauri::AppHandle,
+    entry: SelectionHistoryEntry,
+    max_count: Option<u32>,
+) -> Result<(), String> {
+    let cap = max_count.map(|n| n as usize).unwrap_or_else(history::default_max_count);
+    history::add_entry(&app, entry, cap);
+    Ok(())
+}
+
+/// Removes a recent-selection entry by id. No-op when the id isn't present.
+#[tauri::command]
+#[specta::specta]
+pub fn remove_recent_selection(app: tauri::AppHandle, id: String) -> Result<(), String> {
+    history::remove_entry(&app, &id);
+    Ok(())
+}
+
+/// Clears every recent-selection entry.
+#[tauri::command]
+#[specta::specta]
+pub fn clear_recent_selections(app: tauri::AppHandle) -> Result<(), String> {
+    history::clear_entries(&app);
+    Ok(())
+}
+
+/// Live-applies a new `selection.recentSelections.maxCount` value. Trims the
+/// in-memory store and rewrites disk only when entries actually drop.
+#[tauri::command]
+#[specta::specta]
+pub fn apply_recent_selections_max_count(app: tauri::AppHandle, max_count: u32) -> Result<(), String> {
+    history::apply_max_count(&app, max_count as usize);
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn translate_result_serialization_round_trips() {
+        let r = SelectionTranslateResult {
+            pattern: Some("*.log".to_string()),
+            kind: Some("glob".to_string()),
+            size_min: Some(1024),
+            size_max: None,
+            modified_after: Some("2026-01-01".to_string()),
+            modified_before: None,
+            caveat: None,
+            label: Some("Log files".to_string()),
+        };
+        let json = serde_json::to_string(&r).unwrap();
+        assert!(json.contains("\"pattern\":\"*.log\""));
+        assert!(json.contains("\"sizeMin\":1024"));
+        assert!(json.contains("\"modifiedAfter\":\"2026-01-01\""));
+        assert!(json.contains("\"label\":\"Log files\""));
+    }
+}

apps/desktop/src-tauri/src/ipc.rs

@@ -495,6 +495,12 @@ pub fn builder() -> Builder<tauri::Wry> {
         crate::commands::search::remove_recent_search,
         crate::commands::search::clear_recent_searches,
         crate::commands::search::apply_recent_searches_max_count,
+        crate::commands::selection::translate_selection_query,
+        crate::commands::selection::get_recent_selections,
+        crate::commands::selection::add_recent_selection,
+        crate::commands::selection::remove_recent_selection,
+        crate::commands::selection::clear_recent_selections,
+        crate::commands::selection::apply_recent_selections_max_count,
         crate::commands::e2e::get_e2e_start_path,
         crate::commands::e2e::is_e2e_mode,
         #[cfg(feature = "playwright-e2e")]

apps/desktop/src-tauri/src/ipc_collectors.rs

@@ -190,6 +190,12 @@ pub(crate) fn collect_cross_platform_types(types: &mut Types) -> Vec<Function> {
         crate::commands::search::remove_recent_search,
         crate::commands::search::clear_recent_searches,
         crate::commands::search::apply_recent_searches_max_count,
+        crate::commands::selection::translate_selection_query,
+        crate::commands::selection::get_recent_selections,
+        crate::commands::selection::add_recent_selection,
+        crate::commands::selection::remove_recent_selection,
+        crate::commands::selection::clear_recent_selections,
+        crate::commands::selection::apply_recent_selections_max_count,
         crate::commands::e2e::get_e2e_start_path,
         crate::commands::e2e::is_e2e_mode,
         crate::commands::clipboard::copy_files_to_clipboard,

apps/desktop/src-tauri/src/lib.rs

@@ -121,6 +121,7 @@ mod redact;
 mod restricted_paths;
 pub mod search;
 mod secrets;
+pub mod selection;
 mod settings;
 mod short_id;
 mod space_poller;
@@ -455,6 +456,9 @@ pub fn run() {
             // Load persisted recent search history into the in-memory cache.
             search::history::load_history(app.handle());
 
+            // Same for recent selections (Selection dialog history).
+            selection::history::load_history(app.handle());
+
             // Load manually-added servers and inject into discovery state
             #[cfg(any(target_os = "macos", target_os = "linux"))]
             network::manual_servers::load_manual_servers(app.handle());

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

@@ -67,6 +67,21 @@ field is missing (`build_label` returns `None`).
 **Decision**: Single LLM pass, no refinement.
 **Why**: The previous two-pass system (translate + refine) caused regressions ~15% of the time (over-narrowing, flag dropping). With deterministic structure, there's nothing to refine. Also halves LLM latency.
 
+## Sharing with `selection/`
+
+`crate::selection::history` re-exports `HistoryMode` and `HistoryFilters` from this
+module's `history.rs`. The two pure data types are identical in intent across Search
+and Selection, so the wire shape stays in sync. The entry struct itself
+(`HistoryEntry` here vs `SelectionHistoryEntry`) stays separate because the canonical
+dedupe keys differ (Selection has no scope or exclude-system-dirs). If the mode set
+ever forks between consumers, drop the re-export and copy the types.
+
+The AI parser helpers in `search/ai/parser.rs` are NOT shared with Selection: the
+fields are different (Selection has no `keywords` / `type` / `scope` / `folders`), so
+sharing would have meant exporting a few low-level helpers (`is_year`, `is_range`)
+that aren't worth the coupling. Selection's parser lives independently in
+`crate::selection::ai::parser`.
+
 ## Coupling to `indexing/`
 
 `search/` is a read-only consumer of the indexing DB via `ReadPool`, `WRITER_GENERATION`, and `store::resolve_path`. This is intentional -- search reads from the index but doesn't participate in indexing. The dependency is one-way (`search` -> `indexing`, never reverse) and narrow:

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

@@ -0,0 +1,161 @@
+# Selection module
+
+Backend for the Selection dialog (Select files / Deselect files). Mirrors `crate::search`
+but narrower: there is no scope, no system-dir exclusion, no in-memory index, and the
+matcher itself runs in JS against the focused folder's entries. This module owns just
+the persistent history store and the AI translation pipeline.
+
+## Module structure
+
+| File | Purpose |
+|------|---------|
+| `mod.rs` | Re-exports the public surface. |
+| `history.rs` | `SelectionHistoryEntry`, atomic JSON read/write, canonical-key dedupe, cap eviction, schema-version quarantine. Re-exports `HistoryMode` and `HistoryFilters` from `crate::search::history` so the frontend sees the same mode/filter shape for both consumers. |
+| `ai/mod.rs` | Re-exports the AI submodules. |
+| `ai/prompt.rs` | `build_classification_prompt(sample_names)` and `format_sample_block`. Pure functions; no IPC. Returns the system-prompt string the LLM receives. |
+| `ai/parser.rs` | `parse_selection_response(text)` → `ParsedSelectionLlmResponse`. Key-value line parser; mirrors `search::ai::parser` in style but with the narrower field set. |
+| `ai/query_builder.rs` | `build_selection_translate_result(parsed)` → `SelectionTranslateResult`. Assembles the result type that crosses IPC; `generate_caveat` and `build_label` are the supporting helpers. |
+
+The IPC layer is in `crate::commands::selection`.
+
+## History store
+
+Persistent recent-selections store for the dialog's footer + popover. Same atomic-write
+story as `crate::search::history`; the key tradeoffs are:
+
+- **Persistence path**: `{app_data_dir}/selection-history.json`. Schema-versioned via
+  `_schemaVersion` (currently `1`).
+- **In-memory cache + disk lock**: in-memory `Mutex<HistoryStore>` plus a separate
+  `OnceLock<Mutex<()>>` (`DISK_LOCK`) that serializes the read-modify-write cycle so
+  concurrent IPC commands can't lose writes. Cache guards drop before any `fs` call.
+- **Canonical dedupe key**: `mode | normalized_query | filters | case_sensitive`. Four
+  segments; Search's key has six (it adds `scope` and `exclude_system_dirs`). Filters
+  serialize as alphabetically-keyed `k=v,k=v` pairs with undefined fields omitted. The
+  key is never persisted; it only exists at compare time.
+- **Recovery**: parse failure or schema-version mismatch → rename file to `.broken`,
+  start fresh. The user keeps using the dialog; the corrupted file is preserved for
+  one rotation in case debugging is needed.
+- **Cap**: configurable via `selection.recentSelections.maxCount` (default 1000).
+  `apply_max_count` trims the in-memory store on live-apply; `0` clears everything and
+  short-circuits future adds.
+
+### Decision: separate `selection-history.json` from `search-history.json`
+
+Storing both consumers' history in one file with a `kind` discriminator was rejected.
+Their schemas already diverge (`scope` and `exclude_system_dirs` are irrelevant for
+Selection), and coupling two unrelated migrations forever didn't earn its keep. The
+small cost of two files is invisible at runtime.
+
+### Decision: re-export `HistoryMode` and `HistoryFilters` from `search::history`
+
+The two pure data types are identical in intent across the two consumers. The
+`SelectionHistoryEntry` struct itself stays separate so the on-disk schema doesn't bind
+Selection to Search's canonical-key shape. If Search's mode set or filter shape ever
+diverges from Selection's, the re-export drops out and the types fork; the wiring is
+already isolated enough that the change is mechanical.
+
+## AI translation
+
+The `translate_selection_query(prompt, sample_names)` IPC orchestrates:
+
+1. Verifies the AI provider is `cloud`. Small local models (4-8K context) can't
+   reliably fit a 200+-name folder sample plus the structured prompt and response, so
+   the backend hard-errors when provider isn't cloud. The frontend hides the AI chip
+   in that case, but this gate is the belt-and-braces check for an MCP caller or a
+   misconfigured frontend.
+2. Calls `ai::build_classification_prompt(&sample_names)` to assemble the system
+   prompt with today's date and the folder sample.
+3. Runs `chat_completion` via `crate::ai::client` against the configured cloud backend
+   with `temperature: 0.2`, `max_tokens: 300`, `top_p: 0.9`.
+4. Parses the response via `ai::parse_selection_response` into a
+   `ParsedSelectionLlmResponse`.
+5. Builds the wire-result via `ai::build_selection_translate_result`.
+
+### Decision: cloud-only AI for Selection
+
+Folder samples weigh 1-3k tokens; the prompt plus completion lives ~4-5k tokens. Local
+4-8K context models often can't fit the full payload, and quality on small models is
+unreliable for pattern inference. We surface a tooltip on the gated UI in the frontend
+("AI selection needs a cloud provider. Set one in Settings > AI."); the backend
+returns the same message as a hard error for any non-cloud caller.
+
+### Decision: key-value response format, not JSON
+
+Same rationale as `crate::search::ai`. JSON generation is the #1 failure mode for
+small LLMs. Key-value lines are trivial to produce and parse, missing lines are
+individually skippable, and malformed lines never void the whole response.
+
+### Decision: `pattern` + `kind` instead of structured filter types
+
+The matcher runs on the frontend in JS. There's no benefit to round-tripping a typed
+glob through Rust; the parsed string IS the contract. The kind is `glob` (full-name
+match, `*` and `?` only) or `regex` (JS RegExp). When `pattern` is missing or blank,
+`kind` is forced to `None` so the frontend doesn't compile a half-built query.
+
+### Decision: default `kind` to `glob` when the model omits it
+
+The model occasionally forgets to emit `kind:` for obvious globs (`*.png`, `*.log`).
+Defaulting saves a re-prompt. The parser still drops `kind` to `None` when the value
+isn't one of `glob`/`regex`; the builder catches the missing-kind-with-pattern case
+and substitutes `glob`.
+
+## Real-LLM eval results
+
+The prompt + parser are pinned by `selection/ai/real_llm_eval_test.rs`, six
+`#[ignore]`-gated integration tests against the live OpenAI API. Run them with:
+
+```sh
+OPENAI_API_KEY=$(security find-generic-password -a "$USER" -s "OPENAI_API_KEY" -w) \
+  cargo nextest run --lib --run-ignored only selection::ai::real_llm_eval_test
+```
+
+The default model is `gpt-4o-mini` (cheap, fast, comparable to the model David has
+configured in his Settings UI for everyday use). When David's cloud-provider model
+changes, edit `MODEL` in the eval file and rerun.
+
+| Intent | Sample shape | Assertions | Status |
+|---|---|---|---|
+| "all log files" | mixed `.log` / `.txt` / `.md` / `.png` | pattern contains `log`, `kind` set | passing |
+| "png and jpg images" | mixed image + text extensions | pattern mentions both png and jpg/jpeg | passing |
+| "files bigger than 5 MB" | mixed sizes | `size_min` ∈ [4 MB, 10 MB], pattern present | passing |
+| "backups from last week" | `*-backup-*` files plus noise | `modified_after` set | passing |
+| "every rymd file" | `rymd-*.pdf` plus noise | pattern matches the keyword | passing |
+| "final drafts I haven't shared" | `Final-*` files | pattern OR caveat present (no half-built query) | passing |
+
+The eval also surfaces drift: a prompt change that breaks one of these assertions
+shows up before the dialog wraps around it. Iterate the prompt, rerun the eval, ship
+the prompt change with green tests.
+
+For ad-hoc debugging (peek at the raw model response), add an `eprintln!` to the
+`translate` helper temporarily (allowed in `#[cfg(test)]` blocks for `--no-capture`
+runs); revert before commit so the crate-level deny on `print_stderr` stays clean.
+Alternatively, run the dialog through the live app and tail
+`RUST_LOG=cmdr_lib::selection::ai=debug pnpm dev`.
+
+## IPC surface
+
+All commands live in `crate::commands::selection`:
+
+| Command | Purpose |
+|---|---|
+| `translate_selection_query(prompt, sample_names)` | AI translation; cloud-only. Returns `SelectionTranslateResult` or an error string. |
+| `get_recent_selections(limit)` | Returns persisted entries (newest first). |
+| `add_recent_selection(entry, max_count)` | Adds + dedupes + caps. |
+| `remove_recent_selection(id)` | Removes by id; no-op when missing. |
+| `clear_recent_selections()` | Drops every entry. |
+| `apply_recent_selections_max_count(max_count)` | Live-applies a freshly-tuned cap. |
+
+All six are registered in `crate::ipc::builder` (runtime dispatch) and
+`crate::ipc_collectors::collect_cross_platform_types` (specta). The bindings appear
+in `apps/desktop/src/lib/ipc/bindings.ts`; the typed wrappers live in
+`apps/desktop/src/lib/tauri-commands/selection.ts`.
+
+## Coupling to other modules
+
+- `crate::search::history`: re-exports `HistoryMode` and `HistoryFilters`. One-way.
+- `crate::ai::manager` + `crate::ai::client`: backend resolution and chat completion.
+  Mirrors `crate::commands::search`'s usage exactly.
+- `crate::config::resolved_app_data_dir`: shared persistence-path resolver.
+
+No other modules depend on `selection`; the dialog frontend and command-dispatch wiring
+land in M7.