agentstatedeveloper_core/

candidates.rs

//! Shared candidate-selection logic used by CLI commands and the MCP server.
//!
//! `find_candidates` is the single entry point: it runs FTS5 hybrid search,
//! injects file-stem matches, applies ledger-aware file deduplication (symbols
//! with ledger entries win their file slot), falls back to an in-memory
//! O(N) scorer when the FTS index is not populated, and finishes with a
//! ledger-anchor pass that unconditionally injects invariant/hazard-bearing
//! symbols whose summaries match any query token.

use std::collections::{HashMap, HashSet};
use std::path::Path;

use crate::engine::Engine;
use crate::index::{AsgIndexStore, IndexStore};
use crate::ledger::{AsgLedgerStore, LedgerStore};
use crate::schema::{LedgerEntry, LedgerKind, Symbol, SymbolKind};
use crate::search_fts::{
    FtsFilters, SearchFtsDb, classify_file_role, classify_layer_sym, hybrid_boost, is_stopword,
};

// ---------------------------------------------------------------------------
// Query tokenisation
// ---------------------------------------------------------------------------

/// Tokenise a free-form query into lowercase, stopword-filtered terms.
pub fn query_tokens(query: &str) -> Vec<String> {
    query
        .split(|c: char| c.is_whitespace() || c == '_' || c == '-' || c == '.')
        .map(|t| t.to_lowercase())
        .filter(|t| t.len() >= 2 && !is_stopword(t))
        .collect()
}

/// Parse a query string into `(positive_tokens, exclusion_terms)`.
///
/// Words prefixed with `-` (e.g. `-sample`) are treated as exclusions.
/// The rest are tokenised with the same rules as `query_tokens`.
///
/// Example: `"drift playhead -sample -waveform"` →
///   tokens: `["drift", "playhead"]`, exclusions: `["sample", "waveform"]`
pub fn parse_query(query: &str) -> (Vec<String>, Vec<String>) {
    let mut positive_words: Vec<&str> = Vec::new();
    let mut exclusions: Vec<String> = Vec::new();

    for word in query.split_whitespace() {
        if let Some(excl) = word.strip_prefix('-') {
            let term = excl.to_lowercase();
            if term.len() >= 2 {
                exclusions.push(term);
            }
        } else {
            positive_words.push(word);
        }
    }

    let tokens = positive_words
        .join(" ")
        .split(|c: char| c.is_whitespace() || c == '_' || c == '-' || c == '.')
        .map(|t| t.to_lowercase())
        .filter(|t| t.len() >= 2 && !is_stopword(t))
        .collect();

    (tokens, exclusions)
}

// ---------------------------------------------------------------------------
// Kind helpers
// ---------------------------------------------------------------------------

/// Plan J t-006: gate for the +2.0 view-query boost. A symbol
/// qualifies if EITHER:
///   - `classify_layer_sym` puts it in `"ui"` or `"viewmodel"`
///     (broader directory + qname-suffix sweep), OR
///   - `classify_file_role` (Plan J t-003) puts it in `"view"` or
///     `"viewmodel"` (stem + extension + `/view(s)/` patterns —
///     catches `.vue`, `.svelte`, and projects that name view
///     directories `components/`).
///
/// Either signal alone is sufficient; the union closes M22's
/// reported gap where files clearly named `*View.swift` lived in
/// non-`/views/` directories and missed the boost despite obvious
/// intent.
pub fn view_layer_matches(layer: &str, file: &str) -> bool {
    if layer == "ui" || layer == "viewmodel" {
        return true;
    }
    let role = classify_file_role(file);
    role == "view" || role == "viewmodel"
}

pub fn kind_str(kind: &SymbolKind) -> &'static str {
    match kind {
        SymbolKind::Module => "module",
        SymbolKind::Function => "function",
        SymbolKind::Method => "method",
        SymbolKind::Class => "class",
        SymbolKind::Variable => "variable",
    }
}

// ---------------------------------------------------------------------------
// In-memory fallback scorer
// ---------------------------------------------------------------------------

/// Score a symbol against query tokens using simple substring matching.
/// Used when the FTS index is not populated.
pub fn in_memory_score(
    sym: &crate::Symbol,
    tokens: &[String],
    ledger_store: &AsgLedgerStore,
    engine: &Engine,
) -> u32 {
    let ledger_text: String = ledger_store
        .list_entries(&engine.ref_name, &sym.symbol_id)
        .unwrap_or_default()
        .iter()
        .map(|e| e.summary.to_lowercase())
        .collect::<Vec<_>>()
        .join(" ");
    in_memory_score_with_text(sym, tokens, &ledger_text)
}

/// Same scoring rules as [`in_memory_score`], but takes the symbol's
/// lowercased ledger-summary text directly so bulk callers can supply
/// it from one ledger-tree walk instead of a per-symbol `list_entries`
/// read (Plan T scale finding).
pub fn in_memory_score_with_text(sym: &crate::Symbol, tokens: &[String], ledger_text: &str) -> u32 {
    let qname_lower = sym.qname.to_lowercase();
    let sig_lower = sym.signature.as_deref().unwrap_or("").to_lowercase();
    let doc_lower = sym.doc.as_deref().unwrap_or("").to_lowercase();
    let file_lower = sym.file.to_lowercase();

    let mut score: u32 = 0;
    for token in tokens {
        if qname_lower.contains(token.as_str()) {
            score += 4;
        }
        if !sig_lower.is_empty() && sig_lower.contains(token.as_str()) {
            score += 3;
        }
        if !doc_lower.is_empty() && doc_lower.contains(token.as_str()) {
            score += 3;
        }
        if !ledger_text.is_empty() && ledger_text.contains(token.as_str()) {
            score += 2;
        }
        if file_lower.contains(token.as_str()) {
            score += 1;
        }
    }
    score
}

// ---------------------------------------------------------------------------
// Glob path matching
// ---------------------------------------------------------------------------

/// Match a file path against a glob pattern.
///
/// Supports:
///   `**`  — matches zero or more path segments
///   `*`   — matches any characters within a single segment (no `/`)
///   all other characters match literally (case-sensitive)
pub fn glob_match(pattern: &str, path: &str) -> bool {
    glob_match_parts(
        &pattern.split('/').collect::<Vec<_>>(),
        &path.split('/').collect::<Vec<_>>(),
    )
}

fn glob_match_parts(pat: &[&str], path: &[&str]) -> bool {
    match (pat.first(), path.first()) {
        (None, None) => true,
        (None, _) | (_, None) => {
            // Pattern exhausted with path remaining, or path exhausted but
            // pattern has non-** remaining — check if remaining pattern is all **
            pat.is_empty() && path.is_empty()
                || pat.iter().all(|p| *p == "**") && path.is_empty()
                || pat.is_empty() && path.is_empty()
        }
        (Some(&"**"), _) => {
            // ** matches zero segments (skip it) or one segment (consume path head)
            glob_match_parts(&pat[1..], path) || glob_match_parts(pat, &path[1..])
        }
        (Some(p), Some(s)) => segment_match(p, s) && glob_match_parts(&pat[1..], &path[1..]),
    }
}

/// Match a single path segment against a pattern segment (supports `*`).
fn segment_match(pat: &str, seg: &str) -> bool {
    let parts: Vec<&str> = pat.split('*').collect();
    if parts.len() == 1 {
        return pat == seg;
    }
    let mut remaining = seg;
    for (i, part) in parts.iter().enumerate() {
        if i == 0 {
            if !remaining.starts_with(part) {
                return false;
            }
            remaining = &remaining[part.len()..];
        } else if i == parts.len() - 1 {
            if !remaining.ends_with(part) {
                return false;
            }
        } else {
            match remaining.find(part) {
                Some(pos) => remaining = &remaining[pos + part.len()..],
                None => return false,
            }
        }
    }
    true
}

/// Return true if `file` matches any of the given glob patterns.
pub fn matches_any_path_glob(globs: &[String], file: &str) -> bool {
    globs.iter().any(|g| glob_match(g.as_str(), file))
}

// ---------------------------------------------------------------------------
// Scope alias resolution
// ---------------------------------------------------------------------------

/// Load named scope aliases from `.asd/scopes.toml` in the current directory.
///
/// Format:
/// ```toml
/// drift-pad = ["App/**/DriftPad*", "Packages/SequencerCore/**"]
/// sequencer-core = ["Packages/SequencerCore/**"]
/// ```
///
/// Returns an empty map if the file is absent or unparseable.
pub fn load_scope_aliases(db_path: &Path) -> HashMap<String, Vec<String>> {
    let scopes_path = db_path
        .parent()
        .unwrap_or(Path::new("."))
        .join("scopes.toml");
    let contents = match std::fs::read_to_string(&scopes_path) {
        Ok(c) => c,
        Err(_) => return HashMap::new(),
    };
    let table: toml::Table = match toml::from_str(&contents) {
        Ok(t) => t,
        Err(_) => return HashMap::new(),
    };
    table
        .into_iter()
        .filter_map(|(k, v)| {
            let globs = match v {
                toml::Value::Array(arr) => arr
                    .into_iter()
                    .filter_map(|v| {
                        if let toml::Value::String(s) = v {
                            Some(s)
                        } else {
                            None
                        }
                    })
                    .collect(),
                toml::Value::String(s) => vec![s],
                _ => return None,
            };
            Some((k, globs))
        })
        .collect()
}

/// Resolve a `--scope` name to path globs.
/// Falls back to treating the scope name itself as a path glob if not in the map.
pub fn resolve_scope(scope: &str, db_path: &Path) -> Vec<String> {
    let aliases = load_scope_aliases(db_path);
    aliases
        .get(scope)
        .cloned()
        .unwrap_or_else(|| vec![scope.to_string()])
}

/// Plan J t-011: load named exclude sets from `.asd/scopes.toml`.
///
/// Format (sits alongside the bare-key scope aliases):
/// ```toml
/// # bare entries remain positive scope aliases (load_scope_aliases)
/// drift-pad = ["App/**/DriftPad*"]
///
/// # new: exclude sets keyed under a dedicated table
/// [exclude_sets]
/// tests = ["**/test_*.py", "tests/**", "**/*_test.go"]
/// generated = ["**/generated/**", "**/*_pb2.py"]
/// ```
///
/// `--exclude-set tests` on the CLI expands to those globs and merges
/// into `FtsFilters::exclude_paths`. Returns an empty map when no
/// `[exclude_sets]` table is present (or when the file is missing).
pub fn load_exclude_sets(db_path: &Path) -> HashMap<String, Vec<String>> {
    let scopes_path = db_path
        .parent()
        .unwrap_or(Path::new("."))
        .join("scopes.toml");
    let contents = match std::fs::read_to_string(&scopes_path) {
        Ok(c) => c,
        Err(_) => return HashMap::new(),
    };
    let table: toml::Table = match toml::from_str(&contents) {
        Ok(t) => t,
        Err(_) => return HashMap::new(),
    };
    let excl = match table.get("exclude_sets") {
        Some(toml::Value::Table(t)) => t.clone(),
        _ => return HashMap::new(),
    };
    excl.into_iter()
        .filter_map(|(k, v)| {
            let globs = match v {
                toml::Value::Array(arr) => arr
                    .into_iter()
                    .filter_map(|v| {
                        if let toml::Value::String(s) = v {
                            Some(s)
                        } else {
                            None
                        }
                    })
                    .collect(),
                toml::Value::String(s) => vec![s],
                _ => return None,
            };
            Some((k, globs))
        })
        .collect()
}

/// Resolve a `--exclude-set` name to negative path globs. Unknown
/// names return an empty list rather than treating the name as a glob
/// (avoids silently turning a typo into a path filter).
pub fn resolve_exclude_set(name: &str, db_path: &Path) -> Vec<String> {
    load_exclude_sets(db_path).remove(name).unwrap_or_default()
}

// ---------------------------------------------------------------------------
// Path filter
// ---------------------------------------------------------------------------

/// Retain only candidates whose file matches at least one of the path globs.
/// No-op when `paths_filter` is empty.
fn apply_paths_filter(
    engine: &Engine,
    index_store: &AsgIndexStore,
    fts: Option<&SearchFtsDb>,
    paths_filter: &[String],
    scored: &mut Vec<(f64, String)>,
) {
    if paths_filter.is_empty() {
        return;
    }
    // M62: reuse the caller's open connection — no extra open() per call.
    let qname_strs: Vec<&str> = scored.iter().map(|(_, q)| q.as_str()).collect();
    let resolved = fts
        .map(|f| f.resolve_qnames_bulk(&qname_strs))
        .unwrap_or_default();
    scored.retain(|(_, qname)| {
        if let Some(rsym) = resolved.get(qname.as_str()) {
            matches_any_path_glob(paths_filter, &rsym.file)
        } else {
            match index_store.get_symbol_by_qname(&engine.ref_name, qname) {
                Ok(Some(sym)) => matches_any_path_glob(paths_filter, &sym.file),
                _ => true,
            }
        }
    });
}

// ---------------------------------------------------------------------------
// Negative-path filter (Plan J t-011)
// ---------------------------------------------------------------------------

/// Drop candidates whose file matches ANY of the exclude globs.
/// No-op when `exclude_paths` is empty.
fn apply_exclude_paths_filter(
    engine: &Engine,
    index_store: &AsgIndexStore,
    fts: Option<&SearchFtsDb>,
    exclude_paths: &[String],
    scored: &mut Vec<(f64, String)>,
) {
    if exclude_paths.is_empty() {
        return;
    }
    let qname_strs: Vec<&str> = scored.iter().map(|(_, q)| q.as_str()).collect();
    let resolved = fts
        .map(|f| f.resolve_qnames_bulk(&qname_strs))
        .unwrap_or_default();
    scored.retain(|(_, qname)| {
        let file = if let Some(rsym) = resolved.get(qname.as_str()) {
            rsym.file.clone()
        } else {
            match index_store.get_symbol_by_qname(&engine.ref_name, qname) {
                Ok(Some(sym)) => sym.file,
                _ => return true, // can't resolve → keep (conservative)
            }
        };
        !matches_any_path_glob(exclude_paths, &file)
    });
}

// ---------------------------------------------------------------------------
// Negative-language filter (Plan J t-011)
// ---------------------------------------------------------------------------

/// Drop candidates whose `language` (case-insensitive) is in the list.
/// No-op when `exclude_languages` is empty.
///
/// `ResolvedSymbol` (the FTS bulk-resolve return) doesn't carry the
/// language field, so this filter falls through to index_store lookup
/// per candidate. Acceptable because: (a) exclude_languages is
/// typically empty, (b) when set, it's usually filtering OUT a large
/// chunk so the lookup cost amortizes against the smaller post-filter
/// set the rest of the pipeline processes.
fn apply_exclude_languages_filter(
    engine: &Engine,
    index_store: &AsgIndexStore,
    _fts: Option<&SearchFtsDb>,
    exclude_languages: &[String],
    scored: &mut Vec<(f64, String)>,
) {
    if exclude_languages.is_empty() {
        return;
    }
    let lower: Vec<String> = exclude_languages.iter().map(|s| s.to_lowercase()).collect();
    scored.retain(|(_, qname)| {
        let lang = match index_store.get_symbol_by_qname(&engine.ref_name, qname) {
            Ok(Some(sym)) => sym.language.to_lowercase(),
            _ => return true, // can't resolve → keep (conservative)
        };
        !lower.iter().any(|excl| excl == &lang)
    });
}

// ---------------------------------------------------------------------------
// Exclusion filter
// ---------------------------------------------------------------------------

/// Remove candidates that match any exclusion term (case-insensitive substring)
/// in their qname, file path, doc comment, or signature.
fn apply_exclusions(
    engine: &Engine,
    index_store: &AsgIndexStore,
    fts: Option<&SearchFtsDb>,
    exclude_terms: &[String],
    scored: &mut Vec<(f64, String)>,
) {
    if exclude_terms.is_empty() {
        return;
    }
    // M62: reuse the caller's open connection — no extra open() per call.
    let qname_strs: Vec<&str> = scored.iter().map(|(_, q)| q.as_str()).collect();
    let resolved = fts
        .map(|f| f.resolve_qnames_bulk(&qname_strs))
        .unwrap_or_default();
    scored.retain(|(_, qname)| {
        let qname_lower = qname.to_lowercase();
        let (file_lower, doc_lower, sig_lower) = if let Some(rsym) = resolved.get(qname.as_str()) {
            (
                rsym.file.to_lowercase(),
                rsym.doc.as_deref().unwrap_or("").to_lowercase(),
                rsym.signature.as_deref().unwrap_or("").to_lowercase(),
            )
        } else {
            match index_store.get_symbol_by_qname(&engine.ref_name, qname) {
                Ok(Some(s)) => (
                    s.file.to_lowercase(),
                    s.doc.as_deref().unwrap_or("").to_lowercase(),
                    s.signature.as_deref().unwrap_or("").to_lowercase(),
                ),
                _ => return true,
            }
        };
        !exclude_terms.iter().any(|excl| {
            qname_lower.contains(excl.as_str())
                || file_lower.contains(excl.as_str())
                || doc_lower.contains(excl.as_str())
                || sig_lower.contains(excl.as_str())
        })
    });
}

// ---------------------------------------------------------------------------
// Ledger-anchor pass
// ---------------------------------------------------------------------------

/// Score assigned to anchored symbols — above zero so they appear in results,
/// but below any genuine FTS hit so they don't displace real matches.
const ANCHOR_SCORE: f64 = 0.5;

/// Maximum number of extra symbols that can be injected by the anchor pass.
const MAX_ANCHORS: usize = 5;

/// After candidate selection, inject invariant/hazard-bearing symbols whose
/// ledger summaries match a query token but were dropped by dedup or FTS ranking.
///
/// M60: replaced 2 `get_tree` git reads (ledger tree + qname index) with a
/// single SQL query against the denormalized `ledger_text`/`ledger_flags`
/// UNINDEXED columns in `asd_search_fts`.
///
/// Falls back to the git-based path when the FTS index is unavailable.
fn ledger_anchor_pass(
    engine: &Engine,
    fts: Option<&SearchFtsDb>,
    tokens: &[String],
    candidates: &mut Vec<(f64, String)>,
) {
    if tokens.is_empty() {
        return;
    }

    let existing_qnames: HashSet<String> = candidates.iter().map(|(_, q)| q.clone()).collect();

    // Fast path: reuse caller's connection — zero extra open() calls.
    if let Some(fts) = fts {
        if fts.has_data() {
            let hits = fts.anchor_candidates(tokens, &existing_qnames, MAX_ANCHORS);
            for (qname, _sym_id) in hits {
                candidates.push((ANCHOR_SCORE, qname));
            }
            return;
        }
    }

    // Fallback: git object store (used when FTS index is absent or empty).
    let ledger_prefix = format!("{}/ledger", crate::paths::ASD_ROOT);
    let ledger_tree = match engine.repo.get_tree(&engine.ref_name, &ledger_prefix) {
        Ok(v) => v,
        Err(_) => return,
    };

    let mut matching_sym_ids: Vec<String> = Vec::new();
    if let serde_json::Value::Object(by_symbol) = ledger_tree {
        for (sym_id, per_symbol) in by_symbol {
            if let serde_json::Value::Object(entries_map) = per_symbol {
                for (_entry_id, v) in entries_map {
                    if let Ok(entry) = serde_json::from_value::<LedgerEntry>(v) {
                        if !matches!(entry.kind, LedgerKind::Invariant | LedgerKind::Hazard) {
                            continue;
                        }
                        let summary_lower = entry.summary.to_lowercase();
                        if tokens.iter().any(|t| summary_lower.contains(t.as_str())) {
                            matching_sym_ids.push(sym_id.clone());
                            break;
                        }
                    }
                }
            }
        }
    }

    if matching_sym_ids.is_empty() {
        return;
    }

    let qname_prefix = format!("{}/index/by-qname", crate::paths::ASD_ROOT);
    let id_map: HashMap<String, Symbol> =
        match engine.repo.get_tree(&engine.ref_name, &qname_prefix) {
            Ok(serde_json::Value::Object(map)) => map
                .values()
                .filter_map(|v| serde_json::from_value::<Symbol>(v.clone()).ok())
                .map(|s| (s.symbol_id.clone(), s))
                .collect(),
            _ => HashMap::new(),
        };

    let mut anchors = 0usize;
    for sym_id in matching_sym_ids {
        if anchors >= MAX_ANCHORS {
            break;
        }
        if let Some(sym) = id_map.get(&sym_id) {
            if !existing_qnames.contains(&sym.qname) {
                candidates.push((ANCHOR_SCORE, sym.qname.clone()));
                anchors += 1;
            }
        }
    }
}

// ---------------------------------------------------------------------------
// Candidate selection
// ---------------------------------------------------------------------------

const ASD_PATH_PREFIX: &str = "/asd/v1";

/// Return the top-`depth` `(score, qname)` pairs for a query.
///
/// Strategy:
/// 1. FTS5 hybrid search with BM25 + ledger boost.
/// 2. File-stem injection: for each query token, find files whose stem
///    contains the token and inject a representative symbol for any file
///    not already in the top-`depth` FTS results.
/// 3. Ledger-aware file dedup: per-file, prefer the symbol that has ledger
///    entries (invariant/hazard/decision) over a higher-scoring sibling
///    that does not.  Invariant-bearing symbols must not be silently dropped.
/// 4. Falls back to in-memory O(N) scoring when FTS is unavailable.
pub fn find_candidates(
    engine: &Engine,
    query: &str,
    tokens: &[String],
    filters: &FtsFilters,
    // Kept for signature compatibility with the many CLI/MCP call sites;
    // the fallback path now reads the ledger in one bulk tree walk
    // (`in_memory_scored_symbols`) instead of per-symbol `list_entries`.
    _ledger_store: &AsgLedgerStore,
    index_store: &AsgIndexStore,
    depth: usize,
) -> Vec<(f64, String)> {
    // --- FTS path ---
    // Borrow the engine's already-open FTS connection — no additional
    // Connection::open() per call.  `fts` is `Option<&SearchFtsDb>` and
    // replaces the former `Option<SearchFtsDb>` that was opened per-call.
    let fts: Option<&SearchFtsDb> = engine.fts.as_ref();
    let fts_result = fts
        .filter(|f| f.has_data())
        .and_then(|f| f.search(query, filters, depth * 2).ok());

    if let Some(hits) = fts_result {
        // Ledger-entry cache: read once per symbol during scoring, reuse in
        // covered_files check below. Eliminates 2× list_entries per top-N hit.
        let ledger_cache: HashMap<String, Vec<crate::schema::LedgerEntry>> =
            HashMap::with_capacity(hits.len());
        // Also keep qname → (symbol_id, file) to avoid get_symbol_by_qname in covered_files.
        let mut qname_to_sym: HashMap<String, (String, String)> =
            HashMap::with_capacity(hits.len());

        // M59: track which symbol_ids have ledger entries using the denormalized
        // FTS fields — no list_entries call needed in the scoring loop.
        let mut has_ledger_ids: HashSet<String> = HashSet::new();

        let mut scored: Vec<(f64, String)> = {
            let mut tmp = Vec::with_capacity(hits.len());
            for hit in hits {
                let boost = hybrid_boost(&hit, tokens);
                // M59: use denormalized ledger_text/flags from FTS row — no list_entries call.
                // ledger_text = all summaries concatenated (lowercase).
                // ledger_flags = comma-separated kinds: "ownership,invariant,hazard,decision".
                let (ledger_boost, ownership_struct_boost) = {
                    let sot = if hit.has_ownership() { 2.0_f64 } else { 0.0 };
                    // Count token hits in the concatenated ledger text and weight by kind.
                    let text_boost = if hit.ledger_text.is_empty() {
                        0.0
                    } else {
                        let matches = tokens
                            .iter()
                            .filter(|t| hit.ledger_text.contains(t.as_str()))
                            .count() as f64;
                        if matches == 0.0 {
                            0.0
                        } else {
                            // Weight by highest-priority kind flagged for this symbol.
                            let weight = if hit.has_ownership() {
                                3.0
                            } else if hit.has_invariant() {
                                1.5
                            } else if hit.has_hazard() {
                                1.0
                            } else {
                                0.5
                            };
                            matches * weight
                        }
                    };
                    if hit.has_ledger() {
                        has_ledger_ids.insert(hit.symbol_id.clone());
                    }
                    (text_boost, sot)
                };
                qname_to_sym.insert(hit.qname.clone(), (hit.symbol_id.clone(), hit.file.clone()));
                tmp.push((
                    hit.bm25_score + boost + ledger_boost + ownership_struct_boost,
                    hit.qname,
                ));
            }
            tmp
        };
        scored.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));

        // File-stem injection: a file is "covered" only when the claiming
        // symbol in the top-`depth` results itself has ledger entries.  If a
        // non-ledger symbol holds the slot, the file stays open so a
        // ledger-bearing sibling can be injected via stem.  Files ranked
        // depth+1..depth*4 are always eligible for re-injection.
        // Uses cached ledger data and pre-built qname→sym map — no extra git reads.
        let covered_files: HashSet<String> = scored
            .iter()
            .take(depth)
            .filter_map(|(_, qname)| {
                let (sym_id, file) = qname_to_sym.get(qname)?;
                // M59: check has_ledger_ids (populated from FTS denormalized fields) first;
                // fall back to ledger_cache for stem-injected hits added below.
                let has_led = has_ledger_ids.contains(sym_id)
                    || ledger_cache.get(sym_id).map_or(false, |e| !e.is_empty());
                if has_led { Some(file.clone()) } else { None }
            })
            .collect();

        const VIEW_STEM_HINTS: &[&str] = &[
            "view", "ui", "render", "display", "screen", "layout", "widget", "cell", "button",
            "pad",
        ];
        let query_lower = query.to_lowercase();
        let is_view_query = VIEW_STEM_HINTS.iter().any(|h| query_lower.contains(h));
        // M62: one UNION ALL query for all tokens — replaces N serial round-trips.
        if let Some(fts) = fts {
            let limit = depth * 2 * tokens.len().max(1);
            if let Ok(stem_hits) = fts.file_stem_candidates_batch(tokens, filters, limit) {
                for hit in stem_hits {
                    if !covered_files.contains(&hit.file) {
                        let boost = hybrid_boost(&hit, tokens);
                        let tier = hit.tier;
                        let layer = classify_layer_sym(&hit.file, &hit.qname, tier, &[]);
                        // Plan J t-006: extend the M28 view-query +2.0
                        // boost to ALSO fire on `file_role == "view"`
                        // and `"viewmodel"`. The original gate keyed
                        // only off `classify_layer_sym`, which uses
                        // directory + qname-suffix patterns; that
                        // misses files where the path doesn't follow
                        // the typical UI convention (`.vue`, `.svelte`,
                        // or any project that puts views in
                        // `app/components/` instead of `views/`).
                        // `classify_file_role` (Plan J t-003) is the
                        // newer, stem+extension-aware check — applying
                        // EITHER signal closes the gap without
                        // changing behavior on already-caught hits
                        // (boost is the same magnitude, scoring is
                        // monotone, the boost still only fires when
                        // `is_view_query` is true).
                        let view_boost = if is_view_query && view_layer_matches(layer, &hit.file) {
                            2.0
                        } else {
                            0.0
                        };
                        // Extend maps so the has_ledger + file-dedup passes below
                        // can use cache lookups instead of get_symbol_by_qname reads.
                        qname_to_sym
                            .entry(hit.qname.clone())
                            .or_insert_with(|| (hit.symbol_id.clone(), hit.file.clone()));
                        // M59: propagate ledger presence from stem hit into has_ledger_ids.
                        if hit.has_ledger() {
                            has_ledger_ids.insert(hit.symbol_id.clone());
                        }
                        scored.push((1.0 + boost + view_boost, hit.qname));
                    }
                }
            }
        }

        scored.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
        scored.dedup_by(|a, b| a.1 == b.1);

        // Ledger-aware file dedup: promote symbols with ledger entries above
        // same-file competitors that only have a score advantage, so an
        // invariant-bearing method is never silently dropped.
        //
        // Uses the ledger_cache and qname_to_sym maps built during the scoring
        // and stem-injection passes — no extra git/index reads needed here.
        let has_ledger: HashSet<String> = scored
            .iter()
            .filter_map(|(_, qname)| {
                let (sym_id, _) = qname_to_sym.get(qname.as_str())?;
                // M59: check has_ledger_ids first (no git read), then ledger_cache fallback.
                let has = has_ledger_ids.contains(sym_id)
                    || ledger_cache.get(sym_id).map_or(false, |e| !e.is_empty());
                if has { Some(qname.clone()) } else { None }
            })
            .collect();
        scored.sort_by(|a, b| {
            let a_ledger = has_ledger.contains(&a.1);
            let b_ledger = has_ledger.contains(&b.1);
            b_ledger
                .cmp(&a_ledger)
                .then_with(|| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal))
        });
        let mut seen_files: HashSet<String> = HashSet::new();
        scored.retain(|(_, qname)| {
            match qname_to_sym.get(qname.as_str()) {
                Some((_, file)) => seen_files.insert(file.clone()),
                None => true, // unknown qname (should not happen) — keep it
            }
        });
        // Restore score order for the final result.
        scored.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
        scored.truncate(depth);

        apply_paths_filter(engine, index_store, fts, &filters.paths_filter, &mut scored);
        apply_exclusions(
            engine,
            index_store,
            fts,
            &filters.exclude_terms,
            &mut scored,
        );
        // Plan J t-011: negative globs + language exclusions.
        apply_exclude_paths_filter(
            engine,
            index_store,
            fts,
            &filters.exclude_paths,
            &mut scored,
        );
        apply_exclude_languages_filter(
            engine,
            index_store,
            fts,
            &filters.exclude_languages,
            &mut scored,
        );

        // Ledger-anchor pass: inject invariant/hazard-bearing symbols that
        // matched query tokens but were dropped by dedup or FTS ranking.
        // M62: pass shared fts handle — no extra Connection::open() call.
        ledger_anchor_pass(engine, fts, tokens, &mut scored);

        return scored;
    }

    // Plan M t-006 (1.0.101): in-memory fallback extracted to a named pipeline stage.
    fallback_in_memory_search(engine, tokens, filters, index_store, fts, depth)
}

/// Bulk in-memory scorer shared by every fallback-search caller (core
/// `find_candidates`, MCP `code_search`, CLI `asd search`): ONE
/// by-qname tree read — deserializing the Symbol values the tree
/// already contains — plus ONE ledger-tree walk, instead of a
/// per-qname symbol fetch and a per-symbol ledger read (~54ms each on
/// a cold FTS cache — ~9 minutes at 10k symbols while holding the
/// engine mutex; Plan T scale finding).
///
/// Returns `(score, Symbol)` for every indexed symbol that passes the
/// optional kind/language filters and matches at least one token, in
/// by-qname tree order; callers sort/truncate to their own contract.
/// `kind_filter` compares against [`kind_str`] output (lowercase).
pub fn in_memory_scored_symbols(
    engine: &Engine,
    tokens: &[String],
    kind_filter: Option<&str>,
    lang_filter: Option<&str>,
) -> Vec<(u32, Symbol)> {
    let prefix = format!("{}/index/by-qname", ASD_PATH_PREFIX);
    let symbols: Vec<Symbol> = match engine.repo.get_tree(&engine.ref_name, &prefix) {
        Ok(serde_json::Value::Object(map)) => map
            .into_iter()
            .filter_map(|(_, v)| serde_json::from_value(v).ok())
            .collect(),
        _ => Vec::new(),
    };

    // One ledger walk → symbol_id → lowercased live-entry summary text
    // (the same text `in_memory_score` derives from `list_entries`).
    let ledger_text: HashMap<String, String> = crate::thinking::all_ledger_buckets(engine)
        .into_iter()
        .map(|(symbol_id, entries)| {
            let text = crate::thinking::live_entries(entries)
                .iter()
                .map(|e| e.summary.to_lowercase())
                .collect::<Vec<_>>()
                .join(" ");
            (symbol_id, text)
        })
        .collect();

    let mut scored: Vec<(u32, Symbol)> = Vec::new();
    for sym in symbols {
        if let Some(k) = kind_filter {
            if kind_str(&sym.kind) != k {
                continue;
            }
        }
        if let Some(lang) = lang_filter {
            if sym.language != lang {
                continue;
            }
        }
        let text = ledger_text
            .get(&sym.symbol_id)
            .map(String::as_str)
            .unwrap_or("");
        let s = in_memory_score_with_text(&sym, tokens, text);
        if s > 0 {
            scored.push((s, sym));
        }
    }
    scored
}

/// Plan M t-006 (1.0.101): in-memory O(N) candidate scoring used when
/// the FTS index is absent or empty. Lives behind a single fn so the
/// FTS path in `find_candidates` stays readable and the fallback can
/// be exercised by direct unit tests without spinning up a fake FTS.
fn fallback_in_memory_search(
    engine: &Engine,
    tokens: &[String],
    filters: &FtsFilters,
    index_store: &AsgIndexStore,
    fts: Option<&SearchFtsDb>,
    depth: usize,
) -> Vec<(f64, String)> {
    eprintln!("asd: FTS index not populated — falling back to in-memory search");

    let kind_filter = filters.kind.as_deref().map(|k| k.to_lowercase());
    let lang_filter = filters.language.as_deref();

    let mut scored: Vec<(f64, String)> =
        in_memory_scored_symbols(engine, tokens, kind_filter.as_deref(), lang_filter)
            .into_iter()
            .map(|(s, sym)| (s as f64, sym.qname))
            .collect();
    scored.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
    scored.truncate(depth);
    apply_paths_filter(engine, index_store, fts, &filters.paths_filter, &mut scored);
    apply_exclusions(
        engine,
        index_store,
        fts,
        &filters.exclude_terms,
        &mut scored,
    );
    ledger_anchor_pass(engine, fts, tokens, &mut scored);
    scored
}

/// Explain why a symbol was returned for a query.
///
/// Returns short reason strings like `"name:playhead"`, `"doc:transport"`,
/// `"ledger:2 invariants"`, `"recent-edit"`. Useful as `match_reasons` in
/// agent output so the caller can understand which signal drove ranking.
pub fn explain_match(
    sym: &Symbol,
    tokens: &[String],
    ledger_entries: &[LedgerEntry],
    is_hot: bool,
) -> Vec<String> {
    let qname_lower = sym.qname.to_lowercase();
    let file_lower = sym.file.to_lowercase();
    let sig_lower = sym.signature.as_deref().unwrap_or("").to_lowercase();
    let doc_lower = sym.doc.as_deref().unwrap_or("").to_lowercase();

    let mut reasons: Vec<String> = Vec::new();
    for token in tokens {
        let t = token.as_str();
        if qname_lower.contains(t) {
            reasons.push(format!("name:{}", token));
        } else if file_lower.contains(t) {
            reasons.push(format!("file:{}", token));
        } else if sig_lower.contains(t) {
            reasons.push(format!("sig:{}", token));
        } else if doc_lower.contains(t) {
            reasons.push(format!("doc:{}", token));
        }
    }

    let inv_count = ledger_entries
        .iter()
        .filter(|e| matches!(e.kind, LedgerKind::Invariant))
        .count();
    let haz_count = ledger_entries
        .iter()
        .filter(|e| matches!(e.kind, LedgerKind::Hazard))
        .count();
    if inv_count > 0 {
        reasons.push(format!("invariant-attached:{}", inv_count));
    }
    if haz_count > 0 {
        reasons.push(format!(
            "ledger:{} hazard{}",
            haz_count,
            if haz_count == 1 { "" } else { "s" }
        ));
    }
    // Ownership-boundary: this symbol is explicitly declared as the source-of-truth
    // for a domain concept that overlaps the query.
    let owns: Vec<&str> = ledger_entries
        .iter()
        .filter(|e| e.kind == LedgerKind::Ownership)
        .map(|e| e.summary.as_str())
        .filter(|s| tokens.iter().any(|t| s.to_lowercase().contains(t.as_str())))
        .collect();
    if !owns.is_empty() {
        reasons.push(format!(
            "ownership:{}",
            owns[0]
                .split_whitespace()
                .take(4)
                .collect::<Vec<_>>()
                .join("-")
        ));
    }
    if is_hot {
        reasons.push("recent-edit".to_string());
    }

    reasons
}

// ---------------------------------------------------------------------------
// Uncertainty model helpers
// ---------------------------------------------------------------------------

/// Normalize raw scores to [0.1, 1.0] confidence within the result set.
/// The highest-scoring result gets 1.0; the lowest gets 0.1.
pub fn confidence_scores(scores: &[f64]) -> Vec<f64> {
    if scores.is_empty() {
        return vec![];
    }
    if scores.len() == 1 {
        return vec![1.0];
    }
    let max = scores.iter().cloned().fold(f64::NEG_INFINITY, f64::max);
    let min = scores.iter().cloned().fold(f64::INFINITY, f64::min);
    let range = max - min;
    if range < 1e-9 {
        return vec![1.0; scores.len()];
    }
    scores
        .iter()
        .map(|&s| 0.1 + 0.9 * (s - min) / range)
        .collect()
}

/// Classify a result into a semantic bucket.
///
/// - `core`       — has ledger entries AND high-signal name match or hot file
/// - `relevant`   — has ledger OR name match (previously "supporting", signal-bearing)
/// - `peripheral` — only doc or file-path match; no ledger, name, or recent edit
/// - `noisy`      — no match signal at all
/// - `test-only`  — symbol lives in a test file
pub fn result_bucket(
    file: &str,
    match_reasons: &[String],
    has_ledger: bool,
    is_hot: bool,
) -> &'static str {
    use crate::search_fts::symbol_tier;
    if symbol_tier(file) == 2 {
        return "test-only";
    }
    let has_name = match_reasons.iter().any(|r| r.starts_with("name:"));
    let has_doc_or_file = match_reasons
        .iter()
        .any(|r| r.starts_with("doc:") || r.starts_with("file:"));
    if has_ledger && (has_name || is_hot) {
        return "core";
    }
    if has_ledger || has_name {
        return "relevant";
    }
    if is_hot || has_doc_or_file {
        return "peripheral";
    }
    "noisy"
}

/// One-line explanation of why a result has high or low confidence.
///
/// Used in `--explain` output and agent JSON to replace the bare bucket label.
pub fn confidence_reason(match_reasons: &[String], has_ledger: bool, is_hot: bool) -> String {
    let has_name = match_reasons.iter().any(|r| r.starts_with("name:"));
    let has_inv = match_reasons
        .iter()
        .any(|r| r.starts_with("invariant-attached:"));
    let has_own = match_reasons.iter().any(|r| r.starts_with("ownership:"));
    let has_haz = match_reasons.iter().any(|r| r.starts_with("ledger:"));
    let has_sig = match_reasons.iter().any(|r| r.starts_with("sig:"));
    let has_doc = match_reasons.iter().any(|r| r.starts_with("doc:"));
    let has_file = match_reasons.iter().any(|r| r.starts_with("file:"));

    if has_name && has_inv {
        "strong: name match + invariant-attached".to_string()
    } else if has_name && has_own {
        "strong: name match + ownership declaration".to_string()
    } else if has_name && has_haz {
        "strong: name match + hazard ledger entry".to_string()
    } else if has_name && has_ledger {
        "strong: name match + ledger entry".to_string()
    } else if has_name && is_hot {
        "moderate: name match + recently edited".to_string()
    } else if has_name {
        "moderate: name match only".to_string()
    } else if has_ledger && has_sig {
        "moderate: signature match + ledger entry".to_string()
    } else if has_ledger {
        "moderate: ledger entry (indirect match)".to_string()
    } else if has_sig {
        "weak: signature match only".to_string()
    } else if has_doc {
        "weak: doc-only match".to_string()
    } else if has_file {
        "weak: file path match only".to_string()
    } else {
        "weak: low-signal indirect match".to_string()
    }
}

/// Detect query tokens that match too many unrelated files (broad/ambiguous terms).
///
/// Returns token strings whose FTS hit count across distinct files exceeds the
/// threshold, indicating they will add noise rather than precision.
///
/// Uses a single SQL UNION ALL query to check all tokens in one round-trip
/// (previously N separate fts.search() calls, each fetching and iterating rows).
pub fn detect_ambiguous_tokens(
    tokens: &[String],
    fts: Option<&SearchFtsDb>,
    filters: &FtsFilters,
) -> Vec<String> {
    const THRESHOLD: usize = 25;
    let fts = match fts {
        Some(f) if f.has_data() => f,
        _ => return vec![],
    };
    let candidates: Vec<&str> = tokens
        .iter()
        .filter(|t| !is_stopword(t))
        .map(|t| t.as_str())
        .collect();
    if candidates.is_empty() {
        return vec![];
    }

    let counts = fts
        .count_distinct_files_per_token(&candidates, filters.include_tests)
        .unwrap_or_default();

    counts
        .into_iter()
        .filter(|(_, cnt)| *cnt > THRESHOLD)
        .map(|(tok, _)| tok)
        .collect()
}

/// Heuristic possible-miss warnings for a result set.
///
/// Checks whether the result set covers the layers implied by the query.
/// Returns human-readable warning strings for use in `possible_misses` output.
/// Pass `scope_narrowed = true` to suppress all warnings when the user
/// intentionally restricted results via --scope / --paths / --exclude (t-001).
pub fn detect_possible_misses(
    query: &str,
    layers_present: &HashSet<&str>,
    result_count: usize,
) -> Vec<String> {
    let ql = query.to_lowercase();
    let mut warnings = Vec::new();

    // UI/view query with no view-layer results.
    const VIEW_HINTS: &[&str] = &[
        "view", " ui", "render", "display", "screen", "layout", "widget", "cell", "button", "pad",
    ];
    const VIEW_LAYERS: &[&str] = &["view", "ui", "presentation"];
    if VIEW_HINTS.iter().any(|h| ql.contains(h))
        && !VIEW_LAYERS.iter().any(|l| layers_present.contains(l))
        && result_count > 0
    {
        warnings.push(
            "no view-layer symbols found — query suggests UI involvement; \
             check --scope or path coverage"
                .to_string(),
        );
    }

    // t-004: service/domain query with results only in UI layer.
    const SERVICE_HINTS: &[&str] = &[
        "service",
        "manager",
        "coordinator",
        "handler",
        "processor",
        "store",
        "repository",
        "repo",
    ];
    const SERVICE_LAYERS: &[&str] = &["service", "domain", "core", "infrastructure"];
    if SERVICE_HINTS.iter().any(|h| ql.contains(h))
        && result_count > 0
        && SERVICE_LAYERS.iter().all(|l| !layers_present.contains(l))
        && (layers_present.contains("view") || layers_present.contains("ui"))
    {
        warnings.push(
            "results are all UI-layer — query suggests service/domain involvement; \
             service layer symbols may not be indexed"
                .to_string(),
        );
    }

    // t-004: data/model query missing persistence layer.
    const DATA_HINTS: &[&str] = &[
        "model",
        "entity",
        "persist",
        "database",
        "migration",
        "schema",
        "table",
    ];
    const DATA_LAYERS: &[&str] = &["persistence", "data", "infrastructure", "domain"];
    if DATA_HINTS.iter().any(|h| ql.contains(h))
        && result_count > 0
        && DATA_LAYERS.iter().all(|l| !layers_present.contains(l))
    {
        warnings.push(
            "no persistence/data-layer symbols found — query suggests data model involvement"
                .to_string(),
        );
    }

    // t-005: Named-layer warnings for scheduler, engine, and network.
    const SCHEDULER_HINTS: &[&str] = &[
        "scheduler",
        "schedule",
        "clock",
        "timer",
        "tick",
        "dispatch",
        "queue",
        "async",
    ];
    if SCHEDULER_HINTS.iter().any(|h| ql.contains(h))
        && result_count > 0
        && !layers_present.contains("scheduler")
    {
        warnings.push(
            "scheduler layer absent from results — query implies timing/dispatch involvement; \
             check that scheduler symbols are indexed"
                .to_string(),
        );
    }

    const ENGINE_HINTS: &[&str] = &[
        "engine",
        "audio",
        "video",
        "render",
        "pipeline",
        "runtime",
        "processor",
    ];
    if ENGINE_HINTS.iter().any(|h| ql.contains(h))
        && result_count > 0
        && !layers_present.contains("engine")
        && !layers_present.contains("core_model")
    {
        warnings.push(
            "engine/core layer absent from results — query implies runtime/processing involvement; \
             consider broadening scope or adding the engine layer to the index"
                .to_string(),
        );
    }

    const NETWORK_HINTS: &[&str] = &[
        "network", "api", "http", "request", "response", "endpoint", "fetch", "upload", "download",
    ];
    if NETWORK_HINTS.iter().any(|h| ql.contains(h))
        && result_count > 0
        && !layers_present.contains("network")
        && !layers_present.contains("infrastructure")
    {
        warnings.push(
            "network layer absent from results — query implies API/network involvement; \
             check that network client symbols are indexed"
                .to_string(),
        );
    }

    // Very few results for a precise multi-word query.
    if result_count > 0 && result_count < 3 && ql.split_whitespace().count() >= 3 {
        warnings.push(format!(
            "only {} result{} for a multi-term query — symbols may not be indexed yet",
            result_count,
            if result_count == 1 { "" } else { "s" }
        ));
    }

    warnings
}

/// Suggest refined, scoped queries when the current query contains ambiguous terms.
///
/// Extracts domain-specific co-occurring tokens from the top result qnames and
/// combines them with the non-ambiguous query tokens to produce 2–3 focused suggestions.
pub fn suggest_scoped_queries(
    original_tokens: &[String],
    ambiguous_terms: &[String],
    top_qnames: &[String],
) -> Vec<String> {
    if ambiguous_terms.is_empty() || top_qnames.is_empty() {
        return vec![];
    }

    let amb_set: HashSet<&str> = ambiguous_terms.iter().map(|s| s.as_str()).collect();
    let specific_tokens: Vec<&str> = original_tokens
        .iter()
        .filter(|t| !amb_set.contains(t.as_str()))
        .map(|s| s.as_str())
        .collect();

    // Extract candidate narrowing terms from top result qnames (last segment words).
    let mut cooccur: HashMap<String, usize> = HashMap::new();
    for qname in top_qnames {
        let last = qname
            .rsplit(|c: char| c == '.' || c == ':' || c == '/')
            .next()
            .unwrap_or(qname);
        // Split CamelCase into words.
        let mut cur = String::new();
        let mut words: Vec<String> = Vec::new();
        for ch in last.chars() {
            if ch.is_uppercase() && !cur.is_empty() {
                words.push(cur.clone());
                cur.clear();
            }
            cur.push(ch.to_lowercase().next().unwrap_or(ch));
        }
        if !cur.is_empty() {
            words.push(cur);
        }
        // Also split snake_case.
        let words: Vec<String> = words
            .iter()
            .flat_map(|w| w.split('_').map(|s| s.to_string()).collect::<Vec<_>>())
            .filter(|w| w.len() > 2 && !is_stopword(w) && !amb_set.contains(w.as_str()))
            .collect();
        for w in words {
            if !original_tokens.iter().any(|t| t == &w) {
                *cooccur.entry(w).or_default() += 1;
            }
        }
    }

    // Pick top 3 most-common co-occurring terms not already in the query.
    let mut ranked: Vec<(usize, String)> = cooccur.into_iter().map(|(w, c)| (c, w)).collect();
    ranked.sort_by(|a, b| b.0.cmp(&a.0));

    let mut suggestions = Vec::new();
    for (_, narrowing_term) in ranked.iter().take(3) {
        let mut parts: Vec<&str> = specific_tokens.clone();
        parts.push(narrowing_term.as_str());
        let query = parts.join(" ");
        if !suggestions.contains(&query) {
            suggestions.push(query);
        }
    }
    suggestions
}

/// Distinguish whether low result confidence comes from ambiguous terms or a
/// sparse index. Returns a vec of typed warning objects with kind + message.
///
/// kinds: "ambiguous_term" | "sparse_index"
pub fn detect_confidence_warnings(
    tokens: &[String],
    result_count: usize,
    ambiguous_terms: &[String],
    fts: Option<&SearchFtsDb>,
) -> Vec<serde_json::Value> {
    use serde_json::json;
    let mut warnings = Vec::new();

    // Ambiguous terms already detected upstream — annotate them with advice.
    for term in ambiguous_terms {
        warnings.push(json!({
            "kind": "ambiguous_term",
            "term": term,
            "message": format!(
                "\"{}\" matches too many unrelated files — add more specific terms to narrow results",
                term
            ),
        }));
    }

    // Sparse index: very few results but no ambiguous terms → index may be thin.
    if result_count < 3 && ambiguous_terms.is_empty() && !tokens.is_empty() {
        // Check total indexed symbol count as a proxy for index completeness.
        let total = fts
            .filter(|f| f.has_data())
            .and_then(|f| f.search("", &FtsFilters::default(), 1).ok())
            .is_some();
        if total {
            warnings.push(json!({
                "kind": "sparse_index",
                "message": "very few results — the index may not cover this area yet; \
                            try `asd index` or broaden the query",
            }));
        }
    }

    warnings
}

/// Suggest more specific queries when the current query is too broad.
///
/// Returns a vec of suggestion strings. Empty when the query is already focused.
pub fn suggest_better_queries(tokens: &[String], query: &str) -> Vec<String> {
    if tokens.is_empty() {
        return vec![];
    }
    let mut suggestions = Vec::new();

    // Single-token broad queries.
    let stopword_count = tokens.iter().filter(|t| is_stopword(t)).count();
    let meaningful = tokens.len() - stopword_count;

    if meaningful <= 1 {
        let tok = tokens
            .iter()
            .find(|t| !is_stopword(t))
            .map(|s| s.as_str())
            .unwrap_or(query);
        suggestions.push(format!(
            "try a more specific phrase, e.g. \"{} <subsystem>\" or \"{} <action>\"",
            tok, tok
        ));
    }

    // Stopword-heavy query (>50% stopwords with 3+ tokens).
    if tokens.len() >= 3 && stopword_count * 2 > tokens.len() {
        suggestions.push(
            "query contains many common words — focus on domain nouns and verbs for better precision"
                .to_string(),
        );
    }

    // Very common single terms likely to be ambiguous.
    const BROAD_TERMS: &[&str] = &[
        "update", "get", "set", "handle", "process", "run", "execute", "init", "start", "stop",
        "load", "save", "create", "delete", "state", "data", "model", "manager", "service", "util",
        "helper", "config",
    ];
    for tok in tokens {
        if BROAD_TERMS.contains(&tok.as_str()) && tokens.len() == 1 {
            suggestions.push(format!(
                "\"{}\" is very broad — combine with a domain term, e.g. \"{} playhead\" or \"{} session\"",
                tok, tok, tok
            ));
        }
    }

    suggestions.dedup();
    suggestions
}

/// Tokenise a feedback query string into a set of non-stopword terms.
fn fb_query_tokens(q: &str) -> std::collections::HashSet<String> {
    q.split(|c: char| !c.is_alphabetic())
        .filter(|t| t.len() > 2)
        .map(|t| t.to_lowercase())
        .filter(|t| !is_stopword(t))
        .collect()
}

/// Extract name tokens from a fully-qualified symbol name for sibling suppression.
/// Takes the last `::` or `.`-delimited segment, then splits snake_case by `_`
/// and CamelCase at uppercase boundaries.
fn name_tokens_from_qname(qname: &str) -> HashSet<String> {
    let last = qname
        .rsplit(|c| c == ':' || c == '.')
        .next()
        .unwrap_or(qname);
    // Split CamelCase at uppercase boundaries.
    let mut tokens: Vec<String> = Vec::new();
    let mut cur = String::new();
    for ch in last.chars() {
        if ch.is_uppercase() && !cur.is_empty() {
            tokens.push(std::mem::take(&mut cur));
        }
        cur.push(ch.to_lowercase().next().unwrap_or(ch));
    }
    if !cur.is_empty() {
        tokens.push(cur);
    }
    // Also split by `_`.
    tokens
        .iter()
        .flat_map(|t| t.split('_'))
        .filter(|t| t.len() > 2 && !is_stopword(t))
        .map(|t| t.to_string())
        .collect()
}

/// t-003: Query-family matching — a stored verdict applies to the current query
/// when their token sets overlap by at least one token (not just substring match).
/// This makes "drift playhead" verdicts apply to "playhead drift" and
/// "drift pad playhead position".
fn query_family_matches(
    current_query_tokens: &std::collections::HashSet<String>,
    fb_query: &str,
) -> bool {
    if fb_query.is_empty() {
        return true;
    }
    let fb_tokens = fb_query_tokens(fb_query);
    if fb_tokens.is_empty() {
        return true;
    }
    // Any shared non-stopword token means the queries are in the same family.
    fb_tokens.iter().any(|t| current_query_tokens.contains(t))
}

/// Apply feedback verdicts as score adjustments after candidate selection.
///
/// Metrics returned by `apply_feedback_adjustments`, describing how feedback
/// changed the ranked result set for this query.
#[derive(Debug, Default, Clone, serde::Serialize, serde::Deserialize)]
pub struct FeedbackMetrics {
    /// Feedback entries whose stored query matched the current query family.
    pub entries_applied: usize,
    /// Total symbols removed from results (all causes combined).
    pub suppressed: usize,
    /// Symbols in a noisy file preserved because they had an explicit Useful verdict.
    pub preserved_useful_siblings: usize,
    /// Useful verdicts that boosted a symbol's score.
    pub boosted: usize,
    /// Symbols suppressed by the recurring false-positive rule (≥2 noisy verdicts).
    pub recurring_fp_suppressed: usize,
    /// Plan C t-003: symbols suppressed by an active Constraint/Decision
    /// ledger entry carrying a penalty role (stale-api / audit-pending).
    /// Independent of `suppressed` so callers can tell ranking-time
    /// decisions apart from feedback-time verdicts.
    #[serde(default)]
    pub constraint_penalties_applied: usize,
    /// Plan C t-006: candidates boosted by +1.0 because they fall inside
    /// the active CTX task's recorded scope. Soft bias only.
    #[serde(default)]
    pub task_bias_boosted: usize,
    /// Unique rule names that fired, in first-encounter order.
    /// Values: "exact_noisy", "same_file_sibling_suppression", "useful_boost",
    /// "recurring_fp", "constraint_penalty" (Plan C t-003), "task_bias"
    /// (Plan C t-006), "already_covered" / "diagnostic_only" (Plan C t-005).
    pub rules_applied: Vec<String>,
}

/// `Useful` entries add a boost; `Noisy` / `WrongLayer` entries demote the
/// symbol to negative infinity (effectively removed). Also:
///
/// - t-002: Sibling propagation — when a symbol in a file is marked Noisy or
///   WrongLayer, all other symbols from the same file are also suppressed for
///   query families that overlap the noisy verdict.
/// - t-003: Query-family matching — a stored verdict applies to the current
///   query when they share at least one non-stopword token, not just exact
///   substring match.
/// - Recurring false positives — symbols with ≥2 noisy verdicts sharing a
///   query token are suppressed for any query that overlaps those tokens.
///
/// Called at CLI/MCP call sites after `find_candidates`.
/// Plan C t-006: read the active CTX task scope (file globs) and return
/// it for bias scoring. Source preference: `CTX_ACTIVE_TASK` env var
/// (JSON object), else `.asd/cache/active-task.json` relative to the
/// db's parent dir, else None. Schema: `{"task_id": "...", "scope":
/// ["src/foo/**", ...]}` — only the `scope` array is consumed.
///
/// Returns None when no task state is found or the scope is empty. The
/// caller treats a None return as "no bias to apply".
pub fn read_active_task_scope(db_path_parent: Option<&std::path::Path>) -> Option<Vec<String>> {
    let env_raw = std::env::var("CTX_ACTIVE_TASK").ok();
    read_active_task_scope_from(env_raw.as_deref(), db_path_parent)
}

/// Plan E t-002: parallel-safe variant. Takes the raw env string
/// explicitly so unit tests can exercise the parser without mutating
/// process env (which is racy under `cargo test`'s default parallel
/// runner). Production code path stays simple via the wrapper above.
pub fn read_active_task_scope_from(
    env_raw: Option<&str>,
    db_path_parent: Option<&std::path::Path>,
) -> Option<Vec<String>> {
    let raw: String = env_raw.map(|s| s.to_string()).or_else(|| {
        let p = db_path_parent?
            .join(".asd")
            .join("cache")
            .join("active-task.json");
        std::fs::read_to_string(p).ok()
    })?;
    let v: serde_json::Value = serde_json::from_str(&raw).ok()?;
    let arr = v.get("scope")?.as_array()?;
    let scope: Vec<String> = arr
        .iter()
        .filter_map(|s| s.as_str().map(|s| s.to_string()))
        .filter(|s| !s.is_empty())
        .collect();
    if scope.is_empty() { None } else { Some(scope) }
}

/// Plan C t-006: apply a soft `boost` (default 1.0) to candidates whose
/// file matches any glob in the active task's scope. Soft = additive,
/// never a hard filter — so a wrong scope guess at most demotes the
/// agent's intended targets relative to in-scope ones, never hides
/// them. Returns the boosted count.
pub fn apply_task_bias(
    engine: &Engine,
    index_store: &AsgIndexStore,
    scored: &mut Vec<(f64, String)>,
    scope: &[String],
    boost: f64,
) -> usize {
    if scope.is_empty() {
        return 0;
    }

    // Plan E t-005: bulk qname→file lookup via the FTS cache when
    // available — one SQL roundtrip instead of N. Falls back to the
    // per-candidate index lookup when fts is None (in-memory engines,
    // mid-rebuild).
    let qnames_owned: Vec<String> = scored
        .iter()
        .filter(|(s, _)| s.is_finite())
        .map(|(_, q)| q.clone())
        .collect();
    let file_by_qname: std::collections::HashMap<String, String> =
        if let Some(fts) = engine.fts.as_ref() {
            let qnames_ref: Vec<&str> = qnames_owned.iter().map(|s| s.as_str()).collect();
            fts.files_for_qnames(&qnames_ref, &engine.ref_name)
        } else {
            std::collections::HashMap::new()
        };

    let mut boosted = 0;
    for (score, qname) in scored.iter_mut() {
        if !score.is_finite() {
            continue;
        }
        // Bulk-cache hit avoids the index lookup.
        let file = if let Some(f) = file_by_qname.get(qname) {
            f.clone()
        } else {
            match index_store.get_symbol_by_qname(&engine.ref_name, qname) {
                Ok(Some(s)) => s.file,
                _ => continue,
            }
        };
        if scope.iter().any(|g| glob_match(g, &file)) {
            *score += boost;
            boosted += 1;
        }
    }
    boosted
}

/// Plan E t-008: parse the optional `scope: ["glob"]` array out of a
/// constraint entry's body. The body may itself be a JSON-encoded
/// string OR null. Returns None when no scope is present (penalty
/// applies globally) or when parsing fails — same fallback as the
/// SQL-side helper.
fn constraint_scope_from_body(body: Option<&str>) -> Option<Vec<String>> {
    let raw = body?;
    let v: serde_json::Value = serde_json::from_str(raw).ok()?;
    let arr = v.get("scope")?.as_array()?;
    let globs: Vec<String> = arr
        .iter()
        .filter_map(|g| g.as_str().map(String::from))
        .filter(|g| !g.is_empty())
        .collect();
    if globs.is_empty() { None } else { Some(globs) }
}

/// Plan C t-003: synthesize WrongLayer-like suppression from
/// Constraint/Decision ledger entries that carry a penalty `role`
/// (currently `stale-api` and `audit-pending`). Walks each candidate's
/// ledger entries via the existing AsgLedgerStore; matches go to
/// `NEG_INFINITY` just like the existing Noisy/WrongLayer path.
///
/// Returns the count of candidates suppressed. Cheap on small candidate
/// sets (one ledger walk per symbol via the SQLite cache); large
/// candidate sets can be optimized later via index-time denormalization
/// if needed.
pub fn apply_constraint_penalties(
    engine: &Engine,
    index_store: &AsgIndexStore,
    scored: &mut Vec<(f64, String)>,
) -> usize {
    // Plan E t-004: prefer one-shot SQL over per-candidate ledger walk.
    // Plan E t-008: each penalty entry MAY carry a `scope: [glob]` list in
    // its body JSON — if present, suppression only fires when the
    // candidate's file matches at least one glob. Entries without scope
    // apply globally (preserves the original Plan C t-003 semantics).
    if let Some(fts) = engine.fts.as_ref() {
        if let Ok(pairs) = fts.symbols_with_constraint_penalties_scoped(&engine.ref_name) {
            if !pairs.is_empty() {
                // Build sym_id → Vec<Option<Vec<String>>> so the same
                // symbol may have several penalty entries (e.g. one global
                // + one scoped). The candidate is suppressed when AT
                // LEAST ONE entry would suppress it.
                use std::collections::HashMap;
                let mut by_sym: HashMap<String, Vec<Option<Vec<String>>>> = HashMap::new();
                for (sid, scope) in pairs {
                    by_sym.entry(sid).or_default().push(scope);
                }
                let mut suppressed = 0;
                for (score, qname) in scored.iter_mut() {
                    if *score == f64::NEG_INFINITY {
                        continue;
                    }
                    let sym = match index_store.get_symbol_by_qname(&engine.ref_name, qname) {
                        Ok(Some(s)) => s,
                        _ => continue,
                    };
                    if let Some(entries) = by_sym.get(&sym.symbol_id) {
                        let hit = entries.iter().any(|scope_opt| match scope_opt {
                            None => true, // global — always suppresses
                            Some(globs) => globs.iter().any(|g| glob_match(g, &sym.file)),
                        });
                        if hit {
                            *score = f64::NEG_INFINITY;
                            suppressed += 1;
                        }
                    }
                }
                return suppressed;
            }
            // No penalty entries in the cache — nothing to suppress.
            return 0;
        }
    }

    // Fallback: per-candidate ledger walk when the FTS cache isn't
    // available. Same semantics as the original implementation.
    let ledger_store = crate::ledger::AsgLedgerStore::from_engine(engine);
    let mut suppressed = 0;
    for (score, qname) in scored.iter_mut() {
        if *score == f64::NEG_INFINITY {
            continue;
        }
        let sym = match index_store.get_symbol_by_qname(&engine.ref_name, qname) {
            Ok(Some(s)) => s,
            _ => continue,
        };
        let entries = match ledger_store.list_entries(&engine.ref_name, &sym.symbol_id) {
            Ok(e) => e,
            Err(_) => continue,
        };
        let hit = entries.iter().any(|entry| {
            let kind_matches = matches!(
                entry.kind,
                crate::schema::LedgerKind::Constraint | crate::schema::LedgerKind::Decision
            );
            if !kind_matches {
                return false;
            }
            let role_is_penalty = entry
                .role
                .as_deref()
                .and_then(crate::schema::RoleTag::from_str)
                .map(|r| r.is_penalty_role())
                .unwrap_or(false);
            if !role_is_penalty {
                return false;
            }
            // Plan E t-008: honor scope[] in body JSON if present.
            // Symmetric with the fast path.
            match constraint_scope_from_body(entry.body.as_deref()) {
                None => true, // global penalty
                Some(globs) => globs.iter().any(|g| glob_match(g, &sym.file)),
            }
        });
        if hit {
            *score = f64::NEG_INFINITY;
            suppressed += 1;
        }
    }
    suppressed
}

pub fn apply_feedback_adjustments(
    engine: &Engine,
    index_store: &AsgIndexStore,
    query: &str,
    scored: &mut Vec<(f64, String)>,
    // Plan J t-016: tuple gained `created_at` so the Useful boost can
    // decay by age. Tuple shape kept (vs converting to a struct) to
    // minimize churn across the ~7 CLI/MCP callers; the trait helper
    // `FeedbackStore::flat_verdicts` already produces this shape.
    feedback_entries: &[(
        String,
        String,
        crate::schema::FeedbackVerdict,
        chrono::DateTime<chrono::Utc>,
    )],
) -> FeedbackMetrics {
    // Plan C t-006: bias toward the active CTX task's scope first, so
    // in-scope candidates start with a small head-start before
    // suppression/boost rules run.
    let task_bias_boosted = {
        let parent = engine
            .db_path
            .as_ref()
            .and_then(|p| p.parent())
            .map(|p| p.to_path_buf());
        let scope = read_active_task_scope(parent.as_deref()).unwrap_or_default();
        if scope.is_empty() {
            0
        } else {
            apply_task_bias(engine, index_store, scored, &scope, 1.0)
        }
    };

    // Plan C t-003: apply constraint penalties FIRST so feedback rules
    // don't have to special-case symbols already suppressed.
    let constraint_penalties_applied = apply_constraint_penalties(engine, index_store, scored);

    if feedback_entries.is_empty() {
        let mut m = FeedbackMetrics::default();
        m.constraint_penalties_applied = constraint_penalties_applied;
        m.task_bias_boosted = task_bias_boosted;
        if constraint_penalties_applied > 0 {
            m.rules_applied.push("constraint_penalty".to_string());
        }
        if task_bias_boosted > 0 {
            m.rules_applied.push("task_bias".to_string());
        }
        return m;
    }
    let query_norm = query.to_lowercase();
    let current_tokens: std::collections::HashSet<String> = fb_query_tokens(&query_norm);
    let current_tokens_vec: Vec<&str> = current_tokens.iter().map(|s| s.as_str()).collect();

    // Metrics accumulators.
    let entries_applied = feedback_entries
        .iter()
        .filter(|(_, fb_q, _, _)| query_family_matches(&current_tokens, fb_q))
        .count();
    let mut preserved_useful_siblings: usize = 0;
    let mut boosted: usize = 0;
    let mut recurring_fp_suppressed: usize = 0;
    let mut rules_seen: std::collections::HashSet<&str> = std::collections::HashSet::new();
    let mut rules_applied: Vec<String> = Vec::new();
    macro_rules! record_rule {
        ($name:expr) => {
            if rules_seen.insert($name) {
                rules_applied.push($name.to_string());
            }
        };
    }

    // --- Recurring false positive map ---
    let mut noisy_queries_by_sym: std::collections::HashMap<&str, Vec<&str>> =
        std::collections::HashMap::new();
    for (sym_id, fb_query, verdict, _created_at) in feedback_entries {
        if matches!(
            verdict,
            crate::schema::FeedbackVerdict::Noisy | crate::schema::FeedbackVerdict::WrongLayer
        ) {
            noisy_queries_by_sym
                .entry(sym_id.as_str())
                .or_default()
                .push(fb_query.as_str());
        }
    }
    let recurring_fp: std::collections::HashMap<&str, Vec<String>> = noisy_queries_by_sym
        .into_iter()
        .filter(|(_, queries)| queries.len() >= 2)
        .map(|(sym_id, queries)| {
            let mut token_counts: std::collections::HashMap<String, usize> =
                std::collections::HashMap::new();
            for q in &queries {
                let tokens = fb_query_tokens(q);
                for t in tokens {
                    *token_counts.entry(t).or_default() += 1;
                }
            }
            let suppression_tokens: Vec<String> = token_counts
                .into_iter()
                .filter(|(_, count)| *count >= 2)
                .map(|(t, _)| t)
                .collect();
            (sym_id, suppression_tokens)
        })
        .collect();

    // --- t-001: Build noisy-file map via asd_symbols_meta (M60: no git read).
    // Falls back to get_tree when FTS index is unavailable.
    struct NoisySymInfo {
        sym_id: String,
        name_tokens: HashSet<String>,
    }
    let mut noisy_file_syms: HashMap<String, Vec<NoisySymInfo>> = HashMap::new();
    {
        let noisy_ids: Vec<&str> = feedback_entries
            .iter()
            .filter(|(_, fb_query, verdict, _)| {
                matches!(
                    verdict,
                    crate::schema::FeedbackVerdict::Noisy
                        | crate::schema::FeedbackVerdict::WrongLayer
                ) && query_family_matches(&current_tokens, fb_query)
            })
            .map(|(sym_id, _, _, _)| sym_id.as_str())
            .collect();
        if !noisy_ids.is_empty() {
            // M60: bulk-resolve noisy symbol_ids via FTS — one SQL query.
            let resolved = engine
                .fts
                .as_ref()
                .map(|fts| fts.resolve_symbol_ids_bulk(&noisy_ids))
                .unwrap_or_default();
            if !resolved.is_empty() {
                for (sym_id_str, rsym) in &resolved {
                    let name_tokens = name_tokens_from_qname(&rsym.qname);
                    noisy_file_syms
                        .entry(rsym.file.clone())
                        .or_default()
                        .push(NoisySymInfo {
                            sym_id: sym_id_str.clone(),
                            name_tokens,
                        });
                }
            } else {
                // Fallback: git object store.
                let prefix = format!("{}/index/by-qname", ASD_PATH_PREFIX);
                if let Ok(serde_json::Value::Object(map)) =
                    engine.repo.get_tree(&engine.ref_name, &prefix)
                {
                    let noisy_set: HashSet<&str> = noisy_ids.into_iter().collect();
                    for sym_val in map.values() {
                        if let Ok(sym) = serde_json::from_value::<Symbol>(sym_val.clone()) {
                            if noisy_set.contains(sym.symbol_id.as_str()) {
                                let name_tokens = name_tokens_from_qname(&sym.qname);
                                noisy_file_syms.entry(sym.file.clone()).or_default().push(
                                    NoisySymInfo {
                                        sym_id: sym.symbol_id,
                                        name_tokens,
                                    },
                                );
                            }
                        }
                    }
                }
            }
        }
    }

    // M60: pre-fetch all scored qnames in one SQL batch — no per-symbol git read.
    let scored_qnames: Vec<&str> = scored.iter().map(|(_, q)| q.as_str()).collect();
    let resolved_map = engine
        .fts
        .as_ref()
        .map(|fts| fts.resolve_qnames_bulk(&scored_qnames))
        .unwrap_or_default();

    // --- Score adjustments ---
    for (score, qname) in scored.iter_mut() {
        // M60: use FTS bulk-resolved data; fall back to git read if missing.
        let (sym_file, sym_symbol_id, sym_kind) =
            if let Some(rsym) = resolved_map.get(qname.as_str()) {
                (rsym.file.clone(), rsym.symbol_id.clone(), rsym.kind.clone())
            } else {
                match index_store.get_symbol_by_qname(&engine.ref_name, qname) {
                    Ok(Some(s)) => (s.file, s.symbol_id, format!("{:?}", s.kind).to_lowercase()),
                    _ => continue,
                }
            };
        let sym_id = &sym_symbol_id;
        // Reconstruct a minimal view for the checks below.
        let sym_kind_enum = match sym_kind.as_str() {
            "class" => SymbolKind::Class,
            "module" => SymbolKind::Module,
            _ => SymbolKind::Function,
        };

        // Sibling file suppression: a symbol sharing a file with a noisy symbol
        // is suppressed only when it passes ALL three guards:
        //   1. Not a Class/Module container (those host unrelated symbols).
        //   2. Not the noisy symbol itself (already handled below).
        //   3. Its name tokens overlap with the noisy symbol's name tokens
        //      (t-001: avoid collateral demotions on unrelated symbols).
        //   4. It has no explicit Useful verdict for this query family.
        //   5. It has no independent query affinity (its own name doesn't match
        //      the current query tokens — if it does, it's genuinely relevant).
        if let Some(noisy_syms) = noisy_file_syms.get(&sym_file) {
            let is_container = matches!(sym_kind_enum, SymbolKind::Class | SymbolKind::Module);
            let is_the_noisy_sym = noisy_syms.iter().any(|ns| ns.sym_id == *sym_id);
            if !is_container && !is_the_noisy_sym {
                let has_useful = feedback_entries.iter().any(|(fid, fq, v, _)| {
                    fid == sym_id
                        && matches!(v, crate::schema::FeedbackVerdict::Useful)
                        && query_family_matches(&current_tokens, fq)
                });
                if !has_useful {
                    // t-001: name-specificity guard — only suppress if the sibling's
                    // own name tokens overlap with those of the noisy symbol.
                    // Symbols with no name overlap are unrelated and must not be demoted.
                    let sibling_tokens = name_tokens_from_qname(qname);
                    let name_related = noisy_syms.iter().any(|ns| {
                        ns.sym_id != *sym_id
                            && sibling_tokens.iter().any(|t| ns.name_tokens.contains(t))
                    });
                    // Query-affinity guard: if the sibling's own name matches the current
                    // query tokens it is independently relevant and must be preserved.
                    let query_relevant = sibling_tokens.iter().any(|t| current_tokens.contains(t));
                    if name_related && !query_relevant {
                        *score = f64::NEG_INFINITY;
                        record_rule!("same_file_sibling_suppression");
                        continue;
                    } else {
                        preserved_useful_siblings += 1;
                    }
                } else {
                    preserved_useful_siblings += 1;
                }
            }
        }

        // Per-symbol verdict matching (t-003: query-family aware).
        // Plan J t-016: snapshot `now` ONCE per scoring pass so all
        // entries in this loop decay against the same instant —
        // avoids the (cosmetic but real) bug where two entries with
        // the same created_at could get slightly different decay
        // factors if Utc::now() is called inside the loop body.
        let now_for_decay = chrono::Utc::now();
        for (fb_symbol_id, fb_query, verdict, fb_created_at) in feedback_entries {
            if fb_symbol_id != sym_id {
                continue;
            }
            // t-003: use token-family matching instead of substring containment.
            if !query_family_matches(&current_tokens, fb_query) {
                continue;
            }
            match verdict {
                crate::schema::FeedbackVerdict::Useful => {
                    // Plan J t-016: scale the +1.5 boost by age-based
                    // decay. Negative verdicts (Noisy / WrongLayer /
                    // AlreadyCovered / DiagnosticOnly) intentionally
                    // do NOT decay — they're explicit "this is wrong"
                    // signals, not preferences. The agent can use
                    // `asd feedback mark --ttl-days N` from Plan J
                    // t-014 if they want soft expiry on a negative.
                    let decay = crate::feedback::decay_for_entry(
                        *fb_created_at,
                        now_for_decay,
                        crate::feedback::DEFAULT_FEEDBACK_HALF_LIFE_DAYS,
                    );
                    *score += 1.5 * decay;
                    boosted += 1;
                    record_rule!("useful_boost");
                }
                crate::schema::FeedbackVerdict::Noisy
                | crate::schema::FeedbackVerdict::WrongLayer => {
                    *score = f64::NEG_INFINITY;
                    record_rule!("exact_noisy");
                }
                crate::schema::FeedbackVerdict::AlreadyCovered => {
                    // Plan C t-005: suppress like Noisy, plus a distinct
                    // rule label so callers can tell what drove the cut.
                    *score = f64::NEG_INFINITY;
                    record_rule!("already_covered");
                }
                crate::schema::FeedbackVerdict::DiagnosticOnly => {
                    // Plan C t-005: suppress like Noisy; the t-003
                    // constraint-penalty pass will also catch the symbol
                    // on later queries once the caller writes the matching
                    // Classification entry.
                    *score = f64::NEG_INFINITY;
                    record_rule!("diagnostic_only");
                }
                crate::schema::FeedbackVerdict::Missing => {}
            }
        }

        // Recurring false positive suppression.
        if score.is_finite() {
            if let Some(sup_tokens) = recurring_fp.get(sym_id.as_str()) {
                if current_tokens_vec
                    .iter()
                    .any(|qt| sup_tokens.iter().any(|st| st == *qt))
                {
                    *score = f64::NEG_INFINITY;
                    recurring_fp_suppressed += 1;
                    record_rule!("recurring_fp");
                }
            }
        }
    }
    let before = scored.len();
    scored.retain(|(s, _)| s.is_finite());
    let suppressed = before - scored.len();
    if constraint_penalties_applied > 0 && !rules_applied.iter().any(|r| r == "constraint_penalty")
    {
        rules_applied.push("constraint_penalty".to_string());
    }
    if task_bias_boosted > 0 && !rules_applied.iter().any(|r| r == "task_bias") {
        rules_applied.push("task_bias".to_string());
    }
    FeedbackMetrics {
        entries_applied,
        suppressed,
        preserved_useful_siblings,
        boosted,
        recurring_fp_suppressed,
        constraint_penalties_applied,
        task_bias_boosted,
        rules_applied,
    }
}

/// Per-result explanation of which feedback verdict affected a search hit.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct FeedbackImpact {
    /// Verdict that applied: "useful", "noisy", "wrong_layer", or "sibling_suppressed".
    pub verdict: String,
    /// The original feedback query that triggered this impact.
    pub matched_query: String,
    /// The author who recorded the feedback.
    pub author: String,
}

/// For each qname in `qnames`, determine which feedback verdict (if any)
/// affected it and return a map of qname → FeedbackImpact.
///
/// Used by search commands to annotate results with why they were boosted,
/// demoted, or suppressed.
pub fn explain_feedback_impacts(
    engine: &Engine,
    index_store: &AsgIndexStore,
    query: &str,
    qnames: &[String],
    feedback_entries: &[crate::schema::FeedbackEntry],
) -> HashMap<String, FeedbackImpact> {
    let mut impacts: HashMap<String, FeedbackImpact> = HashMap::new();
    if feedback_entries.is_empty() || qnames.is_empty() {
        return impacts;
    }
    let query_norm = query.to_lowercase();
    let current_tokens = fb_query_tokens(&query_norm);

    // M60: Build noisy-file map via resolve_symbol_ids_bulk — no git read.
    struct NoisyFileEntry {
        sym_id: String,
        name_tokens: HashSet<String>,
    }
    let mut noisy_file_syms: HashMap<String, Vec<NoisyFileEntry>> = HashMap::new();
    {
        let noisy_ids: Vec<&str> = feedback_entries
            .iter()
            .filter(|e| {
                matches!(
                    e.verdict,
                    crate::schema::FeedbackVerdict::Noisy
                        | crate::schema::FeedbackVerdict::WrongLayer
                ) && query_family_matches(&current_tokens, &e.query)
            })
            .map(|e| e.symbol_id.as_str())
            .collect();
        if !noisy_ids.is_empty() {
            let resolved = engine
                .fts
                .as_ref()
                .map(|fts| fts.resolve_symbol_ids_bulk(&noisy_ids))
                .unwrap_or_default();
            if !resolved.is_empty() {
                for (sym_id_str, rsym) in &resolved {
                    noisy_file_syms
                        .entry(rsym.file.clone())
                        .or_default()
                        .push(NoisyFileEntry {
                            sym_id: sym_id_str.clone(),
                            name_tokens: name_tokens_from_qname(&rsym.qname),
                        });
                }
            } else {
                // Fallback: git object store.
                let noisy_set: HashSet<&str> = noisy_ids.into_iter().collect();
                let prefix = format!("{}/index/by-qname", ASD_PATH_PREFIX);
                if let Ok(serde_json::Value::Object(map)) =
                    engine.repo.get_tree(&engine.ref_name, &prefix)
                {
                    for sym_val in map.values() {
                        if let Ok(sym) = serde_json::from_value::<Symbol>(sym_val.clone()) {
                            if noisy_set.contains(sym.symbol_id.as_str()) {
                                noisy_file_syms.entry(sym.file.clone()).or_default().push(
                                    NoisyFileEntry {
                                        sym_id: sym.symbol_id,
                                        name_tokens: name_tokens_from_qname(&sym.qname),
                                    },
                                );
                            }
                        }
                    }
                }
            }
        }
    }

    // M60: pre-fetch all qnames in one SQL batch.
    let qname_strs: Vec<&str> = qnames.iter().map(|q| q.as_str()).collect();
    let resolved_map = engine
        .fts
        .as_ref()
        .map(|fts| fts.resolve_qnames_bulk(&qname_strs))
        .unwrap_or_default();

    for qname in qnames {
        let (sym_id_owned, sym_file, sym_kind_enum) =
            if let Some(rsym) = resolved_map.get(qname.as_str()) {
                let kind = match rsym.kind.as_str() {
                    "class" => SymbolKind::Class,
                    "module" => SymbolKind::Module,
                    _ => SymbolKind::Function,
                };
                (rsym.symbol_id.clone(), rsym.file.clone(), kind)
            } else {
                match index_store.get_symbol_by_qname(&engine.ref_name, qname) {
                    Ok(Some(s)) => {
                        let k = s.kind.clone();
                        (s.symbol_id, s.file, k)
                    }
                    _ => continue,
                }
            };
        let sym_id = &sym_id_owned;

        // Check per-symbol verdicts first (direct match takes priority).
        let mut found = false;
        for entry in feedback_entries {
            if entry.symbol_id != *sym_id {
                continue;
            }
            if !query_family_matches(&current_tokens, &entry.query) {
                continue;
            }
            let v_str = entry.verdict.as_str();
            impacts.insert(
                qname.clone(),
                FeedbackImpact {
                    verdict: v_str.to_string(),
                    matched_query: entry.query.clone(),
                    author: entry.author.clone(),
                },
            );
            found = true;
            break;
        }
        if found {
            continue;
        }

        // Check sibling suppression.
        if let Some(noisy_syms) = noisy_file_syms.get(&sym_file) {
            if !matches!(sym_kind_enum, SymbolKind::Class | SymbolKind::Module) {
                let candidate_tokens = name_tokens_from_qname(qname);
                let overlaps = noisy_syms.iter().any(|ns| {
                    ns.sym_id != *sym_id
                        && candidate_tokens.iter().any(|t| ns.name_tokens.contains(t))
                });
                if overlaps {
                    if let Some(entry) = feedback_entries.iter().find(|e| {
                        noisy_syms.iter().any(|ns| ns.sym_id == e.symbol_id)
                            && matches!(
                                e.verdict,
                                crate::schema::FeedbackVerdict::Noisy
                                    | crate::schema::FeedbackVerdict::WrongLayer
                            )
                            && query_family_matches(&current_tokens, &e.query)
                    }) {
                        impacts.insert(
                            qname.clone(),
                            FeedbackImpact {
                                verdict: "sibling_suppressed".to_string(),
                                matched_query: entry.query.clone(),
                                author: entry.author.clone(),
                            },
                        );
                    }
                }
            }
        }
    }
    impacts
}

// ---------------------------------------------------------------------------
// File-scope feedback (t-003)
// ---------------------------------------------------------------------------

/// Apply file-scoped feedback verdicts to `scored`.
///
/// Entries with `file_scope` set demote or boost all symbols from files
/// matching the glob pattern, subject to query-family matching.
pub fn apply_file_scope_feedback(
    engine: &Engine,
    index_store: &AsgIndexStore,
    query: &str,
    scored: &mut Vec<(f64, String)>,
    // Plan J t-016: tuple gained `created_at` so Useful boosts on
    // file-scope verdicts decay by age, same as the per-symbol path
    // in `apply_feedback_adjustments`.
    file_scope_entries: &[(
        String,
        crate::schema::FeedbackVerdict,
        String,
        chrono::DateTime<chrono::Utc>,
    )],
) {
    if file_scope_entries.is_empty() {
        return;
    }
    let query_norm = query.to_lowercase();
    let current_tokens = fb_query_tokens(&query_norm);

    // M60: pre-fetch all scored qnames in one SQL batch — no per-symbol git read.
    let qname_strs: Vec<&str> = scored.iter().map(|(_, q)| q.as_str()).collect();
    let resolved_map = engine
        .fts
        .as_ref()
        .map(|fts| fts.resolve_qnames_bulk(&qname_strs))
        .unwrap_or_default();

    // Plan J t-016: snapshot now once for the whole pass; see
    // matching comment in apply_feedback_adjustments.
    let now_for_decay = chrono::Utc::now();
    for (score, qname) in scored.iter_mut() {
        if !score.is_finite() {
            continue;
        }
        let file = if let Some(rsym) = resolved_map.get(qname.as_str()) {
            rsym.file.clone()
        } else {
            match index_store.get_symbol_by_qname(&engine.ref_name, qname) {
                Ok(Some(s)) => s.file,
                _ => continue,
            }
        };
        for (file_glob, verdict, entry_query, fb_created_at) in file_scope_entries {
            if !query_family_matches(&current_tokens, entry_query) {
                continue;
            }
            if !glob_match(file_glob, &file) {
                continue;
            }
            // Plan C t-005: all suppression verdicts collapse here. Boost
            // and Missing handled explicitly; rest delegates to
            // `verdict.is_suppression()` so future variants don't need a
            // separate file-scope branch.
            match verdict {
                crate::schema::FeedbackVerdict::Useful => {
                    // Plan J t-016: age-decay the Useful boost.
                    let decay = crate::feedback::decay_for_entry(
                        *fb_created_at,
                        now_for_decay,
                        crate::feedback::DEFAULT_FEEDBACK_HALF_LIFE_DAYS,
                    );
                    *score += 1.5 * decay;
                }
                crate::schema::FeedbackVerdict::Missing => {}
                v if v.is_suppression() => {
                    *score = f64::NEG_INFINITY;
                    break;
                }
                _ => {}
            }
        }
    }
    scored.retain(|(s, _)| s.is_finite());
}

// ---------------------------------------------------------------------------
// Uncertainty Model — structured reason codes and recovery quality metrics
// ---------------------------------------------------------------------------

/// A single, machine-readable uncertainty signal.
///
/// Each variant carries only the data required to understand and act on it.
/// CLI commands collect these into an [`UncertaintyReport`].
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[serde(tag = "code", rename_all = "snake_case")]
pub enum UncertaintyReason {
    /// A query token matches an excessive number of unrelated files.
    /// Action: add a more specific co-occurring domain term.
    /// Source: `query`
    AmbiguousTerm {
        term: String,
        /// Number of distinct files containing this token (if known).
        #[serde(skip_serializing_if = "Option::is_none")]
        file_count: Option<usize>,
    },
    /// The query consists entirely of generic/stopword-like tokens with
    /// no domain anchor. Results are likely noisy.
    /// Source: `query`
    GenericQuery { tokens: Vec<String> },
    /// Fewer results than expected for a multi-term query. Index may be
    /// incomplete for this area, or the query is too specific.
    /// Source: `result_set`
    LowResultCount { count: usize },
    /// The query implies a layer that is absent from the result set.
    /// Source: `result_set`
    MissingLayer {
        expected_layer: String,
        /// Short human-readable hint about what to check.
        hint: String,
    },
    /// Very few results and no ambiguous terms — the index may not cover
    /// this domain yet.
    /// Source: `result_set`
    SparseIndex,
    /// The workspace has no annotation data — results are based on
    /// structural/FTS signals only, so confidence is inherently reduced.
    /// Source: `db_state`
    DbStateUnannotated {
        /// The specific state code, e.g. "unannotated", "clean_room".
        state: String,
    },
}

impl UncertaintyReason {
    /// Score contribution: how much uncertainty this reason adds (0.0–1.0 range).
    pub fn weight(&self) -> f64 {
        match self {
            UncertaintyReason::AmbiguousTerm { .. } => 0.20,
            UncertaintyReason::GenericQuery { .. } => 0.25,
            UncertaintyReason::LowResultCount { .. } => 0.20,
            UncertaintyReason::MissingLayer { .. } => 0.10,
            UncertaintyReason::SparseIndex => 0.15,
            UncertaintyReason::DbStateUnannotated { .. } => 0.10,
        }
    }

    /// Which high-level source category does this reason belong to?
    ///
    /// Returns one of: `"query"` | `"db_state"` | `"result_set"`
    pub fn source(&self) -> &'static str {
        match self {
            UncertaintyReason::AmbiguousTerm { .. } => "query",
            UncertaintyReason::GenericQuery { .. } => "query",
            UncertaintyReason::LowResultCount { .. } => "result_set",
            UncertaintyReason::MissingLayer { .. } => "result_set",
            UncertaintyReason::SparseIndex => "result_set",
            UncertaintyReason::DbStateUnannotated { .. } => "db_state",
        }
    }
}

/// Recovery quality estimate for a single scoped suggestion.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct RecoverySuggestion {
    /// The suggested narrowed query string.
    pub query: String,
    /// Number of ambiguous terms eliminated by this suggestion.
    pub ambiguous_terms_removed: usize,
    /// Domain-specific tokens added vs the original query.
    pub domain_terms_added: Vec<String>,
    /// Coarse recovery estimate: "strong" | "partial" | "weak".
    pub estimated_recovery: String,
}

/// Per-source uncertainty score contributions.
///
/// Allows agents to understand *why* uncertainty is high and which dimension
/// to address first — rather than treating it as a single opaque number.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct UncertaintySourceBreakdown {
    /// Contribution from query signals (ambiguous terms, generic query).
    /// Range [0.0, 1.0]; reduce by narrowing or adding domain terms.
    pub query: f64,
    /// Contribution from workspace/DB state (unannotated, clean-room).
    /// Range [0.0, 1.0]; reduce by annotating commits or running task-close.
    pub db_state: f64,
    /// Contribution from result-set quality (low count, missing layers, sparse index).
    /// Range [0.0, 1.0]; reduce by broadening the query or checking index coverage.
    pub result_set: f64,
    /// Which source dominates: "query" | "db_state" | "result_set" | "none".
    pub primary: String,
}

/// Machine-readable uncertainty rollup.
///
/// Always emitted — even when `level` is "low", so dashboards can rely on
/// structural consistency without null-checking.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct UncertaintyReport {
    /// Aggregated uncertainty level: "low" | "medium" | "high" | "critical".
    pub level: String,
    /// Normalised uncertainty score [0.0, 1.0] (0 = certain, 1 = completely uncertain).
    pub score: f64,
    /// Structured reasons, sorted by weight descending.
    pub reasons: Vec<UncertaintyReason>,
    /// Single most-actionable recommendation for the agent.
    /// Values: "none" | "narrow_query" | "add_domain_term" | "check_index_coverage" | "broaden_query"
    pub recommended_action: String,
    /// Recovery quality metrics: one entry per scoped suggestion.
    pub recovery_suggestions: Vec<RecoverySuggestion>,
    /// True when the query is an exact match for a known indexed symbol name.
    ///
    /// When true, the level is capped at "medium" regardless of ambiguity signals —
    /// because the agent typed the exact name they want and ASD knows that symbol.
    pub exact_symbol_match: bool,
    /// Per-source uncertainty breakdown: query / db_state / result_set.
    ///
    /// Lets agents target the right fix (refine query, annotate more, broaden scope)
    /// instead of responding generically to a high uncertainty level.
    pub sources: UncertaintySourceBreakdown,
}

impl UncertaintyReport {
    pub fn to_json(&self) -> serde_json::Value {
        serde_json::to_value(self).unwrap_or(serde_json::Value::Null)
    }
}

/// Build a structured [`UncertaintyReport`] from the signals already computed
/// by the search/investigate/prepare-change pipeline.
///
/// # Parameters
/// - `tokens` — parsed query tokens (post-stopword filter)
/// - `ambiguous_terms` — tokens detected by `detect_ambiguous_tokens`
/// - `possible_misses` — prose warnings from `detect_possible_misses` (parsed for layer names)
/// - `result_count` — number of results returned
/// - `scoped_suggestions` — suggestions from `suggest_scoped_queries`
/// - `fts` — borrowed FTS connection used to look up per-token file counts for richer reason data
/// - `db_state` — optional data-quality state from `compute_trust_score` (e.g. "unannotated").
///   When `Some("unannotated")` or `Some("clean_room")`, a `DbStateUnannotated` reason is added.
pub fn compute_uncertainty(
    tokens: &[String],
    ambiguous_terms: &[String],
    possible_misses: &[String],
    result_count: usize,
    scoped_suggestions: &[String],
    fts: Option<&SearchFtsDb>,
    db_state: Option<&str>,
) -> UncertaintyReport {
    let mut reasons: Vec<UncertaintyReason> = Vec::new();

    // -----------------------------------------------------------------------
    // 1. Ambiguous terms — one reason per term with file count if available
    // -----------------------------------------------------------------------
    let per_token_counts: HashMap<String, usize> = if !ambiguous_terms.is_empty() {
        let tok_refs: Vec<&str> = ambiguous_terms.iter().map(|s| s.as_str()).collect();
        fts.and_then(|f| f.count_distinct_files_per_token(&tok_refs, false).ok())
            .unwrap_or_default()
            .into_iter()
            .collect()
    } else {
        HashMap::new()
    };

    for term in ambiguous_terms {
        let file_count = per_token_counts.get(term.as_str()).copied();
        reasons.push(UncertaintyReason::AmbiguousTerm {
            term: term.clone(),
            file_count,
        });
    }

    // -----------------------------------------------------------------------
    // 2. Generic query — all meaningful tokens are broad/stopword-adjacent
    // -----------------------------------------------------------------------
    const BROAD_TERMS: &[&str] = &[
        "update", "get", "set", "handle", "process", "run", "execute", "init", "start", "stop",
        "load", "save", "create", "delete", "state", "data", "model", "manager", "service", "util",
        "helper", "config",
    ];
    let meaningful: Vec<&String> = tokens.iter().filter(|t| !is_stopword(t)).collect();
    let all_broad = !meaningful.is_empty()
        && meaningful
            .iter()
            .all(|t| BROAD_TERMS.contains(&t.as_str()) || ambiguous_terms.contains(t));
    if all_broad && meaningful.len() <= 2 {
        reasons.push(UncertaintyReason::GenericQuery {
            tokens: meaningful.iter().map(|s| s.to_string()).collect(),
        });
    }

    // -----------------------------------------------------------------------
    // 3. Low result count (< 3 and multi-term query)
    // -----------------------------------------------------------------------
    if result_count < 3 && result_count > 0 && tokens.len() >= 2 {
        reasons.push(UncertaintyReason::LowResultCount {
            count: result_count,
        });
    }
    if result_count == 0 && !tokens.is_empty() {
        reasons.push(UncertaintyReason::LowResultCount { count: 0 });
    }

    // -----------------------------------------------------------------------
    // 4. Missing layer — parse possible_misses prose for layer names
    // -----------------------------------------------------------------------
    for miss in possible_misses {
        let ml = miss.to_lowercase();
        let (layer, hint) = if ml.contains("view") || ml.contains("ui") {
            (
                "view",
                "query implies UI involvement — check scope or path coverage",
            )
        } else if ml.contains("service") || ml.contains("domain") {
            (
                "service",
                "query implies service/domain involvement — check layer indexing",
            )
        } else if ml.contains("persist") || ml.contains("data") {
            (
                "persistence",
                "query implies data model involvement — check index coverage",
            )
        } else if ml.contains("scheduler") || ml.contains("timing") {
            (
                "scheduler",
                "query implies timing/dispatch — check scheduler symbols indexed",
            )
        } else if ml.contains("engine") || ml.contains("runtime") {
            (
                "engine",
                "query implies runtime processing — consider broadening scope",
            )
        } else if ml.contains("network") || ml.contains("api") {
            (
                "network",
                "query implies network/API — check network client indexing",
            )
        } else {
            continue; // Unknown layer, skip structured encoding
        };
        reasons.push(UncertaintyReason::MissingLayer {
            expected_layer: layer.to_string(),
            hint: hint.to_string(),
        });
    }

    // -----------------------------------------------------------------------
    // 5. Sparse index — few results, no ambiguity → index may not cover this
    // -----------------------------------------------------------------------
    if result_count < 3 && ambiguous_terms.is_empty() && !tokens.is_empty() && result_count > 0 {
        reasons.push(UncertaintyReason::SparseIndex);
    }

    // -----------------------------------------------------------------------
    // 6. DB state — workspace has no annotations yet (unannotated / clean_room)
    // -----------------------------------------------------------------------
    if let Some(state) = db_state {
        if matches!(state, "unannotated" | "clean_room") {
            reasons.push(UncertaintyReason::DbStateUnannotated {
                state: state.to_string(),
            });
        }
    }

    // -----------------------------------------------------------------------
    // Score + level
    // -----------------------------------------------------------------------
    // Cap ambiguous_term contributions at 2 terms (0.40 max) to avoid
    // artificially high scores for long ambiguous queries.
    let amb_count = reasons
        .iter()
        .filter(|r| matches!(r, UncertaintyReason::AmbiguousTerm { .. }))
        .count()
        .min(2);
    let non_amb_score: f64 = reasons
        .iter()
        .filter(|r| !matches!(r, UncertaintyReason::AmbiguousTerm { .. }))
        .map(|r| r.weight())
        .sum::<f64>()
        .min(0.60);
    let raw_score = (amb_count as f64 * 0.20 + non_amb_score).min(1.0);
    let score = (raw_score * 100.0).round() / 100.0;

    let raw_level = if score < 0.15 {
        "low"
    } else if score < 0.45 {
        "medium"
    } else if score < 0.70 {
        "high"
    } else {
        "critical"
    };

    // -----------------------------------------------------------------------
    // Exact-symbol override guard
    //
    // If the query is a single meaningful token that exactly matches a known
    // symbol name in the FTS index, cap the level at "medium".  This prevents
    // false-high uncertainty when an agent uses the exact symbol name — the
    // ambiguity signals fire because the token is also a broad term in other
    // contexts, but if the symbol exists verbatim, ASD knows exactly what the
    // agent wants.
    // -----------------------------------------------------------------------
    let meaningful_tokens: Vec<&String> = tokens.iter().filter(|t| !is_stopword(t)).collect();
    let exact_symbol_match = if meaningful_tokens.len() == 1 {
        let tok = meaningful_tokens[0];
        // Only check if the token looks like a proper name (starts with uppercase
        // or is >= 5 chars to avoid false-positives on tiny common words).
        if tok.len() >= 5 || tok.chars().next().map_or(false, |c| c.is_uppercase()) {
            fts.map(|f| f.has_exact_symbol_name(tok)).unwrap_or(false)
        } else {
            false
        }
    } else {
        false
    };

    // Cap level if exact symbol match — agent is asking for a specific known thing.
    let level = if exact_symbol_match && matches!(raw_level, "high" | "critical") {
        "medium"
    } else {
        raw_level
    };

    // -----------------------------------------------------------------------
    // Recommended action (most actionable, highest-weight reason wins)
    // -----------------------------------------------------------------------
    let recommended_action = if reasons
        .iter()
        .any(|r| matches!(r, UncertaintyReason::AmbiguousTerm { .. }))
    {
        "narrow_query"
    } else if reasons
        .iter()
        .any(|r| matches!(r, UncertaintyReason::GenericQuery { .. }))
    {
        "add_domain_term"
    } else if reasons.iter().any(|r| {
        matches!(
            r,
            UncertaintyReason::MissingLayer { .. } | UncertaintyReason::SparseIndex
        )
    }) {
        "check_index_coverage"
    } else if reasons
        .iter()
        .any(|r| matches!(r, UncertaintyReason::LowResultCount { .. }))
    {
        "broaden_query"
    } else {
        "none"
    };

    // -----------------------------------------------------------------------
    // Recovery quality metrics per suggestion
    // -----------------------------------------------------------------------
    let amb_set: std::collections::HashSet<&str> =
        ambiguous_terms.iter().map(|s| s.as_str()).collect();
    let original_token_set: std::collections::HashSet<&str> =
        tokens.iter().map(|s| s.as_str()).collect();

    let recovery_suggestions: Vec<RecoverySuggestion> = scoped_suggestions
        .iter()
        .map(|sugg| {
            let sugg_tokens: Vec<String> = sugg
                .split_whitespace()
                .map(|t| t.to_lowercase())
                .filter(|t| !is_stopword(t))
                .collect();

            // How many ambiguous terms does this suggestion eliminate?
            let amb_in_sugg: std::collections::HashSet<&str> = sugg_tokens
                .iter()
                .map(|s| s.as_str())
                .filter(|t| amb_set.contains(t))
                .collect();
            let ambiguous_terms_removed = ambiguous_terms.len().saturating_sub(amb_in_sugg.len());

            // Which tokens are genuinely new (not in original query)?
            let domain_terms_added: Vec<String> = sugg_tokens
                .iter()
                .filter(|t| !original_token_set.contains(t.as_str()) && !is_stopword(t))
                .cloned()
                .collect();

            let estimated_recovery = if ambiguous_terms_removed == ambiguous_terms.len()
                && !domain_terms_added.is_empty()
            {
                "strong"
            } else if ambiguous_terms_removed > 0 || !domain_terms_added.is_empty() {
                "partial"
            } else {
                "weak"
            };

            RecoverySuggestion {
                query: sugg.clone(),
                ambiguous_terms_removed,
                domain_terms_added,
                estimated_recovery: estimated_recovery.to_string(),
            }
        })
        .collect();

    // Sort reasons by weight descending for readability.
    reasons.sort_by(|a, b| {
        b.weight()
            .partial_cmp(&a.weight())
            .unwrap_or(std::cmp::Ordering::Equal)
    });

    // -----------------------------------------------------------------------
    // Source breakdown: per-source contribution scores
    // -----------------------------------------------------------------------
    let query_score: f64 = reasons
        .iter()
        .filter(|r| r.source() == "query")
        .map(|r| r.weight())
        .sum::<f64>()
        .min(1.0);
    let db_state_score: f64 = reasons
        .iter()
        .filter(|r| r.source() == "db_state")
        .map(|r| r.weight())
        .sum::<f64>()
        .min(1.0);
    let result_set_score: f64 = reasons
        .iter()
        .filter(|r| r.source() == "result_set")
        .map(|r| r.weight())
        .sum::<f64>()
        .min(1.0);

    let primary_source = {
        let scores = [
            ("query", query_score),
            ("db_state", db_state_score),
            ("result_set", result_set_score),
        ];
        let max = scores
            .iter()
            .cloned()
            .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal));
        match max {
            Some((src, s)) if s > 0.0 => src,
            _ => "none",
        }
    };

    let sources = UncertaintySourceBreakdown {
        query: ((query_score * 100.0).round() / 100.0).max(0.0),
        db_state: ((db_state_score * 100.0).round() / 100.0).max(0.0),
        result_set: ((result_set_score * 100.0).round() / 100.0).max(0.0),
        primary: primary_source.to_string(),
    };

    UncertaintyReport {
        level: level.to_string(),
        score,
        reasons,
        recommended_action: recommended_action.to_string(),
        recovery_suggestions,
        exact_symbol_match,
        sources,
    }
}

// ---------------------------------------------------------------------------
// Feedback State
// ---------------------------------------------------------------------------

use crate::feedback::{AsgFeedbackStore, FeedbackStore};

/// Explicit description of feedback availability for the current query.
///
/// Allows agents to distinguish "no feedback exists" from "feedback exists
/// but didn't fire" from "feedback applied and modified results" — so that
/// a clean-room DB reset is never silently misread as a broken ranker.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct FeedbackState {
    /// Whether any feedback entries exist for this workspace at all.
    pub available: bool,
    /// Reason code:
    /// - `"no_feedback_entries"` — clean-room or reset, nothing recorded
    /// - `"entries_exist_no_query_match"` — feedback exists but none matches
    /// - `"entries_applied"` — feedback entries influenced this query
    pub reason: String,
    /// Total feedback entries recorded across all symbols and queries.
    pub entries_total: usize,
    /// Number of feedback entries whose recorded query shares at least one
    /// token with the current query.
    pub query_matches: usize,
}

impl FeedbackState {
    pub fn to_json(&self) -> serde_json::Value {
        serde_json::to_value(self).unwrap_or(serde_json::Value::Null)
    }
}

/// Build a [`FeedbackState`] for `query` from the feedback store.
///
/// `entries_applied > 0` (from the `FeedbackMetrics` produced during ranking)
/// is passed in so we can distinguish applied vs present-but-unmatched.
/// Compute [`FeedbackState`] from a pre-fetched `entries` slice.
/// Prefer this over [`build_feedback_state`] when the caller already holds
/// the result of `list_all()` — avoids a second git-object read.
pub fn build_feedback_state_from_entries(
    all: &[crate::schema::FeedbackEntry],
    query: &str,
    entries_applied: usize,
) -> FeedbackState {
    let entries_total = all.len();

    if entries_total == 0 {
        return FeedbackState {
            available: false,
            reason: "no_feedback_entries".to_string(),
            entries_total: 0,
            query_matches: 0,
        };
    }

    // Count entries whose recorded query shares ≥1 token with current query.
    let q_tokens: std::collections::HashSet<String> = query
        .split_whitespace()
        .map(|t| t.to_lowercase())
        .filter(|t| t.len() >= 2)
        .collect();

    let query_matches = all
        .iter()
        .filter(|e| {
            e.query
                .split_whitespace()
                .any(|t| q_tokens.contains(&t.to_lowercase()))
        })
        .count();

    let reason = if entries_applied > 0 {
        "entries_applied"
    } else if query_matches > 0 {
        "entries_exist_no_query_match"
    } else {
        "entries_exist_no_query_match"
    };

    FeedbackState {
        available: true,
        reason: reason.to_string(),
        entries_total,
        query_matches,
    }
}

/// Convenience wrapper that fetches feedback entries before calling
/// [`build_feedback_state_from_entries`].  Use the `_from_entries` variant
/// when you already hold a `list_all()` result.
pub fn build_feedback_state(
    engine: &Engine,
    ref_name: &str,
    query: &str,
    entries_applied: usize,
) -> FeedbackState {
    let fb_store = AsgFeedbackStore::from_engine(engine);
    // Plan J t-014: feedback-state-building is part of the ranking
    // path, so expired entries are filtered out here too.
    let all: Vec<crate::schema::FeedbackEntry> = fb_store
        .list_all(ref_name)
        .unwrap_or_default()
        .into_iter()
        .filter(|e| !e.is_expired())
        .collect();
    build_feedback_state_from_entries(&all, query, entries_applied)
}

#[cfg(test)]
mod plan_c_t003_tests {
    //! Decisions-as-constraints regression. A Constraint or Decision
    //! ledger entry carrying a penalty `role` (stale-api / audit-pending)
    //! must suppress its symbol in ranked results just like an explicit
    //! `WrongLayer` feedback verdict would.

    use crate::engine::Engine;
    use crate::index::{AsgIndexStore, IndexStore};
    use crate::ledger::{AsgLedgerStore, LedgerStore};
    use crate::schema::{
        Author, AuthorKind, LedgerEntry, LedgerKind, Position, Symbol, SymbolKind,
    };

    fn seed_engine_with_symbol() -> (Engine, String) {
        let engine = Engine::open_in_memory().unwrap();
        let index = AsgIndexStore::from_engine(&engine);
        let sym = Symbol {
            symbol_id: "sym_stale".into(),
            symbol_fp: "fp_stale".into(),
            qname: "store.legacy.api".into(),
            language: "python".into(),
            kind: SymbolKind::Function,
            file: "store/legacy.py".into(),
            start: Position { line: 1, col: 0 },
            end: Position { line: 5, col: 0 },
            signature: None,
            doc: None,
        };
        index.put_symbol(&engine.ref_name, &sym, "test").unwrap();
        (engine, sym.symbol_id)
    }

    fn append_constraint(engine: &Engine, sym_id: &str, role: Option<&str>) {
        let ledger = AsgLedgerStore::from_engine(engine);
        let mut entry = LedgerEntry::new(
            sym_id,
            LedgerKind::Constraint,
            "legacy api should not be used in new code",
            Author {
                kind: AuthorKind::Agent,
                id: "test".into(),
            },
        );
        entry.role = role.map(str::to_string);
        ledger
            .append_entry(&engine.ref_name, &entry, "test")
            .unwrap();
    }

    #[test]
    fn constraint_with_stale_api_role_suppresses_symbol() {
        let (engine, sym_id) = seed_engine_with_symbol();
        append_constraint(&engine, &sym_id, Some("stale-api"));
        let index = AsgIndexStore::from_engine(&engine);

        let mut scored = vec![(10.0_f64, "store.legacy.api".to_string())];
        let suppressed = super::apply_constraint_penalties(&engine, &index, &mut scored);

        assert_eq!(suppressed, 1);
        assert_eq!(scored[0].0, f64::NEG_INFINITY);
    }

    #[test]
    fn constraint_with_audit_pending_role_suppresses_symbol() {
        let (engine, sym_id) = seed_engine_with_symbol();
        append_constraint(&engine, &sym_id, Some("audit-pending"));
        let index = AsgIndexStore::from_engine(&engine);
        let mut scored = vec![(10.0_f64, "store.legacy.api".to_string())];
        let suppressed = super::apply_constraint_penalties(&engine, &index, &mut scored);
        assert_eq!(suppressed, 1);
        assert_eq!(scored[0].0, f64::NEG_INFINITY);
    }

    #[test]
    fn constraint_without_role_does_not_suppress() {
        // A bare Constraint with no role is still a passive note —
        // backward-compatible with the pre-Plan-C ledger model.
        let (engine, sym_id) = seed_engine_with_symbol();
        append_constraint(&engine, &sym_id, None);
        let index = AsgIndexStore::from_engine(&engine);
        let mut scored = vec![(10.0_f64, "store.legacy.api".to_string())];
        let suppressed = super::apply_constraint_penalties(&engine, &index, &mut scored);
        assert_eq!(suppressed, 0);
        assert_eq!(scored[0].0, 10.0);
    }

    #[test]
    fn non_penalty_role_does_not_suppress() {
        // package-boundary is a BOOST role, not a penalty role — should
        // not trigger NEG_INFINITY.
        let (engine, sym_id) = seed_engine_with_symbol();
        append_constraint(&engine, &sym_id, Some("package-boundary"));
        let index = AsgIndexStore::from_engine(&engine);
        let mut scored = vec![(10.0_f64, "store.legacy.api".to_string())];
        let suppressed = super::apply_constraint_penalties(&engine, &index, &mut scored);
        assert_eq!(suppressed, 0);
    }

    #[test]
    fn apply_feedback_adjustments_reports_constraint_penalty_in_metrics() {
        let (engine, sym_id) = seed_engine_with_symbol();
        append_constraint(&engine, &sym_id, Some("stale-api"));
        let index = AsgIndexStore::from_engine(&engine);
        let mut scored = vec![(10.0_f64, "store.legacy.api".to_string())];
        // Empty feedback set — exercises the early-return branch.
        let metrics =
            super::apply_feedback_adjustments(&engine, &index, "legacy", &mut scored, &[]);
        assert_eq!(metrics.constraint_penalties_applied, 1);
        assert!(
            metrics
                .rules_applied
                .iter()
                .any(|r| r == "constraint_penalty")
        );
        assert_eq!(scored[0].0, f64::NEG_INFINITY);
    }

    // -- Plan C t-005: AlreadyCovered + DiagnosticOnly verdicts ------------

    fn seed_plain_symbol() -> (Engine, String) {
        let engine = Engine::open_in_memory().unwrap();
        let index = AsgIndexStore::from_engine(&engine);
        let sym = Symbol {
            symbol_id: "sym_a".into(),
            symbol_fp: "fp_a".into(),
            qname: "a.b.c".into(),
            language: "python".into(),
            kind: SymbolKind::Function,
            file: "src/a.py".into(),
            start: Position { line: 1, col: 0 },
            end: Position { line: 5, col: 0 },
            signature: None,
            doc: None,
        };
        index.put_symbol(&engine.ref_name, &sym, "test").unwrap();
        (engine, sym.symbol_id)
    }

    #[test]
    fn already_covered_verdict_suppresses_and_labels_rule() {
        let (engine, sym_id) = seed_plain_symbol();
        let index = AsgIndexStore::from_engine(&engine);
        let mut scored = vec![(10.0_f64, "a.b.c".to_string())];
        let metrics = super::apply_feedback_adjustments(
            &engine,
            &index,
            "match my query",
            &mut scored,
            &[(
                sym_id,
                "match my query".into(),
                crate::schema::FeedbackVerdict::AlreadyCovered,
                chrono::Utc::now(), // Plan J t-016: created_at for decay
            )],
        );
        // apply_feedback_adjustments retains only finite scores at the
        // end, so a NEG_INFINITY-suppressed symbol is removed entirely.
        assert!(scored.is_empty(), "suppressed symbol must be dropped");
        assert!(metrics.rules_applied.iter().any(|r| r == "already_covered"));
    }

    #[test]
    fn diagnostic_only_verdict_suppresses_and_labels_rule() {
        let (engine, sym_id) = seed_plain_symbol();
        let index = AsgIndexStore::from_engine(&engine);
        let mut scored = vec![(10.0_f64, "a.b.c".to_string())];
        let metrics = super::apply_feedback_adjustments(
            &engine,
            &index,
            "match my query",
            &mut scored,
            &[(
                sym_id,
                "match my query".into(),
                crate::schema::FeedbackVerdict::DiagnosticOnly,
                chrono::Utc::now(), // Plan J t-016: created_at for decay
            )],
        );
        assert!(scored.is_empty(), "suppressed symbol must be dropped");
        assert!(metrics.rules_applied.iter().any(|r| r == "diagnostic_only"));
    }

    #[test]
    fn feedback_verdict_is_suppression_classification() {
        use crate::schema::FeedbackVerdict::*;
        assert!(!Useful.is_suppression());
        assert!(!Missing.is_suppression());
        assert!(Noisy.is_suppression());
        assert!(WrongLayer.is_suppression());
        assert!(AlreadyCovered.is_suppression());
        assert!(DiagnosticOnly.is_suppression());
    }

    // -- Plan C t-006: CTX task bias ----------------------------------------

    #[test]
    fn apply_task_bias_boosts_in_scope_files_only() {
        let engine = Engine::open_in_memory().unwrap();
        let index = AsgIndexStore::from_engine(&engine);
        for (qn, file) in [
            ("pkg.in_scope.fn", "src/pkg/in_scope.py"),
            ("pkg.out_of_scope.fn", "src/other/file.py"),
        ] {
            let sym = Symbol {
                symbol_id: format!("sym_{qn}"),
                symbol_fp: "fp".into(),
                qname: qn.into(),
                language: "python".into(),
                kind: SymbolKind::Function,
                file: file.into(),
                start: Position { line: 1, col: 0 },
                end: Position { line: 2, col: 0 },
                signature: None,
                doc: None,
            };
            index.put_symbol(&engine.ref_name, &sym, "test").unwrap();
        }
        let mut scored = vec![
            (5.0_f64, "pkg.in_scope.fn".to_string()),
            (5.0_f64, "pkg.out_of_scope.fn".to_string()),
        ];
        let scope = vec!["src/pkg/**".to_string()];
        let n = super::apply_task_bias(&engine, &index, &mut scored, &scope, 1.0);
        assert_eq!(n, 1);
        // In-scope was boosted, out-of-scope was not.
        let in_scope = scored.iter().find(|(_, q)| q == "pkg.in_scope.fn").unwrap();
        let out_scope = scored
            .iter()
            .find(|(_, q)| q == "pkg.out_of_scope.fn")
            .unwrap();
        assert_eq!(in_scope.0, 6.0);
        assert_eq!(out_scope.0, 5.0);
    }

    #[test]
    fn apply_task_bias_with_empty_scope_is_a_noop() {
        let engine = Engine::open_in_memory().unwrap();
        let index = AsgIndexStore::from_engine(&engine);
        let mut scored = vec![(5.0_f64, "anything".to_string())];
        let n = super::apply_task_bias(&engine, &index, &mut scored, &[], 1.0);
        assert_eq!(n, 0);
        assert_eq!(scored[0].0, 5.0);
    }

    #[test]
    fn apply_task_bias_skips_already_suppressed_candidates() {
        let engine = Engine::open_in_memory().unwrap();
        let index = AsgIndexStore::from_engine(&engine);
        let sym = Symbol {
            symbol_id: "sym_z".into(),
            symbol_fp: "fp".into(),
            qname: "z.in_scope.fn".into(),
            language: "python".into(),
            kind: SymbolKind::Function,
            file: "src/pkg/z.py".into(),
            start: Position { line: 1, col: 0 },
            end: Position { line: 2, col: 0 },
            signature: None,
            doc: None,
        };
        index.put_symbol(&engine.ref_name, &sym, "test").unwrap();
        let mut scored = vec![(f64::NEG_INFINITY, "z.in_scope.fn".to_string())];
        let n = super::apply_task_bias(
            &engine,
            &index,
            &mut scored,
            &["src/pkg/**".to_string()],
            1.0,
        );
        assert_eq!(n, 0, "NEG_INFINITY candidates must not be revived by bias");
        assert_eq!(scored[0].0, f64::NEG_INFINITY);
    }

    // Plan E t-002: these tests now use read_active_task_scope_from()
    // and pass the env string explicitly. No process-env mutation, so
    // they're parallel-safe (the wrapper `read_active_task_scope` is a
    // thin std::env::var call covered by integration / smoke testing).

    #[test]
    fn read_active_task_scope_parses_json() {
        let raw = r#"{"task_id":"t-006","scope":["src/pkg/**","tests/pkg/**"]}"#;
        let scope = super::read_active_task_scope_from(Some(raw), None);
        assert_eq!(
            scope,
            Some(vec!["src/pkg/**".to_string(), "tests/pkg/**".to_string()])
        );
    }

    #[test]
    fn read_active_task_scope_returns_none_when_unset() {
        let scope = super::read_active_task_scope_from(None, None);
        assert_eq!(scope, None);
    }

    #[test]
    fn read_active_task_scope_returns_none_on_empty_scope_array() {
        let raw = r#"{"task_id":"t-006","scope":[]}"#;
        assert_eq!(super::read_active_task_scope_from(Some(raw), None), None);
    }

    #[test]
    fn read_active_task_scope_returns_none_on_malformed_json() {
        assert_eq!(
            super::read_active_task_scope_from(Some("not json"), None),
            None
        );
        assert_eq!(super::read_active_task_scope_from(Some("{}"), None), None);
    }

    // -- Plan E t-008: scoped constraint penalties --------------------------

    #[test]
    fn constraint_scope_from_body_parses_json_scope_array() {
        let body = r#"{"scope":["src/legacy/**","tests/legacy/**"]}"#;
        assert_eq!(
            super::constraint_scope_from_body(Some(body)),
            Some(vec![
                "src/legacy/**".to_string(),
                "tests/legacy/**".to_string()
            ])
        );
    }

    #[test]
    fn constraint_scope_from_body_returns_none_when_unset() {
        assert_eq!(super::constraint_scope_from_body(None), None);
        assert_eq!(
            super::constraint_scope_from_body(Some("plain text body")),
            None
        );
        assert_eq!(
            super::constraint_scope_from_body(Some(r#"{"other":"field"}"#)),
            None
        );
        assert_eq!(
            super::constraint_scope_from_body(Some(r#"{"scope":[]}"#)),
            None
        );
    }

    fn seed_engine_with_two_symbols() -> (Engine, String, String) {
        let engine = Engine::open_in_memory().unwrap();
        let index = AsgIndexStore::from_engine(&engine);
        for (qn, file) in [
            ("app.legacy.api", "src/legacy/api.py"),
            ("app.modern.api", "src/modern/api.py"),
        ] {
            let sym = Symbol {
                symbol_id: format!("sym_{qn}"),
                symbol_fp: "fp".into(),
                qname: qn.into(),
                language: "python".into(),
                kind: SymbolKind::Function,
                file: file.into(),
                start: Position { line: 1, col: 0 },
                end: Position { line: 2, col: 0 },
                signature: None,
                doc: None,
            };
            index.put_symbol(&engine.ref_name, &sym, "test").unwrap();
        }
        (
            engine,
            "sym_app.legacy.api".into(),
            "sym_app.modern.api".into(),
        )
    }

    fn append_scoped_constraint(engine: &Engine, sym_id: &str, scope_json: &str) {
        let ledger = AsgLedgerStore::from_engine(engine);
        let mut entry = LedgerEntry::new(
            sym_id,
            LedgerKind::Constraint,
            "legacy api may not be used in new code",
            Author {
                kind: AuthorKind::Agent,
                id: "t".into(),
            },
        );
        entry.role = Some("stale-api".into());
        entry.body = Some(scope_json.to_string());
        ledger
            .append_entry(&engine.ref_name, &entry, "test")
            .unwrap();
    }

    #[test]
    fn scoped_constraint_suppresses_only_in_scope_symbols() {
        // Constraint scoped to src/legacy/** should suppress
        // app.legacy.api but NOT app.modern.api.
        let (engine, legacy_id, _modern_id) = seed_engine_with_two_symbols();
        append_scoped_constraint(&engine, &legacy_id, r#"{"scope":["src/legacy/**"]}"#);
        let index = AsgIndexStore::from_engine(&engine);
        let mut scored = vec![
            (10.0_f64, "app.legacy.api".into()),
            (10.0_f64, "app.modern.api".into()),
        ];
        let n = super::apply_constraint_penalties(&engine, &index, &mut scored);
        assert_eq!(n, 1, "only legacy should be suppressed");
        let legacy = scored.iter().find(|(_, q)| q == "app.legacy.api").unwrap();
        let modern = scored.iter().find(|(_, q)| q == "app.modern.api").unwrap();
        assert_eq!(legacy.0, f64::NEG_INFINITY);
        assert_eq!(modern.0, 10.0);
    }

    #[test]
    fn unscoped_constraint_still_suppresses_globally() {
        // No body / no scope means global penalty — preserves Plan C t-003
        // behavior.
        let (engine, legacy_id, _modern_id) = seed_engine_with_two_symbols();
        append_constraint(&engine, &legacy_id, Some("stale-api")); // no body
        let index = AsgIndexStore::from_engine(&engine);
        let mut scored = vec![(10.0_f64, "app.legacy.api".into())];
        let n = super::apply_constraint_penalties(&engine, &index, &mut scored);
        assert_eq!(n, 1);
        assert_eq!(scored[0].0, f64::NEG_INFINITY);
    }
}

#[cfg(test)]
mod plan_j_t012_explain_match_tests {
    //! Plan J t-012: `match_reasons` is the per-hit "why this result"
    //! array surfaced on every search/investigate response. The
    //! infrastructure already shipped (Plan A / M26 era); these
    //! tests lock the signal-vocabulary contract so future tweaks
    //! can't silently shrink what's reported.

    use crate::candidates::explain_match;
    use crate::schema::{
        Author, AuthorKind, LedgerEntry, LedgerKind, Position, Symbol, SymbolKind,
    };

    fn mk_sym(qname: &str, file: &str, sig: Option<&str>, doc: Option<&str>) -> Symbol {
        Symbol {
            symbol_id: format!("sym_{}", qname.replace('.', "_")),
            symbol_fp: "fp".into(),
            qname: qname.into(),
            language: "python".into(),
            kind: SymbolKind::Function,
            file: file.into(),
            start: Position { line: 1, col: 0 },
            end: Position { line: 5, col: 0 },
            signature: sig.map(str::to_string),
            doc: doc.map(str::to_string),
        }
    }

    fn mk_entry(kind: LedgerKind, summary: &str) -> LedgerEntry {
        LedgerEntry::new(
            "sym_x",
            kind,
            summary,
            Author {
                kind: AuthorKind::Human,
                id: "alice".into(),
            },
        )
    }

    #[test]
    fn name_match_yields_name_reason() {
        let sym = mk_sym("pkg.playhead", "src/playhead.py", None, None);
        let reasons = explain_match(&sym, &["playhead".into()], &[], false);
        assert!(
            reasons.iter().any(|r| r == "name:playhead"),
            "expected name:playhead in {reasons:?}"
        );
    }

    #[test]
    fn file_match_yields_file_reason_when_name_misses() {
        let sym = mk_sym("pkg.x", "src/transport.py", None, None);
        let reasons = explain_match(&sym, &["transport".into()], &[], false);
        assert!(
            reasons.iter().any(|r| r == "file:transport"),
            "expected file:transport in {reasons:?}"
        );
    }

    #[test]
    fn doc_match_yields_doc_reason_when_higher_priority_miss() {
        let sym = mk_sym(
            "pkg.x",
            "src/x.py",
            None,
            Some("Handles the audio mixer pipeline."),
        );
        let reasons = explain_match(&sym, &["mixer".into()], &[], false);
        assert!(
            reasons.iter().any(|r| r == "doc:mixer"),
            "expected doc:mixer in {reasons:?}"
        );
    }

    #[test]
    fn hot_files_get_recent_edit_signal() {
        let sym = mk_sym("pkg.x", "src/x.py", None, None);
        let reasons = explain_match(&sym, &[], &[], true);
        assert!(
            reasons.contains(&"recent-edit".to_string()),
            "is_hot=true must surface `recent-edit`; got {reasons:?}"
        );
    }

    #[test]
    fn invariant_count_appears_as_signal() {
        let sym = mk_sym("pkg.x", "src/x.py", None, None);
        let entries = vec![
            mk_entry(LedgerKind::Invariant, "must hold X"),
            mk_entry(LedgerKind::Invariant, "must hold Y"),
        ];
        let reasons = explain_match(&sym, &[], &entries, false);
        assert!(
            reasons.iter().any(|r| r == "invariant-attached:2"),
            "expected invariant-attached:2 in {reasons:?}"
        );
    }

    #[test]
    fn hazard_count_appears_as_signal_with_pluralization() {
        let sym = mk_sym("pkg.x", "src/x.py", None, None);
        let one = vec![mk_entry(LedgerKind::Hazard, "be careful")];
        let two = vec![
            mk_entry(LedgerKind::Hazard, "be careful 1"),
            mk_entry(LedgerKind::Hazard, "be careful 2"),
        ];
        assert!(
            explain_match(&sym, &[], &one, false)
                .iter()
                .any(|r| r == "ledger:1 hazard")
        );
        assert!(
            explain_match(&sym, &[], &two, false)
                .iter()
                .any(|r| r == "ledger:2 hazards")
        );
    }

    #[test]
    fn ownership_match_surfaces_when_summary_overlaps_query() {
        let sym = mk_sym("pkg.audio", "src/audio.py", None, None);
        let entries = vec![mk_entry(
            LedgerKind::Ownership,
            "audio mixer pipeline source of truth",
        )];
        let reasons = explain_match(&sym, &["audio".into()], &entries, false);
        assert!(
            reasons.iter().any(|r| r.starts_with("ownership:")),
            "expected ownership:* in {reasons:?}"
        );
    }

    #[test]
    fn empty_input_returns_empty_reasons() {
        let sym = mk_sym("pkg.x", "src/x.py", None, None);
        let reasons = explain_match(&sym, &[], &[], false);
        assert!(
            reasons.is_empty(),
            "no tokens, no ledger, not hot → empty; got {reasons:?}"
        );
    }
}

#[cfg(test)]
mod plan_j_t011_exclude_sets_tests {
    //! Plan J t-011: `[exclude_sets]` table parsing in `.asd/scopes.toml`
    //! and `resolve_exclude_set` lookups.

    use super::{load_exclude_sets, matches_any_path_glob, resolve_exclude_set};
    use std::path::PathBuf;

    fn write_scopes_toml(dir: &std::path::Path, body: &str) {
        // load_exclude_sets reads `<db_parent>/scopes.toml` — NOT
        // under `.asd/`. The loader was designed before `.asd/` was
        // standardized; the existing path is load-bearing. Mirror it.
        std::fs::write(dir.join("scopes.toml"), body).unwrap();
    }

    fn db_path_in(dir: &std::path::Path) -> PathBuf {
        // `<dir>/.asd-state.db` → parent is `<dir>` → loader joins
        // `scopes.toml` → reads `<dir>/scopes.toml`.
        dir.join(".asd-state.db")
    }

    #[test]
    fn returns_empty_when_no_exclude_sets_table() {
        let tmp = tempfile::tempdir().unwrap();
        write_scopes_toml(tmp.path(), "drift-pad = [\"App/**/DriftPad*\"]\n");
        let map = load_exclude_sets(&db_path_in(tmp.path()));
        assert!(
            map.is_empty(),
            "no [exclude_sets] table should yield empty map; got {map:?}"
        );
    }

    #[test]
    fn reads_named_exclude_sets() {
        let tmp = tempfile::tempdir().unwrap();
        write_scopes_toml(
            tmp.path(),
            "[exclude_sets]\n\
             tests = [\"**/test_*.py\", \"tests/**\"]\n\
             generated = [\"**/generated/**\"]\n",
        );
        let map = load_exclude_sets(&db_path_in(tmp.path()));
        assert_eq!(map.len(), 2);
        assert_eq!(
            map.get("tests").map(|v| v.len()),
            Some(2),
            "tests must have 2 globs; got {:?}",
            map.get("tests")
        );
        assert_eq!(map.get("generated").map(|v| v.len()), Some(1));
    }

    #[test]
    fn resolve_unknown_returns_empty_not_treated_as_glob() {
        // Unlike --scope (which falls back to treating the name as a
        // glob), --exclude-set on an unknown name returns [] so a typo
        // can't silently morph into a path filter.
        let tmp = tempfile::tempdir().unwrap();
        write_scopes_toml(tmp.path(), "[exclude_sets]\ntests = [\"tests/**\"]\n");
        let globs = resolve_exclude_set("nonexistent", &db_path_in(tmp.path()));
        assert!(
            globs.is_empty(),
            "unknown exclude-set name must return empty, not the literal name; got {globs:?}"
        );
    }

    #[test]
    fn resolve_known_returns_globs() {
        let tmp = tempfile::tempdir().unwrap();
        write_scopes_toml(
            tmp.path(),
            "[exclude_sets]\ntests = [\"tests/**\", \"**/test_*.py\"]\n",
        );
        let globs = resolve_exclude_set("tests", &db_path_in(tmp.path()));
        assert_eq!(globs.len(), 2);
        // Sanity: these globs actually exclude the kinds of files we expect.
        assert!(matches_any_path_glob(&globs, "tests/foo.py"));
        assert!(matches_any_path_glob(&globs, "src/test_widget.py"));
        assert!(!matches_any_path_glob(&globs, "src/widget.py"));
    }

    #[test]
    fn coexists_with_bare_scope_aliases() {
        // The two namespaces (bare keys = scope aliases, [exclude_sets]
        // table = exclude sets) must not interfere.
        let tmp = tempfile::tempdir().unwrap();
        write_scopes_toml(
            tmp.path(),
            "drift-pad = [\"App/**/DriftPad*\"]\n\
             \n[exclude_sets]\n\
             tests = [\"tests/**\"]\n",
        );
        let aliases = super::load_scope_aliases(&db_path_in(tmp.path()));
        let excl = load_exclude_sets(&db_path_in(tmp.path()));
        assert_eq!(aliases.get("drift-pad").map(|v| v.len()), Some(1));
        assert_eq!(excl.get("tests").map(|v| v.len()), Some(1));
        // Cross-namespace: a bare alias is NOT an exclude set and
        // vice-versa.
        assert!(!aliases.contains_key("tests"));
        assert!(!excl.contains_key("drift-pad"));
    }
}

#[cfg(test)]
mod plan_j_t006_view_layer_matches_tests {
    //! Plan J t-006: view-query +2.0 boost gate union with file_role.

    use super::view_layer_matches;

    #[test]
    fn ui_layer_alone_qualifies() {
        // Pre-existing behavior preserved: any "ui" layer fires.
        assert!(view_layer_matches("ui", "anything/not/even/a/view.go"));
    }

    #[test]
    fn viewmodel_layer_alone_qualifies() {
        assert!(view_layer_matches("viewmodel", "Foo.swift"));
    }

    #[test]
    fn non_view_layer_with_non_view_file_does_not_qualify() {
        assert!(!view_layer_matches("scheduler", "src/audio/clock.rs"));
        assert!(!view_layer_matches("persistence", "src/db/migrations.rs"));
    }

    #[test]
    fn file_role_view_closes_layer_gap() {
        // Plan J t-006: layer="other" (classify_layer misses the
        // file) BUT classify_file_role picks it up via stem suffix.
        // This is the M22 field-eval case — `*View.swift` outside
        // a /views/ directory used to miss the boost.
        assert!(view_layer_matches(
            "other",
            "app/components/AcmeFlowView.swift"
        ));
    }

    #[test]
    fn file_role_view_via_vue_extension_qualifies() {
        // Web frontends — single-file components with .vue/.svelte
        // extension. classify_layer typically misses these (no
        // suffix convention); file_role catches them.
        assert!(view_layer_matches("other", "src/Components/UserCard.vue"));
        assert!(view_layer_matches("other", "src/widgets/Toolbar.svelte"));
    }

    #[test]
    fn file_role_viewmodel_closes_layer_gap() {
        // *ViewModel.kt in a non-`/viewmodels/` directory.
        assert!(view_layer_matches(
            "other",
            "app/screens/login/LoginViewModel.kt"
        ));
    }

    #[test]
    fn impl_file_role_not_a_view() {
        // Negative: a regular implementation file shouldn't get the
        // boost just because the layer string is unrecognized.
        assert!(!view_layer_matches("other", "src/services/auth.rs"));
        assert!(!view_layer_matches("other", "src/util/helpers.ts"));
    }

    #[test]
    fn previewservice_is_not_a_view_negative_regression() {
        // From t-003 unit tests: stem_ends_with avoids `Preview*`
        // false-matching `view`. Lock the same regression here so
        // we don't reintroduce it via the boost gate.
        assert!(!view_layer_matches(
            "other",
            "src/preview/PreviewService.swift"
        ));
    }
}