eidos_kernel/

retrieval.rs

//! Retrieval — lexical scoring + CALIBRATED confidence.
//!
//! Ports the Python scorer (haystack = id/title/summary/aliases; exact + partial field
//! checks; per-term bonus + coverage; bands strong≥45 / weak≥25 / fallback). Adds the
//! calibration the Python version lacks: the top hit is demoted `strong → ambiguous` when
//! a runner-up scores within 0.7× of it — so a coin-flip query stops reporting `strong`.

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

use serde::{Deserialize, Serialize};

use crate::schema::{EdgeBasis, Graph, Kind, Node};

mod focus;
mod intent;
mod scoring;

pub use focus::{
    CompoundAnchor, CompoundOmittedAnchor, CompoundSubgraph, OmittedContextCandidate, Subgraph,
    ground_subgraph,
};
pub use scoring::{GroundIndex, RankerConfig};

use intent::query_intent_matches;
use scoring::{
    Bm25fNodeShape, Bm25fScorer, bm25f_df, bm25f_score, relation_phrase, reverse_relation_phrase,
};

#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Confidence {
    Exact,
    Strong,
    Ambiguous,
    Weak,
    Fallback,
}

#[derive(Serialize, Clone, Debug)]
pub struct Hit {
    pub id: String,
    /// Route score: lexical relevance adjusted by reliability signals such as identity anchoring
    /// and canonical-dominance boosting — drives ranking/route.
    pub score: i64,
    /// Raw lexical relevance, BEFORE route reliability penalties or dominance boosts. Lets context
    /// expansion keep useful body evidence even when route ranking prefers anchored front doors.
    pub lexical_score: i64,
    pub confidence: Confidence,
    pub why: Vec<String>,
    /// Structured relation reasons that influenced this hit's ranking.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub relation_matches: Vec<RelationMatch>,
    /// Fraction of the query's IDF weight that lands in the node's curated identity (id/title/
    /// aliases/summary) vs only its body. Calibration input, not serialized.
    #[serde(skip)]
    pub anchor: f64,
    /// True when the route was anchored by a directed relation phrase + endpoint match, not just
    /// local node text. Focus uses this to preserve source-side relation answers.
    #[serde(skip)]
    pub relation_anchor: bool,
}

#[derive(Serialize, Clone, Debug, PartialEq, Eq)]
pub struct RelationMatch {
    pub relation: String,
    pub direction: String,
    pub phrase: String,
    pub endpoint_id: String,
    pub endpoint_title: String,
    pub endpoint_hits: usize,
    pub score_boost: i64,
}

/// How close a runner-up must be (as a fraction of the top score) to make the top hit "ambiguous"
/// rather than "strong". Housed in the calibration registry — see [`crate::calibration`].
use crate::calibration::{AMBIGUITY_RATIO, DISTINCTIVE_NAME_IDF};

/// Common English stopwords — near-zero retrieval signal, so they are dropped from query terms.
/// Without this, a query like "the project findings notes" lets any node containing "the" score
/// (and canonical dominance then promotes it over the relevant node). Whole-query exact/partial
/// field checks are unaffected, so a stopword-y phrase that IS an exact alias still matches.
const STOPWORDS: &[&str] = &[
    "a", "an", "and", "are", "as", "at", "be", "but", "by", "can", "did", "do", "does", "for",
    "from", "had", "has", "have", "how", "i", "in", "is", "it", "its", "me", "my", "need", "of",
    "on", "or", "our", "should", "so", "that", "the", "their", "them", "then", "there", "these",
    "this", "those", "to", "up", "us", "was", "we", "were", "what", "when", "where", "which",
    "will", "with", "would", "you", "your",
];

fn is_stopword(t: &str) -> bool {
    STOPWORDS.binary_search(&t).is_ok()
}

/// True if `a` and `b` differ by at most one edit (insert / delete / substitute). A conservative
/// typo matcher — byte-wise (English-light), O(len), short-circuits on the second edit.
fn within_edit1(a: &[u8], b: &[u8]) -> bool {
    let (la, lb) = (a.len(), b.len());
    if la > lb {
        return within_edit1(b, a);
    }
    if lb - la > 1 {
        return false;
    }
    let (mut i, mut j, mut edited) = (0usize, 0usize, false);
    while i < la && j < lb {
        if a[i] == b[j] {
            i += 1;
            j += 1;
        } else if edited {
            return false;
        } else {
            edited = true;
            if la == lb {
                i += 1; // substitution
            }
            j += 1; // advance the longer (or both, for substitution)
        }
    }
    true
}

/// Conservative light stemmer: strip a single common inflectional suffix so an inflected query
/// term reaches a base-form node ("baking"→"bak", "tests"→"test"). Substring matching downstream
/// means a shortened stem still matches the full word. Guards `-ss/-us/-is` and short words to
/// avoid mangling (e.g. `status`, `class`, `this`). Deterministic, English-light.
fn stem(t: &str) -> String {
    let n = t.len();
    if n > 5 && t.ends_with("ing") {
        return restore_e(&t[..n - 3]);
    }
    if n > 4 && t.ends_with("ed") {
        return restore_e(&t[..n - 2]);
    }
    if n > 3 && t.ends_with('s') && !t.ends_with("ss") && !t.ends_with("us") && !t.ends_with("is") {
        return t[..n - 1].to_string();
    }
    t.to_string()
}

/// After stripping `-ing`/`-ed`, restore a silent `e` elided before it when the stem ends in a
/// consonant-vowel-consonant pattern (Porter's rule): `bak`→`bake`, `cod`→`code`, `writ`→`write` —
/// so a gerund and its base form converge to the same token (token matching, unlike the old
/// substring matching, needs them to be equal). Skips double consonants (`runn`) and `w/x/y` endings.
fn restore_e(base: &str) -> String {
    let b = base.as_bytes();
    let cvc = b.len() >= 3
        && is_consonant(b[b.len() - 3])
        && !is_consonant(b[b.len() - 2])
        && is_consonant(b[b.len() - 1])
        && !matches!(b[b.len() - 1], b'w' | b'x' | b'y');
    if cvc {
        format!("{base}e")
    } else {
        base.to_string()
    }
}

fn is_consonant(c: u8) -> bool {
    !matches!(c.to_ascii_lowercase(), b'a' | b'e' | b'i' | b'o' | b'u')
}

fn terms_of(query_lower: &str) -> Vec<String> {
    query_lower
        .split_whitespace()
        .map(|t| t.trim_matches(|c: char| !c.is_alphanumeric()).to_string())
        .filter(|t| t.chars().count() > 1 && !is_stopword(t))
        .map(|t| stem(&t))
        .collect()
}

fn raw_terms_of(query_lower: &str) -> Vec<String> {
    query_lower
        .split_whitespace()
        .map(|t| t.trim_matches(|c: char| !c.is_alphanumeric()).to_string())
        .filter(|t| t.chars().count() > 1 && !is_stopword(t))
        .collect()
}

/// Confidence bands, calibrated to the measured score distribution (see `band_tests`): clean
/// retrieval accuracy is 100% down to score 45 and garbage tops out ~32, so `strong ≥ 45` is
/// discriminating yet keeps strong high-accuracy and never labels garbage strong.
fn band(score: i64) -> Confidence {
    if score >= crate::calibration::BAND_STRONG_MIN {
        Confidence::Strong
    } else if score >= crate::calibration::BAND_WEAK_MIN {
        Confidence::Weak
    } else {
        Confidence::Fallback
    }
}

/// Anchor-aware confidence: `band(score)` reflects how MANY terms matched and how distinctive
/// they are, but not WHERE they matched. Field testing found a doc that merely *mentions* the
/// query terms in its body (e.g. a brain-dump that lists "VLANs" as a TODO) scoring "strong" —
/// relevant, but not what the doc is *about*. So when NO distinctive query weight lands in the
/// node's curated identity (id/title/aliases/summary), confidence is capped: it's a mention, not
/// a definitional match. Ranking is untouched — only the confidence LABEL is calibrated.
///
/// The cap is tiered by coverage: if ALL query terms matched (coverage == 1.0) AND the score is
/// decent (>= 25), the document genuinely contains the answer — cap to Weak (not Fallback).
/// A body-only match with full term coverage and a real score is "found something relevant but
/// not highly confident." Fallback is reserved for low-score stretches where even the body match
/// is marginal.
fn band_anchored(score: i64, anchor: f64, coverage: f64) -> Confidence {
    let base = band(score);
    if anchor <= 0.0 {
        // NO distinctive query weight in the curated identity → a body-only match.
        // Tier the cap by coverage and score:
        //   - Full coverage + decent score → Weak (the doc genuinely contains all query terms)
        //   - Low score → Fallback (the match is marginal, a body coincidence)
        if coverage >= 1.0 && score >= crate::calibration::BAND_WEAK_MIN {
            return Confidence::Weak;
        }
        return match base {
            Confidence::Exact | Confidence::Strong | Confidence::Ambiguous | Confidence::Weak => {
                Confidence::Fallback
            }
            other => other,
        };
    }
    base
}

/// A bare code symbol name is only identity-grade evidence when it is distinctive enough to avoid
/// common short words like `id`, `run`, or `get` dominating task-shaped searches.
fn is_distinct_code_symbol_name(title: &str) -> bool {
    let significant_chars = title.chars().filter(|c| c.is_alphanumeric()).count();
    significant_chars >= 6 && title.chars().any(|c| c.is_ascii_alphabetic())
}

fn intent_boosts(
    intents: &[&str],
    is_code: bool,
    is_generic_symbol_name: bool,
    matched_identity: usize,
    exact: f64,
    name_boost: f64,
) -> (f64, f64) {
    let generic_code_only = is_code
        && is_generic_symbol_name
        && intents.len() == 1
        && intents.first() == Some(&"code")
        && matched_identity == 0
        && exact <= 0.0
        && name_boost <= 0.0;
    if generic_code_only {
        // "show code/docs" is a broad class request, not evidence that every code symbol is a
        // relevant answer. A generically-named helper (`run`, `get`, `id`) with no identity
        // evidence keeps a small route nudge but never becomes a strong seed. A distinctively
        // named symbol (`LoginForm`) keeps the full intent boost: its name alone is evidence.
        return (6.0, 0.0);
    }
    let boost = intents.len() as f64 * 20.0;
    (boost, boost)
}

/// Demote the top hit `strong → ambiguous` when the runner-up is within `AMBIGUITY_RATIO`
/// of it — the calibration that stops bare ambiguous queries reporting false confidence.
fn calibrate(hits: &mut [Hit]) {
    if hits.len() >= 2 && hits[0].confidence == Confidence::Strong {
        let top = hits[0].score as f64;
        let runner = hits[1].score as f64;
        if top > 0.0 && runner >= AMBIGUITY_RATIO * top {
            hits[0].confidence = Confidence::Ambiguous;
        }
    }
}

/// Adaptive confidence floor — a **presentation** filter, applied at the surface (MCP/CLI), NOT in
/// the retrieval/eval path. The engine always returns the full ranked list so the eval can measure
/// rank-2+ recall honestly; the surface uses this to drop trailing noise before showing results.
///
/// When a confident hit exists (`Exact`/`Strong`/`Ambiguous`), the trailing `Fallback`-band hits are
/// noise, not answers — drop them (the "1 strong + 7 fallback" cleanup). When nothing is confident
/// (a genuinely weak query, or garbage), the ranked list is kept untouched so a weak-but-real answer
/// still surfaces and garbage still reads as rejected. The TOP hit's band is never changed.
pub fn apply_floor(hits: &mut Vec<Hit>) {
    let has_confident = hits.iter().any(|h| {
        matches!(
            h.confidence,
            Confidence::Exact | Confidence::Strong | Confidence::Ambiguous
        )
    });
    if has_confident {
        hits.retain(|h| h.confidence != Confidence::Fallback);
    }
}

/// Canonical dominance: a `has_knowledge` PARENT (a skill) is the front door to its own
/// wiki/trigger pages. When the parent AND some of its children both match, lift the parent's
/// effective score to just above its best-matching child — so the skill ranks first and the
/// specific page follows. Derived from the data (best child + 1), no tuning constant.
/// Without this, subordinate docs out-score their skill on term coverage (real-vault p@1 45%).
fn apply_canonical_dominance(hits: &mut [Hit], graph: &Graph) {
    let score_by_id: HashMap<String, i64> = hits.iter().map(|h| (h.id.clone(), h.score)).collect();
    for h in hits.iter_mut() {
        let best_child = graph
            .edges
            .iter()
            .filter(|e| e.relation == crate::schema::relation::HAS_KNOWLEDGE && e.from == h.id)
            .filter_map(|e| score_by_id.get(&e.to).copied())
            .max();
        if let Some(bc) = best_child
            && bc + 1 > h.score
        {
            h.score = bc + 1;
            h.confidence = band_anchored(h.score, h.anchor, 1.0);
            h.why
                .push("canonical: front door over its own pages".into());
        }
    }
}

/// Ground a query against the graph: ranked hits with calibrated confidence. Builds a fresh
/// [`GroundIndex`] each call — convenient for one-shot use. To ground many queries against one graph,
/// build the index once and call [`ground_with`] (the eval harness and a warm server do this).
pub fn ground(graph: &Graph, query: &str, limit: usize) -> Vec<Hit> {
    ground_with(graph, &GroundIndex::build(graph), query, limit)
}

/// Which nodes are candidates for grounding. `Docs` excludes code symbols
/// (Function/Type/Trait/Module); `Code` keeps only them; `Section` keeps only sub-doc heading blocks;
/// `Subkind` keeps only nodes whose open domain `subkind` matches (e.g. "skill", "agent").
/// `All` is every CANONICAL unit — it deliberately EXCLUDES sections (they're a sub-granularity that
/// would flood the candidate set and displace skills/docs; opt in with `Section`).
#[derive(Clone, PartialEq, Eq, Debug, Default)]
pub enum Scope {
    #[default]
    All,
    Docs,
    Code,
    /// Only sub-doc `Section` nodes (heading blocks) — opt-in granularity.
    Section,
    /// Only nodes whose `subkind` equals this value.
    Subkind(String),
}

impl Scope {
    /// Parse a scope name. `all`/empty → All, `docs`/`doc` → Docs, `code` → Code,
    /// `section`/`sections` → Section; anything else is a `Subkind` filter (so `scope=skill` keeps
    /// only skill nodes). Always `Some`.
    pub fn parse(s: &str) -> Option<Scope> {
        Some(match s.trim().to_ascii_lowercase().as_str() {
            "all" | "" => Scope::All,
            "docs" | "doc" => Scope::Docs,
            "code" => Scope::Code,
            "section" | "sections" => Scope::Section,
            other => Scope::Subkind(other.to_string()),
        })
    }

    /// Does this scope admit `node` as a candidate?
    pub fn admits(&self, node: &Node) -> bool {
        use crate::schema::Kind;
        let is_code = matches!(
            node.kind,
            Kind::Function | Kind::Type | Kind::Trait | Kind::Module
        );
        let is_section = node.kind == Kind::Section;
        match self {
            // canonical scopes exclude sections (sub-granularity); opt in via Scope::Section.
            Scope::All => !is_section,
            Scope::Code => is_code,
            Scope::Docs => !is_code && !is_section,
            Scope::Section => is_section,
            Scope::Subkind(s) => node.subkind.as_deref() == Some(s.as_str()),
        }
    }
}

fn directional_relation_boosts<'a>(
    graph: &'a Graph,
    terms: &[String],
    query_lower: &str,
) -> HashMap<&'a str, Vec<RelationMatch>> {
    if terms.is_empty() {
        return HashMap::new();
    }
    let term_set = terms.iter().map(String::as_str).collect::<HashSet<_>>();
    let raw_term_set = raw_terms_of(query_lower)
        .into_iter()
        .collect::<HashSet<_>>();
    let node_by_id = graph
        .nodes
        .iter()
        .map(|node| (node.id.as_str(), node))
        .collect::<HashMap<_, _>>();
    let mut boosts: HashMap<&str, Vec<RelationMatch>> = HashMap::new();
    let mut seen_boosts = HashSet::new();

    for edge in &graph.edges {
        if edge.basis != EdgeBasis::Resolved {
            continue;
        }
        let Some(from) = node_by_id.get(edge.from.as_str()) else {
            continue;
        };
        let Some(to) = node_by_id.get(edge.to.as_str()) else {
            continue;
        };
        if !relation_is_directionally_searchable(graph, &edge.relation) {
            continue;
        }

        let forward_terms =
            terms_of(&relation_phrase(&edge.relation, &graph.relation_profiles).to_lowercase());
        if !forward_terms.is_empty()
            && forward_terms
                .iter()
                .all(|term| term_set.contains(term.as_str()))
        {
            let endpoint_hits = endpoint_term_hits(to, terms);
            if endpoint_hits > 0
                && seen_boosts.insert((
                    canonical_relation_endpoint(&edge.from),
                    canonical_relation_endpoint(&edge.to),
                    edge.relation.clone(),
                    "forward",
                ))
            {
                let score_boost = 48 + endpoint_hits as i64 * 8;
                boosts
                    .entry(edge.from.as_str())
                    .or_default()
                    .push(RelationMatch {
                        relation: edge.relation.clone(),
                        direction: "forward".to_string(),
                        phrase: relation_phrase(&edge.relation, &graph.relation_profiles),
                        endpoint_id: to.id.clone(),
                        endpoint_title: to.title.clone(),
                        endpoint_hits,
                        score_boost,
                    });
            }
        }

        let reverse_terms = terms_of(
            &reverse_relation_phrase(&edge.relation, &graph.relation_profiles).to_lowercase(),
        );
        let raw_reverse_terms = raw_terms_of(
            &reverse_relation_phrase(&edge.relation, &graph.relation_profiles).to_lowercase(),
        );
        if !reverse_terms.is_empty()
            && raw_reverse_terms
                .iter()
                .all(|term| raw_term_set.contains(term))
        {
            let endpoint_hits = endpoint_term_hits(from, terms);
            if endpoint_hits >= 2
                && seen_boosts.insert((
                    canonical_relation_endpoint(&edge.to),
                    canonical_relation_endpoint(&edge.from),
                    edge.relation.clone(),
                    "reverse",
                ))
            {
                let score_boost = 48 + endpoint_hits as i64 * 8;
                boosts
                    .entry(edge.to.as_str())
                    .or_default()
                    .push(RelationMatch {
                        relation: edge.relation.clone(),
                        direction: "reverse".to_string(),
                        phrase: reverse_relation_phrase(&edge.relation, &graph.relation_profiles),
                        endpoint_id: from.id.clone(),
                        endpoint_title: from.title.clone(),
                        endpoint_hits,
                        score_boost,
                    });
            }
        }
    }

    boosts
}

fn canonical_relation_endpoint(id: &str) -> String {
    id.split_once('#')
        .map_or(id, |(parent, _)| parent)
        .to_string()
}

fn endpoint_term_hits(node: &Node, terms: &[String]) -> usize {
    let mut surface = normalized_endpoint_text(&node.id);
    surface.push(' ');
    surface.push_str(&normalized_endpoint_text(&node.title));
    for alias in &node.aliases {
        surface.push(' ');
        surface.push_str(&normalized_endpoint_text(alias));
    }
    terms
        .iter()
        .filter(|term| {
            let term = normalized_endpoint_text(term);
            !term.is_empty() && surface.contains(&term)
        })
        .count()
}

fn normalized_endpoint_text(value: &str) -> String {
    value
        .chars()
        .filter(char::is_ascii_alphanumeric)
        .flat_map(char::to_lowercase)
        .collect()
}

fn relation_is_directionally_searchable(graph: &Graph, relation: &str) -> bool {
    graph
        .relation_profiles
        .get(relation)
        .cloned()
        .or_else(|| crate::schema::core_relation_profile(relation))
        .is_none_or(|profile| profile.searchable)
}

/// Ground using a precomputed [`GroundIndex`] — the hot path. Byte-for-byte identical results to
/// [`ground`]; the only difference is that the graph-invariant inputs are supplied, not rebuilt.
pub fn ground_with(graph: &Graph, index: &GroundIndex, query: &str, limit: usize) -> Vec<Hit> {
    ground_scoped(graph, index, query, limit, Scope::All)
}

/// Like [`ground_with`], restricted to the candidates a `scope` admits (docs-only / code-only).
/// `Scope::All` is identical to [`ground_with`]. Scope is a pre-filter on which nodes are scored;
/// IDF/df stays corpus-wide (distinctiveness is a global property of the graph).
pub fn ground_scoped(
    graph: &Graph,
    index: &GroundIndex,
    query: &str,
    limit: usize,
    scope: Scope,
) -> Vec<Hit> {
    let q = query.to_lowercase();
    // A blank query grounds nothing — without this guard every `field.contains("")` is true,
    // so an empty query would match (and strongly score) every node.
    if q.trim().is_empty() {
        return Vec::new();
    }
    let terms = terms_of(&q);
    let n = graph.nodes.len();

    // TRIGRAM CANDIDATE NARROWING: disabled temporarily — it's causing a regression.
    // The trigram index is built but we're still investigating why it misses candidates.
    // TODO: fix the trigram candidate coverage, then re-enable.
    // let mut candidate_indices: Vec<usize> =
    //     index.candidates(&terms).unwrap_or_else(|| (0..n).collect());
    // candidate_indices.sort_unstable();
    let candidate_indices: Vec<usize> = (0..n).collect();

    let mut hits: Vec<Hit> = {
        // BM25F: field-weighted BM25 over the precomputed surfaces, length-normalized. This is
        // THE ranker — the legacy substring scorer (env-gated `EIDOS_RANKER=legacy`) was deleted
        // in D0.8 after its byte-identical migration was long proven.
        let bdf = bm25f_df(&terms, &index.bm25_fields);
        // Ranker params come from the index (injected at build; frozen calibration by default).
        // The kernel never reads the environment — same inputs → same scores.
        let params = index.config;
        // ADAPTIVE BANDS: per-query normalization ceiling = the max BM25F a perfect identity match
        // could reach (the query terms' IDF at field-weight saturation). Dividing the score by it
        // makes the score — and therefore the confidence bands — CORPUS-INDEPENDENT: no absolute
        // threshold tied to a particular vault's IDF scale. Self-tunes to any corpus.
        let sat = params.weights[1] / (params.k1 + params.weights[1]); // top field (title) saturation
        let qmax: f64 = terms
            .iter()
            .map(|t| {
                let dft = *bdf.get(t.as_str()).unwrap_or(&0);
                if dft == 0 {
                    0.0
                } else {
                    ((n as f64 - dft as f64 + 0.5) / (dft as f64 + 0.5) + 1.0).ln() * sat
                }
            })
            .sum::<f64>()
            .max(1e-3);
        let scorer = Bm25fScorer {
            terms: &terms,
            df: &bdf,
            n,
            avglen: &index.bm25_avglen,
            params,
        };
        // Fraction of query terms that exist ANYWHERE in the corpus. When most of a query's
        // vocabulary is absent (df == 0), the query is about something this brain does not know —
        // the garbage-near-node class ("task scheduler yoga meditation mindfulness"). A partial
        // identity match must not anchor confidence on such a query: matching the 2 familiar words
        // says nothing about the 3 unknown ones the query is actually about.
        let known_coverage = terms
            .iter()
            .filter(|t| *bdf.get(t.as_str()).unwrap_or(&0) > 0)
            .count() as f64
            / terms.len().max(1) as f64;
        let directional_relation_boosts = directional_relation_boosts(graph, &terms, &q);
        graph
            .nodes
            .iter()
            .enumerate()
            .filter(|(i, _)| candidate_indices.binary_search(i).is_ok())
            .filter(|(_, node)| scope.admits(node))
            .filter_map(|(i, node)| {
                let is_code = matches!(
                    node.kind,
                    Kind::Function | Kind::Type | Kind::Trait | Kind::Module
                );
                let is_module = node.kind == Kind::Module;
                let (s, id_s, matched, matched_identity, matched_name, max_exact_name_idf) =
                    bm25f_score(
                        &index.bm25_fields[i],
                        &scorer,
                        Bm25fNodeShape { is_code, is_module },
                    );
                // exact-match boosts on the normalized 0..100 scale (cheap, high-precision).
                // Computed BEFORE the s<=0 filter: a whole-query id/title match (e.g. "skill.a",
                // which de-slugifies away from the token "skill") must still register even when the
                // tokenized BM25F score is 0.
                let idl = node.id.to_lowercase();
                let titlel = node.title.to_lowercase();
                let exact_query_example = node
                    .query_examples
                    .iter()
                    .any(|example| example.to_lowercase() == q);
                let exact = if idl == q
                    || titlel == q
                    || node.aliases.iter().any(|a| a.to_lowercase() == q)
                {
                    80.0 // whole query == an identity field: the strongest signal, must DOMINATE
                // (clear the ambiguity ratio even when a near-dupe shares the term)
                } else if titlel.contains(&q)
                    || node.aliases.iter().any(|a| a.to_lowercase().contains(&q))
                {
                    6.0 // partial substring — small; must NOT rival an exact match (calibration)
                } else {
                    0.0
                };
                let query_example_boost = if exact_query_example && !is_code {
                    60.0
                } else {
                    0.0
                };
                if s <= 0.0 && exact <= 0.0 && query_example_boost <= 0.0 {
                    return None;
                }
                let coverage = matched as f64 / terms.len().max(1) as f64;
                // IDENTITY coverage: fraction of query terms matching the node's NAME (id/title/
                // aliases), not its body — the garbage guard. "load user router model payload cache"
                // lands `load`+`user` in load_user's name but the rest only in its body (2/6 identity).
                let id_coverage = matched_identity as f64 / terms.len().max(1) as f64;
                // KIND/INTENT PRIOR (the graph-signal layer): when the query asks for a particular
                // kind — "which expert owns…" (agent), "…implemented in code" (code) — boost nodes of
                // that kind. Reuses the legacy intent detection so BM25F is ≥ legacy on intent too.
                let aliases: Vec<String> = node.aliases.iter().map(|a| a.to_lowercase()).collect();
                let intents = query_intent_matches(node, &aliases, &terms);
                // EXACT SYMBOL-NAME, kind-gated: a query term that IS the node's whole title ("hit" for
                // type Hit) prefers the symbol literally named — but for CODE only when the query also
                // carries a structural keyword matching the node's kind ("the Hit STRUCT"→Type, "the
                // retrieval MODULE"→Module). This is legacy's structural-lookup context: it tells "the
                // Hit struct" (boost Hit) from "profile config settings" (no kind word → a generic term
                // matching a module's name must NOT dominate the config symbol the query is about). For
                // docs a bare title-equal term is already an unambiguous signal, so no keyword needed.
                let term_eq_title =
                    !titlel.is_empty() && terms.iter().any(|t| t.as_str() == titlel);
                let kind_kw = match node.kind {
                    Kind::Type => terms
                        .iter()
                        .any(|t| matches!(t.as_str(), "struct" | "enum" | "type")),
                    Kind::Trait => terms.iter().any(|t| t == "trait"),
                    Kind::Module => terms.iter().any(|t| matches!(t.as_str(), "module" | "mod")),
                    Kind::Function => terms
                        .iter()
                        .any(|t| matches!(t.as_str(), "function" | "fn" | "method" | "func")),
                    _ => false,
                };
                let name_boost = if term_eq_title && (!is_code || kind_kw) {
                    20.0
                } else {
                    0.0
                };
                let (intent_boost, anchor_intent_boost) = intent_boosts(
                    &intents,
                    is_code,
                    !is_distinct_code_symbol_name(&titlel),
                    matched_identity,
                    exact,
                    name_boost,
                );
                let has_relation_intent = terms.iter().any(|term| is_relation_query_term(term));
                let relation_term_hits = if has_relation_intent {
                    terms
                        .iter()
                        .filter(|term| index.bm25_fields[i][5].iter().any(|token| token == *term))
                        .count()
                } else {
                    0
                };
                let relation_boost = (relation_term_hits as f64) * 12.0;
                let relation_matches = directional_relation_boosts
                    .get(node.id.as_str())
                    .cloned()
                    .unwrap_or_default();
                let directional_relation_boost =
                    relation_matches.iter().map(|m| m.score_boost).sum::<i64>() as f64;
                let relation_anchor = directional_relation_boost > 0.0;
                let code_action = code_action_subject_match(node, &terms);
                let code_action_boost = code_action
                    .as_ref()
                    .map_or(0.0, |signal| signal.score_boost);
                // normalized relevance in ~[0,100] (s/qmax) → adaptive, corpus-independent bands.
                // NO coverage factor here: ranking keeps the full score so a distinctive single term
                // ("waybar" in "waybar data system build") still outranks generic-term accumulation.
                // + matched_identity + name_boost as tiebreakers: when two nodes saturate the
                // normalization ceiling, the one matching MORE query terms in its NAME, or whose whole
                // name a term equals, wins (kind/specificity disambiguation).
                let score = ((s / qmax) * 100.0
                    + exact
                    + query_example_boost
                    + intent_boost
                    + relation_boost
                    + directional_relation_boost
                    + code_action_boost
                    + matched_identity as f64
                    + name_boost)
                    .round() as i64;
                // Coverage gates CONFIDENCE, not ranking: a high-scoring hit covering <60% of the
                // query is the garbage-near-node class ("rust gardening clippy soup"→skill.rust). Zero
                // its anchor so band_anchored caps it to Weak — and since canonical dominance ALSO
                // recomputes via band_anchored(score, anchor), the cap survives the dominance lift. An
                // exact identity OR intent match is always anchored.
                // name_boost anchors too: a kind-confirmed exact name match ("retrieval module"→
                // mod.retrieval) IS the answer. Without it a module — whose summary no longer anchors
                // it — would never be confident even when the query explicitly names it.
                // DISTINCTIVE-NAME anchor: a RARE query term (high IDF) that EXACTLY names this node
                // unambiguously identifies it, even when common co-terms dilute id_coverage below the
                // 0.4 bar. "why did my CARBONARA turn into scrambled eggs" → carbonara (df=1) names
                // doc.carbonara; egg/scrambled do not. Gated by known_coverage so an out-of-vocabulary
                // garbage query ("carbonara kubernetes payload") can't anchor on the one real term.
                let distinctive_name =
                    max_exact_name_idf >= DISTINCTIVE_NAME_IDF && known_coverage >= 0.6;
                let anchored = exact > 0.0
                    || query_example_boost > 0.0
                    || anchor_intent_boost > 0.0
                    || name_boost > 0.0
                    || code_action_boost > 0.0
                    || relation_anchor
                    || distinctive_name
                    || (id_coverage >= 0.4 && matched_name > 0 && known_coverage >= 0.6);
                let anchor = if anchored {
                    id_s + exact
                        + query_example_boost
                        + anchor_intent_boost
                        + name_boost
                        + code_action_boost
                        + directional_relation_boost
                } else {
                    0.0
                };
                let rank_score =
                    route_score(score as f64, anchor, matched_identity, coverage).round() as i64;
                let mut why = vec![format!(
                    "bm25f {s:.2} (identity {id_s:.2}, cover {:.0}%)",
                    coverage * 100.0
                )];
                if !intents.is_empty() {
                    why.push(format!("query intent match: {}", intents.join(", ")));
                }
                if relation_term_hits > 0 {
                    why.push(format!(
                        "relation context match: {relation_term_hits} terms"
                    ));
                }
                if relation_anchor {
                    let relations = relation_matches
                        .iter()
                        .map(|m| format!("{} {} {}", m.direction, m.relation, m.endpoint_id))
                        .collect::<Vec<_>>()
                        .join(", ");
                    why.push(format!(
                        "directed relation match: +{} ({relations})",
                        directional_relation_boost as i64,
                    ));
                }
                if let Some(code_action) = code_action {
                    why.push(format!(
                        "code action subject match: {} identifier terms",
                        code_action.identifier_hits
                    ));
                }
                if query_example_boost > 0.0 {
                    why.push("exact query_example match".to_string());
                }
                Some(Hit {
                    id: node.id.clone(),
                    score: rank_score,
                    lexical_score: score,
                    confidence: band_anchored(score, anchor, coverage),
                    why,
                    relation_matches,
                    anchor,
                    relation_anchor,
                })
            })
            .collect()
    };
    apply_canonical_dominance(&mut hits, graph);
    // A node whose TITLE carries more query terms is more specific than one that only matches in
    // body/summary text (a symbol NAMED for the concept beats one that merely mentions it).
    // The score boost handles real relevance gaps; this tie-break keeps equal-score ordering
    // deterministic and specificity-preserving. (Titles are precomputed in the index.)
    let title_hit: HashSet<&str> = graph
        .nodes
        .iter()
        .enumerate()
        .filter(|(i, _)| {
            terms
                .iter()
                .any(|term| index.lc_titles[*i].contains(term.as_str()))
        })
        .map(|(_, node)| node.id.as_str())
        .collect();
    let title_term_hits: HashMap<&str, usize> = graph
        .nodes
        .iter()
        .enumerate()
        .map(|(i, node)| {
            (
                node.id.as_str(),
                terms
                    .iter()
                    .filter(|term| index.lc_titles[i].contains(term.as_str()))
                    .count(),
            )
        })
        .collect();
    hits.sort_by(|a, b| {
        b.score
            .cmp(&a.score)
            .then_with(|| {
                title_hit
                    .contains(b.id.as_str())
                    .cmp(&title_hit.contains(a.id.as_str()))
            })
            .then_with(|| {
                title_term_hits
                    .get(b.id.as_str())
                    .cmp(&title_term_hits.get(a.id.as_str()))
            })
            .then_with(|| a.id.cmp(&b.id))
    });
    calibrate(&mut hits);
    hits.truncate(limit);
    hits
}

/// Route-rank penalty for PARTIAL BODY-ONLY mentions: a hit with no anchor and ZERO identity
/// evidence (`matched_identity == 0` — nothing landed in id/title/summary/aliases) that also
/// fails to cover the whole query is a scatter of body words, not an answer. Scale its route
/// rank by coverage so anchored/identity-backed hits outrank it. A hit with ANY identity
/// evidence keeps its full lexical rank even when unanchored: partial identity plus a dominant
/// lexical score (e.g. a runbook section matching 4 of 6 task words) is honest relevance, and
/// the confidence band — not the rank — is where its uncertainty is reported.
fn route_score(score: f64, anchor: f64, matched_identity: usize, coverage: f64) -> f64 {
    if anchor <= 0.0 && matched_identity == 0 && coverage < 1.0 {
        score * coverage.max(0.25)
    } else {
        score
    }
}

#[derive(Debug, Clone, Copy)]
struct CodeActionSignal {
    identifier_hits: usize,
    score_boost: f64,
}

fn code_action_subject_match(node: &Node, terms: &[String]) -> Option<CodeActionSignal> {
    if !matches!(
        node.kind,
        Kind::Function | Kind::Type | Kind::Trait | Kind::Module
    ) || !query_has_code_action_intent(terms)
    {
        return None;
    }
    let subject_terms = terms
        .iter()
        .filter(|term| !is_code_action_control_term(term))
        .map(|term| normalized_identifier_text(term))
        .filter(|term| !term.is_empty())
        .collect::<HashSet<_>>();
    if subject_terms.is_empty() {
        return None;
    }

    let segments = code_identifier_segments(node);
    let identifier_hits = subject_terms
        .iter()
        .filter(|term| segments.contains(term.as_str()))
        .count();
    if identifier_hits == 0 {
        return None;
    }

    let wants_function = terms.iter().any(|term| {
        matches!(
            term.as_str(),
            "definition"
                | "function"
                | "fn"
                | "implement"
                | "implementation"
                | "implemented"
                | "method"
                | "source"
        )
    });
    let kind_boost = match node.kind {
        Kind::Function => 16.0,
        Kind::Type | Kind::Trait => 12.0,
        Kind::Module => 8.0,
        _ => 0.0,
    };
    let function_boost = if wants_function && node.kind == Kind::Function {
        18.0
    } else {
        0.0
    };
    Some(CodeActionSignal {
        identifier_hits,
        score_boost: identifier_hits as f64 * 28.0 + kind_boost + function_boost,
    })
}

fn query_has_code_action_intent(terms: &[String]) -> bool {
    terms.iter().any(|term| is_code_action_control_term(term))
}

fn is_code_action_control_term(term: &str) -> bool {
    matches!(
        term,
        "call"
            | "caller"
            | "callee"
            | "change"
            | "changing"
            | "definition"
            | "function"
            | "fn"
            | "implement"
            | "implementation"
            | "implemented"
            | "method"
            | "modify"
            | "source"
            | "trace"
            | "type"
            | "usage"
            | "use"
            | "used"
            | "uses"
    )
}

fn code_identifier_segments(node: &Node) -> HashSet<String> {
    let mut out = HashSet::new();
    push_identifier_segments(&mut out, &node.id);
    push_identifier_segments(&mut out, &node.title);
    out
}

fn push_identifier_segments(out: &mut HashSet<String>, value: &str) {
    for segment in value.split([':', '.', '#', '/', '-']) {
        let normalized = normalized_identifier_text(segment);
        if !normalized.is_empty() {
            out.insert(normalized);
        }
        for part in segment.split('_') {
            let normalized_part = normalized_identifier_text(part);
            if normalized_part.len() >= 6 {
                out.insert(normalized_part);
            }
        }
    }
    let normalized = normalized_identifier_text(value);
    if !normalized.is_empty() {
        out.insert(normalized);
    }
}

fn normalized_identifier_text(value: &str) -> String {
    value
        .chars()
        .filter(char::is_ascii_alphanumeric)
        .flat_map(char::to_lowercase)
        .collect()
}

fn is_relation_query_term(term: &str) -> bool {
    matches!(
        term,
        "call"
            | "consume"
            | "contract"
            | "depend"
            | "dispatch"
            | "implement"
            | "link"
            | "produce"
            | "reference"
            | "relate"
            | "require"
    )
}

#[cfg(test)]
mod band_tests {
    use super::*;
    use crate::schema::{Edge, EdgeBasis, RelationProfile};

    // Bands recalibrated to the post-IDF/stemming score distribution (measured): clean accuracy is
    // 100% down to score 45, garbage tops out ~32 — so strong≥45 is discriminating AND safe.
    fn test_hit(id: &str, score: i64, confidence: Confidence) -> Hit {
        Hit {
            id: id.into(),
            score,
            lexical_score: score,
            confidence,
            why: Vec::new(),
            relation_matches: Vec::new(),
            anchor: 1.0,
            relation_anchor: false,
        }
    }

    // D4.2: pins for scoring signals the audit flagged with zero direct coverage.

    #[test]
    fn apply_floor_drops_trailing_fallback_only_when_a_confident_hit_exists() {
        // Confident top present → trailing Fallback noise is dropped.
        let mut hits = vec![
            test_hit("a", 60, Confidence::Strong),
            test_hit("b", 20, Confidence::Fallback),
            test_hit("c", 10, Confidence::Fallback),
        ];
        apply_floor(&mut hits);
        assert_eq!(
            hits.iter().map(|h| h.id.as_str()).collect::<Vec<_>>(),
            ["a"]
        );

        // No confident hit → the full ranked list is kept (a weak-but-real answer must survive,
        // and garbage must still read as rejected rather than empty).
        let mut weak = vec![
            test_hit("a", 30, Confidence::Weak),
            test_hit("b", 20, Confidence::Fallback),
        ];
        apply_floor(&mut weak);
        assert_eq!(weak.len(), 2, "no confident hit ⇒ list untouched");
    }

    #[test]
    fn calibrate_demotes_strong_top_when_runner_up_is_within_ambiguity_ratio() {
        // Runner-up ≥ 0.7 × top → the top is a coin-flip, demote Strong → Ambiguous.
        let mut close = vec![
            test_hit("a", 100, Confidence::Strong),
            test_hit("b", 70, Confidence::Strong),
        ];
        calibrate(&mut close);
        assert_eq!(close[0].confidence, Confidence::Ambiguous);

        // Runner-up below the ratio → the top stays Strong (a clear winner).
        let mut clear = vec![
            test_hit("a", 100, Confidence::Strong),
            test_hit("b", 69, Confidence::Strong),
        ];
        calibrate(&mut clear);
        assert_eq!(clear[0].confidence, Confidence::Strong);
    }

    #[test]
    fn canonical_dominance_lifts_a_parent_above_its_best_matching_child() {
        // skill.x --has_knowledge--> doc.x#page ; the child out-scores the parent on term
        // coverage. Dominance lifts the parent to best_child + 1 so the front door ranks first.
        let graph = Graph {
            nodes: Vec::new(),
            edges: vec![Edge {
                from: "skill.x".into(),
                to: "doc.x#page".into(),
                relation: crate::schema::relation::HAS_KNOWLEDGE.into(),
                basis: EdgeBasis::Resolved,
                ..Default::default()
            }],
            ..Default::default()
        };
        let mut hits = vec![
            test_hit("doc.x#page", 80, Confidence::Strong),
            test_hit("skill.x", 50, Confidence::Weak),
        ];
        apply_canonical_dominance(&mut hits, &graph);
        let parent = hits.iter().find(|h| h.id == "skill.x").unwrap();
        assert_eq!(parent.score, 81, "parent lifted to best_child + 1");
        assert!(parent.why.iter().any(|w| w.contains("canonical")));
    }

    #[test]
    fn adding_a_garbage_term_never_raises_a_hits_band() {
        // D4.5 monotonicity invariant — the one the 2026-07-04 gate incident violated: appending
        // an absent (garbage) term to a query dilutes coverage and can only LOWER or keep a hit's
        // confidence, never raise it. Checked across a small spread of node shapes.
        let band_rank = |c: Confidence| match c {
            Confidence::Exact => 4,
            Confidence::Strong => 3,
            Confidence::Ambiguous => 2,
            Confidence::Weak => 1,
            Confidence::Fallback => 0,
        };
        let node = |id: &str, title: &str, summary: &str, aliases: &[&str]| Node {
            id: id.into(),
            kind: Kind::Doc,
            subkind: None,
            title: title.into(),
            summary: summary.into(),
            aliases: aliases
                .iter()
                .map(std::string::ToString::to_string)
                .collect(),
            tags: Vec::new(),
            query_examples: Vec::new(),
            source_files: vec!["f.md".into()],
            span: None,
            partition: None,
        };
        let graph = Graph {
            nodes: vec![
                node(
                    "doc.retry",
                    "Retry Policy",
                    "backoff and dead letter routing",
                    &["retry"],
                ),
                node(
                    "doc.sched",
                    "Scheduler",
                    "the task scheduler loop",
                    &["scheduler"],
                ),
                node("doc.obs", "Observability", "logs metrics traces", &[]),
            ],
            ..Default::default()
        };

        for base in ["retry policy", "scheduler loop", "logs metrics", "retry"] {
            let with_garbage = format!("{base} zzqwxborg");
            let base_hits = ground(&graph, base, 5);
            let noisy_hits = ground(&graph, &with_garbage, 5);
            for bh in &base_hits {
                if let Some(nh) = noisy_hits.iter().find(|h| h.id == bh.id) {
                    assert!(
                        band_rank(nh.confidence) <= band_rank(bh.confidence),
                        "adding a garbage term raised {}'s band from {:?} to {:?} (query {base:?})",
                        bh.id,
                        bh.confidence,
                        nh.confidence
                    );
                }
            }
        }
    }

    #[test]
    fn ranker_config_is_injected_not_read_from_env() {
        // D4: the ranker params flow through GroundIndex (built with a RankerConfig), NOT the
        // environment. A body-heavy node scored with a body-weight-boosted config must produce a
        // DIFFERENT lexical score than the frozen default — proving the injected config reaches
        // the scorer. (Also the purity guarantee: same graph+query+config → same score.)
        let graph = Graph {
            nodes: vec![Node {
                id: "doc.note".to_string(),
                kind: Kind::Doc,
                subkind: None,
                title: "Note".to_string(),
                // Body (summary) carries the query term; a config that boosts the summary field
                // weight scores it higher.
                summary: "kombucha kombucha kombucha fermentation notes".to_string(),
                aliases: Vec::new(),
                tags: Vec::new(),
                query_examples: Vec::new(),
                source_files: vec!["note.md".to_string()],
                span: None,
                partition: None,
            }],
            edges: Vec::new(),
            ..Default::default()
        };

        let default_index = GroundIndex::build(&graph);
        let boosted = RankerConfig {
            weights: [5.0, 8.0, 40.0, 6.0, 4.0, 3.0], // 20x the summary-field weight
            ..RankerConfig::default()
        };
        let boosted_index = GroundIndex::build_with_config(&graph, boosted);

        let default_score =
            ground_with(&graph, &default_index, "kombucha fermentation", 5)[0].lexical_score;
        let boosted_score =
            ground_with(&graph, &boosted_index, "kombucha fermentation", 5)[0].lexical_score;

        assert_ne!(
            default_score, boosted_score,
            "an injected RankerConfig must change scoring"
        );
        // Determinism: same config → same score.
        let repeat =
            ground_with(&graph, &boosted_index, "kombucha fermentation", 5)[0].lexical_score;
        assert_eq!(boosted_score, repeat);
    }

    #[test]
    fn bands_are_calibrated_to_score_distribution() {
        assert_eq!(
            band(45),
            Confidence::Strong,
            "45 is strong (clean accuracy 100% there)"
        );
        assert_eq!(band(44), Confidence::Weak);
        assert_eq!(band(25), Confidence::Weak);
        assert_eq!(band(24), Confidence::Fallback);
        // safety: the garbage ceiling (~32) must never reach 'strong'.
        assert_eq!(
            band(32),
            Confidence::Weak,
            "garbage-range scores stay below strong"
        );
    }

    #[test]
    fn anchor_caps_body_only_mentions_below_strong() {
        // A body-only hit (anchor=0.0) with full coverage + decent score → Weak (not Fallback).
        // The doc genuinely contains all query terms — it's a real-but-weak answer.
        assert_eq!(band_anchored(60, 0.0, 1.0), Confidence::Weak);
        assert_eq!(band_anchored(48, 0.0, 1.0), Confidence::Weak);
        assert_eq!(band_anchored(30, 0.0, 1.0), Confidence::Weak);
        assert_eq!(band_anchored(25, 0.0, 1.0), Confidence::Weak);
        // Low score or partial coverage → still Fallback (marginal match)
        assert_eq!(band_anchored(10, 0.0, 1.0), Confidence::Fallback);
        assert_eq!(band_anchored(30, 0.0, 0.5), Confidence::Fallback);
        // An identity-anchored hit keeps its score-based band.
        assert_eq!(band_anchored(60, 0.5, 1.0), Confidence::Strong);
        assert_eq!(band_anchored(30, 0.9, 1.0), Confidence::Weak);
    }

    #[test]
    fn code_symbol_names_require_distinctive_bare_terms() {
        assert!(is_distinct_code_symbol_name("load_settings"));
        assert!(is_distinct_code_symbol_name("config2"));
        assert!(!is_distinct_code_symbol_name("run"));
        assert!(!is_distinct_code_symbol_name("id"));
        assert!(!is_distinct_code_symbol_name("123456"));
    }

    #[test]
    fn route_score_penalizes_partial_body_only_mentions() {
        assert_eq!(route_score(60.0, 0.0, 0, 0.5), 30.0);
        assert_eq!(route_score(60.0, 0.0, 0, 1.0), 60.0);
        assert_eq!(route_score(60.0, 0.2, 0, 0.5), 60.0);
        // ANY identity evidence exempts a hit from the body-only penalty.
        assert_eq!(route_score(60.0, 0.0, 1, 0.5), 60.0);
    }

    #[test]
    fn anchored_typo_match_beats_partial_body_only_match() {
        let graph = Graph {
            nodes: vec![
                Node {
                    id: "doc.material-inventory".to_string(),
                    kind: Kind::Doc,
                    subkind: None,
                    title: "Material Inventory".to_string(),
                    summary: "Home furniture materials, finishes, and care notes.".to_string(),
                    aliases: Vec::new(),
                    tags: vec!["veneer".to_string(), "desk".to_string()],
                    query_examples: vec![
                        "Desk: walnut veneer over plywood. Do not sand aggressively.".to_string(),
                    ],
                    source_files: vec!["material-inventory.md".to_string()],
                    span: None,
                    partition: None,
                },
                Node {
                    id: "skill.wood-care".to_string(),
                    kind: Kind::Skill,
                    subkind: None,
                    title: "wood-care".to_string(),
                    summary: "Care and repair for wood, veneer, water rings, and scratches."
                        .to_string(),
                    aliases: vec![
                        "veneer".to_string(),
                        "scratch".to_string(),
                        "wood repair".to_string(),
                    ],
                    tags: Vec::new(),
                    query_examples: vec!["fixing small scratches in walnut furniture".to_string()],
                    source_files: vec!["skills/wood-care/SKILL.md".to_string()],
                    span: None,
                    partition: None,
                },
            ],
            edges: Vec::new(),
            ..Default::default()
        };

        let hits = ground(&graph, "veneer desk skratch", 5);

        assert_eq!(
            hits.first().map(|hit| hit.id.as_str()),
            Some("skill.wood-care")
        );
        assert!(
            hits.iter()
                .any(|hit| hit.id == "doc.material-inventory"
                    && hit.confidence == Confidence::Fallback),
            "body-only material doc should remain a low-confidence support hit"
        );
    }

    #[test]
    fn generic_code_intent_does_not_make_body_only_helper_strong() {
        let graph = Graph {
            nodes: vec![Node {
                id: "fn.tests::run".to_string(),
                kind: Kind::Function,
                subkind: None,
                title: "run".to_string(),
                summary: String::new(),
                aliases: Vec::new(),
                tags: Vec::new(),
                query_examples: vec![
                    "debug package eval gates code architecture docs inspect".to_string(),
                ],
                source_files: vec!["tests/cli_graph.rs".to_string()],
                span: None,
                partition: None,
            }],
            edges: Vec::new(),
            ..Default::default()
        };

        let hits = ground(
            &graph,
            "debug package eval gates code architecture docs inspect",
            5,
        );

        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].id, "fn.tests::run");
        assert_eq!(hits[0].confidence, Confidence::Weak);
    }

    /// The garbage-near-node class: a query whose vocabulary is MOSTLY absent from the corpus
    /// ("yoga meditation mindfulness" on a task-scheduler brain) must not produce a confident
    /// answer just because the two familiar words match a node's name. Matching what you know
    /// says nothing about the part of the query you don't. Regression: the id_coverage >= 0.4
    /// anchor arm requires known_coverage >= 0.6, so the top hit stays Weak/Fallback and the
    /// routing directive rejects instead of answering.
    #[test]
    fn mostly_unknown_query_does_not_anchor_partial_name_match() {
        let graph = Graph {
            nodes: vec![
                Node {
                    id: "skill.task-scheduling".to_string(),
                    kind: Kind::Skill,
                    subkind: None,
                    title: "task-scheduling".to_string(),
                    summary: "Scheduling tasks with retry, backoff, and dead-letter queues."
                        .to_string(),
                    aliases: vec!["task scheduler".to_string()],
                    tags: Vec::new(),
                    query_examples: Vec::new(),
                    source_files: vec!["skills/task-scheduling/SKILL.md".to_string()],
                    span: None,
                    partition: None,
                },
                Node {
                    id: "doc.runbook".to_string(),
                    kind: Kind::Doc,
                    subkind: None,
                    title: "Operations Runbook".to_string(),
                    summary: "Symptoms and fixes for task and worker failures.".to_string(),
                    aliases: Vec::new(),
                    tags: Vec::new(),
                    query_examples: Vec::new(),
                    source_files: vec!["runbook.md".to_string()],
                    span: None,
                    partition: None,
                },
            ],
            edges: Vec::new(),
            ..Default::default()
        };

        let hits = ground(&graph, "task scheduler yoga meditation mindfulness", 5);

        let top = hits.first().expect("the familiar terms still match");
        assert!(
            matches!(top.confidence, Confidence::Weak | Confidence::Fallback),
            "a mostly-unknown query must not answer confidently, got {:?} for {}",
            top.confidence,
            top.id
        );
    }

    #[test]
    fn code_action_query_prefers_named_function_over_nearby_type_context() {
        let graph = Graph {
            nodes: vec![
                code_node(
                    "type.policy::Backoff",
                    Kind::Type,
                    "Backoff",
                    "Backoff configuration used by RetryPolicy delay_ms implementation.",
                ),
                code_node(
                    "type.policy::RetryPolicy",
                    Kind::Type,
                    "RetryPolicy",
                    "Retry policy configuration with max attempts and backoff.",
                ),
                code_node(
                    "fn.policy::RetryPolicy::delay_ms",
                    Kind::Function,
                    "delay_ms",
                    "Compute the delay for a retry attempt.",
                ),
            ],
            edges: Vec::new(),
            ..Default::default()
        };

        let hits = ground(&graph, "RetryPolicy delay_ms implementation", 5);

        assert_eq!(
            hits.first().map(|hit| hit.id.as_str()),
            Some("fn.policy::RetryPolicy::delay_ms")
        );
        assert!(
            hits[0]
                .why
                .iter()
                .any(|why| why.contains("code action subject match")),
            "top hit should explain the code-action identifier signal"
        );
    }

    #[test]
    fn resolved_relation_surfaces_are_searchable_without_body_mentions() {
        let graph = Graph {
            nodes: vec![
                Node {
                    id: "doc.router".to_string(),
                    kind: Kind::Doc,
                    subkind: None,
                    title: "Router".to_string(),
                    summary: "Request routing policy.".to_string(),
                    aliases: Vec::new(),
                    tags: Vec::new(),
                    query_examples: Vec::new(),
                    source_files: vec!["router.md".to_string()],
                    span: None,
                    partition: None,
                },
                Node {
                    id: "doc.auth-contract".to_string(),
                    kind: Kind::Doc,
                    subkind: None,
                    title: "Auth Contract".to_string(),
                    summary: "Authentication requirements.".to_string(),
                    aliases: vec!["login rules".to_string()],
                    tags: Vec::new(),
                    query_examples: Vec::new(),
                    source_files: vec!["auth.md".to_string()],
                    span: None,
                    partition: None,
                },
            ],
            edges: vec![Edge {
                from: "doc.router".to_string(),
                to: "doc.auth-contract".to_string(),
                relation: "depends_on".to_string(),
                evidence: "frontmatter".to_string(),
                basis: EdgeBasis::Resolved,
                ..Default::default()
            }],
            ..Default::default()
        };

        let hits = ground(&graph, "depends on auth contract", 5);

        assert_eq!(hits.first().map(|hit| hit.id.as_str()), Some("doc.router"));
        assert!(
            hits[0].why.iter().any(|why| why.contains("bm25f")),
            "relation search should flow through normal BM25F evidence"
        );
        assert_eq!(hits[0].relation_matches.len(), 1);
        let relation_match = &hits[0].relation_matches[0];
        assert_eq!(relation_match.relation, "depends_on");
        assert_eq!(relation_match.direction, "forward");
        assert_eq!(relation_match.phrase, "depends on");
        assert_eq!(relation_match.endpoint_id, "doc.auth-contract");
        assert_eq!(relation_match.endpoint_title, "Auth Contract");
        assert_eq!(relation_match.endpoint_hits, 2);
        assert!(relation_match.score_boost > 0);
    }

    #[test]
    fn forward_relation_query_does_not_trigger_reverse_phrase_by_stem_only() {
        let graph = Graph {
            nodes: vec![
                Node {
                    id: "doc.refund-runbook".to_string(),
                    kind: Kind::Doc,
                    subkind: None,
                    title: "Refund Escalation Runbook".to_string(),
                    summary: "High value refund process.".to_string(),
                    aliases: Vec::new(),
                    tags: Vec::new(),
                    query_examples: Vec::new(),
                    source_files: vec!["refund.md".to_string()],
                    span: None,
                    partition: None,
                },
                Node {
                    id: "doc.release-gate".to_string(),
                    kind: Kind::Doc,
                    subkind: None,
                    title: "Refund Release Gate".to_string(),
                    summary: "Release gate for refund changes.".to_string(),
                    aliases: Vec::new(),
                    tags: Vec::new(),
                    query_examples: Vec::new(),
                    source_files: vec!["gate.md".to_string()],
                    span: None,
                    partition: None,
                },
            ],
            edges: vec![Edge {
                from: "doc.refund-runbook".to_string(),
                to: "doc.release-gate".to_string(),
                relation: "blocks".to_string(),
                evidence: "frontmatter".to_string(),
                basis: EdgeBasis::Resolved,
                ..Default::default()
            }],
            relation_profiles: [(
                "blocks".to_string(),
                RelationProfile::new("blocks", "blocked by", 34),
            )]
            .into_iter()
            .collect(),
        };

        let hits = ground(
            &graph,
            "make high value refund change that blocks refund release gate",
            5,
        );

        assert_eq!(
            hits.first().map(|hit| hit.id.as_str()),
            Some("doc.refund-runbook")
        );
        assert_eq!(hits[0].relation_matches.len(), 1);
        assert_eq!(hits[0].relation_matches[0].direction, "forward");
        assert_eq!(hits[0].relation_matches[0].endpoint_id, "doc.release-gate");
        assert!(
            hits.iter()
                .find(|hit| hit.id == "doc.release-gate")
                .is_none_or(|hit| hit.relation_matches.is_empty()),
            "`blocks` should not satisfy the reverse phrase `blocked by` via stemming alone"
        );
    }

    #[test]
    fn relation_profiles_control_search_phrases() {
        let graph = Graph {
            nodes: vec![
                Node {
                    id: "doc.runbook".to_string(),
                    kind: Kind::Doc,
                    subkind: None,
                    title: "Runbook".to_string(),
                    summary: "Operational playbook.".to_string(),
                    aliases: Vec::new(),
                    tags: Vec::new(),
                    query_examples: Vec::new(),
                    source_files: vec!["runbook.md".to_string()],
                    span: None,
                    partition: None,
                },
                Node {
                    id: "doc.report".to_string(),
                    kind: Kind::Doc,
                    subkind: None,
                    title: "Daily Report".to_string(),
                    summary: "Manager report.".to_string(),
                    aliases: Vec::new(),
                    tags: Vec::new(),
                    query_examples: Vec::new(),
                    source_files: vec!["report.md".to_string()],
                    span: None,
                    partition: None,
                },
            ],
            edges: vec![Edge {
                from: "doc.runbook".to_string(),
                to: "doc.report".to_string(),
                relation: "emits".to_string(),
                evidence: "frontmatter".to_string(),
                basis: EdgeBasis::Resolved,
                ..Default::default()
            }],
            relation_profiles: [(
                "emits".to_string(),
                RelationProfile::new("zorbles", "zorbeled by", 30),
            )]
            .into_iter()
            .collect(),
        };

        let hits = ground(&graph, "zorbles", 5);

        assert_eq!(hits.first().map(|hit| hit.id.as_str()), Some("doc.runbook"));
    }

    #[test]
    fn a_distinctive_name_anchors_confidence_but_a_common_term_does_not() {
        // Band conservatism on common vocabulary: a RARE query term that names a node should anchor
        // it even when common co-terms dilute id_coverage — but the common terms alone must NOT.
        let doc = |id: &str, title: &str, summary: &str| Node {
            id: id.to_string(),
            kind: Kind::Doc,
            subkind: None,
            title: title.to_string(),
            summary: summary.to_string(),
            aliases: Vec::new(),
            tags: Vec::new(),
            query_examples: Vec::new(),
            source_files: vec![format!("{id}.md")],
            span: None,
            partition: None,
        };
        // "carbonara" names one doc (rare → high IDF); "egg" is shared by many (common → low IDF).
        let mut nodes = vec![doc(
            "doc.carbonara",
            "Carbonara",
            "A roman egg pasta with pecorino and guanciale.",
        )];
        for i in 0..8 {
            nodes.push(doc(
                &format!("doc.other{i}"),
                &format!("Recipe {i}"),
                "A dish that uses egg among its ingredients.",
            ));
        }
        let graph = Graph {
            nodes,
            edges: Vec::new(),
            relation_profiles: Default::default(),
        };

        // Distinctive name + common co-term: the distinctive term anchors, so the hit is NOT capped
        // to the body-only Weak/Fallback floor.
        let hits = ground(&graph, "carbonara egg", 5);
        let carbonara = hits.iter().find(|h| h.id == "doc.carbonara").unwrap();
        assert!(
            matches!(
                carbonara.confidence,
                Confidence::Exact | Confidence::Strong | Confidence::Ambiguous
            ),
            "a distinctive name must anchor confidence above Weak, got {:?}",
            carbonara.confidence
        );

        // A common term ALONE must not anchor — "egg" names nothing distinctively.
        let common = ground(&graph, "egg", 5);
        assert!(
            common
                .first()
                .is_none_or(|h| matches!(h.confidence, Confidence::Weak | Confidence::Fallback)),
            "a common term alone must not earn a confident band: {:?}",
            common.first().map(|h| h.confidence)
        );
    }

    #[test]
    fn relation_neighbour_does_not_outrank_an_exact_query_example() {
        // Dogfood regression: "which embedding model should I use" is a verbatim query_example on
        // doc.embeddings (strong identity). doc.evals only DEPENDS ON embeddings, so the topic
        // terms land in its relation surface — but a relation-context match on a zero-identity
        // neighbour must NOT outrank the doc that IS the answer. (Root cause: the ubiquitous verb
        // "use" was a relation-intent trigger, firing the +12/term relation boost on a topical
        // query and inflating the neighbour above the identity hit.)
        let doc = |id: &str, title: &str, summary: &str, qe: &[&str]| Node {
            id: id.to_string(),
            kind: Kind::Doc,
            subkind: None,
            title: title.to_string(),
            summary: summary.to_string(),
            aliases: Vec::new(),
            tags: Vec::new(),
            query_examples: qe.iter().map(|s| s.to_string()).collect(),
            source_files: vec![format!("{id}.md")],
            span: None,
            partition: None,
        };
        let graph = Graph {
            nodes: vec![
                doc(
                    "doc.embeddings",
                    "Choosing an Embedding Model",
                    "Pick by recall and latency.",
                    &["which embedding model should I use"],
                ),
                doc("doc.evals", "Writing Evals", "Build a golden set.", &[]),
            ],
            edges: vec![Edge {
                from: "doc.evals".to_string(),
                to: "doc.embeddings".to_string(),
                relation: "depends_on".to_string(),
                evidence: "frontmatter".to_string(),
                basis: EdgeBasis::Resolved,
                ..Default::default()
            }],
            relation_profiles: [(
                "depends_on".to_string(),
                RelationProfile::new("depends on", "required by", 30),
            )]
            .into_iter()
            .collect(),
        };

        let hits = ground(&graph, "which embedding model should I use", 5);
        assert_eq!(
            hits.first().map(|hit| hit.id.as_str()),
            Some("doc.embeddings"),
            "the doc with the verbatim query_example must outrank its relation neighbour"
        );

        // The direct fix: the ubiquitous verb "use" is NOT a relation-intent trigger (unlike the
        // specific technical verbs), so a topical "which X should I use" query does not fire the
        // relation-context boost that caused the inversion.
        assert!(!is_relation_query_term("use"));
        assert!(is_relation_query_term("depend"));
        assert!(is_relation_query_term("implement"));
    }

    #[test]
    fn exact_query_example_lifts_confidence_to_strong() {
        let graph = Graph {
            nodes: vec![Node {
                id: "doc.dlq".to_string(),
                kind: Kind::Doc,
                subkind: None,
                title: "Dead Letter Handling".to_string(),
                summary: String::new(),
                aliases: vec!["dead letter".to_string()],
                tags: Vec::new(),
                query_examples: vec!["what happens to messages that keep failing".to_string()],
                source_files: vec!["dlq.md".to_string()],
                span: None,
                partition: None,
            }],
            edges: Vec::new(),
            ..Default::default()
        };

        let hits = ground(&graph, "what happens to messages that keep failing", 1);

        assert_eq!(hits.first().map(|hit| hit.id.as_str()), Some("doc.dlq"));
        assert_eq!(
            hits.first().map(|hit| hit.confidence),
            Some(Confidence::Strong)
        );
        assert!(
            hits.first()
                .is_some_and(|hit| hit.why.iter().any(|why| why == "exact query_example match"))
        );
    }

    fn code_node(id: &str, kind: Kind, title: &str, summary: &str) -> Node {
        Node {
            id: id.to_string(),
            kind,
            subkind: None,
            title: title.to_string(),
            summary: summary.to_string(),
            aliases: Vec::new(),
            tags: Vec::new(),
            query_examples: Vec::new(),
            source_files: vec![format!("{}.rs", title.to_ascii_lowercase())],
            span: None,
            partition: None,
        }
    }
}