semantex-core 1.1.0

use super::agent_classifier::{AgentRoute, classify_agent_query, extract_symbol};
use super::agent_formatter::{
    DEFAULT_BUDGET, FormatStyle, append_disambiguation_block, format_code_blocks,
    format_deep_results, format_graph_results, format_search_results,
};
use crate::index::architecture::budget_for_chunk_count;
use crate::search::SearchQuery;
use crate::search::deep as deep_search_module;
use crate::search::hybrid::HybridSearcher;
use crate::server::handler::{
    AdaptiveGraphWalk, AdaptiveOptions, compute_confidence, deep_result_to_response,
    graph_walk_from_store_adaptive, search_result_to_item,
};
use crate::server::protocol::{
    AgentMetrics, AgentRequest, AgentResponse, GraphWalkResponse, SearchResponse, SearchResultItem,
};
use std::path::{Path, PathBuf};
#[cfg(feature = "llm")]
use std::sync::Arc;

/// Default outer-budget timeout for an LLM classifier call. Sized for the
/// `cli:claude` / `cli:codex` backends which include subprocess spawn cost;
/// cloud APIs return faster. Override via `SEMANTEX_LLM_CLASSIFY_TIMEOUT_MS`.
#[cfg(feature = "llm")]
const LLM_CLASSIFY_TIMEOUT_DEFAULT_MS: u64 = 8_000;

#[cfg(feature = "llm")]
fn llm_classify_timeout() -> std::time::Duration {
    std::env::var("SEMANTEX_LLM_CLASSIFY_TIMEOUT_MS")
        .ok()
        .and_then(|s| s.parse::<u64>().ok())
        .map_or_else(
            || std::time::Duration::from_millis(LLM_CLASSIFY_TIMEOUT_DEFAULT_MS),
            std::time::Duration::from_millis,
        )
}

/// Threshold below which `handle_architecture` switches into "tiny repo" mode
/// (god_nodes section only, no communities, no boundaries). Per spec §4 Item 4.
const ARCH_TINY_REPO_THRESHOLD: u64 = 500;

/// Minimum corpus size (chunk count) at or above which the enumeration fan-out
/// bypasses adaptive sizing for its facet searches (full breadth). Below this,
/// facet searches keep normal adaptive sizing so small repos stay focused and
/// don't surface low-signal files (CHANGELOG, CODE_OF_CONDUCT, …). Measured
/// separator: gin 2230 / flask 1616 (small) vs platform 7809 / CopilotKit 21705
/// (large). Overridable via `SEMANTEX_FANOUT_BREADTH_MIN_CHUNKS`.
const FANOUT_BREADTH_MIN_CHUNKS: u64 = 5000;

/// Result from an individual handler method.
pub(crate) struct HandlerResult {
    formatted: String,
    fallback_used: bool,
    result_count: usize,
    /// Structured hits for item-list routes (semantic/exact/structural/exhaustive/
    /// regex/file_pattern/analytical). Empty for synthesis routes (architecture/
    /// feature_planning) whose answer is prose-only. `deep` is also prose-only,
    /// but a directly-requested Deep route (not one of the other routes' internal
    /// `handle_deep` fallback) is the one exception: its own cited sources are a
    /// real file list, so `handle_deep` populates `hits` from them in that case —
    /// see `deep_source_to_hit`. Surfaced to MCP `structuredContent` IN-PROCESS;
    /// NOT part of the wire `AgentResponse` (postcard protocol stays unchanged).
    hits: Vec<crate::server::protocol::SearchResultItem>,
    /// v0.5 Item 6: when the search's top result was `Confidence::Ambiguous`,
    /// up to 3 runner-up suggestions are surfaced here so `handle()` can
    /// populate the matching field on `AgentResponse`. `None` when the
    /// handler did not run a confidence-bearing search or the top result
    /// was Extracted / Inferred.
    disambiguation: Option<Vec<crate::server::protocol::DisambigSuggestion>>,
}

/// Per-route configuration for the consolidated `handle_search` dispatcher.
///
/// The three "list-route" handlers (Semantic, Analytical, Exhaustive) share a
/// single implementation body; this enum captures every dimension along which
/// they differ so the consolidated path reproduces each route's exact behaviour.
#[derive(Clone, Copy)]
enum SearchVariant {
    /// Dense-only path (HyDE when an LLM is wired), max 10 results, FormatStyle::Default.
    /// `is_fallback` propagates into `fallback_used` on success and controls the
    /// two-stage empty fallback (inline deep → "No results").
    Semantic { is_fallback: bool },
    /// Hybrid search with `.code_only()`, max 5 results. `full_code=true` switches
    /// to `format_code_blocks`; `full_code=false` uses FormatStyle::Default.
    /// Empty path: `handle_deep(budget, true)`.
    Analytical { full_code: bool },
    /// Hybrid search, max 20 results, budget×3, FormatStyle::Default.
    /// Empty path: `handle_deep(budget×3, true)`.
    Exhaustive,
}

impl SearchVariant {
    /// Number of results to request from the search layer.
    fn max_results(self) -> usize {
        match self {
            Self::Semantic { .. } => 10,
            Self::Analytical { .. } => 5,
            Self::Exhaustive => 20,
        }
    }

    /// Multiplier applied to the caller-supplied `budget` before formatting
    /// and before passing the budget down to any fallback path.
    fn budget_multiplier(self) -> usize {
        match self {
            Self::Exhaustive => 3,
            _ => 1,
        }
    }

    /// When `true`, add `.code_only()` to the search query.
    fn code_only(self) -> bool {
        matches!(self, Self::Analytical { .. })
    }

    /// When `true`, use `search_semantic` (dense + optional HyDE);
    /// when `false`, use `searcher.search` (hybrid BM25+dense).
    fn use_dense(self) -> bool {
        matches!(self, Self::Semantic { .. })
    }
}

/// Orchestrates agent queries: classify → dispatch → fallback → format.
pub struct AgentPipeline<'a> {
    searcher: &'a HybridSearcher,
    project_root: PathBuf,
    #[cfg(feature = "llm")]
    pub(crate) llm: Option<Arc<dyn crate::llm::LlmCapability>>,
    #[cfg(feature = "llm")]
    runtime: Option<Arc<tokio::runtime::Runtime>>,
}

impl<'a> AgentPipeline<'a> {
    pub fn new(searcher: &'a HybridSearcher, project_root: PathBuf) -> Self {
        Self {
            searcher,
            project_root,
            #[cfg(feature = "llm")]
            llm: None,
            #[cfg(feature = "llm")]
            runtime: None,
        }
    }

    /// Attach an LLM backend for classifier override and HyDE retrieval.
    ///
    /// Accepts `Option<Arc<...>>` so callers can pass the configured backend
    /// or `None` without branching at every call site. When `Some`, `handle`
    /// will attempt to classify the route via the LLM before falling back to
    /// the keyword classifier (`SEMANTEX_LLM_CLASSIFY_TIMEOUT_MS`, default 8 s),
    /// and `handle_semantic` will use HyDE augmentation
    /// (`SEMANTEX_LLM_HYDE_TIMEOUT_MS`, default 15 s). On any LLM failure
    /// or timeout, queries always fall back to the base behavior — HyDE
    /// must never break a search.
    #[cfg(feature = "llm")]
    pub fn with_llm(mut self, llm: Option<Arc<dyn crate::llm::LlmCapability>>) -> Self {
        self.llm = llm;
        self
    }

    /// Attach a shared Tokio runtime for driving async LLM calls (classify +
    /// HyDE). When `Some`, the runtime is reused across calls instead of
    /// constructing a new one each time. When `None` and an LLM is attached,
    /// `classify_route_with_llm_fallback` and `search_semantic` fall back to
    /// building a per-call runtime (legacy behavior, emits a one-time warning).
    #[cfg(feature = "llm")]
    pub fn with_runtime(mut self, rt: Option<Arc<tokio::runtime::Runtime>>) -> Self {
        self.runtime = rt;
        self
    }

    /// Run a Semantic-route search, augmenting with HyDE when an LLM is
    /// wired. Falls back to the plain base search on any HyDE failure.
    fn search_semantic(&self, query: &SearchQuery) -> anyhow::Result<crate::search::SearchOutput> {
        #[cfg(feature = "llm")]
        {
            if let Some(llm) = self.llm.clone() {
                // Use the shared runtime when available; fall back to a
                // per-call runtime as a last resort (emits a one-time warning
                // to highlight the misconfiguration).
                if let Some(ref rt) = self.runtime {
                    // search_with_hyde already handles HyDE-side errors
                    // by returning the base result; only outer runtime
                    // failures land here.
                    return rt.block_on(self.searcher.search_with_hyde(query, llm));
                }
                // No shared runtime — build a per-call one (legacy path).
                tracing::warn!(
                    "AgentPipeline has an LLM but no shared runtime; \
                     building a per-call runtime for HyDE. \
                     Wire a runtime via with_runtime() to avoid this overhead."
                );
                match tokio::runtime::Builder::new_current_thread()
                    .enable_all()
                    .build()
                {
                    Ok(rt) => {
                        return rt.block_on(self.searcher.search_with_hyde(query, llm));
                    }
                    Err(e) => {
                        tracing::warn!(
                            error = %e,
                            "Failed to build tokio runtime for HyDE; falling back to base search"
                        );
                    }
                }
            }
        }
        self.searcher.search(query)
    }

    pub fn handle(&self, request: &AgentRequest) -> AgentResponse {
        self.handle_inner(request).0
    }

    /// Like `handle`, but also returns the structured hits (item-list routes) for
    /// in-process consumers (the MCP `structuredContent` path). The wire
    /// `AgentResponse` is unchanged; hits ride alongside it, not inside it.
    pub fn handle_with_hits(
        &self,
        request: &AgentRequest,
    ) -> (
        AgentResponse,
        Vec<crate::server::protocol::SearchResultItem>,
    ) {
        self.handle_inner(request)
    }

    /// Shared body for `handle` / `handle_with_hits`. Returns the (unchanged)
    /// wire `AgentResponse` plus the structured item-list hits (empty for
    /// prose-only synthesis routes). `handle` discards the hits to keep the
    /// daemon's postcard path byte-identical; the in-process MCP path keeps
    /// them via `handle_with_hits`.
    fn handle_inner(
        &self,
        request: &AgentRequest,
    ) -> (
        AgentResponse,
        Vec<crate::server::protocol::SearchResultItem>,
    ) {
        let start = std::time::Instant::now();
        let classify_start = std::time::Instant::now();

        let route = if let Some(r) = request.route {
            r
        } else {
            self.classify_route_with_llm_fallback(&request.query)
        };
        let classify_us = classify_start.elapsed().as_micros() as u64;

        let budget = request.budget.unwrap_or(DEFAULT_BUDGET);

        let search_start = std::time::Instant::now();
        let result = match route {
            AgentRoute::FilePattern => self.handle_file_pattern(&request.query),
            AgentRoute::Regex => self.handle_regex(&request.query, budget),
            AgentRoute::ExactSymbol => self.handle_exact_symbol(&request.query, budget),
            AgentRoute::Structural => self.handle_structural(&request.query, budget),
            AgentRoute::Deep => self.handle_deep(&request.query, budget, false),
            AgentRoute::Analytical => {
                self.handle_analytical(&request.query, budget, request.full_code)
            }
            AgentRoute::Exhaustive => self.handle_exhaustive(&request.query, budget),
            AgentRoute::Semantic => self.handle_semantic(&request.query, budget, false),
            AgentRoute::Architecture => self.handle_architecture(&request.query, budget),
            AgentRoute::FeaturePlanning => self.handle_feature_planning(&request.query, budget),
        };
        let search_ms = search_start.elapsed().as_millis() as u64;

        let format_start = std::time::Instant::now();
        let formatted = format!("[route: {route}]\n\n{}", result.formatted);
        let format_ms = format_start.elapsed().as_millis() as u64;

        // Capture the structured hits BEFORE moving `result.disambiguation` into
        // the response. These ride alongside the (unchanged) wire `AgentResponse`
        // for the in-process MCP `structuredContent` path; `handle` drops them.
        let hits = result.hits;
        let response = AgentResponse {
            route,
            formatted,
            metrics: AgentMetrics {
                classify_us,
                search_ms,
                format_ms,
                total_ms: start.elapsed().as_millis() as u64,
                fallback_used: result.fallback_used,
                result_count: result.result_count,
            },
            disambiguation: result.disambiguation,
        };
        (response, hits)
    }

    /// Classify the query route, preferring the LLM classifier when one is
    /// configured. Falls back to the keyword classifier on LLM error or timeout.
    ///
    /// When `feature = "llm"` is disabled this is just a thin wrapper around
    /// [`classify_agent_query`]. When enabled and an LLM is attached, the LLM
    /// call runs inside a per-call current-thread Tokio runtime so the caller
    /// (which is always sync in the daemon and MCP paths) need not be `async`.
    // `&self` is only used under `#[cfg(feature = "llm")]` (to access `self.llm`).
    // Without that feature the argument is unused; we suppress the lint rather
    // than changing the signature, since the `#[cfg]`-gated body must remain.
    #[allow(clippy::unused_self)]
    fn classify_route_with_llm_fallback(&self, query: &str) -> AgentRoute {
        #[cfg(feature = "llm")]
        {
            if let Some(ref llm) = self.llm {
                let timeout = llm_classify_timeout();
                let llm_ref = llm.as_ref();

                // Use the shared runtime when available; fall back to a
                // per-call runtime as a last resort (emits a one-time warning).
                if let Some(ref rt) = self.runtime {
                    let result = rt.block_on(async {
                        tokio::time::timeout(timeout, llm_ref.classify_route(query)).await
                    });
                    match result {
                        Ok(Ok(r)) => {
                            tracing::debug!(
                                model = llm.label(),
                                route = ?r,
                                "LLM classified route"
                            );
                            return r;
                        }
                        Ok(Err(e)) => {
                            tracing::warn!(
                                error = %e,
                                "LLM classifier failed, falling back to keyword"
                            );
                        }
                        Err(_timeout) => {
                            tracing::info!(
                                "LLM classifier timed out (>{}ms), falling back to keyword",
                                timeout.as_millis()
                            );
                        }
                    }
                } else {
                    // No shared runtime — build a per-call one (legacy path).
                    // This should not happen in production wiring; the warning
                    // surfaces misconfiguration.
                    tracing::warn!(
                        "AgentPipeline has an LLM but no shared runtime; \
                         building a per-call runtime for classify. \
                         Wire a runtime via with_runtime() to avoid this overhead."
                    );
                    match tokio::runtime::Builder::new_current_thread()
                        .enable_all()
                        .build()
                    {
                        Ok(rt) => {
                            let result = rt.block_on(async {
                                tokio::time::timeout(timeout, llm_ref.classify_route(query)).await
                            });
                            match result {
                                Ok(Ok(r)) => {
                                    tracing::debug!(
                                        model = llm.label(),
                                        route = ?r,
                                        "LLM classified route (per-call runtime)"
                                    );
                                    return r;
                                }
                                Ok(Err(e)) => {
                                    tracing::warn!(
                                        error = %e,
                                        "LLM classifier failed, falling back to keyword"
                                    );
                                }
                                Err(_timeout) => {
                                    tracing::info!(
                                        "LLM classifier timed out (>{}ms), falling back to keyword",
                                        timeout.as_millis()
                                    );
                                }
                            }
                        }
                        Err(e) => {
                            tracing::warn!(
                                error = %e,
                                "Failed to build tokio runtime for LLM classify, falling back to keyword"
                            );
                        }
                    }
                }
            }
        }
        classify_agent_query(query)
    }

    fn handle_semantic(&self, query: &str, budget: usize, is_fallback: bool) -> HandlerResult {
        self.handle_search(query, budget, SearchVariant::Semantic { is_fallback })
    }

    fn handle_deep(&self, query: &str, budget: usize, is_fallback: bool) -> HandlerResult {
        match deep_search_module::deep_search(self.searcher, query, 20, true) {
            Ok(result) if !result.answer.is_empty() => {
                // Deep's answer is prose-only, so (unlike the item-list routes)
                // there is normally no structured hit list to surface — EXCEPT
                // when this is a directly-requested Deep route (`is_fallback ==
                // false`, the only caller being the top-level dispatch above).
                // In that one case the synthesis's own cited sources ARE a
                // real file list, so expose them as hits: this is what lets
                // `include_history` (server.rs) find files to look up commit
                // history for on the Deep route. Internal reuse of
                // `handle_deep` as a fallback from Architecture/Exhaustive/
                // FeaturePlanning/etc keeps the historical empty-hits
                // behavior — those routes' own structured output, if any,
                // comes from elsewhere, and populating hits here would leak
                // `all_hits`/`structuredContent` into unrelated routes.
                //
                // Built from `result.sources` (the INTERNAL type, which
                // carries real chunk content) BEFORE `deep_result_to_response`
                // converts to the wire `DeepSearchSource` and drops it — the
                // wire type intentionally stays thin so it's never at risk of
                // a postcard binary-protocol compatibility break; hits are a
                // separate, MCP-only surface with no such constraint.
                let total = result.sources.len();
                let hits = if is_fallback {
                    Vec::new()
                } else {
                    result
                        .sources
                        .iter()
                        .enumerate()
                        .map(|(rank, s)| deep_source_to_hit(s, rank, total))
                        .collect()
                };
                let resp = deep_result_to_response(result);
                let count = resp.sources.len();
                HandlerResult {
                    formatted: format_deep_results(&resp, budget),
                    fallback_used: is_fallback,
                    result_count: count,
                    hits,
                    disambiguation: None,
                }
            }
            _ => {
                if is_fallback {
                    HandlerResult {
                        formatted: format!("No results found for: {query}"),
                        fallback_used: true,
                        result_count: 0,
                        hits: Vec::new(),
                        disambiguation: None,
                    }
                } else {
                    self.handle_semantic(query, budget, true)
                }
            }
        }
    }

    fn handle_exact_symbol(&self, query: &str, budget: usize) -> HandlerResult {
        let symbol = query.trim_matches(|c| c == '`' || c == '"' || c == '\'');
        let sq = SearchQuery::new(symbol).max_results(5);
        if let Ok(output) = self.searcher.search(&sq)
            && !output.results.is_empty()
        {
            let items: Vec<SearchResultItem> = output
                .results
                .iter()
                .map(|r| search_result_to_item(r, true))
                .collect();
            let confidence = compute_confidence(&items);
            let disambig = disambiguation_from_results(&output.results);
            let count = items.len();
            let hits = items.clone();
            let resp = SearchResponse {
                results: items,
                duration_ms: output.metrics.total_ms,
                dense_count: output.metrics.dense_count,
                sparse_count: output.metrics.sparse_count,
                fused_count: output.metrics.fused_count,
                metrics: None,
                confidence: Some(confidence),
                disambiguation: disambig.clone(),
            };
            let mut formatted = format_search_results(&resp, FormatStyle::Default, budget);
            if let Some(suggestions) = &disambig {
                append_disambiguation_block(&mut formatted, suggestions);
            }
            return HandlerResult {
                formatted,
                fallback_used: false,
                result_count: count,
                hits,
                disambiguation: disambig,
            };
        }
        // Fallback: grep mode
        let sq = SearchQuery::new(symbol).grep_mode().max_results(10);
        match self.searcher.search(&sq) {
            Ok(output) if !output.results.is_empty() => {
                let items: Vec<SearchResultItem> = output
                    .results
                    .iter()
                    .map(|r| search_result_to_item(r, true))
                    .collect();
                let count = items.len();
                let hits = items.clone();
                let resp = SearchResponse {
                    results: items,
                    duration_ms: output.metrics.total_ms,
                    dense_count: 0,
                    sparse_count: output.metrics.sparse_count,
                    fused_count: output.metrics.fused_count,
                    metrics: None,
                    confidence: Some("medium".into()),
                    disambiguation: None,
                };
                HandlerResult {
                    formatted: format_search_results(&resp, FormatStyle::Default, budget),
                    fallback_used: true,
                    result_count: count,
                    hits,
                    disambiguation: None,
                }
            }
            _ => HandlerResult {
                formatted: format!("Symbol not found: {symbol}"),
                fallback_used: true,
                result_count: 0,
                hits: Vec::new(),
                disambiguation: None,
            },
        }
    }

    /// v0.5 Item 7 — adaptive structural walk.
    ///
    /// Uses [`AdaptiveOptions::default()`] (min=5, max=50, depth_initial=1).
    /// When the depth-1 caller / callee list is oversized, the adaptive
    /// walk replaces it with a per-module summary string surfaced through
    /// `AdaptiveGraphWalk::*_summary`. When undersized, it walks one level
    /// deeper and merges. We append the summary text outside
    /// `format_graph_results` so the existing formatter stays untouched
    /// (it is owned by W-Gamma per spec §10).
    fn handle_structural(&self, query: &str, budget: usize) -> HandlerResult {
        if let Some(symbol) = extract_symbol(query) {
            let walk: AdaptiveGraphWalk = self.searcher.with_store(|store| {
                graph_walk_from_store_adaptive(store, &symbol, AdaptiveOptions::default())
                    .unwrap_or_else(|_| AdaptiveGraphWalk {
                        response: GraphWalkResponse {
                            target: vec![],
                            callers: vec![],
                            callees: vec![],
                            type_refs: vec![],
                            hierarchy: vec![],
                        },
                        callers_summary: None,
                        callees_summary: None,
                    })
            });
            let resp = &walk.response;
            let total = resp.target.len()
                + resp.callers.len()
                + resp.callees.len()
                + resp.type_refs.len()
                + resp.hierarchy.len()
                + usize::from(walk.callers_summary.is_some())
                + usize::from(walk.callees_summary.is_some());
            if total > 0 {
                let mut formatted = format_graph_results(resp);
                // Append collapsed summaries (Item 7): each replaces the
                // per-item list with one line. Done outside `format_graph_results`
                // so the W-Gamma-owned formatter stays untouched.
                if let Some(s) = &walk.callers_summary {
                    if !formatted.ends_with('\n') {
                        formatted.push('\n');
                    }
                    formatted.push_str("\nCallers (collapsed):\n  ");
                    formatted.push_str(s);
                    formatted.push('\n');
                }
                if let Some(s) = &walk.callees_summary {
                    if !formatted.ends_with('\n') {
                        formatted.push('\n');
                    }
                    formatted.push_str("\nCallees (collapsed):\n  ");
                    formatted.push_str(s);
                    formatted.push('\n');
                }
                // Structured hits: flatten the graph-walk sections into one
                // ranked, file-bearing list (target → callers → callees →
                // type_refs → hierarchy). Each item already carries a
                // repo-relative `file` (via `chunk_to_item`), so a route-stress
                // harness scoring the structural/`usage` mechanism against
                // file-level gold gets the SAME files the formatter rendered.
                // When a section was collapsed to a summary (Item 7) its `Vec`
                // is empty, so those items don't appear here — matching the
                // formatted output.
                let hits: Vec<SearchResultItem> = resp
                    .target
                    .iter()
                    .chain(resp.callers.iter())
                    .chain(resp.callees.iter())
                    .chain(resp.type_refs.iter())
                    .chain(resp.hierarchy.iter())
                    .cloned()
                    .collect();
                return HandlerResult {
                    formatted,
                    fallback_used: false,
                    result_count: total,
                    hits,
                    disambiguation: None,
                };
            }
        }
        // Fallback to deep
        self.handle_deep(query, budget, true)
    }

    fn handle_analytical(&self, query: &str, budget: usize, full_code: bool) -> HandlerResult {
        self.handle_search(query, budget, SearchVariant::Analytical { full_code })
    }

    fn handle_exhaustive(&self, query: &str, budget: usize) -> HandlerResult {
        // OFF by default: byte-identical to the original exhaustive handler.
        if !exhaustive_fanout_enabled() {
            return self.handle_search(query, budget, SearchVariant::Exhaustive);
        }
        self.handle_exhaustive_fanout(query, budget)
    }

    /// Enumeration fan-out for the exhaustive route (gated behind
    /// `SEMANTEX_EXHAUSTIVE_FANOUT`). Decomposes an enumeration query into
    /// per-item facets, runs a hybrid search per facet, then unions + dedups +
    /// diversifies the hits so the answer covers the whole repo instead of
    /// clustering on one subsystem. Falls back to the plain exhaustive search
    /// when there is nothing to fan out (single facet) or the fan-out yields
    /// no hits.
    fn handle_exhaustive_fanout(&self, query: &str, budget: usize) -> HandlerResult {
        let facets = enumeration_facets(query);
        // Nothing to fan out — single concept (or no enumeration marker).
        if facets.len() <= 1 {
            return self.handle_search(query, budget, SearchVariant::Exhaustive);
        }

        // Corpus-size gate for the breadth bypass (mirrors the
        // `handle_architecture` chunk_count precedent). LARGE corpora: bypass
        // adaptive sizing so facet queries ("environment variables") — which
        // don't read as exhaustive — aren't clipped, giving full repo coverage.
        // SMALL corpora: keep normal adaptive sizing so the route stays focused
        // and doesn't surface low-signal files (CHANGELOG, CODE_OF_CONDUCT, …).
        let chunk_count = self.searcher.with_store(|s| s.chunk_count().unwrap_or(0));
        let full_breadth = fanout_full_breadth(chunk_count, fanout_breadth_threshold());

        // Run one hybrid search per facet (match Exhaustive: max 20, no
        // code_only). Skip facets whose search errors — never abort the route.
        let mut all_facet_results: Vec<Vec<crate::types::SearchResult>> = Vec::new();
        for facet in &facets {
            let base = SearchQuery::new(facet).max_results(20);
            let sq = if full_breadth {
                base.disable_adaptive()
            } else {
                base
            };
            if let Ok(output) = self.searcher.search(&sq) {
                all_facet_results.push(output.results);
            }
        }

        let merged = union_diversify(all_facet_results, 3, 40);
        // No coverage from the fan-out — fall back to the plain exhaustive path.
        if merged.is_empty() {
            return self.handle_search(query, budget, SearchVariant::Exhaustive);
        }

        // Success path: mirror `handle_search`'s standard search-results format,
        // with metrics zeroed (fused_count reflects the diversified union).
        let effective_budget = budget * SearchVariant::Exhaustive.budget_multiplier();
        let items: Vec<SearchResultItem> = merged
            .iter()
            .map(|r| search_result_to_item(r, true))
            .collect();
        let disambig = disambiguation_from_results(&merged);
        let confidence = compute_confidence(&items);
        let count = items.len();
        let hits = items.clone();
        let resp = SearchResponse {
            results: items,
            duration_ms: 0,
            dense_count: 0,
            sparse_count: 0,
            fused_count: merged.len(),
            metrics: None,
            confidence: Some(confidence),
            disambiguation: disambig.clone(),
        };
        let mut formatted = format_search_results(&resp, FormatStyle::Default, effective_budget);
        if let Some(suggestions) = &disambig {
            append_disambiguation_block(&mut formatted, suggestions);
        }
        HandlerResult {
            formatted,
            fallback_used: false,
            result_count: count,
            hits,
            disambiguation: disambig,
        }
    }

    /// Consolidated handler for the three "list-route" variants that differ only
    /// in config: Semantic (dense, max 10, FormatStyle::Default), Analytical
    /// (hybrid + code_only, max 5, full_code-conditional format), and Exhaustive
    /// (hybrid, max 20, budget×3, FormatStyle::Default).
    ///
    /// Every observable output — result count, format, fallback path, structured
    /// hits, disambiguation — is derived from the variant config below.
    /// Byte-identical to the three original handlers for every route.
    fn handle_search(&self, query: &str, budget: usize, variant: SearchVariant) -> HandlerResult {
        let effective_budget = budget * variant.budget_multiplier();
        let sq = {
            let base = SearchQuery::new(query).max_results(variant.max_results());
            if variant.code_only() {
                base.code_only()
            } else {
                base
            }
        };
        let search_result = if variant.use_dense() {
            self.search_semantic(&sq)
        } else {
            self.searcher.search(&sq)
        };
        match search_result {
            Ok(output) if !output.results.is_empty() => {
                let items: Vec<SearchResultItem> = output
                    .results
                    .iter()
                    .map(|r| search_result_to_item(r, true))
                    .collect();
                let disambig = disambiguation_from_results(&output.results);
                let count = items.len();
                let hits = items.clone();

                // Analytical + full_code: emit raw code blocks instead of the
                // standard search-results format. Falls back to deep if no
                // content is available.
                if let SearchVariant::Analytical { full_code: true } = variant {
                    let code_contents: Vec<String> = items
                        .iter()
                        .map(|i| i.content.clone().unwrap_or_default())
                        .collect();
                    let mut formatted =
                        format_code_blocks(&items, &code_contents, effective_budget);
                    if formatted == "No code blocks to display." {
                        return self.handle_deep(query, effective_budget, true);
                    }
                    if let Some(suggestions) = &disambig {
                        append_disambiguation_block(&mut formatted, suggestions);
                    }
                    return HandlerResult {
                        formatted,
                        fallback_used: false,
                        result_count: count,
                        hits,
                        disambiguation: disambig,
                    };
                }

                // All other variants: standard search-results format.
                // Semantic propagates `is_fallback` into `fallback_used` (it can be called
                // as a fallback from handle_deep with is_fallback=true); Analytical and
                // Exhaustive always return false on success.
                let fallback_used_on_hit = match variant {
                    SearchVariant::Semantic { is_fallback } => is_fallback,
                    _ => false,
                };
                let confidence = compute_confidence(&items);
                let resp = SearchResponse {
                    results: items,
                    duration_ms: output.metrics.total_ms,
                    dense_count: output.metrics.dense_count,
                    sparse_count: output.metrics.sparse_count,
                    fused_count: output.metrics.fused_count,
                    metrics: None,
                    confidence: Some(confidence),
                    disambiguation: disambig.clone(),
                };
                let mut formatted =
                    format_search_results(&resp, FormatStyle::Default, effective_budget);
                if let Some(suggestions) = &disambig {
                    append_disambiguation_block(&mut formatted, suggestions);
                }
                HandlerResult {
                    formatted,
                    fallback_used: fallback_used_on_hit,
                    result_count: count,
                    hits,
                    disambiguation: disambig,
                }
            }
            _ => {
                // Semantic has a unique two-stage fallback when it was not already a
                // fallback call: try deep search inline (same as handle_deep does), and
                // on double-failure preserve `fallback_used: false` to match the original
                // handle_semantic behaviour.
                if let SearchVariant::Semantic { is_fallback } = variant {
                    if is_fallback {
                        // Already a fallback (called from handle_deep) — terminal failure.
                        return HandlerResult {
                            formatted: format!("No results found for: {query}"),
                            fallback_used: true,
                            result_count: 0,
                            hits: Vec::new(),
                            disambiguation: None,
                        };
                    }
                    // Primary semantic call: fall back to deep search.
                    match deep_search_module::deep_search(self.searcher, query, 20, true) {
                        Ok(result) if !result.answer.is_empty() => {
                            let resp = deep_result_to_response(result);
                            let count = resp.sources.len();
                            return HandlerResult {
                                formatted: format_deep_results(&resp, effective_budget),
                                fallback_used: true,
                                result_count: count,
                                hits: Vec::new(),
                                disambiguation: None,
                            };
                        }
                        _ => {
                            return HandlerResult {
                                formatted: format!("No results found for: {query}"),
                                fallback_used: false,
                                result_count: 0,
                                hits: Vec::new(),
                                disambiguation: None,
                            };
                        }
                    }
                }
                // Analytical and Exhaustive: delegate to handle_deep with the
                // (possibly budget-multiplied) effective budget.
                self.handle_deep(query, effective_budget, true)
            }
        }
    }

    fn handle_regex(&self, query: &str, budget: usize) -> HandlerResult {
        let sq = SearchQuery::new(query).grep_mode().max_results(20);
        let (items, duration_ms, sparse_count, fused_count) = match self.searcher.search(&sq) {
            Ok(output) => {
                let items: Vec<SearchResultItem> = output
                    .results
                    .iter()
                    .map(|r| search_result_to_item(r, true))
                    .collect();
                (
                    items,
                    output.metrics.total_ms,
                    output.metrics.sparse_count,
                    output.metrics.fused_count,
                )
            }
            Err(_) => (vec![], 0u64, 0usize, 0usize),
        };
        let hits = items.clone();
        let resp = SearchResponse {
            results: items.clone(),
            duration_ms,
            dense_count: 0,
            sparse_count,
            fused_count,
            metrics: None,
            confidence: None,
            disambiguation: None,
        };
        HandlerResult {
            formatted: format_search_results(&resp, FormatStyle::Grep, budget),
            fallback_used: false,
            result_count: items.len(),
            hits,
            disambiguation: None,
        }
    }

    fn handle_file_pattern(&self, query: &str) -> HandlerResult {
        glob_files(&self.project_root, query)
    }

    /// Phase 4 — Architecture overview. Replaces the v0.3 M6 visible MCP tool
    /// (which regressed CCB by encouraging agents to call it alongside other
    /// structural tools). Returns the same ArchOverview (god nodes +
    /// communities + boundaries) but rendered as formatted text and routed
    /// internally by `semantex_agent` based on classifier intent.
    ///
    /// v0.3.1 Item 1 + Item 4 (per spec §4): the overview is now size-adaptive.
    /// `chunk_count < 500` → tiny-repo mode (god_nodes only, max 5, no
    /// communities / boundaries — too few to be meaningful, and rendering
    /// them on tiny repos triggers the agent to do follow-up exploration).
    /// `chunk_count >= 500` → use the `budget_for_chunk_count` tier
    /// (small / medium / large) from Item 1.
    fn handle_architecture(&self, query: &str, budget: usize) -> HandlerResult {
        use crate::index::architecture::build_arch_overview;
        let db_path = self.project_root.join(".semantex").join("chunks.db");
        let chunk_count = self.searcher.with_store(|s| s.chunk_count().unwrap_or(0));
        // Item 1: derive the adaptive budget from index size.
        // Item 4: when chunk_count < 500, force communities=0 and boundaries=0
        // so build_arch_overview skips those passes; cap god_nodes at 5.
        let mut arch_budget = budget_for_chunk_count(chunk_count as usize);
        if chunk_count < ARCH_TINY_REPO_THRESHOLD {
            arch_budget.god_nodes = arch_budget.god_nodes.min(5);
            arch_budget.communities = 0;
            arch_budget.boundaries = 0;
        }
        let Ok(overview) = self
            .searcher
            .with_store(|store| build_arch_overview(store, &db_path, Some(arch_budget)))
        else {
            return self.handle_deep(query, budget, true);
        };
        if overview.god_nodes.is_empty()
            && overview.communities.is_empty()
            && overview.boundaries.is_empty()
        {
            // Pre-v0.3 index without architecture tables → fall back to deep.
            return self.handle_deep(query, budget, true);
        }
        let mut out = String::with_capacity(2048);
        let _ = std::fmt::Write::write_fmt(&mut out, format_args!("# Architectural overview\n\n"));
        if !overview.god_nodes.is_empty() {
            out.push_str("## Top central symbols (PageRank-ranked)\n\n");
            for (i, g) in overview.god_nodes.iter().enumerate() {
                let role = g
                    .semantic_role
                    .as_deref()
                    .map(|r| format!(" [{r}]"))
                    .unwrap_or_default();
                let _ = std::fmt::Write::write_fmt(
                    &mut out,
                    format_args!(
                        "{:>2}. `{}` ({} L{}-{}){} — centrality {:.4}\n",
                        i + 1,
                        g.symbol,
                        g.file,
                        g.start_line,
                        g.end_line,
                        role,
                        g.centrality
                    ),
                );
            }
            out.push('\n');
        }
        if !overview.communities.is_empty() {
            out.push_str("## Communities (clusters via call-graph BFS)\n\n");
            for c in &overview.communities {
                let _ = std::fmt::Write::write_fmt(
                    &mut out,
                    format_args!("### {} — {} members\n", c.label, c.size),
                );
                if !c.entry_points.is_empty() {
                    out.push_str("Entry points: ");
                    let mut first = true;
                    for ep in &c.entry_points {
                        if !first {
                            out.push_str(", ");
                        }
                        let _ = std::fmt::Write::write_fmt(
                            &mut out,
                            format_args!(
                                "`{}` ({}:{}-{})",
                                ep.symbol, ep.file, ep.start_line, ep.end_line
                            ),
                        );
                        first = false;
                    }
                    out.push_str("\n\n");
                }
                if !c.member_files.is_empty() {
                    out.push_str("Sample files:\n");
                    for f in &c.member_files {
                        let _ = std::fmt::Write::write_fmt(&mut out, format_args!("  - {f}\n"));
                    }
                    out.push('\n');
                }
            }
        }
        if !overview.boundaries.is_empty() {
            out.push_str("## Cross-directory coupling (top import-edge counts)\n\n");
            for b in &overview.boundaries {
                let _ = std::fmt::Write::write_fmt(
                    &mut out,
                    format_args!("- `{}` → `{}` — {} edges\n", b.from, b.to, b.edge_count),
                );
            }
            out.push('\n');
        }
        if out.len() > budget * 3 {
            // floor_char_boundary keeps the truncate point on a UTF-8 char
            // boundary; raw String::truncate panics mid-codepoint (e.g. on
            // em-dashes in arch overviews or non-ASCII identifiers).
            let cut = out.floor_char_boundary(budget * 3);
            out.truncate(cut);
            out.push_str("\n[truncated to fit response budget]\n");
        }
        let total =
            overview.god_nodes.len() + overview.communities.len() + overview.boundaries.len();
        HandlerResult {
            formatted: out,
            fallback_used: false,
            result_count: total,
            hits: Vec::new(),
            disambiguation: None,
        }
    }

    /// v0.6 Item 10 — Feature-planning route. The classifier sends
    /// "if I wanted to add X, what files would change?" questions here.
    /// We build a 3-step plan (Architecture → ConventionLookup →
    /// ImpactedFiles) and merge per-step outputs into one response,
    /// collapsing what would otherwise be 30+ external tool turns into a
    /// single `semantex_agent` call.
    ///
    /// Safety: the planner enforces a 5-step cap and a 10s wall (see
    /// `search::planner::{MAX_STEPS, MAX_WALL}`). On any planner error —
    /// timeout, step failure, oversized plan — we fall back to the
    /// existing `handle_deep` path. The existing deep handler is reused
    /// unchanged; W-Gamma and v0.5 own its body.
    fn handle_feature_planning(&self, query: &str, budget: usize) -> HandlerResult {
        use super::planner::{Plan, PlanStepKind};

        let Ok(plan) = Plan::new(query, super::agent_classifier::AgentRoute::FeaturePlanning)
        else {
            return self.handle_deep(query, budget, true);
        };

        // Each step is a thin search-shaped call. The runner returns the
        // step's formatted body; `Plan::execute` concatenates them.
        let runner = |step: &super::planner::PlanStep,
                      _remaining: std::time::Duration|
         -> anyhow::Result<String> {
            match step.kind {
                PlanStepKind::Architecture => {
                    Ok(self.handle_architecture(&step.query, budget).formatted)
                }
                PlanStepKind::ConventionLookup
                | PlanStepKind::ImpactedFiles
                | PlanStepKind::ExampleSites
                | PlanStepKind::Synthesize => {
                    let sq = SearchQuery::new(&step.query).max_results(8);
                    match self.searcher.search(&sq) {
                        Ok(output) if !output.results.is_empty() => {
                            let items: Vec<SearchResultItem> = output
                                .results
                                .iter()
                                .map(|r| search_result_to_item(r, true))
                                .collect();
                            let resp = SearchResponse {
                                results: items,
                                duration_ms: output.metrics.total_ms,
                                dense_count: output.metrics.dense_count,
                                sparse_count: output.metrics.sparse_count,
                                fused_count: output.metrics.fused_count,
                                metrics: None,
                                confidence: Some("medium".into()),
                                disambiguation: None,
                            };
                            Ok(format_search_results(&resp, FormatStyle::Default, budget))
                        }
                        _ => Ok(String::new()),
                    }
                }
            }
        };

        match plan.execute(runner) {
            Ok(result) => HandlerResult {
                formatted: result.merged,
                fallback_used: false,
                result_count: result
                    .per_step
                    .iter()
                    .filter(|s| !s.output.is_empty())
                    .count(),
                hits: Vec::new(),
                disambiguation: None,
            },
            Err(_) => self.handle_deep(query, budget, true),
        }
    }
}

/// Convert one of Deep's cited sources into the same structured-hit shape
/// item-list routes use, so a directly-requested Deep route's `hits` (see
/// `handle_deep`) can feed `include_history` / MCP `structuredContent` like
/// any other route.
///
/// Takes the INTERNAL `search::deep::DeepSource` (not the wire
/// `DeepSearchSource`) specifically so real chunk content survives into
/// `content` — some MCP clients only surface `structuredContent` and never
/// render the parallel prose `answer` text, so leaving these hits as empty
/// pointers silently threw away the entire point of a "deep" query for that
/// caller (confirmed independently on two different repos/sessions).
///
/// Deep sources aren't independently re-ranked here — there's no fused
/// retrieval score once the synthesis pipeline has already selected and
/// deduped them — so `score` reflects synthesis order (earlier = more
/// central to the answer) on a 0.5–1.0 scale instead of a flat `0.0`, which
/// downstream consumers could otherwise mistake for "no relevance data."
fn deep_source_to_hit(
    source: &crate::search::deep::DeepSource,
    rank: usize,
    total: usize,
) -> crate::server::protocol::SearchResultItem {
    let score = if total == 0 {
        0.0
    } else {
        1.0 - (rank as f32 / total as f32) * 0.5
    };
    crate::server::protocol::SearchResultItem {
        file: source.file.clone(),
        start_line: source.start_line,
        end_line: source.end_line,
        score,
        source: "deep".to_string(),
        chunk_type: source.kind.clone().unwrap_or_default(),
        name: source.name.clone(),
        language: None,
        content: if source.content.is_empty() {
            None
        } else {
            Some(source.content.clone())
        },
        kind: source.kind.clone(),
        summary: None,
    }
}

// --- v0.5 Item 6: confidence-driven disambiguation suggestions -------------

/// Max number of runner-up entries surfaced in the disambiguation block.
/// Per spec §5 Item 6 — bounded at 3.
const DISAMBIG_MAX_SUGGESTIONS: usize = 3;

/// Compute disambiguation suggestions for the agent's top result.
///
/// Returns `Some(Vec<DisambigSuggestion>)` with up to
/// `DISAMBIG_MAX_SUGGESTIONS` runner-up entries iff `results[0].confidence`
/// is `Confidence::Ambiguous`. Otherwise returns `None`.
///
/// Suggestion selection rules:
/// - Skip the top result itself (index 0).
/// - Skip any candidate whose symbol name matches an already-included
///   suggestion (or the top result's name) — runners-up with the same
///   name as the top result wouldn't help refine the query.
/// - Skip candidates without a symbol name (TextWindow / PdfPage chunks
///   can't be referenced by name in a refined query).
/// - Bound to `DISAMBIG_MAX_SUGGESTIONS` entries.
pub(crate) fn disambiguation_from_results(
    results: &[crate::types::SearchResult],
) -> Option<Vec<crate::server::protocol::DisambigSuggestion>> {
    use crate::server::protocol::DisambigSuggestion;
    use crate::types::Confidence;

    let top = results.first()?;
    if top.confidence != Confidence::Ambiguous {
        return None;
    }

    let mut seen_names: Vec<String> = Vec::with_capacity(DISAMBIG_MAX_SUGGESTIONS + 1);
    if let Some(name) = top.chunk.symbol_name() {
        seen_names.push(name.to_string());
    }

    let mut out: Vec<DisambigSuggestion> = Vec::with_capacity(DISAMBIG_MAX_SUGGESTIONS);
    for r in results.iter().skip(1) {
        if out.len() >= DISAMBIG_MAX_SUGGESTIONS {
            break;
        }
        let Some(name) = r.chunk.symbol_name() else {
            continue;
        };
        if seen_names.iter().any(|n| n == name) {
            continue;
        }
        seen_names.push(name.to_string());
        out.push(DisambigSuggestion {
            name: name.to_string(),
            path: r.chunk.file_path.display().to_string(),
            line: r.chunk.start_line as usize,
        });
    }

    if out.is_empty() { None } else { Some(out) }
}

/// Perform a filesystem glob walk and return matching file paths.
/// Extracted as a standalone fn to enable unit testing without constructing AgentPipeline.
pub(crate) fn glob_files(root: &Path, pattern: &str) -> HandlerResult {
    use ignore::WalkBuilder;

    // Try to compile as a globset pattern
    let matcher = globset::GlobBuilder::new(pattern)
        .case_insensitive(false)
        .build()
        .and_then(|g| {
            let mut b = globset::GlobSetBuilder::new();
            b.add(g);
            b.build()
        });

    let Ok(glob_set) = matcher else {
        return HandlerResult {
            formatted: format!("Invalid glob pattern: {pattern}"),
            fallback_used: false,
            result_count: 0,
            hits: Vec::new(),
            disambiguation: None,
        };
    };

    let mut files: Vec<String> = Vec::new();
    let walker = WalkBuilder::new(root)
        .hidden(false)
        .git_ignore(true)
        .git_global(false)
        .build();

    for entry in walker.flatten() {
        let path = entry.path();
        if !path.is_file() {
            continue;
        }
        // Skip .git, .semantex, node_modules, target
        let should_skip = path.components().any(|c| {
            matches!(
                c.as_os_str().to_str(),
                Some(".git" | ".semantex" | "node_modules" | "target")
            )
        });
        if should_skip {
            continue;
        }
        // Get relative path
        let Ok(rel) = path.strip_prefix(root) else {
            continue;
        };
        if glob_set.is_match(rel) {
            // Normalize to forward slashes so repo-relative hits are identical
            // across platforms (the gold matcher / LLM consumers expect `/`,
            // not Windows `\`).
            files.push(rel.to_string_lossy().replace('\\', "/"));
        }
    }

    files.sort();
    let total = files.len();
    // Structured hits: one file-level item per match (repo-relative `file`),
    // capped to match the formatted listing so a route-stress harness can
    // score the file_pattern route against file-level gold. file_pattern is a
    // pure filesystem glob, so there is no chunk/line/score — items carry the
    // repo-relative path with a synthetic "File" chunk_type and rank-implied
    // ordering (files are already sorted; first-listed = rank 1).
    let hits: Vec<crate::server::protocol::SearchResultItem> = files
        .iter()
        .take(50)
        .map(|f| crate::server::protocol::SearchResultItem {
            file: f.clone(),
            start_line: 0,
            end_line: 0,
            score: 0.0,
            source: "FilePattern".to_string(),
            chunk_type: "File".to_string(),
            name: None,
            language: None,
            content: None,
            kind: None,
            summary: None,
        })
        .collect();
    let mut lines: Vec<String> = files.into_iter().take(50).collect();
    if total > 50 {
        lines.push(format!("... and {} more files", total - 50));
    }

    HandlerResult {
        formatted: lines.join("\n"),
        fallback_used: false,
        result_count: total,
        hits,
        disambiguation: None,
    }
}

/// Syntactically decompose an enumeration question ("list all X, Y, and Z")
/// into per-item facets so the caller can fan out narrow searches that won't
/// cluster on a single subsystem. Pure string surgery — no semantics, no
/// model. The full original `query` is always included as the final facet so
/// the holistic view (and single-concept enumerations) stay covered.
///
/// Returns content fragments first, then the original query. If nothing
/// survives decomposition, returns just `[query]`.
// Consumed by the enumeration fan-out in `handle_exhaustive`.
fn enumeration_facets(query: &str) -> Vec<String> {
    // Sentinel substituted for every multi-char split delimiter, so we can
    // split once without re-splitting on bare "," inside the multi-char forms.
    const SENTINEL: &str = "\u{0}";
    /// Universal stopwords — a fragment composed entirely of these (after
    /// stripping non-alphanumerics) carries no retrieval signal and is dropped.
    const STOP: &[&str] = &[
        "the",
        "a",
        "an",
        "this",
        "that",
        "these",
        "those",
        "it",
        "its",
        "they",
        "them",
        "their",
        "there",
        "where",
        "when",
        "what",
        "which",
        "who",
        "is",
        "are",
        "was",
        "were",
        "be",
        "been",
        "does",
        "do",
        "did",
        "done",
        "project",
        "repo",
        "repository",
        "codebase",
        "supports",
        "supported",
        "support",
        "defined",
        "define",
        "defines",
        "exist",
        "exists",
        "existing",
        "used",
        "use",
        "uses",
        "using",
        "in",
        "on",
        "of",
        "for",
        "to",
        "and",
        "or",
        "all",
        "every",
        "any",
        "each",
        "with",
        "that's",
        "here",
    ];

    // 1. Strip a leading enumeration marker. ALL detection + slicing happens on
    //    the lowercased copy `lower`, so every byte offset indexes the SAME
    //    string it was computed from — `to_lowercase()` is not byte-length-
    //    preserving (e.g. `İ` U+0130 grows 2→3 bytes), so slicing `query` with a
    //    `lower` offset would land mid-codepoint and panic. Content facets are
    //    therefore lowercased; that is fine (facets are case-insensitive search
    //    queries). The original-case query is re-appended verbatim in step 5.
    //    Use the marker that appears earliest in the string.
    const MARKERS: &[&str] = &[
        "list all",
        "list every",
        "find all",
        "find every",
        "show all",
        "show every",
        "what are all",
        "where are all",
        "enumerate all",
        "enumerate every",
        "enumerate ",
    ];
    let lower = query.to_lowercase();
    let mut best: Option<(usize, usize)> = None; // (start, marker_len)
    for m in MARKERS {
        if let Some(pos) = lower.find(m) {
            match best {
                Some((bp, _)) if pos >= bp => {}
                _ => best = Some((pos, m.len())),
            }
        }
    }
    let remainder: &str = match best {
        Some((pos, len)) => &lower[pos + len..],
        None => &lower,
    };

    // 2. Split the remainder into fragments on commas / semicolons / standalone
    //    " and " / " or ". Replace the multi-char (and comma+and) delimiters
    //    with a sentinel first so "android"/"category" are never split.
    let mut work = remainder.to_string();
    for delim in [", and ", ", or ", " and ", " or ", "; ", ", ", ";", ","] {
        work = work.replace(delim, SENTINEL);
    }

    let mut fragments: Vec<String> = Vec::new();
    for raw in work.split(SENTINEL) {
        // Normalize: strip a leading "and "/"or " left over from edge splits.
        // `frag` is a slice of `lower` (already lowercased), so we strip the
        // lowercase prefixes directly off it — no cross-string byte offsets,
        // hence no char-boundary panic.
        let mut frag = raw.trim();
        if let Some(rest) = frag.strip_prefix("and ") {
            frag = rest;
        } else if let Some(rest) = frag.strip_prefix("or ") {
            frag = rest;
        }
        // 3. Trim whitespace + trailing '.'.
        let frag = frag.trim().trim_end_matches('.').trim();
        if frag.len() < 3 {
            continue;
        }
        // Drop if every word (lowercased, alnum-only) is a stopword.
        let all_stop = frag.split_whitespace().all(|w| {
            let cleaned: String = w
                .chars()
                .filter(|c| c.is_alphanumeric())
                .flat_map(char::to_lowercase)
                .collect();
            cleaned.is_empty() || STOP.contains(&cleaned.as_str())
        });
        if all_stop {
            continue;
        }
        fragments.push(frag.to_string());
    }

    // 4. Lowercase-dedup (preserve first-seen original case); cap at 6.
    let mut facets: Vec<String> = Vec::new();
    let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
    for frag in fragments {
        let key = frag.to_lowercase();
        if seen.insert(key) {
            facets.push(frag);
            if facets.len() == 6 {
                break;
            }
        }
    }

    // 5. Always include the full original query, unless already present.
    let query_lower = query.to_lowercase();
    if !facets.iter().any(|f| f.to_lowercase() == query_lower) {
        facets.push(query.to_string());
    }

    // 6. If the only facet is the original query, return just that.
    if facets.len() == 1 {
        return vec![query.to_string()];
    }
    facets
}

/// Union + dedup + diversify the per-facet result lists from the enumeration
/// fan-out into a single ranked Vec.
///
/// Pure (no I/O, no model): given the per-facet hit lists, it (1) flattens and
/// dedups by `(file_path, start_line)` — the same identity `search_result_to_item`
/// keys each item on — keeping the higher `.score` on a collision; (2) sorts by
/// score descending (tie-break by file then start_line for determinism); then
/// (3) greedily admits results while that file's running count is `< per_file_cap`,
/// stopping at `total_cap`. The per-file cap spreads coverage across files so an
/// enumeration question covers the whole repo instead of clustering on one
/// subsystem.
fn union_diversify(
    result_lists: Vec<Vec<crate::types::SearchResult>>,
    per_file_cap: usize,
    total_cap: usize,
) -> Vec<crate::types::SearchResult> {
    use std::collections::HashMap;
    use std::path::PathBuf;

    // 1. Flatten + dedup by (file, start_line), keeping the higher score.
    let mut best: HashMap<(PathBuf, u32), crate::types::SearchResult> = HashMap::new();
    for list in result_lists {
        for r in list {
            let key = (r.chunk.file_path.clone(), r.chunk.start_line);
            match best.get(&key) {
                Some(existing) if existing.score >= r.score => {}
                _ => {
                    best.insert(key, r);
                }
            }
        }
    }

    // 2. Sort by score desc; deterministic tie-break by (file, start_line).
    let mut deduped: Vec<crate::types::SearchResult> = best.into_values().collect();
    deduped.sort_by(|a, b| {
        b.score
            .partial_cmp(&a.score)
            .unwrap_or(std::cmp::Ordering::Equal)
            .then_with(|| a.chunk.file_path.cmp(&b.chunk.file_path))
            .then_with(|| a.chunk.start_line.cmp(&b.chunk.start_line))
    });

    // 3. Greedily admit while per-file count < cap, until total_cap.
    let mut per_file: HashMap<PathBuf, usize> = HashMap::new();
    let mut admitted: Vec<crate::types::SearchResult> =
        Vec::with_capacity(total_cap.min(deduped.len()));
    for r in deduped {
        if admitted.len() >= total_cap {
            break;
        }
        let count = per_file.entry(r.chunk.file_path.clone()).or_insert(0);
        if *count >= per_file_cap {
            continue;
        }
        *count += 1;
        admitted.push(r);
    }
    admitted
}

/// Pure parser for the `SEMANTEX_EXHAUSTIVE_FANOUT` flag, factored out so the
/// default-ON contract is unit-testable without touching process env. ON by
/// default (the corpus gate in `handle_exhaustive_fanout` makes it safe); only
/// an explicit `"0"` or (case-insensitively) `"false"` disables it.
fn fanout_flag_from(value: Option<&str>) -> bool {
    match value {
        Some(v) => !(v == "0" || v.eq_ignore_ascii_case("false")),
        None => true,
    }
}

/// Whether the exhaustive-route facet fan-out is enabled. Gated behind
/// `SEMANTEX_EXHAUSTIVE_FANOUT`; ON by default. Disable with
/// `SEMANTEX_EXHAUSTIVE_FANOUT=0`.
fn exhaustive_fanout_enabled() -> bool {
    fanout_flag_from(std::env::var("SEMANTEX_EXHAUSTIVE_FANOUT").ok().as_deref())
}

/// Pure corpus-size gate for the fan-out's breadth bypass: a facet search
/// disables adaptive sizing (keeps full breadth) only when the corpus is large
/// enough that an enumeration genuinely spans many files. Small corpora keep
/// normal adaptive sizing so they stay focused.
fn fanout_full_breadth(chunk_count: u64, threshold: u64) -> bool {
    chunk_count >= threshold
}

/// Resolve the breadth threshold: `SEMANTEX_FANOUT_BREADTH_MIN_CHUNKS` if it
/// parses as a `u64`, else the built-in `FANOUT_BREADTH_MIN_CHUNKS`.
fn fanout_breadth_threshold() -> u64 {
    std::env::var("SEMANTEX_FANOUT_BREADTH_MIN_CHUNKS")
        .ok()
        .and_then(|s| s.parse::<u64>().ok())
        .unwrap_or(FANOUT_BREADTH_MIN_CHUNKS)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::SemantexConfig;
    use crate::index::storage::ChunkStore;
    use crate::search::hybrid::HybridSearcher;
    use crate::search::sparse_search::SparseIndex;
    use crate::types::{AstNodeKind, Chunk, ChunkType};
    use tempfile::TempDir;

    /// Build a sparse-only `HybridSearcher` backed by a small populated index:
    /// a chunk store with two AST-node chunks plus a matching Tantivy sparse
    /// index, so `searcher.search` returns genuine non-empty hits. Mirrors the
    /// `build_empty_searcher` pattern in `server::handler`, but actually
    /// inserts content so item-list routes surface structured hits.
    fn build_populated_searcher() -> (TempDir, HybridSearcher) {
        let dir = TempDir::new().expect("tempdir");
        let semantex_dir = dir.path().join(".semantex");
        std::fs::create_dir_all(&semantex_dir).unwrap();
        let db_path = semantex_dir.join("chunks.db");

        // Insert two AST-node chunks (write-mode store), then drop so the
        // sparse-only searcher can re-open in search mode.
        let chunk_ids: Vec<u64> = {
            let store = ChunkStore::open(&db_path).expect("create chunk store");
            let chunks = [
                (
                    "auth/login.rs",
                    "authenticateUser",
                    "fn authenticateUser(creds: Credentials) -> Session { /* login */ }",
                ),
                (
                    "auth/logout.rs",
                    "endSession",
                    "fn endSession(session: Session) { /* logout */ }",
                ),
            ];
            chunks
                .iter()
                .map(|(file, name, content)| {
                    let chunk = Chunk {
                        id: 0,
                        file_path: std::path::PathBuf::from(file),
                        start_line: 1,
                        end_line: 3,
                        content: (*content).to_string(),
                        chunk_type: ChunkType::AstNode {
                            name: (*name).to_string(),
                            kind: AstNodeKind::Function,
                            language: "rust".into(),
                            structured_meta: None,
                        },
                    };
                    store.insert_chunk(&chunk, 0, 0).expect("insert chunk")
                })
                .collect()
        };

        // Build the matching sparse index. `use_bm25_stemmer` defaults to true
        // (SemantexConfig::default), so create with stemmer=true to match.
        {
            let index = SparseIndex::create(&semantex_dir.join("sparse"), true).expect("create");
            let mut writer = index.writer().expect("writer");
            writer
                .add_document(
                    chunk_ids[0],
                    "fn authenticateUser creds Credentials Session login authentication",
                    "auth/login.rs",
                )
                .expect("add 0");
            writer
                .add_document(
                    chunk_ids[1],
                    "fn endSession session Session logout authentication",
                    "auth/logout.rs",
                )
                .expect("add 1");
            writer.commit().expect("commit");
        }

        let config = SemantexConfig::default();
        let searcher = HybridSearcher::open_sparse_only(&semantex_dir, &config)
            .expect("open sparse-only searcher");
        (dir, searcher)
    }

    /// Task 6 (A2): `handle_with_hits` must surface the structured
    /// `SearchResultItem` hits for an item-list route (Semantic), alongside the
    /// unchanged prose `AgentResponse`. The wire `AgentResponse` is untouched;
    /// hits ride alongside it for the in-process MCP `structuredContent` path.
    #[test]
    fn handle_with_hits_returns_structured_hits_for_item_route() {
        let (_dir, searcher) = build_populated_searcher();
        let pipeline = AgentPipeline::new(&searcher, std::path::PathBuf::from("/tmp/a2-hits-test"));

        let (resp, hits) = pipeline.handle_with_hits(&AgentRequest {
            query: "authentication".into(),
            route: Some(AgentRoute::Semantic),
            budget: Some(12_000),
            full_code: false,
        });

        assert!(!resp.formatted.is_empty());
        assert!(
            !hits.is_empty(),
            "Semantic route must surface structured hits"
        );
        assert!(hits.iter().all(|h| !h.file.is_empty()));
    }

    /// E2E Wave 3 fix: a directly-requested Deep route must surface structured
    /// hits (the synthesis's own cited sources, or the semantic-fallback's
    /// hits when the synthesis comes back empty on a tiny corpus) — this is
    /// what makes `include_history` reachable on the Deep route in
    /// `semantex-mcp/server.rs::tool_agent`, which looks up commit history for
    /// hit files. Before the fix, `handle_deep` hardcoded `hits: Vec::new()`,
    /// so the documented Deep|Analytical `include_history` gate could never
    /// fire on Deep.
    #[test]
    fn handle_with_hits_returns_hits_for_direct_deep_route() {
        let (_dir, searcher) = build_populated_searcher();
        let pipeline =
            AgentPipeline::new(&searcher, std::path::PathBuf::from("/tmp/deep-hits-test"));

        let (resp, hits) = pipeline.handle_with_hits(&AgentRequest {
            query: "how does authentication work".into(),
            route: Some(AgentRoute::Deep),
            budget: Some(12_000),
            full_code: false,
        });

        assert_eq!(resp.route, AgentRoute::Deep);
        assert!(!resp.formatted.is_empty());
        assert!(
            !hits.is_empty(),
            "a directly-requested Deep route must yield structured hits \
             (include_history depends on this)"
        );
        assert!(hits.iter().all(|h| !h.file.is_empty()));
    }

    /// `deep_source_to_hit` maps a Deep cited source into the shared
    /// `SearchResultItem` shape: file/lines/name/kind carried over verbatim,
    /// `source` tagged "deep", and `score` pinned to 0.0 (Deep tracks no
    /// per-source relevance score — nothing is fabricated).
    #[test]
    fn deep_source_to_hit_maps_provenance_fields() {
        let source = crate::search::deep::DeepSource {
            file: "auth/login.rs".to_string(),
            start_line: 3,
            end_line: 17,
            name: Some("authenticateUser".to_string()),
            kind: Some("function".to_string()),
            content: "fn authenticateUser() {}".to_string(),
            also_matched_via: Vec::new(),
        };
        let hit = deep_source_to_hit(&source, 0, 4);
        assert_eq!(hit.file, "auth/login.rs");
        assert_eq!(hit.start_line, 3);
        assert_eq!(hit.end_line, 17);
        assert_eq!(hit.source, "deep");
        assert_eq!(hit.name.as_deref(), Some("authenticateUser"));
        assert_eq!(hit.kind.as_deref(), Some("function"));
        assert_eq!(hit.chunk_type, "function");
        assert_eq!(hit.content.as_deref(), Some("fn authenticateUser() {}"));
        assert!(hit.summary.is_none());
    }

    #[test]
    fn deep_source_to_hit_score_descends_by_rank_never_hits_zero() {
        // Rank 0 of N scores highest; later ranks score lower but never 0.0 —
        // a flat 0.0 across every hit is indistinguishable from "no relevance
        // data" to a caller inspecting `structuredContent` alone.
        let source = crate::search::deep::DeepSource {
            file: "a.rs".to_string(),
            start_line: 1,
            end_line: 2,
            name: None,
            kind: None,
            content: "fn a() {}".to_string(),
            also_matched_via: Vec::new(),
        };
        let first = deep_source_to_hit(&source, 0, 4);
        let last = deep_source_to_hit(&source, 3, 4);
        assert!(first.score > last.score);
        assert!(last.score > 0.0);
    }

    #[test]
    fn deep_source_to_hit_empty_content_maps_to_none() {
        let source = crate::search::deep::DeepSource {
            file: "a.rs".to_string(),
            start_line: 1,
            end_line: 2,
            name: None,
            kind: None,
            content: String::new(),
            also_matched_via: Vec::new(),
        };
        let hit = deep_source_to_hit(&source, 0, 1);
        assert!(hit.content.is_none());
    }

    /// Integration: a query with `.disable_adaptive()` returns at least as many
    /// results as the same query without it, driven through the real
    /// `HybridSearcher.search()` adaptive stage. Skipping the adaptive pipeline
    /// can only widen (never narrow) the result set — the fan-out relies on this
    /// to keep full breadth. Best-effort: the fixture is small (2 chunks), so
    /// this guards the wiring and the monotonic-breadth contract rather than a
    /// large clip.
    #[test]
    fn disable_adaptive_returns_at_least_as_many_results() {
        let (_dir, searcher) = build_populated_searcher();

        let base = searcher
            .search(&SearchQuery::new("authentication").max_results(20))
            .expect("base search");
        let wide = searcher
            .search(
                &SearchQuery::new("authentication")
                    .max_results(20)
                    .disable_adaptive(),
            )
            .expect("disable_adaptive search");

        assert!(
            wide.results.len() >= base.results.len(),
            "disable_adaptive must not return fewer results than adaptive \
             (wide={}, base={})",
            wide.results.len(),
            base.results.len()
        );
    }

    /// Route-stress seam (daemon path): the `Request::AgentHits` handler must
    /// return a `Response::AgentHits` carrying the forced route plus the
    /// engine's structured ranked hits. This is the exact path the benchmark
    /// harness drives via `daemon_agent_hits_binary` / `agent --json-hits`.
    #[test]
    fn handle_agent_hits_returns_structured_hits_response() {
        use crate::server::handler::Handler;
        use crate::server::protocol::{Request, Response};
        use std::sync::atomic::AtomicU64;

        let (_dir, searcher) = build_populated_searcher();
        let count = AtomicU64::new(0);
        let handler = Handler::new(
            &searcher,
            &count,
            std::path::PathBuf::from("/tmp/agent-hits-handler"),
        );

        let resp = handler.handle(
            Request::AgentHits(AgentRequest {
                query: "authentication".into(),
                route: Some(AgentRoute::Semantic),
                budget: Some(12_000),
                full_code: false,
            }),
            std::time::Instant::now(),
        );

        let Response::AgentHits(ah) = resp else {
            panic!("expected Response::AgentHits");
        };
        assert_eq!(ah.route, AgentRoute::Semantic);
        assert!(!ah.hits.is_empty(), "forced semantic route must yield hits");
        assert!(ah.hits.iter().all(|h| !h.file.is_empty()));
    }

    /// `handle` (the wire path) must produce the SAME `AgentResponse` shape as
    /// `handle_with_hits(...).0` — both delegate to `handle_inner`, so the
    /// daemon's postcard `AgentResponse` is unaffected by the hits surfacing.
    ///
    /// NOTE: the formatted body embeds the live per-search `duration_ms`
    /// (`agent_formatter`: "[N results, {ms}ms ...]"), so two independent live
    /// searches can differ on that one number. We therefore assert structural
    /// parity (route, result_count, fallback, disambiguation, and the
    /// route-header prefix) rather than a byte-for-byte body match.
    #[test]
    fn handle_matches_handle_with_hits_response() {
        let (_dir, searcher) = build_populated_searcher();
        let pipeline = AgentPipeline::new(&searcher, std::path::PathBuf::from("/tmp/a2-parity"));
        let req = AgentRequest {
            query: "authentication".into(),
            route: Some(AgentRoute::Semantic),
            budget: Some(12_000),
            full_code: false,
        };
        let wire = pipeline.handle(&req);
        let (with_hits, _hits) = pipeline.handle_with_hits(&req);
        assert_eq!(wire.route, with_hits.route);
        // Both carry the identical route-header prefix that `handle_inner`
        // prepends; the wire path is byte-identical up to embedded timings.
        assert!(wire.formatted.starts_with("[route: semantic]"));
        assert!(with_hits.formatted.starts_with("[route: semantic]"));
        assert_eq!(wire.metrics.result_count, with_hits.metrics.result_count);
        assert_eq!(wire.metrics.fallback_used, with_hits.metrics.fallback_used);
        assert_eq!(wire.disambiguation, with_hits.disambiguation);
    }

    #[test]
    fn test_dispatch_routes_file_pattern() {
        use super::super::agent_classifier::{AgentRoute, classify_agent_query};
        assert_eq!(classify_agent_query("*.rs"), AgentRoute::FilePattern);
    }

    #[test]
    fn test_handle_file_pattern_finds_files() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("foo.rs"), "").unwrap();
        std::fs::write(dir.path().join("bar.rs"), "").unwrap();
        std::fs::write(dir.path().join("baz.py"), "").unwrap();

        let result = glob_files(dir.path(), "*.rs");
        assert!(result.formatted.contains("foo.rs"));
        assert!(result.formatted.contains("bar.rs"));
        assert!(!result.formatted.contains("baz.py"));
        assert_eq!(result.result_count, 2);
    }

    /// Route-stress seam: the `file_pattern` (glob) route must surface
    /// structured, repo-relative hits — not just a formatted listing — so the
    /// harness can score the glob mechanism against file-level gold.
    #[test]
    fn file_pattern_route_surfaces_repo_relative_hits() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(dir.path().join("sub")).unwrap();
        std::fs::write(dir.path().join("foo.rs"), "").unwrap();
        std::fs::write(dir.path().join("sub/bar.rs"), "").unwrap();
        std::fs::write(dir.path().join("baz.py"), "").unwrap();

        let result = glob_files(dir.path(), "**/*.rs");
        let files: Vec<&str> = result.hits.iter().map(|h| h.file.as_str()).collect();
        assert!(files.contains(&"foo.rs"), "files: {files:?}");
        // Repo-relative, not absolute — exactly what the gold matcher expects.
        assert!(files.contains(&"sub/bar.rs"), "files: {files:?}");
        assert!(!files.iter().any(|f| f.contains("baz.py")));
        assert!(
            result.hits.iter().all(|h| !h.file.starts_with('/')),
            "hits must be repo-relative, got {files:?}"
        );
    }

    #[test]
    fn test_handle_file_pattern_excludes_git() {
        let dir = tempfile::tempdir().unwrap();
        let git = dir.path().join(".git");
        std::fs::create_dir(&git).unwrap();
        std::fs::write(git.join("config"), "").unwrap();
        std::fs::write(dir.path().join("main.rs"), "").unwrap();

        let result = glob_files(dir.path(), "*");
        assert!(result.formatted.contains("main.rs"));
        assert!(!result.formatted.contains(".git"));
    }

    #[test]
    fn test_handle_file_pattern_caps_at_50() {
        let dir = tempfile::tempdir().unwrap();
        for i in 0..60 {
            std::fs::write(dir.path().join(format!("file{i:03}.rs")), "").unwrap();
        }
        let result = glob_files(dir.path(), "*.rs");
        assert!(result.formatted.contains("... and 10 more files"));
        assert_eq!(result.result_count, 60);
    }

    // ── SearchVariant config lock ──────────────────────────────────────────────

    /// Guard the per-route variant config captured in `SearchVariant`. Each
    /// assertion locks a dimension that, if changed, would silently alter
    /// observable route behaviour.
    ///
    /// Semantic: dense path, max 10, no code_only, budget×1.
    /// Analytical: hybrid path, max 5, code_only=true, budget×1.
    /// Exhaustive: hybrid path, max 20, no code_only, budget×3.
    #[test]
    fn search_variant_config_is_locked() {
        // Semantic (is_fallback=false — the dispatch path)
        let sem = SearchVariant::Semantic { is_fallback: false };
        assert_eq!(sem.max_results(), 10, "Semantic max_results");
        assert_eq!(sem.budget_multiplier(), 1, "Semantic budget_multiplier");
        assert!(!sem.code_only(), "Semantic must NOT set code_only");
        assert!(sem.use_dense(), "Semantic must use dense (HyDE) path");

        // Semantic (is_fallback=true — called from handle_deep as fallback)
        let sem_fb = SearchVariant::Semantic { is_fallback: true };
        assert!(
            sem_fb.use_dense(),
            "Semantic fallback must still use dense path"
        );

        // Analytical
        let ana = SearchVariant::Analytical { full_code: false };
        assert_eq!(ana.max_results(), 5, "Analytical max_results");
        assert_eq!(ana.budget_multiplier(), 1, "Analytical budget_multiplier");
        assert!(ana.code_only(), "Analytical must set code_only");
        assert!(!ana.use_dense(), "Analytical must use hybrid path");

        // Analytical full_code variant — same search config, different format
        let ana_fc = SearchVariant::Analytical { full_code: true };
        assert_eq!(ana_fc.max_results(), 5);
        assert!(ana_fc.code_only());

        // Exhaustive
        let exh = SearchVariant::Exhaustive;
        assert_eq!(exh.max_results(), 20, "Exhaustive max_results");
        assert_eq!(
            exh.budget_multiplier(),
            3,
            "Exhaustive budget_multiplier (×3)"
        );
        assert!(!exh.code_only(), "Exhaustive must NOT set code_only");
        assert!(!exh.use_dense(), "Exhaustive must use hybrid path");
    }

    /// Exhaustive route must apply the budget×3 multiplier end-to-end: the
    /// formatted result passes the effective budget to the formatter, not the
    /// raw budget. We verify this via the populated searcher so a real search
    /// result is formatted, then confirm the result count matches Exhaustive's
    /// max_results ceiling (≤20) rather than Semantic's (≤10).
    #[test]
    fn exhaustive_route_uses_budget_multiplier_and_max20() {
        let (_dir, searcher) = build_populated_searcher();
        let pipeline =
            AgentPipeline::new(&searcher, std::path::PathBuf::from("/tmp/variant-exh-test"));
        let (resp, _hits) = pipeline.handle_with_hits(&AgentRequest {
            query: "authentication".into(),
            route: Some(AgentRoute::Exhaustive),
            budget: Some(12_000),
            full_code: false,
        });
        assert!(resp.formatted.contains("[route: exhaustive]"));
        // result_count ≤ 20 (Exhaustive max) — our tiny index has 2 chunks
        assert!(
            resp.metrics.result_count <= 20,
            "Exhaustive result_count {} exceeds max 20",
            resp.metrics.result_count
        );
    }

    /// Analytical route must issue a code_only query (hybrid, max 5). With our
    /// populated searcher the query hits both chunks; the result count must be
    /// ≤5 (Analytical's max), not 10 or 20.
    #[test]
    fn analytical_route_uses_max5_and_code_only() {
        let (_dir, searcher) = build_populated_searcher();
        let pipeline =
            AgentPipeline::new(&searcher, std::path::PathBuf::from("/tmp/variant-ana-test"));
        let (resp, _hits) = pipeline.handle_with_hits(&AgentRequest {
            query: "authentication".into(),
            route: Some(AgentRoute::Analytical),
            budget: Some(12_000),
            full_code: false,
        });
        assert!(resp.formatted.contains("[route: analytical]"));
        assert!(
            resp.metrics.result_count <= 5,
            "Analytical result_count {} exceeds max 5",
            resp.metrics.result_count
        );
    }

    /// Semantic route must use the dense path (search_semantic); with a
    /// sparse-only test searcher it falls back to deep search (no dense
    /// model present), which either returns a deep result or "No results
    /// found" — either way the route header must be emitted correctly.
    #[test]
    fn semantic_route_emits_correct_route_header() {
        let (_dir, searcher) = build_populated_searcher();
        let pipeline =
            AgentPipeline::new(&searcher, std::path::PathBuf::from("/tmp/variant-sem-test"));
        let (resp, _hits) = pipeline.handle_with_hits(&AgentRequest {
            query: "authentication".into(),
            route: Some(AgentRoute::Semantic),
            budget: Some(12_000),
            full_code: false,
        });
        assert!(
            resp.formatted.starts_with("[route: semantic]"),
            "Semantic must emit [route: semantic] header, got: {}",
            &resp.formatted[..resp.formatted.len().min(80)]
        );
    }

    // --- enumeration_facets: syntactic decomposition of "list all X, Y, Z" --

    #[test]
    fn enumeration_facets_splits_multi_item() {
        let q = "List all configuration options, environment variables, and CLI flags this project supports and where they are defined.";
        let facets = enumeration_facets(q);
        assert!(
            facets
                .iter()
                .any(|f| f.to_lowercase().contains("configuration options")),
            "missing 'configuration options' facet: {facets:?}"
        );
        assert!(
            facets
                .iter()
                .any(|f| f.to_lowercase().contains("environment variables")),
            "missing 'environment variables' facet: {facets:?}"
        );
        assert!(
            facets
                .iter()
                .any(|f| f.to_lowercase().contains("cli flags")),
            "missing 'cli flags' facet: {facets:?}"
        );
        assert!(
            facets.iter().any(|f| f == q),
            "missing exact original query facet: {facets:?}"
        );
    }

    #[test]
    fn enumeration_facets_drops_stopword_fragments() {
        let q = "List all configuration options, environment variables, and CLI flags this project supports and where they are defined.";
        let facets = enumeration_facets(q);
        assert!(
            !facets
                .iter()
                .any(|f| f.trim().to_lowercase() == "where they are defined"),
            "all-stopword fragment was not dropped: {facets:?}"
        );
    }

    #[test]
    fn enumeration_facets_single_concept_passthrough() {
        let q = "list all environment variables";
        let facets = enumeration_facets(q);
        assert!(facets.len() <= 2, "too many facets: {facets:?}");
        assert!(
            facets
                .iter()
                .all(|f| f.to_lowercase().contains("environment variables")),
            "junk fragment present: {facets:?}"
        );
    }

    #[test]
    fn enumeration_facets_caps() {
        let q = "find all a1, b2, c3, d4, e5, f6, g7, h8";
        let facets = enumeration_facets(q);
        assert!(facets.len() <= 7, "facets not capped: {facets:?}");
    }

    #[test]
    fn enumeration_facets_no_marker_returns_query() {
        let q = "how does auth work";
        let facets = enumeration_facets(q);
        assert_eq!(facets, vec!["how does auth work".to_string()]);
    }

    #[test]
    fn enumeration_facets_unicode_no_panic() {
        // Regression: byte offsets were computed on `query.to_lowercase()` but
        // used to slice `query`. `to_lowercase()` is NOT byte-length-preserving
        // (e.g. `İ` U+0130 grows 2→3 bytes), so the offsets drifted onto a
        // non-char-boundary and the slice panicked. Default-on fan-out + an
        // inline daemon agent path means that panic crashed the whole daemon.
        // Must not panic, and must return a non-empty Vec.
        let f1 = enumeration_facets("İlist allé, foo");
        assert!(!f1.is_empty(), "unicode marker query produced empty facets");

        let f2 = enumeration_facets("list all café options, naïve config");
        assert!(
            !f2.is_empty(),
            "unicode multi-item query produced empty facets"
        );
    }

    // --- exhaustive fan-out: union_diversify + gate -----------------------

    /// Minimal `SearchResult` builder for fan-out union/diversify tests.
    /// Identity is keyed on `(file_path, start_line)` — the SAME pair that
    /// `search_result_to_item` reads — so dedup tests exercise the real key.
    fn mk_result(file: &str, line: u32, score: f32) -> crate::types::SearchResult {
        crate::types::SearchResult {
            chunk: Chunk {
                id: 0,
                file_path: std::path::PathBuf::from(file),
                start_line: line,
                end_line: line + 10,
                content: format!("// {file}:{line}"),
                chunk_type: ChunkType::AstNode {
                    name: format!("sym_{line}"),
                    kind: AstNodeKind::Function,
                    language: "rust".into(),
                    structured_meta: None,
                },
            },
            score,
            source: crate::types::SearchSource::Hybrid,
            score_dense: 0.0,
            score_sparse: 0.0,
            score_exact: 0.0,
            confidence: crate::types::Confidence::Inferred,
            confidence_score: 0.5,
        }
    }

    #[test]
    fn union_diversify_dedups_by_file_line_keeping_higher_score() {
        // Same (file, line) appears in two lists at different scores: keep the
        // higher score; output sorted by score descending.
        let list_a = vec![mk_result("a.rs", 10, 0.50), mk_result("b.rs", 20, 0.90)];
        let list_b = vec![mk_result("a.rs", 10, 0.80), mk_result("c.rs", 30, 0.70)];
        let merged = union_diversify(vec![list_a, list_b], 3, 40);

        // Dedup: (a.rs,10) appears once, with the HIGHER score 0.80.
        let a10: Vec<&crate::types::SearchResult> = merged
            .iter()
            .filter(|r| {
                r.chunk.file_path == std::path::Path::new("a.rs") && r.chunk.start_line == 10
            })
            .collect();
        assert_eq!(
            a10.len(),
            1,
            "duplicate (file,line) not deduped: {merged:?}"
        );
        assert!(
            (a10[0].score - 0.80).abs() < 1e-6,
            "dedup must keep higher score, got {}",
            a10[0].score
        );

        // Three distinct keys survive.
        assert_eq!(merged.len(), 3, "expected 3 unique results: {merged:?}");

        // Sorted by score descending: 0.90 (b), 0.80 (a), 0.70 (c).
        let scores: Vec<f32> = merged.iter().map(|r| r.score).collect();
        assert!(
            scores.windows(2).all(|w| w[0] >= w[1]),
            "results not sorted by score desc: {scores:?}"
        );
        assert!((scores[0] - 0.90).abs() < 1e-6);
        assert!((scores[1] - 0.80).abs() < 1e-6);
        assert!((scores[2] - 0.70).abs() < 1e-6);
    }

    #[test]
    fn union_diversify_caps_per_file() {
        // Six results, all from the SAME file but distinct lines: no more than
        // per_file_cap (= 2) may survive for that file.
        let list = vec![
            mk_result("same.rs", 1, 0.99),
            mk_result("same.rs", 2, 0.98),
            mk_result("same.rs", 3, 0.97),
            mk_result("same.rs", 4, 0.96),
            mk_result("same.rs", 5, 0.95),
            mk_result("same.rs", 6, 0.94),
        ];
        let merged = union_diversify(vec![list], 2, 40);
        let from_same = merged
            .iter()
            .filter(|r| r.chunk.file_path == std::path::Path::new("same.rs"))
            .count();
        assert_eq!(from_same, 2, "per_file_cap not enforced: {merged:?}");
        assert_eq!(merged.len(), 2);
    }

    #[test]
    fn union_diversify_caps_total() {
        // 30 results across 30 distinct files: total_cap (= 5) bounds output.
        let list: Vec<crate::types::SearchResult> = (0..30)
            .map(|i| mk_result(&format!("f{i}.rs"), 1, 1.0 - (i as f32) * 0.01))
            .collect();
        let merged = union_diversify(vec![list], 3, 5);
        assert!(
            merged.len() <= 5,
            "total_cap not enforced: {} > 5",
            merged.len()
        );
        assert_eq!(merged.len(), 5);
    }

    #[test]
    fn fanout_full_breadth_gates_on_corpus_size() {
        // Small corpora (gin 2230, flask 1616) keep normal adaptive sizing →
        // false; large corpora (platform 7809, CopilotKit 21705) get full
        // breadth → true. Boundary is inclusive (>= threshold).
        assert!(
            !fanout_full_breadth(2230, 5000),
            "gin (2230) is small → no breadth bypass"
        );
        assert!(
            !fanout_full_breadth(1616, 5000),
            "flask (1616) is small → no breadth bypass"
        );
        assert!(
            fanout_full_breadth(7809, 5000),
            "platform (7809) is large → full breadth"
        );
        assert!(
            fanout_full_breadth(21705, 5000),
            "CopilotKit (21705) is large → full breadth"
        );
        // Boundary: exactly at threshold counts as large (>=).
        assert!(
            fanout_full_breadth(5000, 5000),
            "exactly at threshold (>=) → full breadth"
        );
        assert!(
            !fanout_full_breadth(4999, 5000),
            "just below threshold → no breadth bypass"
        );
    }

    #[test]
    fn exhaustive_fanout_enabled_by_default() {
        // The corpus gate makes fan-out safe, so the shipped default is now ON.
        // Only an explicit "0"/"false" (case-insensitive) disables it.
        assert!(
            fanout_flag_from(None),
            "unset must be ON (shipped default is now on)"
        );
        assert!(fanout_flag_from(Some("")), "empty must be ON (default)");
        assert!(fanout_flag_from(Some("1")), "\"1\" must be ON");
        assert!(fanout_flag_from(Some("true")), "\"true\" must be ON");
        // Explicit opt-out.
        assert!(!fanout_flag_from(Some("0")), "\"0\" must be OFF");
        assert!(!fanout_flag_from(Some("false")), "\"false\" must be OFF");
        assert!(!fanout_flag_from(Some("FALSE")), "\"FALSE\" must be OFF");
    }
}

// --- Spec L: LLM-classifier tests (feature-gated) --------------------------

#[cfg(all(feature = "llm", test))]
mod llm_tests {
    use super::*;
    use crate::llm::LlmCapability;
    use crate::search::agent_classifier::AgentRoute;

    // ── Finding 10: shared-runtime reuse test ──────────────────────────────

    /// Verify that `AgentPipeline` uses the injected shared runtime for
    /// `classify_route_with_llm_fallback` instead of constructing a new one
    /// per call.
    ///
    /// Strategy: inject a mock LLM (returns `Structural`) + a pre-built
    /// runtime, then call `classify_route_with_llm_fallback` via the harness.
    /// The mock will only succeed if it is driven by the runtime we pass in —
    /// if the pipeline somehow builds its own runtime the call still works
    /// (async is runtime-agnostic here), but the important guarantee is that
    /// this test does NOT itself construct a per-call runtime — it reuses the
    /// one it injects. This documents and enforces the Finding 10 contract.
    #[test]
    fn classify_uses_injected_runtime_not_per_call() {
        // Build the shared runtime ONCE (as the daemon does at bind time).
        let rt = Arc::new(
            tokio::runtime::Builder::new_current_thread()
                .enable_all()
                .build()
                .expect("failed to build shared test runtime"),
        );

        let mock: Arc<dyn LlmCapability> = Arc::new(MockLlm {
            route: AgentRoute::Structural,
            fail: false,
        });

        // Drive classify via the harness that mirrors AgentPipeline internals.
        // We pass the same Arc<Runtime> as `with_runtime` would receive.
        let llm_ref = mock.as_ref();
        let timeout = llm_classify_timeout();
        let result = rt.block_on(async {
            tokio::time::timeout(timeout, llm_ref.classify_route("hello world")).await
        });
        let route = match result {
            Ok(Ok(r)) => r,
            _ => classify_agent_query("hello world"),
        };

        // "hello world" keyword-classifies as Semantic; mock returns Structural.
        // If the runtime was reused correctly the mock drove the result.
        assert_eq!(
            route,
            AgentRoute::Structural,
            "shared-runtime path must return mock's route"
        );
    }

    /// A mock LLM that always returns `AgentRoute::Structural`.
    struct MockLlm {
        route: AgentRoute,
        fail: bool,
    }

    #[async_trait::async_trait]
    impl LlmCapability for MockLlm {
        async fn classify_route(&self, _query: &str) -> anyhow::Result<AgentRoute> {
            if self.fail {
                anyhow::bail!("mock LLM classify error");
            }
            Ok(self.route)
        }

        async fn synthesize_hyde_doc(&self, _query: &str) -> anyhow::Result<String> {
            if self.fail {
                anyhow::bail!("mock LLM synthesize error");
            }
            Ok("fn handle_request(req: &Request) -> Response { /* mock */ }".to_string())
        }

        fn label(&self) -> &str {
            "mock-llm"
        }
    }

    /// When an LLM is attached and returns a route, `classify_route_with_llm_fallback`
    /// should return that route (not the keyword default).
    #[test]
    fn llm_classifier_overrides_keyword_default() {
        // "hello world" would keyword-classify as Semantic, but our mock returns Structural.
        let pipeline_wrapper = LlmClassifyHarness::new(AgentRoute::Structural, false);
        let route = pipeline_wrapper.classify("hello world");
        assert_eq!(route, AgentRoute::Structural);
    }

    /// When the mock LLM returns Err, `classify_route_with_llm_fallback` must fall
    /// back to the keyword classifier (not panic, not return the error).
    #[test]
    fn llm_classifier_falls_back_on_error() {
        // "hello world" → keyword: Semantic
        let pipeline_wrapper =
            LlmClassifyHarness::new(AgentRoute::Structural, true /* fail */);
        let route = pipeline_wrapper.classify("hello world");
        // keyword classifier returns Semantic for plain text
        assert_eq!(route, AgentRoute::Semantic);
    }

    /// Test harness that calls `classify_route_with_llm_fallback` without
    /// needing a real HybridSearcher.
    struct LlmClassifyHarness {
        llm: Arc<dyn LlmCapability>,
    }

    impl LlmClassifyHarness {
        fn new(route: AgentRoute, fail: bool) -> Self {
            let mock = MockLlm { route, fail };
            Self {
                llm: Arc::new(mock),
            }
        }

        /// Call the pipeline's classify helper in isolation using a minimal
        /// no-op searcher. We can't easily construct HybridSearcher in tests,
        /// but we CAN test the classify logic by building a harness that calls
        /// the same runtime code.
        fn classify(&self, query: &str) -> AgentRoute {
            // Exercise the same runtime path used in `classify_route_with_llm_fallback`.
            let llm_ref = self.llm.as_ref();
            match tokio::runtime::Builder::new_current_thread()
                .enable_all()
                .build()
            {
                Ok(rt) => {
                    let timeout = llm_classify_timeout();
                    let result = rt.block_on(async {
                        tokio::time::timeout(timeout, llm_ref.classify_route(query)).await
                    });
                    match result {
                        Ok(Ok(r)) => r,
                        Ok(Err(_e)) => classify_agent_query(query),
                        Err(_timeout) => classify_agent_query(query),
                    }
                }
                Err(_) => classify_agent_query(query),
            }
        }
    }
}

// --- v0.5 Item 6: disambiguation suggestion tests --------------------------

#[cfg(test)]
mod disambig_tests {
    use super::*;
    use crate::types::{AstNodeKind, Chunk, ChunkType, Confidence, SearchResult, SearchSource};
    use std::path::PathBuf;

    /// Build a synthetic AST-node SearchResult with the given name, file,
    /// line, score, and per-result confidence.
    fn mk_result(
        name: &str,
        file: &str,
        line: u32,
        score: f32,
        confidence: Confidence,
    ) -> SearchResult {
        SearchResult {
            chunk: Chunk {
                id: 0,
                file_path: PathBuf::from(file),
                start_line: line,
                end_line: line + 10,
                content: format!("fn {name}() {{}}"),
                chunk_type: ChunkType::AstNode {
                    name: name.into(),
                    kind: AstNodeKind::Function,
                    language: "rust".into(),
                    structured_meta: None,
                },
            },
            score,
            source: SearchSource::Hybrid,
            score_dense: 0.0,
            score_sparse: 0.0,
            score_exact: 0.0,
            confidence,
            confidence_score: 0.5,
        }
    }

    /// Spec §5 Item 6: synthetic SearchResult with Ambiguous top result
    /// produces up to 3 disambiguation entries.
    #[test]
    fn ambiguous_top_produces_three_suggestions() {
        let results = vec![
            mk_result(
                "userAuthHandler",
                "auth/users.rs",
                42,
                0.92,
                Confidence::Ambiguous,
            ),
            mk_result(
                "tokenAuthHandler",
                "auth/tokens.rs",
                18,
                0.91,
                Confidence::Inferred,
            ),
            mk_result(
                "sessionAuth",
                "sessions/handler.rs",
                107,
                0.90,
                Confidence::Inferred,
            ),
            mk_result(
                "authMiddleware",
                "api/middleware.rs",
                12,
                0.88,
                Confidence::Inferred,
            ),
        ];

        let disambig = disambiguation_from_results(&results).expect("must populate");
        assert_eq!(disambig.len(), 3);
        assert_eq!(disambig[0].name, "tokenAuthHandler");
        assert_eq!(disambig[0].path, "auth/tokens.rs");
        assert_eq!(disambig[0].line, 18);
        assert_eq!(disambig[1].name, "sessionAuth");
        assert_eq!(disambig[2].name, "authMiddleware");
    }

    /// Spec §5 Item 6: when top result is Extracted (not Ambiguous),
    /// disambiguation is None and formatted output contains no
    /// disambiguation block.
    #[test]
    fn extracted_top_produces_no_suggestions() {
        let results = vec![
            mk_result(
                "authHandler",
                "auth/main.rs",
                1,
                0.99,
                Confidence::Extracted,
            ),
            mk_result(
                "tokenAuthHandler",
                "auth/tokens.rs",
                18,
                0.50,
                Confidence::Inferred,
            ),
            mk_result(
                "sessionAuth",
                "sessions/handler.rs",
                107,
                0.40,
                Confidence::Inferred,
            ),
        ];

        let disambig = disambiguation_from_results(&results);
        assert!(
            disambig.is_none(),
            "Extracted top must not populate disambig"
        );
    }

    /// Spec §5 Item 6: when top is Inferred (also not Ambiguous), no
    /// suggestions either.
    #[test]
    fn inferred_top_produces_no_suggestions() {
        let results = vec![mk_result(
            "lonely",
            "src/m.rs",
            1,
            0.5,
            Confidence::Inferred,
        )];
        assert!(disambiguation_from_results(&results).is_none());
    }

    /// Spec §5 Item 6: dedup by name — a runner-up that shares a name
    /// with the top (e.g. polymorphic same-named symbol in two files) is
    /// skipped, since refining by that name wouldn't disambiguate.
    #[test]
    fn runners_up_with_duplicate_names_are_skipped() {
        let results = vec![
            mk_result("commonName", "a/x.rs", 10, 0.92, Confidence::Ambiguous),
            // duplicate name as top → skip
            mk_result("commonName", "b/x.rs", 20, 0.91, Confidence::Inferred),
            // duplicate name as the next pick → skip second instance
            mk_result("uniqueName", "c/x.rs", 30, 0.90, Confidence::Inferred),
            mk_result("uniqueName", "d/x.rs", 40, 0.89, Confidence::Inferred),
            mk_result("otherName", "e/x.rs", 50, 0.88, Confidence::Inferred),
        ];

        let disambig = disambiguation_from_results(&results).expect("must populate");
        assert_eq!(disambig.len(), 2);
        assert_eq!(disambig[0].name, "uniqueName");
        assert_eq!(disambig[0].path, "c/x.rs");
        assert_eq!(disambig[1].name, "otherName");
    }

    /// Empty results → None (caller is responsible for not calling on
    /// empties, but the helper is safe).
    #[test]
    fn empty_results_produce_no_suggestions() {
        assert!(disambiguation_from_results(&[]).is_none());
    }

    /// Spec §5 Item 6: runners-up that are TextWindow chunks (no
    /// symbol name) are skipped — agents can't refine by a missing name.
    #[test]
    fn runners_up_without_symbol_names_are_skipped() {
        let no_name_result = SearchResult {
            chunk: Chunk {
                id: 0,
                file_path: PathBuf::from("text.md"),
                start_line: 1,
                end_line: 1,
                content: "lorem ipsum".into(),
                chunk_type: ChunkType::TextWindow { window_index: 0 },
            },
            score: 0.91,
            source: SearchSource::Sparse,
            score_dense: 0.0,
            score_sparse: 0.0,
            score_exact: 0.0,
            confidence: Confidence::Inferred,
            confidence_score: 0.5,
        };
        let results = vec![
            mk_result("topResult", "a/x.rs", 1, 0.92, Confidence::Ambiguous),
            no_name_result,
            mk_result("realRunner", "b/x.rs", 30, 0.89, Confidence::Inferred),
        ];
        let disambig = disambiguation_from_results(&results).expect("must populate");
        assert_eq!(disambig.len(), 1);
        assert_eq!(disambig[0].name, "realRunner");
    }
}