kimetsu_brain/

context.rs

#[path = "delivery.rs"]
pub mod delivery;

use std::cmp::Ordering;
use std::collections::HashMap;

use kimetsu_core::config::{BrokerWeights, StageWeights};
use kimetsu_core::memory::MemoryScope;
use kimetsu_core::{KimetsuResult, ids::new_id};
use rusqlite::{Connection, OptionalExtension, params};
use serde::{Deserialize, Serialize};

// -----------------------------------------------------------------------
// E3: task-kind classification + adaptive retrieval routing
// -----------------------------------------------------------------------

/// The inferred kind of the current coding task. Classified once at
/// intake from the task description string — deterministic keyword
/// scan, no model call, zero allocation-heavy work.
///
/// `Feature` is the NEUTRAL default: it does not change weights or
/// prefer_roles at all, so every existing `..Default::default()`
/// construction produces exactly the prior retrieval behaviour.
///
/// Precedence when multiple keyword sets match:
///   Debug > Investigation > Refactor > Docs > Feature
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TaskKind {
    /// Neutral / catch-all (add, implement, build, create, support, …).
    /// Must NOT alter weights or prefer_roles — keeps existing tests green.
    #[default]
    Feature,
    /// fix, bug, error, fail, crash, panic, regression, broken, debug,
    /// stack trace, exception — up freshness, prefer failure_pattern.
    Debug,
    /// refactor, rename, cleanup, restructure, simplify, extract,
    /// deduplicate, reorganize — up scope, prefer convention.
    Refactor,
    /// document, readme, changelog, comment, docstring, docs, tutorial,
    /// guide — near-neutral mild adjustments.
    Docs,
    /// investigate, analyze, understand, why, explore, find out,
    /// root cause, audit, trace — up relevance, prefer fact + preference.
    Investigation,
}

/// Classify a task description string into a [`TaskKind`] using a
/// deterministic keyword scan over the lowercased text. No model call.
///
/// Precedence (highest wins when multiple sets match):
///   Debug > Investigation > Refactor > Docs > Feature
pub fn classify_task(task: &str) -> TaskKind {
    let lower = task.to_ascii_lowercase();

    // Debug keywords (highest priority)
    const DEBUG_KW: &[&str] = &[
        "fix",
        "bug",
        "error",
        "fail",
        "crash",
        "panic",
        "regression",
        "broken",
        "debug",
        "stack trace",
        "exception",
    ];
    if DEBUG_KW.iter().any(|kw| lower.contains(kw)) {
        return TaskKind::Debug;
    }

    // Investigation keywords
    const INVESTIGATE_KW: &[&str] = &[
        "investigate",
        "analyze",
        "understand",
        " why ",
        "explore",
        "find out",
        "root cause",
        "audit",
        "trace",
    ];
    if INVESTIGATE_KW.iter().any(|kw| lower.contains(kw)) {
        return TaskKind::Investigation;
    }

    // Refactor keywords
    const REFACTOR_KW: &[&str] = &[
        "refactor",
        "rename",
        "cleanup",
        "clean up",
        "restructure",
        "simplify",
        "extract",
        "deduplicate",
        "reorganize",
    ];
    if REFACTOR_KW.iter().any(|kw| lower.contains(kw)) {
        return TaskKind::Refactor;
    }

    // Docs keywords
    const DOCS_KW: &[&str] = &[
        "document",
        "readme",
        "changelog",
        "comment",
        "docstring",
        "docs",
        "tutorial",
        "guide",
    ];
    if DOCS_KW.iter().any(|kw| lower.contains(kw)) {
        return TaskKind::Docs;
    }

    // Default: Feature (neutral)
    TaskKind::Feature
}

/// Compose task-kind weight biases on top of the stage weights.
///
/// For `Feature`, returns `base` UNCHANGED — this is the neutrality
/// guarantee that keeps all existing retrieval tests green.
///
/// For other kinds, one component is multiplied by a bias factor and
/// the result is renormalized so the four weights still sum to the same
/// total as `base`, preserving overall scoring magnitude (just the mix
/// changes).
///
/// Bias factors (applied before renorm):
/// - Debug       → freshness × 1.6  (recent failures matter most)
/// - Refactor    → scope × 1.6      (project/repo conventions matter most)
/// - Investigation → relevance × 1.4 (broad fact/preference recall)
/// - Docs        → mild (confidence × 1.15, near-neutral)
fn weights_for_task_kind(base: StageWeights, kind: TaskKind) -> StageWeights {
    match kind {
        TaskKind::Feature => base,
        TaskKind::Debug => renorm(StageWeights {
            freshness: base.freshness * 1.6,
            ..base
        }),
        TaskKind::Refactor => renorm(StageWeights {
            scope: base.scope * 1.6,
            ..base
        }),
        TaskKind::Investigation => renorm(StageWeights {
            relevance: base.relevance * 1.4,
            ..base
        }),
        TaskKind::Docs => renorm(StageWeights {
            confidence: base.confidence * 1.15,
            ..base
        }),
    }
}

/// Renormalize `StageWeights` so the four components sum to the same
/// total as before the bias was applied. This preserves scoring
/// magnitude — only the mix changes.
fn renorm(w: StageWeights) -> StageWeights {
    let sum = w.relevance + w.confidence + w.freshness + w.scope;
    if sum <= f32::EPSILON {
        return w;
    }
    // The original sum (before any bias) isn't available here; instead
    // we scale to 1.0 and then the absolute scores are comparable
    // because normalize_and_score already places components in [0,1].
    // NOTE: the stage weights themselves don't need to sum to 1.0 —
    // the existing defaults (0.5+0.2+0.2+0.1=1.0) do, but the
    // renormalization target should be the unbiased sum so we don't
    // change the overall scale. Since we only modify ONE component by a
    // small factor, we scale back to 1.0 (the natural target).
    StageWeights {
        relevance: w.relevance / sum,
        confidence: w.confidence / sum,
        freshness: w.freshness / sum,
        scope: w.scope / sum,
    }
}

/// Return the additional `prefer_roles` hints implied by `kind`.
///
/// These are MERGED with any caller-supplied `prefer_roles` (not
/// clobbered), so the task-kind bias is additive.
/// For `Feature`, returns an empty slice — zero effect on existing behaviour.
fn task_kind_prefer_roles(kind: TaskKind) -> &'static [&'static str] {
    match kind {
        TaskKind::Feature => &[],
        TaskKind::Debug => &["failure_pattern"],
        TaskKind::Refactor => &["convention"],
        TaskKind::Investigation => &["fact", "preference"],
        TaskKind::Docs => &["convention"],
    }
}
use time::OffsetDateTime;

use crate::embeddings::{
    self, DEFAULT_HYBRID_ALPHA, Embedder, cosine_similarity, decode_embedding,
};

/// v0.4.2: a pre-computed query embedding paired with the producing
/// model's id. Threaded down into [`memory_candidates`] so each row
/// can decide whether to contribute a cosine term (only when the
/// row's `embedding_model` matches the active query's `model_id`).
///
/// S5.1: `pub(crate)` so `backend.rs` can name the type in the
/// `RetrievalBackend` trait signature without exposing it outside the crate.
#[derive(Debug, Clone)]
pub(crate) struct QueryEmbedding {
    pub(crate) vector: Vec<f32>,
    pub(crate) model_id: String,
}

impl QueryEmbedding {
    fn from_embedder(embedder: &dyn Embedder, query: &str) -> Option<Self> {
        if embedder.is_noop() {
            return None;
        }
        match embedder.embed(query) {
            Ok(v) if v.len() == embedder.dim() => Some(Self {
                vector: v,
                model_id: embedder.model_id().to_string(),
            }),
            // NotImplemented / dim-mismatch / load failure → silently
            // skip the cosine blend. v0.4.2 surfaces no warning here
            // by design — the broker stays usable on best-effort
            // semantic retrieval.
            _ => None,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContextCapsule {
    pub id: String,
    pub kind: String,
    pub summary: String,
    pub token_estimate: u32,
    pub expansion_handle: String,
    pub provenance: Vec<ProvenanceRef>,
    pub confidence: f32,
    pub freshness: f32,
    pub relevance: f32,
    pub scope_weight: f32,
    pub score: f32,
    /// v2.7: set by [`apply_supersession_penalty`] when a newer near-duplicate
    /// sibling was also a candidate. Carried on the capsule so the penalty can
    /// be REAPPLIED after cross-encoder reranking — the reranker scores pure
    /// query relevance and would otherwise resurrect the older twin whenever
    /// the query's wording happens to match it better (measured: resolution
    /// 0.58 → 0.36 when reranking landed without this flag).
    #[serde(default)]
    pub superseded_hint: bool,
    /// Legacy serialized usefulness sign; bounded when reranking old capsules.
    #[serde(default)]
    pub rerank_policy_tier: i8,
    /// Claim identity read in the same SQLite snapshot as the hydrated text.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub claim_revision: Option<String>,
    /// Structured evidence read alongside this capsule text and revision.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub facts: Vec<crate::fact_store::StoredFact>,
    /// Decayed usefulness multiplier and provenance discount carried to reranking.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rerank_usefulness: Option<f32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rerank_trust: Option<f32>,
}

/// Revision bindings for the actual delivered capsules. Conflicting versions of
/// one ID are omitted because the legacy event map can represent only one claim.
pub fn memory_revision_bindings(
    capsules: &[ContextCapsule],
) -> std::collections::BTreeMap<String, String> {
    let mut bindings = std::collections::BTreeMap::new();
    let mut ambiguous = std::collections::HashSet::new();
    for c in capsules {
        if let (Some(id), Some(revision)) = (
            c.expansion_handle.strip_prefix("memory:"),
            c.claim_revision.as_ref(),
        ) {
            if bindings.get(id).is_some_and(|old| old != revision) {
                ambiguous.insert(id.to_string());
            }
            bindings.insert(id.to_string(), revision.clone());
        }
    }
    for id in ambiguous {
        bindings.remove(&id);
    }
    bindings
}

impl ContextCapsule {
    /// v1.0.0: build a render-only capsule from daemon wire data. Only the
    /// fields the hook renders (`summary`, `kind`, `score`) are meaningful;
    /// the rest are zeroed — this capsule is never re-scored or expanded.
    pub fn wire_minimal(summary: String, kind: String, score: f32) -> Self {
        Self {
            id: String::new(),
            kind,
            summary,
            token_estimate: 0,
            expansion_handle: String::new(),
            provenance: Vec::new(),
            confidence: 0.0,
            freshness: 0.0,
            relevance: 0.0,
            scope_weight: 0.0,
            score,
            superseded_hint: false,
            rerank_policy_tier: 0,
            claim_revision: None,
            facts: vec![],
            rerank_usefulness: None,
            rerank_trust: None,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProvenanceRef {
    pub source: String,
    pub id: String,
    pub excerpt: Option<String>,
}

#[derive(Debug, Clone, Default)]
pub struct ContextRequest {
    /// Hydrate structured evidence only for consumers that explicitly request it.
    pub include_fact_evidence: bool,
    /// Defer intermediate budgeting to a final evidence-aware renderer; requires a bounded pool.
    pub defer_fact_budget: bool,
    pub stage: String,
    pub query: String,
    pub budget_tokens: u32,
    /// v2.6: per-request override for how the lexical and semantic rankings
    /// are merged (`"linear"` / `"rrf"`; see [`crate::fusion`]).
    ///
    /// Empty (the default) means "use `[broker] fusion`". This exists so
    /// `kimetsu brain tune` can sweep the two rules against one corpus in one
    /// process — the reason the shipped default is still `linear` is that
    /// nothing had measured the alternative on a real brain.
    pub fusion: String,
    /// v2.6: per-request override for how `raw_relevance` is normalized into
    /// the `relevance` term (`"per_kind"` / `"global"`; see
    /// [`Normalization`]).
    ///
    /// Empty (the default) means "use `[broker] normalization`". Exists for
    /// the same reason `fusion` does: the alternative had to be measurable on
    /// one corpus in one process before it could be argued for.
    pub normalization: String,
    /// v0.6: domain-hint tags. Capsules whose text or kind contains any
    /// of these strings receive a 1.4× score boost, pushing on-domain
    /// capsules above the `min_score` threshold when they would otherwise
    /// be filtered out.
    pub tags: Vec<String>,
    /// v0.6: minimum composite score for inclusion. When > 0.0 and the
    /// top-scoring capsule falls below this threshold, `ContextBundle`
    /// is returned with `skipped: true` and an empty capsule list —
    /// zero tokens injected. 0.0 (default) disables the check.
    pub min_score: f32,
    /// v0.6: hard cap on returned capsules regardless of token budget.
    /// 0 = no cap (budget-only limit, prior behaviour).
    pub max_capsules: usize,
    /// v0.6: role-preference boost. Capsules whose `kind` matches one
    /// of these strings receive an additional 1.3× multiplier after the
    /// tag boost (e.g. `["semantic_operator", "anti_pattern"]` for bench).
    pub prefer_roles: Vec<String>,
    /// v0.8: hard kind filter applied BEFORE scoring + capping. When
    /// non-empty, only candidates whose capsule `kind` is in this list
    /// survive — so a higher-ranked repo file or off-kind memory can't
    /// consume a (often single) slot. Used by the proactive engine to
    /// restrict recall to actionable kinds (failure_pattern, command,
    /// convention). Empty (default) keeps all kinds, prior behaviour.
    pub kinds: Vec<String>,
    /// D1e: absolute cosine-similarity floor. On embeddings builds,
    /// memory candidates whose cosine to the query is below this
    /// threshold are dropped before budgeting. 0.0 (default) disables
    /// the floor — matches pre-D1e behaviour. Repo-file and manifest
    /// candidates are unaffected (they have no cosine score). Populated
    /// from `BrokerSection.min_semantic_score` by the pipeline; callers
    /// that don't set it get the prior behaviour automatically.
    pub min_semantic_score: f32,
    /// Explicit public override: None preserves legacy zero=inherited; Some(0)
    /// disables, Some(-1) selects model auto, Some(positive) sets a floor.
    pub min_semantic_score_override: Option<f32>,
    /// v1.0.0: absolute *lexical* relevance floor for memory candidates,
    /// as the fraction of the query's IDF-weighted discriminating power a
    /// memory must cover. Unlike `min_semantic_score` this needs no query
    /// embedding, so it protects the FTS-only hook path. When > 0.0, memory
    /// candidates below the floor are dropped BEFORE scoring (so they don't
    /// even set the per-kind normalization max). Repo-file/manifest
    /// candidates are unaffected. 0.0 (default) disables it — every existing
    /// `..Default::default()` construction is unchanged. Populated from
    /// `BrokerSection.min_lexical_coverage` by the pipeline.
    pub min_lexical_coverage: f32,
    /// Some(0) explicitly disables the lexical floor; None inherits legacy behavior.
    pub min_lexical_coverage_override: Option<f32>,
    /// E3: inferred kind of the current task. Defaults to `Feature`
    /// (the neutral kind) so every existing `..Default::default()`
    /// construction is unchanged — Feature does NOT alter weights or
    /// prefer_roles. Set by the pipeline via `classify_task` at intake.
    pub task_kind: TaskKind,
    /// v2.7: ABSOLUTE abstention floor. `min_score` above compares against the
    /// normalized composite, whose top candidate always carries relevance 1.0
    /// — it can rank candidates but cannot express "nothing here is genuinely
    /// relevant", so it never abstains on a plausible-but-wrong corpus (the
    /// workflow benchmark measured false-injection 1.00 at a 60-memory brain).
    /// This floor gates on absolute evidence instead: the best raw cosine any
    /// memory candidate achieved. When > 0.0 and no cosine-backed memory
    /// candidate clears it — and the bundle would contain only memory capsules
    /// — the retrieval returns `skipped: true` with zero tokens injected.
    /// Lexical-only and cross-model candidates are unmeasured on this scale and
    /// therefore exempt. Repo-file/manifest capsules also suppress the gate: an
    /// FTS hit on real repo content is its own evidence the bundle is useful.
    /// 0.0 (default) disables the gate. Populated from
    /// `BrokerSection.abstain_min_score` by the pipeline.
    pub abstain_evidence: f32,
    /// Some(0) disables abstention; Some(-1) uses model auto; None inherits.
    pub abstain_evidence_override: Option<f32>,
}

#[derive(Debug, Clone)]
pub struct ContextBundle {
    pub stage: String,
    pub budget_tokens: u32,
    pub used_tokens: u32,
    pub capsules: Vec<ContextCapsule>,
    pub excluded: Vec<ContextCapsule>,
    /// v0.6: true when the top capsule score was below `min_score`.
    /// All capsules are empty; no tokens were injected.
    pub skipped: bool,
    /// v0.6: best composite score observed before the skip check.
    /// Useful for diagnostics ("why was the brain silent?").
    pub top_score: f32,
    /// v2.7: best ABSOLUTE cosine evidence any memory candidate achieved.
    /// Unlike `top_score` this is not normalized, so "0.42" means the same
    /// thing on a 3-memory brain and a 3000-memory brain. `-1.0` means no
    /// comparable cosine was available (lean builds or cross-model rows), so
    /// the cosine-calibrated gate has no verdict. Exposed for diagnostics and
    /// threshold sweeps.
    pub top_abs_evidence: f32,
    /// v2.6: what fraction of the query's discriminating power the returned
    /// capsules cover, *collectively*, in `[0, 1]`.
    ///
    /// Kimetsu already abstains at the bundle level — nothing above
    /// `min_score` means an empty bundle and zero tokens. What it never did is
    /// say anything about a bundle it *does* return, so a reader handed three
    /// capsules that touch half the question has no way to tell that from
    /// three that answer it, and confabulates the rest. That is what BEAM's
    /// abstention track measures, and where Kimetsu scores worst (45% / 30%).
    ///
    /// IDF-weighted against the corpus, so a query term present in every
    /// memory contributes nothing and a rare one dominates — the same weighting
    /// the per-memory lexical floor uses, applied to the bundle as a whole.
    /// 1.0 when there is no discriminating term to measure against.
    pub evidence_coverage: f32,
    /// v2.6: the discriminating query terms *no* returned capsule mentions.
    ///
    /// The actionable half of `evidence_coverage`: a reader can be told
    /// precisely what memory does not know about, rather than being handed a
    /// number. Empty when coverage is complete or unmeasurable.
    pub uncovered_terms: Vec<String>,
    /// v2.6: true when the query asked about order and the capsules were
    /// re-rendered chronologically, oldest first, each carrying its date.
    ///
    /// The reader needs to be told, or a time-ordered bundle looks like a
    /// relevance-ranked one whose ranking has gone wrong. See
    /// [`crate::ordering`] for why ordering is rendered rather than retrieved.
    pub chronological: bool,
    /// Conflicts observed in eligible evidence before delivery trimming.
    pub known_fact_conflicts: Vec<String>,
}

/// Discriminating weight per query token, for *bundle* coverage.
///
/// Deliberately not [`corpus_token_idf`]. That one zeroes a token the corpus
/// has never seen (`df == 0`), because for the per-memory floor an
/// out-of-corpus word would sink every candidate — the on-topic memory that
/// matches the rare in-corpus word would be wrongly pruned.
///
/// For coverage the same fact means the opposite. A query term that appears in
/// **no** memory is the strongest possible evidence that memory does not cover
/// this question, which is precisely what the reader needs to be told. Zeroing
/// it would make "how do I checkpoint the WAL during a Kubernetes rollout"
/// report full coverage on the strength of the WAL half alone — the exact
/// confabulation this is meant to prevent.
///
/// So `df == 0` gets the maximal weight, and only `df == N` (present in every
/// memory, e.g. the project name) is zeroed.
fn coverage_token_idf(conn: &Connection, tokens: &[String]) -> KimetsuResult<HashMap<String, f32>> {
    token_idf(conn, tokens, false)
}

/// Render the partial-evidence warning for a bundle, if it needs one.
///
/// The point is to let a reader abstain on Kimetsu's advice rather than
/// confabulate from partial evidence. Naming the missing terms is what makes
/// that actionable — "memory does not cover X" is a fact the reader can act on,
/// where a coverage number is not.
///
/// Returns `None` when coverage is adequate, so a complete bundle costs nothing.
pub fn partial_evidence_notice(bundle: &ContextBundle) -> Option<String> {
    if bundle.skipped || bundle.capsules.is_empty() {
        return None; // an empty bundle already says everything it can
    }
    if bundle.evidence_coverage > PARTIAL_EVIDENCE_COVERAGE || bundle.uncovered_terms.is_empty() {
        return None;
    }
    // Cap the list: naming twenty terms is noise, and the first few are the
    // highest-IDF ones anyway (content_tokens preserves query order, and the
    // uncovered list is filtered from it).
    const MAX_NAMED: usize = 6;
    let named: Vec<&str> = bundle
        .uncovered_terms
        .iter()
        .take(MAX_NAMED)
        .map(String::as_str)
        .collect();
    let more = bundle.uncovered_terms.len().saturating_sub(named.len());
    let suffix = if more > 0 {
        format!(" (and {more} more)")
    } else {
        String::new()
    };
    Some(format!(
        "Partial memory: nothing above covers {}{}. Treat the rest as unknown \
         rather than inferring it.",
        named.join(", "),
        suffix
    ))
}

/// Coverage at or below which a bundle is worth flagging as partial.
///
/// Chosen to mirror `min_lexical_coverage`'s default (0.5): a bundle that
/// collectively covers less of the query than a single memory would need to
/// survive the per-memory floor is, by the system's own standard, thin.
pub const PARTIAL_EVIDENCE_COVERAGE: f32 = 0.5;

/// Measure how much of `query`'s discriminating power `capsules` collectively
/// cover, and which terms none of them mention.
///
/// Deliberately computed over the *union* of the capsules rather than the best
/// one: the question is whether the bundle answers the query, not whether any
/// single memory does.
pub(crate) fn evidence_coverage(
    conn: &Connection,
    query: &str,
    capsules: &[ContextCapsule],
) -> (f32, Vec<String>) {
    let content = content_tokens(query);
    if content.is_empty() {
        return (1.0, Vec::new());
    }
    let Ok(idf) = coverage_token_idf(conn, &content) else {
        return (1.0, Vec::new());
    };
    // Everything the bundle says, lowercased once.
    let haystack = capsules
        .iter()
        .map(|c| c.summary.to_ascii_lowercase())
        .collect::<Vec<_>>()
        .join(" ");

    let mut total = 0.0f32;
    let mut hit = 0.0f32;
    let mut uncovered = Vec::new();
    for token in &content {
        let weight = idf.get(token).copied().unwrap_or(0.0);
        if weight <= 0.0 {
            continue; // corpus-ubiquitous or out-of-corpus: no signal either way
        }
        total += weight;
        if haystack.contains(token.as_str()) {
            hit += weight;
        } else {
            uncovered.push(token.clone());
        }
    }
    if total <= f32::EPSILON {
        // No discriminating term to measure against — claiming a gap here
        // would make every vague query look like a memory failure.
        return (1.0, Vec::new());
    }
    (hit / total, uncovered)
}

/// S5.1: a single memory candidate produced by candidate generation and
/// consumed by the broker (scoring, floors, rerank).
///
/// `pub(crate)` so `backend.rs` can name the type in the `RetrievalBackend`
/// trait signature without exposing it outside the crate.
#[derive(Debug, Clone)]
pub(crate) struct Candidate {
    pub(crate) capsule: ContextCapsule,
    pub(crate) raw_relevance: f32,
    /// D1e: the row's embedding vector, present when the row's
    /// `embedding_model` matches the active query embedder's id.
    /// `None` for repo-file/manifest candidates and for memory rows
    /// whose model differs from the active embedder (cross-model
    /// rows). Used by the candidate-stage embedding-MMR pass.
    pub(crate) embedding: Option<Vec<f32>>,
    /// D1e: raw cosine similarity between this candidate and the
    /// query embedding. Present when `embedding` is `Some`. Used for
    /// the absolute semantic relevance floor (min_semantic_score).
    pub(crate) cosine: Option<f32>,
    /// v2.6: the memory's RFC 3339 creation time, carried so the bundle can be
    /// re-rendered in time order when the query asks about sequence (see
    /// [`crate::ordering`]). `None` for repo files and manifests, which have no
    /// position in the memory timeline.
    pub(crate) created_at: Option<String>,
}

pub fn retrieve_context(
    conn: &Connection,
    repo_root: &str,
    weights: &BrokerWeights,
    request: ContextRequest,
) -> KimetsuResult<ContextBundle> {
    retrieve_context_multi(conn, repo_root, weights, request, &[])
}

/// v0.4.1: multi-conn variant. `extra_memory_conns` is searched for
/// memory candidates only (repo files + manifests stay project-local).
/// The candidate stream is concatenated BEFORE normalization so the
/// blended set is normalized together — keeping a user-brain capsule
/// and a project-brain capsule comparable on the same `raw_relevance`
/// scale.
///
/// Today `extra_memory_conns` carries at most one entry (the user
/// brain at `~/.kimetsu/brain.db`); the slice shape leaves room for
/// future scope tiers (team brain, org brain) without breaking the
/// signature.
///
/// v0.4.2: uses [`embeddings::open_default_embedder`] for the cosine
/// term. Pre-v0.4.3 the default is `NoopEmbedder`, which short-
/// circuits the cosine path so retrieval stays FTS-only — exact
/// v0.4.1 behavior. v0.4.3 swaps the default to a real embedder.
pub fn retrieve_context_multi(
    conn: &Connection,
    repo_root: &str,
    weights: &BrokerWeights,
    request: ContextRequest,
    extra_memory_conns: &[&Connection],
) -> KimetsuResult<ContextBundle> {
    let embedder = embeddings::open_default_embedder();
    retrieve_context_with_embedder(
        conn,
        repo_root,
        weights,
        request,
        extra_memory_conns,
        embedder,
    )
}

/// v0.4.2: explicit-embedder variant. Lets tests inject `StubEmbedder`
/// or any other [`Embedder`] without going through
/// [`embeddings::open_default_embedder`]. v0.4.3 callers (chat REPL,
/// MCP server) can also use this directly to hold one embedder
/// instance for the lifetime of a session instead of paying the
/// model-load cost on every retrieval.
///
/// S5.1: delegates to [`retrieve_context_with_embedder_and_backend`] with
/// the default [`crate::backend::FlatBackend`]. All existing call sites
/// (including the full test suite) are unchanged and continue to get exactly
/// the pre-S5.1 FTS + ANN behaviour.
pub fn retrieve_context_with_embedder(
    conn: &Connection,
    repo_root: &str,
    weights: &BrokerWeights,
    request: ContextRequest,
    extra_memory_conns: &[&Connection],
    embedder: &dyn Embedder,
) -> KimetsuResult<ContextBundle> {
    retrieve_context_with_embedder_and_backend(
        conn,
        repo_root,
        weights,
        request,
        extra_memory_conns,
        embedder,
        &crate::backend::FlatBackend {
            fusion: crate::fusion::Fusion::Linear,
        },
    )
}

/// S5.1: backend-aware variant of [`retrieve_context_with_embedder`].
///
/// Identical to `retrieve_context_with_embedder` except that the memory
/// candidate step is delegated to `backend.memory_candidates()` instead of
/// the hard-coded [`memory_candidates`] call. The broker (lexical/semantic
/// floors, scoring, MMR, compression, budgeting) runs ABOVE the backend and
/// is backend-agnostic.
///
/// [`BrainSession`] methods call this variant so the `[storage] backend`
/// config field takes effect. Tests that call `retrieve_context_with_embedder`
/// directly still use [`crate::backend::FlatBackend`] implicitly — zero
/// behaviour change.
pub(crate) fn retrieve_context_with_embedder_and_backend(
    conn: &Connection,
    repo_root: &str,
    weights: &BrokerWeights,
    request: ContextRequest,
    extra_memory_conns: &[&Connection],
    embedder: &dyn Embedder,
    backend: &dyn crate::backend::RetrievalBackend,
) -> KimetsuResult<ContextBundle> {
    let query_embedding = QueryEmbedding::from_embedder(embedder, &request.query);
    let half_life_days = weights.decay_half_life_days;
    let mut candidates = Vec::new();
    candidates.extend(backend.memory_candidates(
        conn,
        &request.query,
        query_embedding.as_ref(),
        half_life_days,
        request.include_fact_evidence,
    )?);
    for extra in extra_memory_conns {
        candidates.extend(backend.memory_candidates(
            extra,
            &request.query,
            query_embedding.as_ref(),
            half_life_days,
            request.include_fact_evidence,
        )?);
    }
    // v2.5.2 consolidation v1: bounded query-association routing boost —
    // memories that repeatedly answered SIMILAR past queries (per the
    // citation-derived query_routes table) gain up to ROUTING_BOOST_CAP
    // relevance from a fixed per-retrieval budget. Applied to memory
    // candidates only, before file/manifest candidates join the pool.
    crate::reinforce::apply_query_routing(
        conn,
        &request.query,
        query_embedding.as_ref(),
        &mut candidates,
    );

    candidates.extend(repo_file_candidates(conn, repo_root, &request.query, 30)?);
    candidates.extend(manifest_candidates(conn, repo_root, &request.query)?);

    // v0.8: proactive kind filter — restrict to actionable kinds BEFORE
    // scoring + capping so a higher-ranked repo file or off-kind memory
    // can't take the proactive slot and get filtered out afterwards.
    // Memory capsules carry the generic `kind: "memory"` and encode the
    // real memory kind in the summary prefix ("scope:kind - text"), so
    // match against that for memories.
    if !request.kinds.is_empty() {
        candidates.retain(|c| {
            request
                .kinds
                .iter()
                .any(|k| capsule_matches_kind(&c.capsule, k))
        });
    }

    // v1.0.0: absolute LEXICAL relevance floor. The FTS-only hook path has
    // no cosine, so the `min_semantic_score` floor below can't protect it —
    // a broad conceptual query whose only matching tokens are corpus-
    // ubiquitous (e.g. the project name) would otherwise surface unrelated
    // memories, which per-kind normalization later promotes to relevance=1.0
    // regardless of how weak the match is.
    //
    // We compute an IDF-weighted coverage in [0,1] over the query's CONTENT
    // tokens (stopwords removed; ubiquitous tokens carry ~0 IDF so they don't
    // drive coverage) and drop a memory candidate when its coverage is below
    // the floor AND it has no semantic support. Applied BEFORE scoring so
    // pruned rows don't even set the per-kind normalization max. Only memory
    // candidates are floored — repo_file/manifest capsules pass through (an
    // FTS match on file content is itself a relevance signal, and overview
    // queries *want* the README). Inert when the floor is 0.0 or the query
    // has no discriminating (non-ubiquitous) content token.
    if request.min_lexical_coverage > 0.0 {
        let content = content_tokens(&request.query);
        if !content.is_empty() {
            let idf = corpus_token_idf(conn, &content)?;
            let total_idf: f32 = content
                .iter()
                .map(|t| idf.get(t).copied().unwrap_or(0.0))
                .sum();
            // Skip the floor when no content token is discriminating — every
            // token is corpus-ubiquitous, so we have no signal to floor on.
            if total_idf > f32::EPSILON {
                candidates.retain(|c| {
                    if c.capsule.kind != "memory" {
                        return true; // repo_file / manifest pass through
                    }
                    // Semantic support keeps a lexically-thin but on-topic
                    // memory on embeddings builds (cosine is None on the hook).
                    if c.cosine.is_some_and(|cos| cos >= SEMANTIC_KEEP_COSINE) {
                        return true;
                    }
                    weighted_coverage(&content, &idf, &c.capsule.summary)
                        >= request.min_lexical_coverage
                });
            }
        }
    }

    // E3: compose task-kind weight bias over stage weights, then renormalize.
    // For Feature (default), weights_for_task_kind returns the base unchanged.
    let stage_weights = weights_for_stage(weights, &request.stage);
    let effective_weights = weights_for_task_kind(stage_weights, request.task_kind);
    normalize_and_score(
        &mut candidates,
        effective_weights,
        Normalization::from_config(&request.normalization),
    );

    // E3: merge task-kind prefer_role hints with caller-supplied prefer_roles.
    // For Feature the hints are empty so this is a no-op (neutral).
    let kind_role_hints = task_kind_prefer_roles(request.task_kind);
    let mut effective_prefer_roles: Vec<String> = request.prefer_roles.clone();
    for &hint in kind_role_hints {
        let hint_s = hint.to_string();
        if !effective_prefer_roles.contains(&hint_s) {
            effective_prefer_roles.push(hint_s);
        }
    }

    // v0.6: apply tag boost (1.4×) and role-preference boost (1.3×) after
    // normalisation so the multipliers operate on the [0,1]-normalised score
    // rather than the raw pre-normalisation values.
    //
    // E3: the role-preference check uses `capsule_matches_kind` so that
    // memory capsules (whose outer `kind` is always `"memory"`) are matched
    // against the real sub-kind embedded in their summary prefix
    // (`"scope:kind - text"`). This makes task-kind prefer_role hints
    // (e.g. "failure_pattern" for Debug) actually work for memory capsules.
    // For non-memory capsules (repo_file, manifest) the outer kind is checked
    // directly — same behaviour as before for caller-supplied prefer_roles.
    if !request.tags.is_empty() || !effective_prefer_roles.is_empty() {
        let tags_lc: Vec<String> = request
            .tags
            .iter()
            .map(|t| t.to_ascii_lowercase())
            .collect();
        for c in &mut candidates {
            let summary_lc = c.capsule.summary.to_ascii_lowercase();
            if !tags_lc.is_empty() && tags_lc.iter().any(|t| summary_lc.contains(t.as_str())) {
                c.capsule.score *= 1.4;
            }
            if !effective_prefer_roles.is_empty()
                && effective_prefer_roles.iter().any(|r| {
                    // For memory capsules: check the real sub-kind embedded in the
                    // summary prefix ("scope:kind - text") via capsule_matches_kind.
                    // This makes task-kind prefer_role hints work for memory capsules
                    // whose outer `kind` field is always the generic "memory" string.
                    // For non-memory capsules: fall back to the original substring
                    // check on the outer `kind` field (preserves v0.6 behaviour for
                    // caller-supplied prefer_roles like "semantic_operator").
                    if c.capsule.kind == "memory" {
                        capsule_matches_kind(&c.capsule, r.as_str())
                    } else {
                        c.capsule.kind.contains(r.as_str())
                    }
                })
            {
                c.capsule.score *= 1.3;
            }
        }
    }

    // v2.7: newer-wins supersession penalty. The workflow benchmark measured
    // that a cited incumbent buries its own replacement: the usefulness boost
    // feeds the relevance axis, freshness cannot distinguish memories written
    // minutes apart (30-day half-life), and nothing at ranking time knows two
    // candidates conflict. When two memory candidates are near-duplicates by
    // embedding cosine, the OLDER one is penalized so the newer statement of
    // the same topic wins the ordering regardless of its sibling's citations.
    // Inert on lean builds (no embeddings) and for genuinely distinct memories.
    apply_supersession_penalty(&mut candidates);

    // D1e-2: absolute semantic relevance floor. On embeddings builds
    // (query_embedding is Some), drop candidates whose cosine to the
    // query is strictly below min_semantic_score. This ensures a
    // genuinely-irrelevant corpus hits the zero-capsule skipped path
    // rather than surfacing its "best of a bad lot". Inert on lean
    // builds (query_embedding is None) or when floor is 0.0.
    //
    // Applied BEFORE the candidate→capsule conversion so irrelevant
    // rows don't consume budget or affect normalization.
    //
    // Only applied to memory candidates (those with cosine populated);
    // repo_file and manifest candidates have cosine=None and are
    // always passed through — they're matched by FTS which is already
    // a signal of relevance.
    if query_embedding.is_some() && request.min_semantic_score > 0.0 {
        candidates.retain(|c| {
            // Keep non-memory candidates (no cosine) and memory
            // candidates that cleared the floor.
            match c.cosine {
                Some(cos) => cos >= request.min_semantic_score,
                None => true,
            }
        });
    }

    // D1e-1: candidate-stage embedding-MMR. On embeddings builds,
    // apply MMR over the ranked Vec<Candidate> using cosine similarity
    // between candidate embeddings as the redundancy measure. This
    // collapses true semantic near-duplicates ("prefer rg over grep"
    // and "use ripgrep") that Jaccard-of-tokens would miss.
    //
    // When EITHER candidate lacks an embedding (repo-file, manifest,
    // or a cross-model memory row), falls back to Jaccard similarity
    // of summary tokens — the same measure the existing capsule-stage
    // MMR uses. This preserves lean parity exactly.
    //
    // Sort by score descending first so the greedy MMR seeds on the
    // top-scoring candidate (same as the capsule-stage MMR).
    candidates.sort_by(|a, b| {
        b.capsule
            .score
            .partial_cmp(&a.capsule.score)
            .unwrap_or(Ordering::Equal)
            .then_with(|| {
                b.capsule
                    .freshness
                    .partial_cmp(&a.capsule.freshness)
                    .unwrap_or(Ordering::Equal)
            })
            // Deterministic tiebreak on the STABLE handle (memory:<id> /
            // file:<path>) — capsule.id is a fresh random ULID per retrieval,
            // so tiebreaking on it would make retrieval non-reproducible on
            // score+freshness ties.
            .then_with(|| a.capsule.expansion_handle.cmp(&b.capsule.expansion_handle))
    });

    // Run embedding-MMR on embeddings builds; lean builds skip directly
    // to the capsule-stage Jaccard MMR below.
    let embedding_mmr_ran = query_embedding.is_some() && !candidates.is_empty();
    let candidates = if embedding_mmr_ran {
        apply_candidate_mmr_diversity(candidates, 0.7)
    } else {
        candidates
    };

    // v2.6: keep each memory's creation time keyed by its stable handle before
    // the candidates are consumed. Only built when the question is actually
    // about order — on every other query it would be a map nobody reads.
    let created_at_by_handle: std::collections::HashMap<String, String> =
        if crate::ordering::is_ordering_query(&request.query) {
            candidates
                .iter()
                .filter_map(|c| {
                    c.created_at
                        .clone()
                        .map(|ts| (c.capsule.expansion_handle.clone(), ts))
                })
                .collect()
        } else {
            std::collections::HashMap::new()
        };

    // v2.7: best absolute evidence over the surviving memory candidates —
    // COSINE ONLY. Lexical relevance lives on a different scale (token
    // overlap, ~0.2-0.6 for good matches) and comparing it against a
    // cosine-calibrated floor silently killed every lexical-only retrieval
    // (lean builds, cross-model rows). When no candidate carries a cosine the
    // gate has no verdict: -1.0 = "unmeasured", and both the hard gate below
    // and the band arbitration treat it as exempt.
    let top_abs_evidence = candidates
        .iter()
        .filter(|c| c.capsule.kind == "memory")
        .filter_map(|c| c.cosine)
        .fold(f32::NAN, f32::max);
    let top_abs_evidence = if top_abs_evidence.is_nan() {
        -1.0
    } else {
        top_abs_evidence
    };
    // Repo-file/manifest capsules suppress the evidence gate: an FTS hit on
    // real repo content is its own evidence the bundle is useful.
    let memory_only = candidates.iter().all(|c| c.capsule.kind == "memory");

    let mut capsules = candidates
        .into_iter()
        .map(|candidate| candidate.capsule)
        .collect::<Vec<_>>();

    // After embedding-MMR the candidate list is already in MMR order.
    // On lean builds (no embedding-MMR) we still need to sort by score.
    if !embedding_mmr_ran {
        capsules.sort_by(|left, right| {
            right
                .score
                .partial_cmp(&left.score)
                .unwrap_or(Ordering::Equal)
                .then_with(|| {
                    right
                        .freshness
                        .partial_cmp(&left.freshness)
                        .unwrap_or(Ordering::Equal)
                })
                // Stable handle tiebreak (capsule.id is random per retrieval).
                .then_with(|| left.expansion_handle.cmp(&right.expansion_handle))
        });
    }

    // v0.6: confidence-aware skip — if the top score is below the caller's
    // threshold, return an empty bundle immediately. Zero tokens injected.
    //
    // v2.7: joined by the absolute abstention gate. `top_score` is normalized
    // (the best candidate always carries relevance 1.0), so `min_score` ranks
    // but cannot abstain; `abstain_evidence` compares the best RAW cosine /
    // relevance against an absolute floor, so a corpus with nothing genuinely
    // relevant stays silent instead of shipping its best-of-a-bad-lot.
    let top_score = capsules.first().map(|c| c.score).unwrap_or(0.0);
    let composite_skip = request.min_score > 0.0 && top_score < request.min_score;
    // The hard floor sits one band-width BELOW the configured threshold: the
    // [threshold - width, threshold) band is not decided here but by
    // [`rerank_and_arbitrate`] at the call sites that own a cross-encoder —
    // raw bi-encoder cosine under-scores paraphrased matches, and the band is
    // exactly where those live. Callers without a reranker fail the band
    // closed, which reproduces the plain hard-gate behavior.
    let evidence_skip = request.abstain_evidence > 0.0
        && memory_only
        && top_abs_evidence >= 0.0
        && top_abs_evidence < (request.abstain_evidence - abstain_band_width()).max(0.0);
    if composite_skip || evidence_skip {
        return Ok(ContextBundle {
            stage: request.stage,
            budget_tokens: request.budget_tokens,
            used_tokens: 0,
            capsules: Vec::new(),
            excluded: capsules,
            skipped: true,
            top_score,
            top_abs_evidence,
            // A skipped bundle covers nothing, by construction.
            evidence_coverage: 0.0,
            uncovered_terms: Vec::new(),
            // Nothing was rendered, so nothing was rendered in time order.
            chronological: false,
            known_fact_conflicts: vec![],
        });
    }

    // MP-17 #13: capsule-stage Jaccard MMR — safety net / lean path.
    // On embeddings builds the candidate-stage embedding-MMR already
    // collapsed semantic near-duplicates; this pass is largely a no-op
    // (same-kind Jaccard score will be low for already-deduped summaries)
    // but provides a final guard against any remaining token-level
    // duplicates (e.g. repo files with heavily overlapping snippets).
    // On lean builds this is the sole diversity mechanism (unchanged).
    let capsules = apply_mmr_diversity(capsules, 0.7);

    let capsule_budget = request.budget_tokens / 2;
    let mut used_tokens = 0u32;
    let mut included = Vec::new();
    let mut excluded = Vec::new();

    for capsule in capsules {
        // v0.6: max_capsules cap (0 = disabled)
        if request.max_capsules > 0 && included.len() >= request.max_capsules {
            excluded.push(capsule);
            continue;
        }
        if (request.defer_fact_budget && request.max_capsules > 0)
            || used_tokens.saturating_add(capsule.token_estimate) <= capsule_budget
        {
            used_tokens = used_tokens.saturating_add(capsule.token_estimate);
            included.push(capsule);
        } else {
            excluded.push(capsule);
        }
    }

    let (coverage, uncovered_terms) = evidence_coverage(conn, &request.query, &included);

    // v2.6: presentation only, and last — the budget has already decided which
    // capsules ship, so re-rendering can neither admit one it rejected nor drop
    // one it chose. Coverage is measured before the date prefixes are added so
    // the score describes the memories, not their timestamps.
    //
    // `used_tokens` is recomputed because the prefixes are real tokens.
    let chronological = !created_at_by_handle.is_empty();
    let included = if chronological {
        let dated = crate::ordering::render_chronologically(included, &created_at_by_handle);
        used_tokens = dated.iter().map(|c| c.token_estimate).sum();
        dated
    } else {
        included
    };

    Ok(ContextBundle {
        stage: request.stage,
        budget_tokens: request.budget_tokens,
        used_tokens,
        capsules: included,
        excluded,
        skipped: false,
        top_score,
        top_abs_evidence,
        evidence_coverage: coverage,
        uncovered_terms,
        chronological,
        known_fact_conflicts: vec![],
    })
}

/// History/lineage path: search memories including expired ones (valid_to in the past).
///
/// This is the companion to `retrieve_context` for cases where you WANT to see
/// superseded, expired, or historically-valid memories — e.g. `kimetsu brain memory list`,
/// blame attribution, and lineage inspection.  The default retrieval path
/// (`retrieve_context` / `memory_candidates`) always excludes expired memories.
///
/// Returns the most recent `limit` active memories (invalidated_at IS NULL,
/// superseded_by IS NULL) including those whose `valid_to` has passed.
/// Superseded and invalidated rows are excluded (those are never valid for injection;
/// the `blame` path has its own direct SQL for those).
pub fn search_memories_including_expired(
    conn: &Connection,
    limit: u32,
) -> KimetsuResult<Vec<ContextCapsule>> {
    let mut stmt = conn.prepare_cached(
        "
        SELECT memory_id, scope, kind, text, confidence, created_at,
               use_count, usefulness_score, valid_from, valid_to
        FROM memories
        WHERE invalidated_at IS NULL
          AND superseded_by IS NULL
        ORDER BY created_at DESC
        LIMIT ?1
        ",
    )?;
    let rows = stmt.query_map(params![limit], |row| {
        Ok((
            row.get::<_, String>(0)?,
            row.get::<_, String>(1)?,
            row.get::<_, String>(2)?,
            row.get::<_, String>(3)?,
            row.get::<_, f32>(4)?,
            row.get::<_, String>(5)?,
            row.get::<_, i64>(6)?,
            row.get::<_, f64>(7)?,
            row.get::<_, Option<String>>(8)?,
            row.get::<_, Option<String>>(9)?,
        ))
    })?;
    let now_utc = OffsetDateTime::now_utc();
    let mut capsules = Vec::new();
    for row in rows {
        let (
            memory_id,
            scope,
            kind,
            text,
            confidence,
            created_at,
            _use_count,
            _usefulness,
            _valid_from,
            valid_to,
        ) = row?;
        let freshness = freshness(&created_at);
        let scope_weight = scope_weight(&scope);
        // Annotate expired memories so callers can identify them in history output.
        let suffix = if let Some(ref vt) = valid_to {
            if OffsetDateTime::parse(vt, &time::format_description::well_known::Rfc3339)
                .is_ok_and(|end| end <= now_utc)
            {
                format!(" [expired valid_to={vt}]")
            } else {
                format!(" [valid_to={vt}]")
            }
        } else {
            String::new()
        };
        let revision = crate::projector::claim_revision_at(conn, &memory_id, None)?;
        let facts = crate::fact_store::load(conn, &memory_id, &revision)?;
        let claim_revision = Some(revision);
        capsules.push(ContextCapsule {
            id: new_id().to_string(),
            kind: "memory".to_string(),
            summary: format!("{scope}:{kind} - {text}{suffix}"),
            token_estimate: estimate_tokens(&text) + 8,
            expansion_handle: format!("memory:{memory_id}"),
            provenance: vec![ProvenanceRef {
                source: "Memory".to_string(),
                id: memory_id,
                excerpt: Some(excerpt(&text)),
            }],
            confidence,
            freshness,
            relevance: 0.0,
            scope_weight,
            score: 0.0,
            superseded_hint: false,
            rerank_policy_tier: 0,
            claim_revision,
            facts,
            rerank_usefulness: None,
            rerank_trust: None,
        });
    }
    Ok(capsules)
}

pub fn search_repo_files(
    conn: &Connection,
    repo_root: &str,
    query: &str,
    limit: u32,
) -> KimetsuResult<Vec<ContextCapsule>> {
    let candidates = repo_file_candidates(conn, repo_root, query, limit)?;
    let mut capsules = candidates
        .into_iter()
        .map(|mut candidate| {
            candidate.capsule.relevance = candidate.raw_relevance;
            candidate.capsule.score = candidate.raw_relevance;
            candidate.capsule
        })
        .collect::<Vec<_>>();
    capsules.sort_by(|left, right| {
        right
            .score
            .partial_cmp(&left.score)
            .unwrap_or(Ordering::Equal)
            .then_with(|| left.expansion_handle.cmp(&right.expansion_handle))
    });
    Ok(capsules)
}

// -----------------------------------------------------------------------
// ANN candidate generation via the usearch HNSW index — embeddings only.
// (The old brute-force `vec0` index code was removed in T3c; usearch now
// supersedes it entirely. See `crate::ann`.)
// -----------------------------------------------------------------------

/// Top-K ANN candidates from the usearch HNSW index.
///
/// Returns memory rows fetched from `memories` (same columns as
/// `latest_memory_candidates`) built into `Candidate`s via
/// `memory_row_to_candidate`. Callers union this with the FTS set and dedup.
#[cfg(feature = "embeddings")]
fn memory_ann_candidates(
    conn: &Connection,
    qe: &QueryEmbedding,
    k: u32,
    query_tokens: &[String],
    half_life_days: f32,
    include_facts: bool,
) -> KimetsuResult<Vec<Candidate>> {
    // Tier-3: ANN candidate generation via the usearch HNSW index.
    let handle = crate::ann::handle_for_query(conn, qe.vector.len(), &qe.model_id)?;
    let hits = handle
        .read()
        .unwrap_or_else(|p| p.into_inner())
        .search(&qe.vector, k as usize)?;
    // Map rowids back to memory_ids (active-only is enforced by the index, but
    // we still join `memories` below for the full row + the embedding_model
    // residual filter, so collect rowids here).
    let knn_rowids: Vec<i64> = hits.into_iter().map(|(rowid, _dist)| rowid).collect();
    if knn_rowids.is_empty() {
        return Ok(Vec::new());
    }

    // Fetch full memory rows for those rowids (same projection as latest_memory_candidates).
    let placeholders: String = knn_rowids
        .iter()
        .enumerate()
        .map(|(i, _)| format!("?{}", i + 1))
        .collect::<Vec<_>>()
        .join(", ");
    let sql = format!(
        "SELECT memory_id, scope, kind, text, confidence, created_at,
                use_count, usefulness_score, embedding, embedding_model,
                last_useful_at, provenance_snapshot_json
         FROM   memories
         WHERE  invalidated_at IS NULL
           AND  superseded_by IS NULL
           AND  (valid_from IS NULL OR julianday(valid_from) <= julianday('now'))
          AND (valid_to IS NULL OR julianday(valid_to) > julianday('now'))
           AND  embedding_model = ?{model_param}
           AND  rowid IN ({placeholders})",
        model_param = knn_rowids.len() + 1
    );
    let mut stmt = conn.prepare(&sql)?;
    let mut params_vec: Vec<&dyn rusqlite::ToSql> = knn_rowids
        .iter()
        .map(|n| n as &dyn rusqlite::ToSql)
        .collect();
    params_vec.push(&qe.model_id);
    let rows_iter = stmt.query_map(params_vec.as_slice(), |row| {
        Ok((
            row.get::<_, String>(0)?,
            row.get::<_, String>(1)?,
            row.get::<_, String>(2)?,
            row.get::<_, String>(3)?,
            row.get::<_, f32>(4)?,
            row.get::<_, String>(5)?,
            row.get::<_, i64>(6)?,
            row.get::<_, f64>(7)?,
            row.get::<_, Option<Vec<u8>>>(8)?,
            row.get::<_, Option<String>>(9)?,
            row.get::<_, Option<String>>(10)?,
            row.get::<_, Option<String>>(11)?,
        ))
    })?;

    let mut candidates = Vec::new();
    for row in rows_iter {
        let (
            memory_id,
            scope,
            kind,
            text,
            confidence,
            created_at,
            use_count,
            usefulness_score,
            embedding,
            embedding_model,
            last_useful_at,
            provenance_snapshot,
        ) = row?;
        let (cosine, row_vec) =
            compute_cosine_and_vec(Some(qe), embedding.as_deref(), embedding_model.as_deref());
        let claim_revision = crate::projector::claim_revision_at(conn, &memory_id, None)?;
        if let Some(mut candidate) = memory_row_to_candidate(
            query_tokens,
            memory_id,
            scope,
            kind,
            text,
            confidence,
            created_at,
            use_count,
            usefulness_score,
            last_useful_at,
            provenance_snapshot,
            half_life_days,
            None, // no raw FTS relevance override — cosine drives ranking
            cosine,
            row_vec,
        ) {
            candidate.capsule.claim_revision = Some(claim_revision);
            hydrate_fact_evidence(conn, &mut candidate, include_facts)?;
            candidates.push(candidate);
        }
    }
    Ok(candidates)
}

/// Attach evidence only after row eligibility, while the text SELECT holds its snapshot.
pub(crate) fn hydrate_fact_evidence(
    conn: &Connection,
    candidate: &mut Candidate,
    include_facts: bool,
) -> KimetsuResult<()> {
    if include_facts {
        if let (Some(id), Some(revision)) = (
            candidate.capsule.expansion_handle.strip_prefix("memory:"),
            candidate.capsule.claim_revision.as_deref(),
        ) {
            candidate.capsule.facts = crate::fact_store::load(conn, id, revision)?;
        }
    }
    Ok(())
}

/// S5.1: the flat memory candidate function exposed as `pub(crate)` so
/// [`crate::backend::FlatBackend`] can delegate to it without copying logic.
///
/// Runs the FTS + usearch-ANN (embeddings) or FTS + recency (lean) candidate
/// pipeline — identical behaviour to pre-S5.1.
pub(crate) fn memory_candidates_flat(
    conn: &Connection,
    query: &str,
    query_embedding: Option<&QueryEmbedding>,
    half_life_days: f32,
    fusion: crate::fusion::Fusion,
    include_facts: bool,
) -> KimetsuResult<Vec<Candidate>> {
    memory_candidates(
        conn,
        query,
        query_embedding,
        half_life_days,
        fusion,
        include_facts,
    )
}

/// Build the flat candidate pool, merging the lexical and semantic rankings
/// with `fusion`.
///
/// The two sources — FTS5 and the ANN index — are independent rankings over the
/// same corpus, and how they are merged is a real ranking decision rather than
/// plumbing. See [`crate::fusion`].
fn memory_candidates(
    conn: &Connection,
    query: &str,
    query_embedding: Option<&QueryEmbedding>,
    half_life_days: f32,
    // Read only on the embeddings build: the lean path has a single ranking,
    // so there is nothing to fuse and any rule is the identity.
    #[cfg_attr(not(feature = "embeddings"), allow(unused_variables))] fusion: crate::fusion::Fusion,
    include_facts: bool,
) -> KimetsuResult<Vec<Candidate>> {
    let query_tokens = query_tokens(query);

    // D1c: on embeddings builds with a real query vector, run BOTH FTS and
    // ANN and fuse the two rankings. This replaces the recency-bounded
    // latest_memory_candidates fallback as the semantic-recall source when
    // embeddings are active.
    #[cfg(feature = "embeddings")]
    if let Some(qe) = query_embedding {
        // FTS candidates (may be empty if no lexical matches).
        let fts_candidates = if let Some(fts_query) = fts_query(query) {
            memory_fts_candidates(
                conn,
                &query_tokens,
                &fts_query,
                80,
                Some(qe),
                half_life_days,
                include_facts,
            )?
        } else {
            Vec::new()
        };

        // ANN candidates — top-80 nearest neighbours from the usearch index.
        let ann_candidates =
            memory_ann_candidates(conn, qe, 80, &query_tokens, half_life_days, include_facts)?;

        // Both sources return best-first, which is what rank-based fusion needs.
        return Ok(crate::fusion::fuse(
            fusion,
            vec![fts_candidates, ann_candidates],
        ));
    }

    // Lean (NoopEmbedder) path: unchanged — FTS then recency fallback.
    if let Some(fts_query) = fts_query(query) {
        let candidates = memory_fts_candidates(
            conn,
            &query_tokens,
            &fts_query,
            80,
            query_embedding,
            half_life_days,
            include_facts,
        )?;
        if !candidates.is_empty() {
            return Ok(candidates);
        }
    }

    latest_memory_candidates(
        conn,
        &query_tokens,
        200,
        query_embedding,
        half_life_days,
        include_facts,
    )
}

fn latest_memory_candidates(
    conn: &Connection,
    query_tokens: &[String],
    limit: u32,
    query_embedding: Option<&QueryEmbedding>,
    half_life_days: f32,
    include_facts: bool,
) -> KimetsuResult<Vec<Candidate>> {
    // MP-4d: exclude invalidated memories from retrieval. The row stays in
    // brain.db so `memory list` and replay can still see the history; only
    // the broker filters it out.
    //
    // v0.4.2: SELECT now also pulls the optional embedding + model id
    // so we can blend a cosine score with the lexical match.
    //
    // v0.5.1: SELECT also pulls `last_useful_at` so the broker can
    // apply the half-life decay term (memories that helped recently
    // outvote memories that haven't been confirmed useful in months).
    let mut stmt = conn.prepare_cached(
        "
        SELECT memory_id, scope, kind, text, confidence, created_at,
               use_count, usefulness_score, embedding, embedding_model,
               last_useful_at, provenance_snapshot_json
        FROM memories
        WHERE invalidated_at IS NULL
          AND superseded_by IS NULL
          AND (valid_from IS NULL OR julianday(valid_from) <= julianday('now'))
          AND (valid_to IS NULL OR julianday(valid_to) > julianday('now'))
        ORDER BY created_at DESC
        LIMIT ?1
        ",
    )?;

    let rows = stmt.query_map(params![limit], |row| {
        Ok((
            row.get::<_, String>(0)?,
            row.get::<_, String>(1)?,
            row.get::<_, String>(2)?,
            row.get::<_, String>(3)?,
            row.get::<_, f32>(4)?,
            row.get::<_, String>(5)?,
            row.get::<_, i64>(6)?,
            row.get::<_, f64>(7)?,
            row.get::<_, Option<Vec<u8>>>(8)?,
            row.get::<_, Option<String>>(9)?,
            row.get::<_, Option<String>>(10)?,
            row.get::<_, Option<String>>(11)?,
        ))
    })?;

    let mut candidates = Vec::new();
    for row in rows {
        let (
            memory_id,
            scope,
            kind,
            text,
            confidence,
            created_at,
            use_count,
            usefulness_score,
            embedding,
            embedding_model,
            last_useful_at,
            provenance_snapshot,
        ) = row?;
        let (cosine, row_vec) = compute_cosine_and_vec(
            query_embedding,
            embedding.as_deref(),
            embedding_model.as_deref(),
        );
        let claim_revision = crate::projector::claim_revision_at(conn, &memory_id, None)?;
        if let Some(mut candidate) = memory_row_to_candidate(
            query_tokens,
            memory_id,
            scope,
            kind,
            text,
            confidence,
            created_at,
            use_count,
            usefulness_score,
            last_useful_at,
            provenance_snapshot,
            half_life_days,
            None,
            cosine,
            row_vec,
        ) {
            candidate.capsule.claim_revision = Some(claim_revision);
            hydrate_fact_evidence(conn, &mut candidate, include_facts)?;
            candidates.push(candidate);
        }
    }
    Ok(candidates)
}

fn memory_fts_candidates(
    conn: &Connection,
    query_tokens: &[String],
    fts_query: &str,
    limit: u32,
    query_embedding: Option<&QueryEmbedding>,
    half_life_days: f32,
    include_facts: bool,
) -> KimetsuResult<Vec<Candidate>> {
    let mut stmt = conn.prepare_cached(
        "
        SELECT m.memory_id, m.scope, m.kind, m.text, m.confidence, m.created_at,
               m.use_count, m.usefulness_score, bm25(memories_fts) AS rank,
               m.embedding, m.embedding_model, m.last_useful_at,
               m.provenance_snapshot_json
        FROM memories_fts
        JOIN memories m
          ON m.memory_id = memories_fts.memory_id
        WHERE m.invalidated_at IS NULL
          AND m.superseded_by IS NULL
          AND (m.valid_from IS NULL OR julianday(m.valid_from) <= julianday('now'))
          AND (m.valid_to IS NULL OR julianday(m.valid_to) > julianday('now'))
          AND memories_fts MATCH ?1
        ORDER BY rank
        LIMIT ?2
        ",
    )?;

    let rows = stmt.query_map(params![fts_query, limit], |row| {
        Ok((
            row.get::<_, String>(0)?,
            row.get::<_, String>(1)?,
            row.get::<_, String>(2)?,
            row.get::<_, String>(3)?,
            row.get::<_, f32>(4)?,
            row.get::<_, String>(5)?,
            row.get::<_, i64>(6)?,
            row.get::<_, f64>(7)?,
            row.get::<_, f64>(8)?,
            row.get::<_, Option<Vec<u8>>>(9)?,
            row.get::<_, Option<String>>(10)?,
            row.get::<_, Option<String>>(11)?,
            row.get::<_, Option<String>>(12)?,
        ))
    })?;

    let mut candidates = Vec::new();
    for row in rows {
        let (
            memory_id,
            scope,
            kind,
            text,
            confidence,
            created_at,
            use_count,
            usefulness_score,
            rank,
            embedding,
            embedding_model,
            last_useful_at,
            provenance_snapshot,
        ) = row?;
        let fts_relevance = (-rank as f32).max(0.0);
        let (cosine, row_vec) = compute_cosine_and_vec(
            query_embedding,
            embedding.as_deref(),
            embedding_model.as_deref(),
        );
        let claim_revision = crate::projector::claim_revision_at(conn, &memory_id, None)?;
        if let Some(mut candidate) = memory_row_to_candidate(
            query_tokens,
            memory_id,
            scope,
            kind,
            text,
            confidence,
            created_at,
            use_count,
            usefulness_score,
            last_useful_at,
            provenance_snapshot,
            half_life_days,
            Some(fts_relevance),
            cosine,
            row_vec,
        ) {
            candidate.capsule.claim_revision = Some(claim_revision);
            hydrate_fact_evidence(conn, &mut candidate, include_facts)?;
            candidates.push(candidate);
        }
    }
    Ok(candidates)
}

/// v0.4.2 / D1e: cosine helper — returns both the cosine score and the
/// decoded row embedding vector for a memory row. Used by all three
/// memory-candidate retrieval paths (FTS, ANN, latest-recency) to
/// populate `Candidate.cosine` and `Candidate.embedding` for the
/// candidate-stage embedding-MMR pass.
///
/// Returns `(None, None)` when:
///   * `query_embedding` is None (NoopEmbedder / lean build)
///   * The row has no embedding bytes
///   * The row's `embedding_model` doesn't match the active query's
///     model id (cross-model mismatch — vectors are incomparable)
///
/// Cross-model rows are intentionally NOT blended: a row embedded
/// with `stub-d8` and a query embedded with `bge-small-en-v1.5`
/// produce meaningless dot products. Falling back to FTS for those
/// rows keeps hybrid retrieval safe across schema upgrades and
/// `kimetsu brain reindex` migrations (v0.4.3).
///
/// D1e: variant that returns both the cosine score and the decoded row
/// embedding vector. Used by callsites that need to store the vector
/// on the `Candidate` for the candidate-stage embedding-MMR pass.
/// When the row is cross-model or has no embedding, both fields are
/// `None` — identical semantics to [`compute_cosine`].
fn compute_cosine_and_vec(
    query_embedding: Option<&QueryEmbedding>,
    row_bytes: Option<&[u8]>,
    row_model: Option<&str>,
) -> (Option<f32>, Option<Vec<f32>>) {
    let q = match query_embedding {
        Some(q) => q,
        None => return (None, None),
    };
    let bytes = match row_bytes {
        Some(b) => b,
        None => return (None, None),
    };
    let model = match row_model {
        Some(m) => m,
        None => return (None, None),
    };
    if model != q.model_id {
        return (None, None);
    }
    let row_vec = match decode_embedding(bytes, Some(q.vector.len())) {
        Ok(v) => v,
        Err(_) => return (None, None),
    };
    let score = cosine_similarity(&q.vector, &row_vec);
    (Some(score), Some(row_vec))
}

#[allow(clippy::too_many_arguments)]
pub(crate) fn memory_row_to_candidate(
    query_tokens: &[String],
    memory_id: String,
    scope: String,
    kind: String,
    text: String,
    confidence: f32,
    created_at: String,
    use_count: i64,
    usefulness_score: f64,
    last_useful_at: Option<String>,
    // v2.6: the memory's stored provenance snapshot, classified into a trust
    // multiplier. See `crate::trust`.
    provenance_snapshot: Option<String>,
    half_life_days: f32,
    raw_relevance_override: Option<f32>,
    cosine_score: Option<f32>,
    // D1e: decoded embedding vector for this row (same model as the
    // active query embedder). None for cross-model rows, rows without
    // embeddings, or lean builds. Stored on Candidate for the
    // candidate-stage embedding-MMR pass.
    row_embedding: Option<Vec<f32>>,
) -> Option<Candidate> {
    let lexical = lexical_relevance(query_tokens, &format!("{kind} {text}"));
    let lexical_term = raw_relevance_override.unwrap_or(lexical).max(lexical);

    // v0.4.2: hybrid blend.
    //   final = (1 - α) * lexical + α * normalized_cosine
    // where normalized_cosine maps [-1, 1] -> [0, 1] so it composes
    // with the lexical relevance scale.
    //
    // When cosine_score is None (NoopEmbedder, NULL row embedding,
    // cross-model mismatch), the cosine term drops out and the
    // candidate scores lexical-only — exact v0.4.1 behavior. The
    // caller's gate `raw_relevance <= 0.0 && !query_tokens.is_empty()`
    // still works because in the no-cosine path `raw_relevance ==
    // lexical_term`.
    let raw_relevance = match cosine_score {
        Some(c) => {
            let normalized_cos = ((c + 1.0) * 0.5).clamp(0.0, 1.0);
            (1.0 - DEFAULT_HYBRID_ALPHA) * lexical_term + DEFAULT_HYBRID_ALPHA * normalized_cos
        }
        None => lexical_term,
    };

    // Drop the row when neither lexical nor cosine had any signal —
    // an empty query OR a candidate that didn't match any of the
    // search terms. The cosine-only path is still allowed through
    // (raw_relevance > 0) for semantic-only matches against rows
    // whose words don't textually overlap the query.
    if raw_relevance <= 0.0 && !query_tokens.is_empty() {
        return None;
    }

    let freshness = freshness(&created_at);
    let scope_weight = scope_weight(&scope);
    // v0.5.1: usefulness multiplier with half-life decay applied to
    // the *deviation from neutral*. A 6-month-old memory that scored
    // 1.5 (max boost) decays toward 1.0 (neutral) — NOT toward 0,
    // because losing confidence in old signal shouldn't penalize a
    // memory below a brand-new memory with zero history.
    let raw_multiplier = usefulness_multiplier(usefulness_score as f32, use_count as u32);
    let decay = usefulness_decay(last_useful_at.as_deref(), &created_at, half_life_days);
    let multiplier = 1.0 + (raw_multiplier - 1.0) * decay;
    let biased_relevance = apply_usefulness_boost(raw_relevance, multiplier);
    // Retain the sign for older serialized consumers. New capsules carry the full multiplier.
    let rerank_policy_tier = if multiplier > 1.0 + f32::EPSILON {
        1
    } else if multiplier < 1.0 - f32::EPSILON {
        -1
    } else {
        0
    };
    // Reliance and outcome association do not verify a memory or erase origin.
    let provenance =
        crate::trust::Provenance::from_snapshot(provenance_snapshot.as_deref().unwrap_or("{}"));
    let trusted_relevance =
        biased_relevance * crate::trust::trust_multiplier(provenance, last_useful_at.is_some());

    Some(Candidate {
        raw_relevance: trusted_relevance,
        embedding: row_embedding,
        cosine: cosine_score,
        created_at: Some(created_at),
        capsule: ContextCapsule {
            id: new_id().to_string(),
            kind: "memory".to_string(),
            summary: format!("{scope}:{kind} - {text}"),
            token_estimate: estimate_tokens(&text) + 8,
            expansion_handle: format!("memory:{memory_id}"),
            provenance: vec![ProvenanceRef {
                source: "Memory".to_string(),
                id: memory_id,
                excerpt: Some(excerpt(&text)),
            }],
            confidence,
            freshness,
            relevance: 0.0,
            scope_weight,
            score: 0.0,
            superseded_hint: false,
            rerank_policy_tier,
            claim_revision: None,
            facts: vec![],
            rerank_usefulness: Some(multiplier),
            rerank_trust: Some(crate::trust::trust_multiplier(
                provenance,
                last_useful_at.is_some(),
            )),
        },
    })
}

/// v0.5.1: half-life decay factor applied to the *deviation from
/// neutral* of [`usefulness_multiplier`]. Returns a value in `[0.0,
/// 1.0]` where 1.0 = "use full envelope" (memory was confirmed useful
/// recently) and 0.0 = "treat as neutral" (memory's confirmation is
/// ancient).
///
/// Reference timestamp:
///   * `last_useful_at` (set by the projector when a cited memory's
///     run ended in run.finished) if present
///   * fallback to `created_at` so a brand-new memory that's never
///     been cited yet decays from its birthday — same shape, but
///     starts fresh.
///
/// Math:
///   decay = exp(-ln(2) * age_days / half_life_days)
/// so at age == half_life the contribution is halved, at 2*half_life
/// it's quartered, etc.
///
/// Safety rails:
///   * `half_life_days <= 0` disables decay (returns 1.0) so an
///     operator can opt out via project.toml.
///   * Unparseable RFC3339 timestamps return 1.0 — fail-open so a
///     corrupted row doesn't get silently demoted out of retrieval.
pub(crate) fn usefulness_decay(
    last_useful_at: Option<&str>,
    created_at: &str,
    half_life_days: f32,
) -> f32 {
    if half_life_days <= 0.0 {
        return 1.0;
    }
    let reference = last_useful_at.unwrap_or(created_at);
    let Ok(reference_ts) =
        OffsetDateTime::parse(reference, &time::format_description::well_known::Rfc3339)
    else {
        return 1.0;
    };
    let age = OffsetDateTime::now_utc() - reference_ts;
    let age_days = (age.whole_seconds().max(0) as f32) / 86_400.0;
    let exponent = -std::f32::consts::LN_2 * age_days / half_life_days;
    exponent.exp().clamp(0.0, 1.0)
}

// v2.5.1: the boost cap and multiplier envelope live in crate::scoring (the
// one-page home of every learning-loop constant).
pub(crate) use crate::scoring::USEFULNESS_BOOST_CAP;

/// Apply the usefulness multiplier to a relevance score with the boost gain
/// capped at [`USEFULNESS_BOOST_CAP`] (see there for why).
pub(crate) fn apply_usefulness_boost(raw_relevance: f32, multiplier: f32) -> f32 {
    if multiplier <= 1.0 {
        return raw_relevance * multiplier;
    }
    (raw_relevance * multiplier).min(raw_relevance + USEFULNESS_BOOST_CAP)
}

/// MP-4b multiplier in [0.5, 1.5] derived from a memory's outcome history.
/// `use_count < 3` is treated as small-sample and yields 1.0 (neutral) so a
/// brand-new memory has a fair chance to demonstrate value before being
/// boosted or penalized.
pub(crate) fn usefulness_multiplier(usefulness_score: f32, use_count: u32) -> f32 {
    // MP-17e: soften the hard sample-size threshold via Bayesian smoothing.
    //
    // Old behaviour: hard cutoff at use_count < 3 returned neutral 1.0,
    // then full envelope kicked in. That meant a memory with 2 uses (both
    // helpful) was treated identically to a memory with 0 uses, which
    // wasted early signal. New behaviour: linearly blend toward the
    // full multiplier as use_count climbs to FULL_CONFIDENCE_USES.
    use crate::scoring::{FULL_CONFIDENCE_USES, MULTIPLIER_MAX, MULTIPLIER_MIN};
    if use_count == 0 {
        return 1.0;
    }
    let ratio = usefulness_score / use_count as f32; // in -1.0..1.0 typically
    let normalized = ((ratio + 1.0) / 2.0).clamp(0.0, 1.0); // map to 0..1
    let full_multiplier = MULTIPLIER_MIN + normalized * (MULTIPLIER_MAX - MULTIPLIER_MIN);
    let confidence = (use_count as f32 / FULL_CONFIDENCE_USES as f32).min(1.0);
    1.0 * (1.0 - confidence) + full_multiplier * confidence
}

fn repo_file_candidates(
    conn: &Connection,
    repo_root: &str,
    query: &str,
    limit: u32,
) -> KimetsuResult<Vec<Candidate>> {
    let Some(fts_query) = fts_query(query) else {
        return Ok(Vec::new());
    };

    let mut stmt = conn.prepare_cached(
        "
        SELECT path, snippet, language_guess, bm25(repo_files_fts) AS rank
        FROM repo_files_fts
        WHERE repo_root = ?1 AND repo_files_fts MATCH ?2
        ORDER BY rank
        LIMIT ?3
        ",
    )?;

    let rows = stmt.query_map(params![repo_root, fts_query, limit], |row| {
        Ok((
            row.get::<_, String>(0)?,
            row.get::<_, String>(1)?,
            row.get::<_, String>(2)?,
            row.get::<_, f64>(3)?,
        ))
    })?;

    let mut candidates = Vec::new();
    for row in rows {
        let (path, snippet, language, rank) = row?;
        let raw_relevance = (-rank as f32).max(0.0);
        let summary = format!("{path} ({language}) - {}", excerpt(&snippet));
        let token_estimate = estimate_tokens(&summary) + 8;
        candidates.push(Candidate {
            raw_relevance,
            embedding: None,
            cosine: None,
            // A repo file has no position in the memory timeline.
            created_at: None,
            capsule: ContextCapsule {
                id: new_id().to_string(),
                kind: "repo_file".to_string(),
                summary,
                token_estimate,
                expansion_handle: format!("file:{path}"),
                provenance: vec![ProvenanceRef {
                    source: "RepoFile".to_string(),
                    id: path.clone(),
                    excerpt: Some(excerpt(&snippet)),
                }],
                confidence: 0.9,
                freshness: 1.0,
                relevance: 0.0,
                scope_weight: 0.9,
                score: 0.0,
                superseded_hint: false,
                rerank_policy_tier: 0,
                claim_revision: None,
                facts: vec![],
                rerank_usefulness: None,
                rerank_trust: None,
            },
        });
    }
    Ok(candidates)
}

fn manifest_candidates(
    conn: &Connection,
    repo_root: &str,
    query: &str,
) -> KimetsuResult<Vec<Candidate>> {
    if let Some(fts_query) = fts_query(query) {
        let candidates = manifest_fts_candidates(conn, repo_root, &fts_query, 30)?;
        if !candidates.is_empty() {
            return Ok(candidates);
        }
    }

    let query_tokens = query_tokens(query);
    let mut stmt = conn.prepare_cached(
        "
        SELECT manifest_path, manifest_kind, parsed_summary_json
        FROM repo_manifests
        WHERE repo_root = ?1
        ORDER BY manifest_path
        ",
    )?;

    let rows = stmt.query_map(params![repo_root], |row| {
        Ok((
            row.get::<_, String>(0)?,
            row.get::<_, String>(1)?,
            row.get::<_, String>(2)?,
        ))
    })?;

    let mut candidates = Vec::new();
    for row in rows {
        let (path, kind, summary_json) = row?;
        let raw_relevance =
            lexical_relevance(&query_tokens, &format!("{path} {kind} {summary_json}"));
        if raw_relevance <= 0.0 && !query_tokens.is_empty() {
            continue;
        }
        let summary = format!("{path} manifest ({kind})");
        let token_estimate = estimate_tokens(&summary) + 8;
        candidates.push(Candidate {
            raw_relevance,
            embedding: None,
            cosine: None,
            // A repo file has no position in the memory timeline.
            created_at: None,
            capsule: ContextCapsule {
                id: new_id().to_string(),
                kind: "repo_manifest".to_string(),
                summary,
                token_estimate,
                expansion_handle: format!("file:{path}"),
                provenance: vec![ProvenanceRef {
                    source: "Manifest".to_string(),
                    id: path,
                    excerpt: Some(excerpt(&summary_json)),
                }],
                confidence: 0.95,
                freshness: 1.0,
                relevance: 0.0,
                scope_weight: 0.9,
                score: 0.0,
                superseded_hint: false,
                rerank_policy_tier: 0,
                claim_revision: None,
                facts: vec![],
                rerank_usefulness: None,
                rerank_trust: None,
            },
        });
    }
    Ok(candidates)
}

fn manifest_fts_candidates(
    conn: &Connection,
    repo_root: &str,
    fts_query: &str,
    limit: u32,
) -> KimetsuResult<Vec<Candidate>> {
    let mut stmt = conn.prepare_cached(
        "
        SELECT manifest_path, manifest_kind, parsed_summary_json,
               bm25(repo_manifests_fts) AS rank
        FROM repo_manifests_fts
        WHERE repo_root = ?1 AND repo_manifests_fts MATCH ?2
        ORDER BY rank
        LIMIT ?3
        ",
    )?;

    let rows = stmt.query_map(params![repo_root, fts_query, limit], |row| {
        Ok((
            row.get::<_, String>(0)?,
            row.get::<_, String>(1)?,
            row.get::<_, String>(2)?,
            row.get::<_, f64>(3)?,
        ))
    })?;

    let mut candidates = Vec::new();
    for row in rows {
        let (path, kind, summary_json, rank) = row?;
        let raw_relevance = (-rank as f32).max(0.0);
        let summary = format!("{path} manifest ({kind})");
        let token_estimate = estimate_tokens(&summary) + 8;
        candidates.push(Candidate {
            raw_relevance,
            embedding: None,
            cosine: None,
            // A repo file has no position in the memory timeline.
            created_at: None,
            capsule: ContextCapsule {
                id: new_id().to_string(),
                kind: "repo_manifest".to_string(),
                summary,
                token_estimate,
                expansion_handle: format!("file:{path}"),
                provenance: vec![ProvenanceRef {
                    source: "Manifest".to_string(),
                    id: path,
                    excerpt: Some(excerpt(&summary_json)),
                }],
                confidence: 0.95,
                freshness: 1.0,
                relevance: 0.0,
                scope_weight: 0.9,
                score: 0.0,
                superseded_hint: false,
                rerank_policy_tier: 0,
                claim_revision: None,
                facts: vec![],
                rerank_usefulness: None,
                rerank_trust: None,
            },
        });
    }
    Ok(candidates)
}

/// v2.6: how `raw_relevance` becomes the `relevance` term of the composite
/// score.
///
/// ## Per-kind (the rule through v2.5)
///
/// Each `kind` is normalized against the best `raw_relevance` *of that kind*.
/// The consequence is that the top memory and the top repo_file both score
/// `relevance = 1.0` no matter how good either actually is: on a query where
/// memory has the answer and no file is relevant, the best of the irrelevant
/// files is still promoted to a perfect relevance and competes for budget on
/// the strength of the other three score terms alone.
///
/// That is the distortion the lexical and semantic *floors* exist to
/// compensate for — they prune the weak candidate before normalization can
/// flatter it. A floor is a blunt instrument for this: it is a fixed
/// threshold standing in for a comparison the normalizer could just make.
///
/// ## Global
///
/// One max over all candidates, so `relevance` means the same thing across
/// kinds and a candidate that is merely the best of a bad kind keeps a low
/// relevance. Nothing else in the pipeline changes.
///
/// ## Which one runs
///
/// Selectable, defaulting to `per_kind`. Global normalization is the more
/// principled rule and it is *still* not the default here, for the same
/// reason RRF is not: the house rule is that a ranking change ships with a
/// measurement on a real corpus, and an argument from first principles is not
/// one. `[broker] normalization` and the per-request override are how a
/// corpus gets to settle it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Normalization {
    /// Normalize within each capsule kind. Kimetsu's behaviour through v2.5.
    #[default]
    PerKind,
    /// Normalize against a single max over every candidate.
    Global,
}

impl Normalization {
    /// Parse from config. Unknown values fall back to the default, matching
    /// how `[broker] fusion` treats an unrecognized rule — a typo in a config
    /// file must not silently change ranking.
    pub fn from_config(value: &str) -> Self {
        match value.trim().to_ascii_lowercase().as_str() {
            "global" => Self::Global,
            _ => Self::PerKind,
        }
    }
}

fn normalize_and_score(
    candidates: &mut [Candidate],
    weights: StageWeights,
    normalization: Normalization,
) {
    // The per-kind rule keys on the capsule kind; the global rule uses one
    // bucket for everything. Sharing the map keeps a single scoring loop.
    let mut max_by_kind = HashMap::<String, f32>::new();
    let bucket = |candidate: &Candidate| match normalization {
        Normalization::PerKind => candidate.capsule.kind.clone(),
        Normalization::Global => String::new(),
    };
    for candidate in candidates.iter() {
        max_by_kind
            .entry(bucket(candidate))
            .and_modify(|max| *max = (*max).max(candidate.raw_relevance))
            .or_insert(candidate.raw_relevance);
    }

    for candidate in candidates {
        let max = max_by_kind.get(&bucket(candidate)).copied().unwrap_or(0.0);
        let relevance = if max <= f32::EPSILON {
            if candidate.raw_relevance > 0.0 {
                1.0
            } else {
                0.0
            }
        } else {
            (candidate.raw_relevance / max).clamp(0.0, 1.0)
        };
        candidate.capsule.relevance = relevance;
        candidate.capsule.score = weights.relevance * relevance
            + weights.confidence * candidate.capsule.confidence
            + weights.freshness * candidate.capsule.freshness
            + weights.scope * candidate.capsule.scope_weight;
    }
}

/// v2.7: two memory candidates whose embeddings agree at least this much are
/// treated as statements of the same topic for the newer-wins rule. High on
/// purpose — complementary-but-distinct lessons on one subject must not
/// penalize each other; only near-restatements qualify.
pub(crate) const SUPERSESSION_MIN_COSINE: f32 = 0.85;

/// Explicit correction language supplies extra evidence that two moderately
/// similar memories are successive versions of one fact. The 0.82 floor admits
/// the measured "no longer uses replica-1" update pair (cosine 0.837) without
/// broadening the rule for ordinary memories, which still require 0.85.
pub(crate) const SUPERSESSION_CUE_MIN_COSINE: f32 = 0.82;

/// A correction can also identify a rewritten update whose embedding moved
/// substantially because the replacement contains new implementation detail.
/// Require both several shared content tokens and dense overlap with the
/// smaller text; the cue alone is never sufficient.
pub(crate) const SUPERSESSION_CUE_MIN_SHARED_TOKENS: usize = 3;
pub(crate) const SUPERSESSION_CUE_MIN_LEXICAL_OVERLAP: f32 = 0.35;

/// v2.7: score multiplier applied (once) to the older member of a
/// near-duplicate pair. Sized from the workflow benchmark's measured failure:
/// a cited incumbent's usefulness boost gives it a ~1.08× composite advantage
/// over its fresher replacement, so 0.80 flips the ordering with margin while
/// leaving genuinely-unrelated rankings untouched.
pub(crate) const SUPERSESSION_PENALTY: f32 = 0.80;

/// v2.7: minimum age gap for the newer-wins rule. Supersession implies
/// temporal SUCCESSION — a near-duplicate written milliseconds apart is one
/// authoring event (a batch ingest, two variants of one lesson), not an
/// update, and penalizing the "older" of the pair broke the importance
/// dimension's cited-must-outrank assertion (92.1% → 81.6% on the
/// comprehensive A/B). One second cleanly separates same-batch co-writes
/// (Δ≈ms) from genuine cross-task updates (Δ≥ seconds); explicit correction
/// language provides the narrow exception for ordered batch imports.
pub(crate) const SUPERSESSION_MIN_AGE_GAP_SECS: f64 = 1.0;

/// Text can establish succession even when storage timestamps cannot. This is
/// intentionally a narrow phrase list: it only applies to near-duplicate
/// memory pairs, and only when exactly one side carries an explicit correction
/// cue. Generic recency words such as "new" are excluded because they appear
/// in ordinary co-written lessons too often.
fn has_explicit_supersession_signal(text: &str) -> bool {
    // Normalize punctuation to word boundaries before matching. Correction
    // language commonly appears parenthesized ("(switched from tabs)"); a
    // literal-space matcher misses it even though the words are unambiguous.
    // Keeping outer spaces prevents the single-word cues from matching inside
    // unrelated words (for example `now` inside `known`).
    let words = text
        .to_ascii_lowercase()
        .chars()
        .map(|c| if c.is_ascii_alphanumeric() { c } else { ' ' })
        .collect::<String>();
    let text = format!(
        " {} ",
        words.split_whitespace().collect::<Vec<_>>().join(" ")
    );
    [
        " now ",
        " no longer ",
        " renamed from ",
        " switched from ",
        " as of ",
        " currently ",
        " after the ",
        " supersedes ",
        " replaced by ",
        " silently breaks ",
    ]
    .iter()
    .any(|signal| text.contains(signal))
}

fn has_supersession_lexical_identity(a: &str, b: &str) -> bool {
    let a = content_tokens(a);
    let b = content_tokens(b);
    let smaller = a.len().min(b.len());
    if smaller == 0 {
        return false;
    }
    let shared = a.iter().filter(|token| b.contains(token)).count();
    shared >= SUPERSESSION_CUE_MIN_SHARED_TOKENS
        && shared as f32 / smaller as f32 >= SUPERSESSION_CUE_MIN_LEXICAL_OVERLAP
}

/// v2.7: newer-wins supersession pass. Strong embedding near-duplicates
/// qualify directly; moderately similar or rewritten pairs must also carry
/// exactly one explicit correction cue and enough lexical identity. For
/// lexical-only rewrites, the replacement must be at least as relevant to the
/// current query so historical questions can still retrieve the old fact.
/// The OLDER candidate is multiplied by `SUPERSESSION_PENALTY` at most once,
/// however many newer siblings it has. Runs after normalization and boosts so
/// the penalty is the last word: a heavily-cited incumbent cannot out-boost
/// its own replacement.
///
/// Requires both embeddings and both parseable `created_at` timestamps; pairs
/// missing either are left alone (lean builds are unaffected end to end).
pub(crate) fn apply_supersession_penalty(candidates: &mut [Candidate]) {
    let parsed: Vec<Option<OffsetDateTime>> = candidates
        .iter()
        .map(|c| {
            if c.capsule.kind != "memory" || c.embedding.is_none() {
                return None;
            }
            c.created_at.as_deref().and_then(|ts| {
                OffsetDateTime::parse(ts, &time::format_description::well_known::Rfc3339).ok()
            })
        })
        .collect();

    let mut penalized = vec![false; candidates.len()];
    for i in 0..candidates.len() {
        let Some(ti) = parsed[i] else { continue };
        for j in (i + 1)..candidates.len() {
            let Some(tj) = parsed[j] else { continue };
            let (Some(ei), Some(ej)) = (&candidates[i].embedding, &candidates[j].embedding) else {
                continue;
            };
            let signals = (
                has_explicit_supersession_signal(&candidates[i].capsule.summary),
                has_explicit_supersession_signal(&candidates[j].capsule.summary),
            );
            let exactly_one_signal = signals.0 ^ signals.1;
            let similarity = crate::embeddings::cosine_similarity(ei, ej);
            let cue_related = exactly_one_signal
                && (similarity >= SUPERSESSION_CUE_MIN_COSINE
                    || has_supersession_lexical_identity(
                        &candidates[i].capsule.summary,
                        &candidates[j].capsule.summary,
                    ));
            if similarity < SUPERSESSION_MIN_COSINE && !cue_related {
                continue;
            }
            // Sub-second gaps (incl. identical timestamps) are normally one
            // authoring event, not a supersession. A single explicit
            // correction cue can still establish direction for batch imports;
            // if both or neither carry one, there is no defensible winner.
            let gap = (ti - tj).abs();
            let subsecond = (gap.whole_milliseconds().unsigned_abs() as f64)
                < SUPERSESSION_MIN_AGE_GAP_SECS * 1000.0;
            let older = if subsecond {
                match signals {
                    (true, false) => j,
                    (false, true) => i,
                    _ => continue,
                }
            } else {
                match ti.cmp(&tj) {
                    Ordering::Less => i,
                    Ordering::Greater => j,
                    Ordering::Equal => continue,
                }
            };
            if similarity < SUPERSESSION_CUE_MIN_COSINE {
                // Lexical-only rewrites below the cue-qualified cosine floor
                // can be related facts rather than mutually exclusive
                // restatements. Apply newer-wins only when the replacement is
                // at least as relevant to THIS query. This preserves historical
                // questions such as "which embedder reached MRR 1.0?" while
                // still resolving "what is preferred now?" to the newer
                // recommendation. Cue-marked pairs at 0.82+ are close enough
                // to use the ordinary newer-wins policy directly.
                let replacement = if older == i { j } else { i };
                let replacement_has_signal = if replacement == i {
                    signals.0
                } else {
                    signals.1
                };
                let query_favors_replacement =
                    match (candidates[replacement].cosine, candidates[older].cosine) {
                        (Some(replacement_cosine), Some(older_cosine)) => {
                            replacement_cosine >= older_cosine
                        }
                        _ => false,
                    };
                if !replacement_has_signal || !query_favors_replacement {
                    continue;
                }
            }
            if !penalized[older] {
                penalized[older] = true;
                candidates[older].capsule.score *= SUPERSESSION_PENALTY;
                // Mark it so post-retrieval reranking can reapply the penalty
                // on the cross-encoder's score domain.
                candidates[older].capsule.superseded_hint = true;
            }
        }
    }
}

fn weights_for_stage(weights: &BrokerWeights, stage: &str) -> StageWeights {
    match stage {
        "localization" => weights.localization.clone(),
        "patch_plan" => weights.patch_plan.clone(),
        "verification" => weights.verification.clone(),
        "review" => weights.review.clone(),
        _ => None,
    }
    .unwrap_or(StageWeights {
        relevance: weights.relevance,
        confidence: weights.confidence,
        freshness: weights.freshness,
        scope: weights.scope,
    })
}

fn scope_weight(scope: &str) -> f32 {
    match scope.parse::<MemoryScope>() {
        Ok(MemoryScope::Run) => 1.0,
        Ok(MemoryScope::Repo) => 0.9,
        Ok(MemoryScope::Project) => 0.7,
        Ok(MemoryScope::GlobalUser) => 0.5,
        Err(_) => 0.3,
    }
}

fn freshness(created_at: &str) -> f32 {
    let Ok(created_at) =
        OffsetDateTime::parse(created_at, &time::format_description::well_known::Rfc3339)
    else {
        return 0.5;
    };
    let age = OffsetDateTime::now_utc() - created_at;
    let age_days = age.whole_seconds().max(0) as f32 / 86_400.0;
    (-std::f32::consts::LN_2 * age_days / 30.0)
        .exp()
        .clamp(0.0, 1.0)
}

/// v1.0.0: a memory whose cosine to the query clears this bar is kept by
/// the lexical floor even when it shares few query words — a genuine
/// semantic match shouldn't be pruned for lexical thinness. Inert on the
/// FTS-only hook path (cosine is always `None` there).
const SEMANTIC_KEEP_COSINE: f32 = 0.20;

/// v1.0.0: generic English function words carry no topical signal, so they
/// are stripped before the IDF-weighted lexical floor. Kept deliberately
/// small — only true stopwords. Content words like "repo" or "idea" are NOT
/// here; their commonness is handled by IDF, not a hand-maintained list.
const STOPWORDS: &[&str] = &[
    "the", "and", "for", "are", "but", "not", "you", "your", "with", "this", "that", "these",
    "those", "from", "into", "about", "what", "whats", "which", "who", "whom", "how", "why",
    "when", "where", "can", "could", "would", "should", "will", "shall", "does", "did", "was",
    "were", "been", "being", "have", "has", "had", "its", "it", "is", "as", "at", "by", "of", "to",
    "in", "on", "or", "an", "be", "do", "me", "my", "we", "us", "our", "im", "ive", "let", "lets",
    "please", "tell", "give", "show", "want", "need", "get", "got", "use", "using", "there",
    "their", "they", "them", "then", "than", "some", "any", "all", "more", "most", "such", "via",
    "per",
    // v2.6: the function words this list had always meant to cover. The
    // comment in `content_tokens` cited "during" as the reason stemming runs
    // after the stopword check, and "during" was not actually in the list —
    // harmless while these tokens only nudged a floor, but v2.6 shows uncovered
    // terms to the user by name, and "nothing above covers during" is noise.
    // These also reconcile this list with `graph::STOPWORDS`, which had a
    // different set; two disagreeing stopword lists in one codebase is its own
    // small defect.
    "during", "while", "until", "unless", "before", "after", "again", "against", "above", "below",
    "between", "through", "under", "over", "because", "also", "just", "only", "very", "much",
    "many", "each", "both", "same", "other", "another", "always", "never", "still", "even", "ever",
    "every", "first", "found", "thing", "things", "value", "default", "if", "so", "up", "out",
    "off", "down", "no", "yes",
];

/// v1.0.0: tokenize a query into deduped CONTENT tokens — the same word
/// split as [`query_tokens`] but with stopwords removed and WITHOUT the
/// `CLASS_HINTS` tool-name expansions (those are a retrieval *boost*, not
/// part of the user's topical intent). Used only by the lexical floor.
fn content_tokens(query: &str) -> Vec<String> {
    let mut seen = std::collections::HashSet::new();
    query
        .split(|ch: char| !ch.is_ascii_alphanumeric() && ch != '_')
        .map(str::trim)
        .filter(|part| part.len() >= 2)
        .map(str::to_ascii_lowercase)
        .filter(|t| !STOPWORDS.contains(&t.as_str()))
        // Stem AFTER the stopword check ("during" must not stem to "dur"
        // and dodge the list) so inflected variants share one IDF entry.
        .map(|t| light_stem(&t).to_string())
        .filter(|t| seen.insert(t.clone()))
        .collect()
}

/// v1.0.0: discriminating weight for each content token over the
/// (non-invalidated) memory corpus, where `df` is the number of memories
/// whose text contains the token as a substring (matching
/// [`lexical_relevance`]'s substring semantics). Only tokens that actually
/// partition the corpus carry weight; the two useless extremes are zeroed:
///
///   * `df == N` — the token is in EVERY memory (the project name). `idf =
///     ln((N+1)/(N+1)) = 0` falls out of the formula naturally.
///   * `df == 0` — the token is in NO memory (an out-of-corpus word like a
///     generic English verb). It can't distinguish one memory from another,
///     so it's forced to 0. Leaving it at its (maximal) raw IDF would let a
///     single generic query word sink every candidate's coverage below the
///     floor — the on-topic memory that matches the *rare, in-corpus* word
///     would be wrongly pruned.
///
/// Everything in between gets `idf = ln((N+1)/(df+1))` — rarer ⇒ larger.
/// Best-effort: a query/count failure yields 0 for that token (fail-open).
fn corpus_token_idf(conn: &Connection, tokens: &[String]) -> KimetsuResult<HashMap<String, f32>> {
    token_idf(conn, tokens, true)
}

/// Prefix MATCH uses the same FTS tokenizer as candidate retrieval. Each matched
/// memory counts once even when its text repeats a token. N and df both refer to
/// non-invalidated indexed documents, including historical/superseded documents.
/// One indexed posting-list lookup per unique token replaces per-term text scans.
fn token_idf(
    conn: &Connection,
    tokens: &[String],
    zero_absent: bool,
) -> KimetsuResult<HashMap<String, f32>> {
    let n: i64 = conn.query_row(
        "SELECT COUNT(*) FROM memories_fts JOIN memories m USING(memory_id) WHERE m.invalidated_at IS NULL",
        [], |r| r.get(0))?;
    let mut idf = HashMap::new();
    if n == 0 {
        return Ok(idf);
    }
    let mut stmt = conn.prepare_cached(
        "SELECT COUNT(DISTINCT m.memory_id) FROM memories_fts JOIN memories m USING(memory_id)
         WHERE memories_fts MATCH ?1 AND m.invalidated_at IS NULL",
    )?;
    for token in tokens {
        if idf.contains_key(token) {
            continue;
        }
        let pattern = format!("text : \"{}\"*", token.replace('"', "\"\""));
        let df: i64 = stmt.query_row(params![pattern], |r| r.get(0))?;
        let weight = if zero_absent && df == 0 {
            0.0
        } else {
            (((n + 1) as f32) / ((df + 1) as f32)).ln().max(0.0)
        };
        idf.insert(token.clone(), weight);
    }
    Ok(idf)
}

/// v1.0.0: the IDF-weighted fraction of the query's discriminating power that
/// `summary` lexically covers, in `[0,1]`. Tokens present in the haystack
/// contribute their IDF weight to the numerator; all tokens contribute to the
/// denominator. A summary that matches only the query's low-IDF (common)
/// words scores near 0; one that matches the rare, topical words scores near
/// 1. Returns 0 when the total weight is ~0 (all tokens ubiquitous).
fn weighted_coverage(content: &[String], idf: &HashMap<String, f32>, summary: &str) -> f32 {
    let haystack = summary.to_ascii_lowercase();
    let mut total = 0.0f32;
    let mut hit = 0.0f32;
    for token in content {
        let weight = idf.get(token).copied().unwrap_or(0.0);
        total += weight;
        if weight > 0.0 && haystack.contains(token.as_str()) {
            hit += weight;
        }
    }
    if total <= f32::EPSILON {
        0.0
    } else {
        (hit / total).clamp(0.0, 1.0)
    }
}

/// v1.0.0: light query-side stemming — strip the common English inflection
/// suffixes so "benchmarked"/"benchmarking" reduce to "benchmark". Because
/// downstream matching uses substring lexical hints and FTS-prefix document
/// frequencies (`fts_query` also appends `*`), the
/// stem matches every variant in the corpus while the inflected form matches
/// none of them — an unstemmed "benchmarked" gets df=0, loses all IDF
/// weight, and the relevance floor goes blind on the query's one
/// discriminating word. Haystacks stay raw; only query tokens are stemmed.
/// Conservative: a suffix is stripped only when ≥4 chars remain, and only
/// one suffix is stripped.
///
/// v2.6: plus the English y→ies rule, which the suffix list alone gets wrong in
/// both directions. `"retries"` strips `es` to `retri`; `"retry"` matches no
/// suffix and stays `retry`; neither is a prefix of the other, so a query
/// asking about `retry` treats a corpus that says `retries` as not mentioning
/// it at all. BrainBench's sycophancy track found this by flagging a gap on a
/// question the memories plainly answered — the same defect silently costs the
/// lexical floor its IDF weight on any `-y` word (`query`, `policy`, `memory`,
/// `binary`), which is a large share of the vocabulary this corpus is made of.
///
/// Stripping a trailing `y`/`i` after a consonant collapses both forms onto the
/// shared prefix (`retry`, `retries` → `retr`), which is what substring and
/// FTS-prefix matching need. Only after a consonant, so `day`/`key` keep their
/// vowel-`y`, and only with ≥4 chars remaining, so short words are left alone.
fn light_stem(token: &str) -> &str {
    let mut stem = token;
    for suffix in ["ing", "ed", "es", "s"] {
        if let Some(stripped) = token.strip_suffix(suffix)
            && stripped.len() >= 4
        {
            stem = stripped;
            break;
        }
    }
    if stem.len() >= 5
        && let Some(trimmed) = stem.strip_suffix('y').or_else(|| stem.strip_suffix('i'))
        && trimmed
            .chars()
            .next_back()
            .is_some_and(|c| !matches!(c, 'a' | 'e' | 'i' | 'o' | 'u'))
    {
        return trimmed;
    }
    stem
}

fn query_tokens(query: &str) -> Vec<String> {
    let mut tokens: Vec<String> = query
        .split(|ch: char| !ch.is_ascii_alphanumeric() && ch != '_')
        .map(str::trim)
        .filter(|part| part.len() >= 2)
        .map(str::to_ascii_lowercase)
        .map(|t| light_stem(&t).to_string())
        .collect();
    // MP-17 #11: task-class routing — augment the query with tool-aware
    // tokens so MP-17b's tool-proficiency capsules surface higher when
    // the task description matches a known class. Cheap keyword fan-out;
    // the underlying lexical_relevance counts substring matches so the
    // augmented tokens only matter when a capsule's text actually mentions
    // them (i.e. the new MP-17b capsules light up, not generic text).
    let lower = query.to_ascii_lowercase();
    for (triggers, expansions) in CLASS_HINTS.iter() {
        if triggers.iter().any(|t| lower.contains(t)) {
            tokens.extend(expansions.iter().map(|e| e.to_string()));
        }
    }
    tokens
}

// MP-17 #11: (trigger keywords, expansion tokens) pairs.
//
// When the user task mentions a trigger, we add the expansions to the
// query token set. Capsules whose text mentions the same expansions
// then score higher on lexical_relevance. The expansions are kimetsu
// tool / concept names so MP-17b capsules (which document those tools)
// surface preferentially.
const CLASS_HINTS: &[(&[&str], &[&str])] = &[
    (
        &[
            "build",
            "compile",
            "make",
            "cargo",
            "cmake",
            "configure",
            "install",
            "train",
            "benchmark",
            "test suite",
            "ray trace",
            "render",
        ],
        &[
            "shell_background",
            "shell_status",
            "shell_output",
            "shell_stop",
            "long_running",
        ],
    ),
    (
        &[
            "edit", "modify", "change", "fix", "update", "patch", "refactor", "rename",
        ],
        &["edit_file", "apply_patch", "old_string", "new_string"],
    ),
    (
        &[
            "read", "inspect", "review", "analyze", "examine", "view", "show",
        ],
        &["read_file", "offset", "limit", "multi_read"],
    ),
    (
        &["find", "locate", "search", "look up", "discover", "list"],
        &["glob", "search_files", "list_files"],
    ),
    (
        &["plan", "step", "checklist", "todo", "task list", "phase"],
        &["plan", "todos"],
    ),
    (
        &[
            "verify",
            "check",
            "ensure",
            "validate",
            "pass test",
            "verifier",
        ],
        &["finish", "verifier", "verification"],
    ),
    (
        &[
            "image",
            "png",
            "jpeg",
            "jpg",
            "pdf",
            "diagram",
            "screenshot",
        ],
        &["view_image", "base64", "sha256"],
    ),
    (&["delete", "remove", "rm "], &["delete_file", "recursive"]),
    (&["rename", "move file", "mv "], &["move_file"]),
];

/// v0.8: does a capsule satisfy a requested (memory) kind? Repo/manifest
/// capsules match only by their literal `kind`; memory capsules
/// (`kind == "memory"`) match against the real kind embedded in their
/// `"scope:kind - text"` summary prefix.
fn capsule_matches_kind(capsule: &ContextCapsule, wanted: &str) -> bool {
    if capsule.kind == wanted {
        return true;
    }
    if capsule.kind == "memory"
        && let Some((prefix, _)) = capsule.summary.split_once(" - ")
        && let Some((_scope, mkind)) = prefix.split_once(':')
    {
        return mkind == wanted;
    }
    false
}

pub(crate) fn fts_query(query: &str) -> Option<String> {
    let tokens = query_tokens(query);
    if tokens.is_empty() {
        return None;
    }
    Some(
        tokens
            .into_iter()
            .take(12)
            .map(|token| format!("{token}*"))
            .collect::<Vec<_>>()
            .join(" OR "),
    )
}

/// D1e: candidate-stage MMR using embedding cosine similarity as the
/// redundancy measure, with Jaccard-of-summary-tokens as the fallback
/// when either candidate lacks an embedding vector.
///
/// Called BEFORE the candidate→capsule conversion so the `Candidate`
/// embedding fields are still accessible. Input must already be sorted
/// by descending score (the pipeline sorts before calling this).
///
/// Redundancy measure:
///   * Both candidates have embeddings of the same model → cosine(a, b).
///     cosine ∈ [-1, 1]; we use it directly as the overlap penalty.
///     Two paraphrases ("prefer rg" / "use ripgrep") will typically
///     share high cosine (≥0.85) and collapse to one slot.
///   * Either candidate lacks an embedding → Jaccard of summary-token
///     sets, scaled by 0.5 for cross-kind pairs (mirrors the existing
///     capsule-stage logic).
///
/// Cross-kind pairs are penalized at half the same-kind rate for both
/// measures (consistent with the capsule-stage Jaccard MMR).
fn apply_candidate_mmr_diversity(mut sorted: Vec<Candidate>, lambda: f32) -> Vec<Candidate> {
    if sorted.len() <= 1 {
        return sorted;
    }
    // Pre-tokenize summaries for the Jaccard fallback.
    let summaries: Vec<std::collections::HashSet<String>> = sorted
        .iter()
        .map(|c| summary_token_set(&c.capsule.summary))
        .collect();

    let mut picked_indices: Vec<usize> = Vec::with_capacity(sorted.len());
    let mut remaining: Vec<usize> = (0..sorted.len()).collect();

    // Seed with the highest-scoring candidate.
    picked_indices.push(remaining.remove(0));

    while !remaining.is_empty() {
        let mut best_idx_in_remaining = 0;
        let mut best_score = f32::MIN;

        for (i, &cand) in remaining.iter().enumerate() {
            let mut max_overlap = 0.0f32;
            for &p in &picked_indices {
                // Compute redundancy between candidate `cand` and
                // already-picked `p`.
                let same_kind = sorted[cand].capsule.kind == sorted[p].capsule.kind;
                let raw_overlap = candidate_pair_overlap(
                    &sorted[cand],
                    &sorted[p],
                    &summaries[cand],
                    &summaries[p],
                );
                let overlap = if same_kind {
                    raw_overlap
                } else {
                    raw_overlap * 0.5
                };
                if overlap > max_overlap {
                    max_overlap = overlap;
                }
            }
            let mmr = lambda * sorted[cand].capsule.score - (1.0 - lambda) * max_overlap;
            if mmr > best_score {
                best_score = mmr;
                best_idx_in_remaining = i;
            }
        }
        picked_indices.push(remaining.remove(best_idx_in_remaining));
    }

    // Reconstruct in picked order.
    let mut taken: Vec<Option<Candidate>> = sorted.drain(..).map(Some).collect();
    let mut out = Vec::with_capacity(taken.len());
    for idx in picked_indices {
        if let Some(c) = taken[idx].take() {
            out.push(c);
        }
    }
    out
}

/// D1e: overlap between two candidates for MMR.
///
/// * Both have embeddings → cosine similarity (clamped to [0,1] to
///   treat anti-correlated vectors as non-redundant, not negatively
///   redundant).
/// * Either lacks an embedding → Jaccard of summary-token sets.
fn candidate_pair_overlap(
    a: &Candidate,
    b: &Candidate,
    tokens_a: &std::collections::HashSet<String>,
    tokens_b: &std::collections::HashSet<String>,
) -> f32 {
    if let (Some(va), Some(vb)) = (a.embedding.as_deref(), b.embedding.as_deref()) {
        // Cosine in [-1,1]; clamp to [0,1] so negative correlation
        // (very different content) contributes 0 overlap rather than
        // a negative penalty (which would spuriously boost unrelated
        // content over moderately-related content).
        cosine_similarity(va, vb).max(0.0)
    } else {
        jaccard(tokens_a, tokens_b)
    }
}

/// MP-17 #13: greedy MMR (Maximal Marginal Relevance) re-ranking.
///
/// Given capsules already sorted by relevance score, walk the list and
/// at each step pick the next capsule that maximizes
/// `lambda * score - (1 - lambda) * max_overlap_with_already_picked`.
///
/// Overlap = Jaccard similarity of the lowercased token sets of the
/// `summary` field. Capsules from different kinds (memory / repo_file /
/// manifest) get a 0.5 similarity floor so redundancy is only penalized
/// within-kind (a memory and a repo_file aren't really redundant even
/// if they share words).
fn apply_mmr_diversity(mut sorted: Vec<ContextCapsule>, lambda: f32) -> Vec<ContextCapsule> {
    if sorted.len() <= 1 {
        return sorted;
    }
    // Pre-tokenize summaries for cheap Jaccard.
    let summaries: Vec<std::collections::HashSet<String>> = sorted
        .iter()
        .map(|c| summary_token_set(&c.summary))
        .collect();
    let mut picked_indices: Vec<usize> = Vec::with_capacity(sorted.len());
    let mut remaining: Vec<usize> = (0..sorted.len()).collect();

    // Always seed with the top-scoring capsule.
    picked_indices.push(remaining.remove(0));

    while !remaining.is_empty() {
        let mut best_idx_in_remaining = 0;
        let mut best_score = f32::MIN;
        for (i, &cand) in remaining.iter().enumerate() {
            let mut max_overlap = 0.0f32;
            for &p in &picked_indices {
                let raw = jaccard(&summaries[cand], &summaries[p]);
                let overlap = if sorted[cand].kind == sorted[p].kind {
                    raw
                } else {
                    // cross-kind: scale down so we don't over-penalize a memory
                    // that happens to share words with a repo file.
                    raw * 0.5
                };
                if overlap > max_overlap {
                    max_overlap = overlap;
                }
            }
            let mmr = lambda * sorted[cand].score - (1.0 - lambda) * max_overlap;
            if mmr > best_score {
                best_score = mmr;
                best_idx_in_remaining = i;
            }
        }
        picked_indices.push(remaining.remove(best_idx_in_remaining));
    }
    // Reorder `sorted` to match picked_indices.
    let mut out = Vec::with_capacity(sorted.len());
    // We need to drain in picked_indices order; do it by taking with mem::replace.
    let mut taken: Vec<Option<ContextCapsule>> = sorted.drain(..).map(Some).collect();
    for idx in picked_indices {
        if let Some(c) = taken[idx].take() {
            out.push(c);
        }
    }
    out
}

fn summary_token_set(s: &str) -> std::collections::HashSet<String> {
    s.split(|ch: char| !ch.is_ascii_alphanumeric() && ch != '_')
        .filter(|t| t.len() >= 3)
        .map(str::to_ascii_lowercase)
        .collect()
}

fn jaccard(a: &std::collections::HashSet<String>, b: &std::collections::HashSet<String>) -> f32 {
    if a.is_empty() && b.is_empty() {
        return 0.0;
    }
    let intersection = a.intersection(b).count();
    let union = a.union(b).count();
    intersection as f32 / union.max(1) as f32
}

fn lexical_relevance(tokens: &[String], haystack: &str) -> f32 {
    if tokens.is_empty() {
        return 0.0;
    }
    let haystack = haystack.to_ascii_lowercase();
    let matches = tokens
        .iter()
        .filter(|token| haystack.contains(token.as_str()))
        .count();
    matches as f32 / tokens.len() as f32
}

pub fn estimate_tokens(text: &str) -> u32 {
    ((text.split_whitespace().count() as f32) * 1.33).ceil() as u32
}

// -----------------------------------------------------------------------
// v1.5 (Story 2.1): render-time capsule compression
// -----------------------------------------------------------------------

/// Render-time compression: strips the `[tags: ...]` prefix and the trailing
/// `(context: ...)` suffix, then caps at the first `max_sentences` sentences.
///
/// **Architectural invariant**: this function is called ONLY at render time —
/// after retrieval and reranking. Ranking inputs, stored `summary` text, and
/// the eval/bench retrieval paths are never affected. The full text stays
/// available via `expansion_handle`.
///
/// Sentence splitting uses `". "` / `".\n"` boundaries (simple, reliable,
/// UTF-8-safe). Common abbreviation edge cases are deliberately NOT handled —
/// the savings far outweigh an occasional mid-abbreviation split.
///
/// The `scope:kind - ` prefix that memory summaries carry (e.g.
/// `"project:fact - Some lesson here."`) is preserved: compression applies
/// only to the text *after* the ` - ` separator.
///
/// Fallback: never returns an empty string — when trimming would leave nothing,
/// the original input is returned unchanged.
pub fn compress_for_render(summary: &str, max_sentences: usize) -> String {
    if max_sentences == 0 {
        return summary.to_string();
    }

    // ── 1. Strip [tags: ...] prefix (if present) ─────────────────────────
    let text = if let Some(rest) = summary.strip_prefix('[') {
        // Find the closing ']' followed by optional whitespace
        if let Some(idx) = rest.find(']') {
            rest[idx + 1..].trim_start()
        } else {
            summary
        }
    } else {
        summary
    };

    // ── 2. Strip (context: ...) suffix (if present) ──────────────────────
    let text = if let Some(idx) = text.rfind('(') {
        let candidate = text[..idx].trim_end();
        // Only strip if the parenthetical looks like a trailing annotation
        // (contains a ':' inside), to avoid stripping content parentheses.
        let inner = &text[idx + 1..];
        if inner.contains(':') && inner.trim_end().ends_with(')') {
            candidate
        } else {
            text
        }
    } else {
        text
    };

    // ── 3. Detect and preserve "scope:kind - " prefix ────────────────────
    let (scope_prefix, body) = if let Some(dash_pos) = text.find(" - ") {
        let prefix_candidate = &text[..dash_pos];
        // Must look like "word:word" (no spaces in the prefix part)
        if !prefix_candidate.contains(' ') && prefix_candidate.contains(':') {
            let body_start = dash_pos + 3; // len(" - ")
            (&text[..body_start], &text[body_start..])
        } else {
            ("", text)
        }
    } else {
        ("", text)
    };

    // ── 4. Cap at max_sentences on the body ──────────────────────────────
    let compressed_body = cap_sentences(body, max_sentences);

    // ── 5. Reassemble; fallback to original if result would be empty ─────
    let result = if scope_prefix.is_empty() {
        compressed_body.to_string()
    } else {
        format!("{scope_prefix}{compressed_body}")
    };

    if result.trim().is_empty() {
        summary.to_string()
    } else {
        result
    }
}

/// Return the first `n` sentences from `text`, where sentences end at
/// `". "` or `".\n"` boundaries. The terminal period is included in the
/// returned slice. If fewer than `n` sentences exist the full text is returned.
fn cap_sentences(text: &str, n: usize) -> &str {
    let bytes = text.as_bytes();
    let len = bytes.len();
    let mut count = 0;
    let mut i = 0;
    while i < len {
        // Look for ". " or ".\n" — a period followed by whitespace.
        if bytes[i] == b'.' {
            let next = i + 1;
            if next < len && (bytes[next] == b' ' || bytes[next] == b'\n') {
                count += 1;
                if count >= n {
                    // Include the period, trim trailing whitespace on the slice.
                    return text[..=i].trim_end();
                }
            }
        }
        i += 1;
    }
    // Fewer than n sentences — return the whole text.
    text.trim_end()
}

fn excerpt(text: &str) -> String {
    let value = one_line(text);
    value.chars().take(256).collect()
}

fn one_line(text: &str) -> String {
    text.split_whitespace().collect::<Vec<_>>().join(" ")
}

// -----------------------------------------------------------------------
// F2: capsule resolver — expand a headline handle to its full text.
// -----------------------------------------------------------------------

/// Maximum bytes returned when resolving a `file:` handle. Keeps large
/// source files from flooding the context window on a single expand call.
const FILE_EXPAND_CAP_BYTES: usize = 2048;

/// F2: resolve an expansion handle to its full text content.
///
/// Handles:
/// - `memory:<id>` → `SELECT text FROM memories WHERE memory_id = ?`
/// - `file:<path>` → read `repo_root/<path>`, capped at [`FILE_EXPAND_CAP_BYTES`]
/// - `run:<id>`    → deferred; returns a descriptive error
/// - anything else → returns a descriptive error
///
/// This is the resolver that the `expand_capsule` agent tool delegates to.
/// All errors are user-visible (returned to the agent as a tool-result
/// error string) and never crash the dispatch loop.
pub fn resolve_capsule(
    conn: &Connection,
    repo_root: &std::path::Path,
    handle: &str,
) -> kimetsu_core::KimetsuResult<String> {
    if let Some(memory_id) = handle.strip_prefix("memory:") {
        // SELECT the raw text from the memories table.
        let mut stmt = conn.prepare_cached(
            "SELECT text FROM memories WHERE memory_id = ? AND invalidated_at IS NULL",
        )?;
        let text: Option<String> = stmt
            .query_row(rusqlite::params![memory_id], |row| row.get(0))
            .optional()?;
        match text {
            Some(t) => Ok(t),
            None => {
                Err(format!("expand_capsule: no active memory found for handle `{handle}`").into())
            }
        }
    } else if let Some(rel_path) = handle.strip_prefix("file:") {
        // Sanitize: reject absolute paths (drive-letter or Unix-root) and
        // `..` traversal. On Windows, POSIX-style `/foo` paths are not
        // considered absolute by `is_absolute()` (no drive prefix), so we
        // also reject paths with a RootDir component.
        let path = std::path::Path::new(rel_path);
        if path.is_absolute() {
            return Err(format!(
                "expand_capsule: `{handle}` is an absolute path — only repo-relative paths are supported"
            )
            .into());
        }
        for component in path.components() {
            match component {
                std::path::Component::ParentDir => {
                    return Err(format!(
                        "expand_capsule: `{handle}` contains `..` traversal — rejected"
                    )
                    .into());
                }
                std::path::Component::RootDir | std::path::Component::Prefix(_) => {
                    return Err(format!(
                        "expand_capsule: `{handle}` is an absolute path — only repo-relative paths are supported"
                    )
                    .into());
                }
                _ => {}
            }
        }
        let full_path = repo_root.join(path);
        let bytes = std::fs::read(&full_path)
            .map_err(|e| format!("expand_capsule: could not read `{rel_path}`: {e}"))?;
        // Bound the returned slice so huge files don't blow the context window.
        let bounded = if bytes.len() > FILE_EXPAND_CAP_BYTES {
            let mut end = FILE_EXPAND_CAP_BYTES;
            // Snap back to a UTF-8 boundary so we don't slice mid-codepoint.
            while end > 0 && (bytes[end] & 0xC0) == 0x80 {
                end -= 1;
            }
            let s = String::from_utf8_lossy(&bytes[..end]);
            format!(
                "{s}\n[... truncated at {FILE_EXPAND_CAP_BYTES} bytes; call expand_capsule again with a line range if needed]"
            )
        } else {
            String::from_utf8_lossy(&bytes).into_owned()
        };
        Ok(bounded)
    } else if handle.starts_with("run:") {
        Err(format!(
            "expand_capsule: `run:` handle expansion is not yet supported (handle: `{handle}`)"
        )
        .into())
    } else {
        Err(format!(
            "expand_capsule: unrecognised handle format `{handle}`; \
             expected `memory:<id>`, `file:<path>`, or `run:<id>`"
        )
        .into())
    }
}

// ── v1.0.0: cross-encoder reranking ──────────────────────────────────────

/// v1.0.0: final-stage cross-encoder rerank over already-retrieved capsules.
/// Reranks by `summary`, overwrites `score` with the sigmoid-normalized
/// rerank score, sorts descending, drops capsules below `floor`, truncates
/// to `cap` (0 = no cap). Fail-open: on a rerank error the input ordering
/// is returned unchanged (truncated to `cap`) — a broken reranker must
/// never lose retrieval entirely.
/// v2.7: width of the evidence band below `abstain_evidence` in which the
/// cross-encoder arbitrates instead of the raw cosine. Below
/// `abstain_evidence - ABSTAIN_BAND_WIDTH` the retrieval hard-abstains.
pub const ABSTAIN_BAND_WIDTH: f32 = 0.10;

fn abstain_band_width() -> f32 {
    std::env::var("KIMETSU_ABSTAIN_BAND_WIDTH")
        .ok()
        .and_then(|v| v.parse::<f32>().ok())
        .unwrap_or(ABSTAIN_BAND_WIDTH)
        .clamp(0.0, 1.0)
}

/// v2.7: default cross-encoder score a band bundle must reach to be injected.
/// Swept on the workflow benchmark (ms-marco-tinybert, n=150/floor): recall
/// was FLAT from 0.3 through 0.95 (useful-hit 0.80 → 0.79) while
/// false-injection fell monotonically (0.32 → 0.24) — genuinely relevant band
/// bundles saturate the tinybert sigmoid, junk does not. 0.9 takes most of
/// that precision and leaves margin for cross-encoders whose scores don't
/// saturate as hard. Overridable via `KIMETSU_ABSTAIN_RERANK_FLOOR`.
pub const ABSTAIN_RERANK_FLOOR: f32 = 0.9;

fn abstain_rerank_floor() -> f32 {
    std::env::var("KIMETSU_ABSTAIN_RERANK_FLOOR")
        .ok()
        .and_then(|v| v.parse::<f32>().ok())
        .unwrap_or(ABSTAIN_RERANK_FLOOR)
}

/// v2.7: post-retrieval reranking + evidence-band arbitration, shared by every
/// call site that owns a cross-encoder (CLI `brain context`, MCP server, embed
/// daemon).
///
/// The retrieval pipeline hard-abstains below `abstain_evidence -`
/// [`ABSTAIN_BAND_WIDTH`] and returns bundles above it. This helper decides
/// the band in between: the cross-encoder rescoring recognizes paraphrased
/// matches that raw bi-encoder cosine under-scores, so a band bundle whose
/// best rerank score clears [`ABSTAIN_RERANK_FLOOR`] is injected and one that
/// doesn't is converted to a skipped (zero-token) bundle. Out-of-band bundles
/// are reranked for ordering but never converted.
///
/// With no reranker available the band FAILS CLOSED (skipped) — equivalent to
/// the plain hard gate at `abstain_evidence` — so a lean build is never
/// noisier than the gate promises. Bundles containing non-memory capsules are
/// never converted (repo evidence stands on its own), and `abstain_evidence
/// <= 0` disables arbitration entirely.
pub fn rerank_and_arbitrate(
    query: &str,
    mut bundle: ContextBundle,
    reranker: Option<&dyn crate::embeddings::Reranker>,
    abstain_evidence: f32,
    rerank_floor: f32,
    rerank_cap: usize,
) -> ContextBundle {
    if bundle.skipped || bundle.capsules.is_empty() {
        return bundle;
    }
    let memory_only = bundle.capsules.iter().all(|c| c.kind == "memory");
    // top_abs_evidence < 0.0 means "no cosine evidence exists" (lean builds,
    // cross-model rows) — the band is a cosine construct, so it is exempt.
    let in_band = abstain_evidence > 0.0
        && memory_only
        && bundle.top_abs_evidence >= 0.0
        && bundle.top_abs_evidence < abstain_evidence;

    let to_skipped = |mut bundle: ContextBundle| -> ContextBundle {
        let rejected = std::mem::take(&mut bundle.capsules);
        bundle.excluded.extend(rejected);
        bundle.skipped = true;
        bundle.used_tokens = 0;
        bundle.evidence_coverage = 0.0;
        bundle.uncovered_terms = Vec::new();
        bundle.chronological = false;
        bundle
    };

    match reranker {
        Some(rr) => {
            let reranked = rerank_capsules_with_diagnostics(
                query,
                std::mem::take(&mut bundle.capsules),
                rr,
                rerank_floor,
                rerank_cap,
            );
            // Admission is calibrated on the RAW cross-encoder score, before
            // ranking policy is applied. Otherwise usefulness or supersession
            // could silently alter abstention behavior.
            let best_raw_rerank = reranked.best_raw_score.unwrap_or(0.0);
            bundle.capsules = reranked.capsules;
            bundle.used_tokens = bundle.capsules.iter().map(|c| c.token_estimate).sum();
            if in_band && best_raw_rerank < abstain_rerank_floor() {
                to_skipped(bundle)
            } else {
                bundle
            }
        }
        // No arbiter: the band fails closed, matching the hard gate.
        None if in_band => to_skipped(bundle),
        None => bundle,
    }
}

pub fn rerank_capsules(
    query: &str,
    capsules: Vec<ContextCapsule>,
    reranker: &dyn crate::embeddings::Reranker,
    floor: f32,
    cap: usize,
) -> Vec<ContextCapsule> {
    rerank_capsules_with_diagnostics(query, capsules, reranker, floor, cap).capsules
}

struct RerankOutcome {
    capsules: Vec<ContextCapsule>,
    /// Best raw cross-encoder score among capsules that survived the ranking
    /// floor.
    /// `None` means the reranker did not produce a usable verdict.
    best_raw_score: Option<f32>,
}

fn effective_rerank_policy_tier(capsule: &ContextCapsule) -> i8 {
    // A superseded memory must not retain a historic citation advantage over
    // its replacement. Its explicit post-rerank penalty carries that policy.
    if capsule.superseded_hint {
        0
    } else {
        capsule.rerank_policy_tier
    }
}

fn rerank_capsules_with_diagnostics(
    query: &str,
    capsules: Vec<ContextCapsule>,
    reranker: &dyn crate::embeddings::Reranker,
    floor: f32,
    cap: usize,
) -> RerankOutcome {
    if capsules.is_empty() {
        return RerankOutcome {
            capsules,
            best_raw_score: None,
        };
    }

    // Rerank on the FULL summary. Truncating to a snippet was tried for
    // latency and measurably cratered quality on the eval fixture
    // (recall@4 0.83 → 0.66, below even FTS) — the cross-encoder needs the
    // whole lesson to judge relevance. Reranking is therefore a
    // quality-over-latency opt-in, not part of the hook's 300ms budget.
    let docs: Vec<&str> = capsules.iter().map(|c| c.summary.as_str()).collect();
    let scores = match reranker.rerank(query, &docs) {
        // The trait contract is one score per doc in doc order; a custom
        // third-party reranker that returns a short vec would otherwise
        // silently drop the unscored tail via the zip below — treat a
        // length mismatch as an error and fail open instead.
        Ok(s) if s.len() == docs.len() => s,
        _ => {
            // Fail-open: preserve input order, just apply cap.
            let mut out = capsules;
            if cap > 0 && out.len() > cap {
                out.truncate(cap);
            }
            return RerankOutcome {
                capsules: out,
                best_raw_score: None,
            };
        }
    };

    // Apply bounded usefulness, then trust and supersession; admission uses raw scores.
    let mut ranked: Vec<(ContextCapsule, f32)> = capsules
        .into_iter()
        .zip(scores)
        .map(|(mut c, s)| {
            let multiplier = if c.superseded_hint {
                1.0
            } else {
                c.rerank_usefulness
                    .unwrap_or(1.0 + 0.5 * effective_rerank_policy_tier(&c) as f32)
            };
            c.score = apply_usefulness_boost(s, multiplier.clamp(0.5, 1.5))
                * c.rerank_trust.unwrap_or(1.0).clamp(0.0, 1.0);
            if c.superseded_hint {
                c.score *= SUPERSESSION_PENALTY;
            }
            (c, s)
        })
        .collect();

    ranked.sort_by(|a, b| b.0.score.total_cmp(&a.0.score));

    // This is the ordinary per-capsule retention floor. The separate
    // evidence-band decision reads `best_raw_score` before the supersession
    // policy is reapplied, because its 0.9 threshold was calibrated on the
    // cross-encoder's sigmoid scale.
    ranked.retain(|(_, raw_score)| *raw_score >= floor);

    // Admission evidence is independent of policy ordering and output cap.
    // A high-confidence neutral capsule displaced by a cited one still proves
    // that the in-band bundle has relevant evidence.
    let best_raw_score = ranked
        .iter()
        .map(|(_, raw_score)| *raw_score)
        .max_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));

    if cap > 0 && ranked.len() > cap {
        ranked.truncate(cap);
    }

    RerankOutcome {
        capsules: ranked.into_iter().map(|(c, _)| c).collect(),
        best_raw_score,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn capsule(kind: &str, summary: &str) -> ContextCapsule {
        ContextCapsule {
            id: "c".into(),
            kind: kind.into(),
            summary: summary.into(),
            token_estimate: 1,
            expansion_handle: "memory:x".into(),
            provenance: vec![],
            confidence: 1.0,
            freshness: 1.0,
            relevance: 1.0,
            scope_weight: 1.0,
            score: 1.0,
            superseded_hint: false,
            rerank_policy_tier: 0,
            claim_revision: None,
            facts: vec![],
            rerank_usefulness: None,
            rerank_trust: None,
        }
    }

    /// Create a unique temp directory under the system temp path.
    /// Named by `tag` so test failures are diagnosable.
    fn make_test_dir(tag: &str) -> std::path::PathBuf {
        use std::time::{SystemTime, UNIX_EPOCH};
        let ts = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map(|d| d.subsec_nanos())
            .unwrap_or(0);
        let dir = std::env::temp_dir().join(format!("kbrain_test_{tag}_{ts}"));
        std::fs::create_dir_all(&dir).expect("create test dir");
        dir
    }

    #[test]
    fn capsule_matches_kind_reads_memory_summary_prefix() {
        // Memory capsule: real kind lives in the "scope:kind - text" prefix.
        let mem = capsule("memory", "project:failure_pattern - linker not found");
        assert!(capsule_matches_kind(&mem, "failure_pattern"));
        assert!(!capsule_matches_kind(&mem, "command"));
        // Non-memory capsules match only by literal kind, never via prefix.
        let repo = capsule("repo_file", "src/lib.rs:command - run build");
        assert!(capsule_matches_kind(&repo, "repo_file"));
        assert!(!capsule_matches_kind(&repo, "command"));
    }

    /// MP-17e: zero-use rows are neutral (no data); use_count >= 1 starts
    /// blending toward the full multiplier (Bayesian smoothing).
    #[test]
    fn usefulness_multiplier_neutral_at_zero_uses() {
        // use_count = 0 is the only strictly-neutral case.
        assert!((usefulness_multiplier(0.0, 0) - 1.0).abs() < f32::EPSILON);
        assert!((usefulness_multiplier(5.0, 0) - 1.0).abs() < f32::EPSILON);
        assert!((usefulness_multiplier(-5.0, 0) - 1.0).abs() < f32::EPSILON);
    }

    /// MP-17e: between use_count 1..3 the multiplier blends linearly from
    /// neutral (1.0) toward the full envelope. A use_count of 2 with a
    /// perfect ratio lands at 2/3 of the way to the max boost.
    #[test]
    fn usefulness_multiplier_blends_smoothly_in_transition() {
        // use_count = 1, ratio = 1.0 -> confidence 1/3, blend toward 1.5
        // expected = 1.0 * 2/3 + 1.5 * 1/3 = 1.1667
        let one_use = usefulness_multiplier(1.0, 1);
        assert!((one_use - 1.166_666_6).abs() < 1e-4, "got {one_use}");
        // use_count = 2, ratio = 1.0 -> confidence 2/3, blend toward 1.5
        // expected = 1.0 * 1/3 + 1.5 * 2/3 = 1.3333
        let two_uses = usefulness_multiplier(2.0, 2);
        assert!((two_uses - 1.333_333_4).abs() < 1e-4, "got {two_uses}");
        // use_count = 2 with ratio = -1.0 should pull toward the penalty side.
        let two_uses_bad = usefulness_multiplier(-2.0, 2);
        // expected = 1.0 * 1/3 + 0.5 * 2/3 = 0.6667
        assert!(
            (two_uses_bad - 0.666_666_7).abs() < 1e-4,
            "got {two_uses_bad}"
        );
    }

    /// MP-4b: at use_count >= 3 the multiplier maps ratio in [-1, 1] linearly
    /// onto [MULTIPLIER_MIN, MULTIPLIER_MAX] = [0.5, 1.5]. A neutral memory
    /// (ratio = 0) gets a 1.0 multiplier.
    #[test]
    fn usefulness_multiplier_maps_ratio_onto_envelope() {
        // ratio = 1.0 -> 1.5 (max boost)
        assert!((usefulness_multiplier(5.0, 5) - 1.5).abs() < f32::EPSILON);
        // ratio = -1.0 -> 0.5 (max penalty)
        assert!((usefulness_multiplier(-5.0, 5) - 0.5).abs() < f32::EPSILON);
        // ratio = 0.0 -> 1.0 (neutral)
        let mid = usefulness_multiplier(0.0, 6);
        assert!((mid - 1.0).abs() < f32::EPSILON, "got {mid}");
        // ratio = 0.5 -> 1.25 (mid boost)
        let high = usefulness_multiplier(2.0, 4);
        assert!((high - 1.25).abs() < f32::EPSILON, "got {high}");
        // ratio = -0.5 -> 0.75 (mid penalty)
        let low = usefulness_multiplier(-2.0, 4);
        assert!((low - 0.75).abs() < f32::EPSILON, "got {low}");
    }

    /// MP-4b: the multiplier is bounded so even a runaway score cannot
    /// dominate the budget; a single memory with usefulness_score >> use_count
    /// is clamped at the upper envelope.
    #[test]
    fn usefulness_multiplier_clamps_to_envelope() {
        // ratio > 1.0 is clamped to 1.0 -> 1.5
        assert!((usefulness_multiplier(100.0, 5) - 1.5).abs() < f32::EPSILON);
        // ratio < -1.0 is clamped to -1.0 -> 0.5
        assert!((usefulness_multiplier(-100.0, 5) - 0.5).abs() < f32::EPSILON);
    }

    // ----- v2.5.1: citation-boost saturation (LoCoMo k=5 collapse fix) -----

    /// The boost's absolute gain is capped: a max-boosted (1.5x) weakly
    /// relevant memory must NOT outrank a strongly relevant uncited one.
    /// This is the exact inversion observed in the LoCoMo learning run
    /// (junk at raw 0.39 x 1.5 = 0.58 beat a true match at 0.53).
    #[test]
    fn boost_gain_is_capped_so_cited_junk_cannot_beat_relevant_uncited() {
        let junk = apply_usefulness_boost(0.39, 1.5);
        let true_match = apply_usefulness_boost(0.53, 1.0);
        assert!(
            junk < true_match,
            "capped boost must preserve relevance order: junk {junk} vs match {true_match}"
        );
        // gain never exceeds the cap
        assert!(junk <= 0.39 + USEFULNESS_BOOST_CAP + f32::EPSILON);
    }

    /// Within a relevance band the boost still reorders: a proven memory at
    /// slightly lower relevance may overtake a neutral near-equal. This is
    /// the behaviour that produced the +4.6 holdout gain and must survive.
    #[test]
    fn boost_still_reorders_within_a_relevance_band() {
        let proven = apply_usefulness_boost(0.85, 1.5);
        let neutral = apply_usefulness_boost(0.90, 1.0);
        assert!(
            proven > neutral,
            "capped boost must still reorder near-equals: proven {proven} vs neutral {neutral}"
        );
    }

    /// Penalties stay multiplicative: suppressing net-negative memories
    /// below their raw relevance is desirable and unbounded-downward is safe
    /// (floor 0.5x from the multiplier envelope).
    #[test]
    fn penalty_side_remains_multiplicative() {
        let penalized = apply_usefulness_boost(0.8, 0.5);
        assert!((penalized - 0.4).abs() < 1e-6);
    }

    // ----- MP-17 #11: task-class query expansion -----

    #[test]
    fn query_tokens_expands_build_class() {
        let toks = query_tokens("Build the project from source");
        assert!(toks.iter().any(|t| t == "build"));
        // class-aware expansion adds tool tokens:
        assert!(toks.iter().any(|t| t == "shell_background"));
        assert!(toks.iter().any(|t| t == "long_running"));
    }

    #[test]
    fn query_tokens_expands_edit_class() {
        let toks = query_tokens("Modify the config to fix the bug");
        assert!(toks.iter().any(|t| t == "edit_file"));
        assert!(toks.iter().any(|t| t == "apply_patch"));
    }

    #[test]
    fn query_tokens_expands_search_class() {
        let toks = query_tokens("Find all references to the symbol");
        assert!(toks.iter().any(|t| t == "glob"));
        assert!(toks.iter().any(|t| t == "search_files"));
    }

    #[test]
    fn query_tokens_no_expansion_on_unrelated_query() {
        let toks = query_tokens("hello world testing nothing");
        // Only the "test" trigger fires here -> verification expansion.
        assert!(toks.iter().any(|t| t == "hello"));
        // The base tokens are present regardless.
        assert!(toks.iter().any(|t| t == "world"));
    }

    // ----- MP-17 #13: MMR diversity helpers -----

    #[test]
    fn jaccard_is_zero_for_disjoint_sets() {
        let a: std::collections::HashSet<String> =
            ["foo", "bar"].iter().map(|s| s.to_string()).collect();
        let b: std::collections::HashSet<String> =
            ["baz", "qux"].iter().map(|s| s.to_string()).collect();
        assert!((jaccard(&a, &b) - 0.0).abs() < f32::EPSILON);
    }

    #[test]
    fn jaccard_is_one_for_identical_sets() {
        let a: std::collections::HashSet<String> =
            ["foo", "bar"].iter().map(|s| s.to_string()).collect();
        let b = a.clone();
        assert!((jaccard(&a, &b) - 1.0).abs() < f32::EPSILON);
    }

    #[test]
    fn jaccard_partial_overlap() {
        let a: std::collections::HashSet<String> = ["foo", "bar", "baz"]
            .iter()
            .map(|s| s.to_string())
            .collect();
        let b: std::collections::HashSet<String> =
            ["bar", "qux"].iter().map(|s| s.to_string()).collect();
        // intersection = {bar} = 1, union = {foo,bar,baz,qux} = 4
        assert!((jaccard(&a, &b) - 0.25).abs() < f32::EPSILON);
    }

    #[test]
    fn summary_token_set_lowercases_and_filters_short() {
        let set = summary_token_set("Build the Foo-bar project");
        assert!(set.contains("build"));
        assert!(set.contains("foo"));
        assert!(set.contains("bar"));
        assert!(set.contains("project"));
        // "the" is len=3, included; "a" or "i" would be excluded.
        assert!(set.contains("the"));
    }

    // ----- v0.4.2: hybrid retrieval end-to-end -----

    /// Helper: open an in-memory brain.db, initialize schema, insert
    /// a memory row (post-projector shape) plus its embedding +
    /// embedding_model and the matching FTS entry.
    fn insert_memory_with_embedding(
        conn: &rusqlite::Connection,
        memory_id: &str,
        text: &str,
        embedder: &dyn embeddings::Embedder,
    ) {
        let normalized = kimetsu_core::memory::normalize_memory_text(text);
        conn.execute(
            "
            INSERT INTO memories (
                memory_id, scope, kind, text, normalized_text, confidence,
                source_event_id, provenance_snapshot_json, created_at,
                use_count, usefulness_score, embedding, embedding_model
            )
            VALUES (?1, 'global_user', 'fact', ?2, ?3, 1.0, NULL, '{}',
                    '2026-05-01T00:00:00Z', 0, 0.0, ?4, ?5)
            ",
            rusqlite::params![
                memory_id,
                text,
                normalized,
                embeddings::encode_embedding(&embedder.embed(text).expect("embed test row")),
                embedder.model_id(),
            ],
        )
        .expect("insert memory");
        conn.execute(
            "INSERT INTO memories_fts (memory_id, text, kind, scope) VALUES (?1, ?2, 'fact', 'global_user')",
            rusqlite::params![memory_id, text],
        )
        .expect("insert fts row");
    }

    /// v0.4.2: the cosine blend changes retrieval ranking when two
    /// memories tie lexically but differ semantically (via the stub
    /// embedder's hashed-bucket vectors).
    ///
    /// Setup: two memories, neither containing the query's literal
    /// words. With pure FTS, neither matches and we fall back to
    /// latest-memory ranking. With the stub embedder enabled, the
    /// memory that's "semantically closer" to the query (shares
    /// hash buckets) outranks the other.
    #[test]
    fn hybrid_retrieval_uses_cosine_score_to_rerank() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");
        let stub = embeddings::StubEmbedder::new();

        insert_memory_with_embedding(&conn, "m_rg", "use ripgrep for code search", &stub);
        insert_memory_with_embedding(
            &conn,
            "m_unrelated",
            "cookie recipe with chocolate chips",
            &stub,
        );

        // Query shares words with m_rg but not m_unrelated. FTS will
        // already prefer m_rg here; we use that as the baseline.
        let weights = kimetsu_core::config::BrokerWeights::default();
        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "ripgrep search".to_string(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &stub,
        )
        .expect("retrieve");

        let memory_handles: Vec<_> = bundle
            .capsules
            .iter()
            .filter(|c| c.expansion_handle.starts_with("memory:"))
            .collect();
        assert!(
            !memory_handles.is_empty(),
            "at least one memory should surface"
        );
        // The semantically-relevant memory must rank first.
        assert_eq!(
            memory_handles[0].expansion_handle,
            "memory:m_rg",
            "ripgrep memory should outrank the cookie recipe; ranked: {:?}",
            memory_handles
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );
    }

    /// v2.7: the absolute abstention gate. `top_abs_evidence` carries the best
    /// raw cosine; a floor above it skips the bundle entirely, a floor below
    /// it (or 0.0) lets the bundle through. Self-calibrating: the test reads
    /// the achieved evidence first rather than hard-coding a stub cosine.
    #[test]
    fn abstain_evidence_gate_skips_on_weak_absolute_evidence() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");
        let stub = embeddings::StubEmbedder::new();
        insert_memory_with_embedding(&conn, "m_rg", "use ripgrep for code search", &stub);

        let weights = kimetsu_core::config::BrokerWeights::default();
        let retrieve = |abstain: f32| {
            retrieve_context_with_embedder(
                &conn,
                "/fake-repo",
                &weights,
                ContextRequest {
                    stage: "localization".to_string(),
                    query: "ripgrep search".to_string(),
                    budget_tokens: 4000,
                    abstain_evidence: abstain,
                    ..Default::default()
                },
                &[],
                &stub,
            )
            .expect("retrieve")
        };

        let open = retrieve(0.0);
        assert!(!open.skipped, "gate off must not skip");
        assert!(
            open.top_abs_evidence > 0.0,
            "a matching memory must report positive absolute evidence"
        );

        // The retrieval-internal gate hard-abstains one band-width below the
        // configured floor (the band itself is decided by the caller's
        // cross-encoder via rerank_and_arbitrate).
        let above = retrieve(open.top_abs_evidence + ABSTAIN_BAND_WIDTH + 0.05);
        assert!(
            above.skipped,
            "a floor a full band above the best evidence must hard-abstain (evidence {})",
            open.top_abs_evidence
        );
        assert!(above.capsules.is_empty(), "skipped bundle injects nothing");

        // In the band: retrieval itself does NOT skip — the arbiter decides.
        let in_band = retrieve(open.top_abs_evidence + 0.05);
        assert!(
            !in_band.skipped,
            "an in-band bundle passes through for arbitration"
        );

        let below = retrieve((open.top_abs_evidence - 0.05).max(0.01));
        assert!(!below.skipped, "a floor below the best evidence passes");
        assert!(!below.capsules.is_empty());
    }

    /// v0.4.2: when a row's stored `embedding_model` doesn't match
    /// the active query embedder's id, the row's cosine contribution
    /// is skipped — falling back to FTS-only for that row. Critical
    /// for safety across `kimetsu brain reindex` migrations (v0.4.3)
    /// where some rows might be embedded with the new model and some
    /// with the old.
    #[test]
    fn hybrid_retrieval_skips_cosine_on_model_id_mismatch() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");
        let stub = embeddings::StubEmbedder::new();
        insert_memory_with_embedding(&conn, "m_xref", "use ripgrep for code search", &stub);

        // Stomp the row's embedding_model with a synthetic id that
        // doesn't match the active embedder. Simulates a `kimetsu
        // brain reindex` mid-migration where some rows are on the
        // new model and some on the old.
        conn.execute(
            "UPDATE memories SET embedding_model = 'bge-small-en-v1.5' WHERE memory_id = 'm_xref'",
            [],
        )
        .expect("force model_id mismatch");

        // Query through the stub embedder. Its model_id is "stub-d8";
        // the row's is "bge-small-en-v1.5". The cosine path MUST be
        // skipped for this row; FTS still surfaces it on the lexical
        // match because retrieval doesn't crash on cross-model rows.
        let weights = kimetsu_core::config::BrokerWeights::default();
        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "ripgrep search".to_string(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &stub,
        )
        .expect("retrieve");

        assert!(
            bundle
                .capsules
                .iter()
                .any(|c| c.expansion_handle == "memory:m_xref"),
            "cross-model row should still match lexically (cosine skipped, FTS works)"
        );
    }

    // ----- v0.5.1: usefulness decay -----

    /// v0.5.1: `half_life_days <= 0` is the operator opt-out hatch.
    /// Decay must short-circuit to 1.0 so the usefulness multiplier
    /// is unmodified — exact pre-v0.5.1 behavior for projects that
    /// set `decay_half_life_days = 0` in project.toml.
    #[test]
    fn usefulness_decay_disabled_when_half_life_is_zero_or_negative() {
        // Even a 5-year-old reference returns 1.0 with decay disabled.
        let ancient = "2021-01-01T00:00:00Z";
        assert!((usefulness_decay(Some(ancient), ancient, 0.0) - 1.0).abs() < f32::EPSILON);
        assert!((usefulness_decay(Some(ancient), ancient, -1.0) - 1.0).abs() < f32::EPSILON);
    }

    /// v0.5.1: unparseable timestamps return 1.0 (fail-open). A
    /// corrupted row shouldn't get silently dropped out of retrieval
    /// just because its `last_useful_at` got mangled.
    #[test]
    fn usefulness_decay_returns_one_on_unparseable_timestamps() {
        assert!(
            (usefulness_decay(Some("not-a-date"), "also-not", 30.0) - 1.0).abs() < f32::EPSILON
        );
    }

    /// v0.5.1: a memory whose reference timestamp is "now" (no age)
    /// decays by zero — full contribution.
    #[test]
    fn usefulness_decay_full_at_zero_age() {
        // Use a timestamp from the future so age clamps to 0.
        let future = "2099-01-01T00:00:00Z";
        let d = usefulness_decay(Some(future), future, 30.0);
        assert!((d - 1.0).abs() < f32::EPSILON, "got {d}");
    }

    /// v0.5.1: at age == half_life, decay = 0.5; at age = 2 * half_life,
    /// decay = 0.25. Computed by setting `last_useful_at` to (now - days)
    /// using OffsetDateTime arithmetic — the only way to get a stable
    /// "now-relative" timestamp without freezing the clock.
    #[test]
    fn usefulness_decay_follows_half_life_curve() {
        let half_life = 10.0_f32;
        let now = OffsetDateTime::now_utc();
        let fmt = &time::format_description::well_known::Rfc3339;

        // age = half_life -> decay ~= 0.5
        let one_half_life_ago = (now - time::Duration::seconds((half_life * 86_400.0) as i64))
            .format(fmt)
            .expect("format");
        let d1 = usefulness_decay(Some(&one_half_life_ago), &one_half_life_ago, half_life);
        assert!(
            (d1 - 0.5).abs() < 0.01,
            "expected ~0.5 at one half-life, got {d1}"
        );

        // age = 2 * half_life -> decay ~= 0.25
        let two_half_lives_ago = (now
            - time::Duration::seconds((2.0 * half_life * 86_400.0) as i64))
        .format(fmt)
        .expect("format");
        let d2 = usefulness_decay(Some(&two_half_lives_ago), &two_half_lives_ago, half_life);
        assert!(
            (d2 - 0.25).abs() < 0.01,
            "expected ~0.25 at two half-lives, got {d2}"
        );
    }

    /// v0.5.1: when `last_useful_at` is None the function falls back to
    /// `created_at`. A 1-day-old never-cited memory should still get
    /// nearly-full decay (close to 1.0) for a 30-day half-life.
    #[test]
    fn usefulness_decay_falls_back_to_created_at_when_last_useful_is_none() {
        let now = OffsetDateTime::now_utc();
        let fmt = &time::format_description::well_known::Rfc3339;
        let one_day_ago = (now - time::Duration::seconds(86_400))
            .format(fmt)
            .expect("format");
        let d = usefulness_decay(None, &one_day_ago, 30.0);
        // exp(-ln(2) / 30) ≈ 0.977
        assert!(
            (d - 0.977).abs() < 0.01,
            "expected ~0.977 for 1-day-old created_at under 30d half-life, got {d}"
        );
    }

    /// v0.5.1: end-to-end retrieval test. Two memories with identical
    /// lexical match, identical use_count, identical (max) usefulness
    /// score — one cited yesterday, one cited a year ago. Decay must
    /// rank the recent one first.
    #[test]
    fn aged_cited_memory_ranks_below_recently_cited_memory() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");

        let now = OffsetDateTime::now_utc();
        let fmt = &time::format_description::well_known::Rfc3339;
        let one_day_ago = (now - time::Duration::seconds(86_400))
            .format(fmt)
            .expect("format");
        let one_year_ago = (now - time::Duration::seconds(365 * 86_400))
            .format(fmt)
            .expect("format");

        // Both memories say "use ripgrep for code search", both have
        // use_count = 5, usefulness_score = 5 (max boost → 1.5
        // multiplier). The only difference is `last_useful_at`.
        for (mid, last_useful) in [("m_recent", &one_day_ago), ("m_aged", &one_year_ago)] {
            let text = "use ripgrep for code search";
            let normalized = kimetsu_core::memory::normalize_memory_text(text);
            conn.execute(
                "
                INSERT INTO memories (
                    memory_id, scope, kind, text, normalized_text, confidence,
                    source_event_id, provenance_snapshot_json, created_at,
                    use_count, usefulness_score, last_useful_at
                )
                VALUES (?1, 'global_user', 'fact', ?2, ?3, 1.0, NULL, '{}',
                        '2024-01-01T00:00:00Z', 5, 5.0, ?4)
                ",
                rusqlite::params![mid, text, normalized, last_useful],
            )
            .expect("insert memory");
            conn.execute(
                "INSERT INTO memories_fts (memory_id, text, kind, scope)
                 VALUES (?1, ?2, 'fact', 'global_user')",
                rusqlite::params![mid, text],
            )
            .expect("insert fts");
        }

        // Default broker weights → 30-day half-life. 1 year ≈ 12 half-lives.
        let weights = kimetsu_core::config::BrokerWeights::default();
        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "ripgrep search".to_string(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve");

        let mem_order: Vec<&str> = bundle
            .capsules
            .iter()
            .filter_map(|c| c.expansion_handle.strip_prefix("memory:"))
            .collect();
        assert_eq!(
            mem_order.first().copied(),
            Some("m_recent"),
            "recently-cited memory must rank first under decay; got order {mem_order:?}"
        );
    }

    /// v0.5.1: with decay disabled (half_life = 0) the aged + recent
    /// memories tie and the deterministic tiebreaker (id) decides —
    /// proves the ranking flip in the previous test is *caused* by
    /// decay, not by some unrelated side effect of the timestamp.
    #[test]
    fn aged_cited_memory_does_not_decay_when_half_life_is_zero() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");

        let now = OffsetDateTime::now_utc();
        let fmt = &time::format_description::well_known::Rfc3339;
        let one_day_ago = (now - time::Duration::seconds(86_400))
            .format(fmt)
            .expect("format");
        let one_year_ago = (now - time::Duration::seconds(365 * 86_400))
            .format(fmt)
            .expect("format");

        for (mid, last_useful) in [("m_recent", &one_day_ago), ("m_aged", &one_year_ago)] {
            let text = "use ripgrep for code search";
            let normalized = kimetsu_core::memory::normalize_memory_text(text);
            conn.execute(
                "
                INSERT INTO memories (
                    memory_id, scope, kind, text, normalized_text, confidence,
                    source_event_id, provenance_snapshot_json, created_at,
                    use_count, usefulness_score, last_useful_at
                )
                VALUES (?1, 'global_user', 'fact', ?2, ?3, 1.0, NULL, '{}',
                        '2024-01-01T00:00:00Z', 5, 5.0, ?4)
                ",
                rusqlite::params![mid, text, normalized, last_useful],
            )
            .expect("insert memory");
            conn.execute(
                "INSERT INTO memories_fts (memory_id, text, kind, scope)
                 VALUES (?1, ?2, 'fact', 'global_user')",
                rusqlite::params![mid, text],
            )
            .expect("insert fts");
        }

        // Disable decay via broker config.
        let weights = kimetsu_core::config::BrokerWeights {
            decay_half_life_days: 0.0,
            ..Default::default()
        };

        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "ripgrep search".to_string(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve");

        // Both memories should surface. With decay disabled, their
        // scores are identical (same multiplier, same lexical match,
        // same freshness band since both created_at are equal). The
        // sort tiebreaker falls back to id, so m_aged < m_recent
        // alphabetically.
        let scores: Vec<(String, f32)> = bundle
            .capsules
            .iter()
            .filter_map(|c| {
                c.expansion_handle
                    .strip_prefix("memory:")
                    .map(|id| (id.to_string(), c.score))
            })
            .collect();
        assert_eq!(scores.len(), 2, "both memories should surface");
        let recent_score = scores
            .iter()
            .find(|(id, _)| id == "m_recent")
            .map(|(_, s)| *s)
            .expect("m_recent present");
        let aged_score = scores
            .iter()
            .find(|(id, _)| id == "m_aged")
            .map(|(_, s)| *s)
            .expect("m_aged present");
        // With decay off, the two multipliers are equal → scores match.
        assert!(
            (recent_score - aged_score).abs() < 1e-4,
            "with decay disabled the two memories should tie on score: recent={recent_score} aged={aged_score}"
        );
    }

    /// v0.4.2: with [`NoopEmbedder`] the retrieval path is identical
    /// to v0.4.1 — no cosine term contributes, stored embeddings (if
    /// any) are ignored. Regression guard so the default build
    /// behaves identically to pre-v0.4.2.
    #[test]
    fn hybrid_retrieval_with_noop_embedder_is_lexical_only() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");
        let stub = embeddings::StubEmbedder::new();
        // Two memories, both with non-null embeddings.
        insert_memory_with_embedding(&conn, "m_a", "use ripgrep", &stub);
        insert_memory_with_embedding(&conn, "m_b", "use ripgrep too", &stub);

        // Query through the Noop default. QueryEmbedding will be
        // None → no cosine blend → exact FTS ranking.
        let weights = kimetsu_core::config::BrokerWeights::default();
        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "ripgrep".to_string(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve");

        let count = bundle
            .capsules
            .iter()
            .filter(|c| c.expansion_handle.starts_with("memory:"))
            .count();
        assert_eq!(count, 2, "both memories should surface via FTS");
    }

    // ---------------------------------------------------------------
    // D1d tests: ANN index correctness, rebuild on model change, dedup
    // ---------------------------------------------------------------

    /// D1d test 1: ANN finds a semantic match that FTS misses.
    ///
    /// Strategy: use a manually-crafted ("oracle") embedder that returns a
    /// FIXED known vector for any input, paired with a direct-SQL memory
    /// insertion that stores the SAME vector for the "semantic" memory and a
    /// DIFFERENT vector for the "lexical decoy". The query text and memory
    /// texts deliberately share NO words, so FTS returns nothing. ANN
    /// surfaces the semantically-near memory via the usearch index.
    ///
    /// Concretely:
    ///   - query text = "phosphorescent bioluminescent organism" (no overlap
    ///     with any memory text)
    ///   - m_semantic text = "cookie recipe chocolate" — completely different
    ///     words, but we MANUALLY store the same vector as the query embedding.
    ///   - m_decoy text = "git rebase squash commits" — different text,
    ///     orthogonal vector.
    ///
    /// The "oracle" embedder always returns [1,0,0,0,0,0,0,0] for any text.
    /// We store [1,0,0,0,0,0,0,0] for m_semantic and [0,1,0,0,0,0,0,0] for
    /// m_decoy. Cosine("oracle query", m_semantic) = 1.0; cosine(query,
    /// m_decoy) = 0.0. FTS finds nothing (no shared tokens). ANN finds
    /// m_semantic as the nearest neighbour.
    #[cfg(feature = "embeddings")]
    #[test]
    fn ann_finds_semantic_match_fts_misses() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");

        // Oracle embedder: always returns the same unit vector regardless of text.
        // This lets us control cosine similarity independently of word overlap.
        struct OracleEmbedder;
        impl embeddings::Embedder for OracleEmbedder {
            fn embed(&self, _text: &str) -> Result<Vec<f32>, embeddings::EmbedderError> {
                // [1,0,0,0,0,0,0,0] — unit vector along dim-0
                Ok(vec![1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0])
            }
            fn model_id(&self) -> &str {
                "oracle-d8"
            }
            fn dim(&self) -> usize {
                8
            }
        }

        let model_id = "oracle-d8";

        // m_semantic: text shares NO tokens with the query, but stored
        // embedding is [1,0,...,0] — cosine with the oracle query vector = 1.0.
        let sem_vec = embeddings::encode_embedding(&[1.0f32, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]);
        let sem_text = "cookie recipe chocolate";
        let sem_norm = kimetsu_core::memory::normalize_memory_text(sem_text);
        conn.execute(
            "INSERT INTO memories (
                 memory_id, scope, kind, text, normalized_text, confidence,
                 source_event_id, provenance_snapshot_json, created_at,
                 use_count, usefulness_score, embedding, embedding_model
             )
             VALUES ('m_semantic', 'global_user', 'fact', ?1, ?2, 1.0, NULL, '{}',
                     '2026-01-01T00:00:00Z', 0, 0.0, ?3, ?4)",
            rusqlite::params![sem_text, sem_norm, sem_vec, model_id],
        )
        .expect("insert m_semantic");
        conn.execute(
            "INSERT INTO memories_fts (memory_id, text, kind, scope)
             VALUES ('m_semantic', ?1, 'fact', 'global_user')",
            rusqlite::params![sem_text],
        )
        .expect("insert m_semantic fts");

        // m_decoy: different text, orthogonal vector [0,1,0,...,0].
        let decoy_vec = embeddings::encode_embedding(&[0.0f32, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]);
        let decoy_text = "git rebase squash commits";
        let decoy_norm = kimetsu_core::memory::normalize_memory_text(decoy_text);
        conn.execute(
            "INSERT INTO memories (
                 memory_id, scope, kind, text, normalized_text, confidence,
                 source_event_id, provenance_snapshot_json, created_at,
                 use_count, usefulness_score, embedding, embedding_model
             )
             VALUES ('m_decoy', 'global_user', 'fact', ?1, ?2, 1.0, NULL, '{}',
                     '2026-01-01T00:00:00Z', 0, 0.0, ?3, ?4)",
            rusqlite::params![decoy_text, decoy_norm, decoy_vec, model_id],
        )
        .expect("insert m_decoy");
        conn.execute(
            "INSERT INTO memories_fts (memory_id, text, kind, scope)
             VALUES ('m_decoy', ?1, 'fact', 'global_user')",
            rusqlite::params![decoy_text],
        )
        .expect("insert m_decoy fts");

        // Sanity: FTS must find nothing for the query tokens.
        let fts_hits: i64 = conn
            .query_row(
                "SELECT COUNT(*) FROM memories_fts \
                 WHERE memories_fts MATCH 'phosphorescent bioluminescent'",
                [],
                |r| r.get(0),
            )
            .unwrap_or(0);
        assert_eq!(
            fts_hits, 0,
            "sanity: query tokens must not appear in any memory text"
        );

        // Retrieve via oracle embedder.
        // query = "phosphorescent bioluminescent organism" has no lexical
        // overlap with either memory. ANN must surface m_semantic (cosine=1).
        let weights = kimetsu_core::config::BrokerWeights::default();
        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "phosphorescent bioluminescent organism".to_string(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &OracleEmbedder,
        )
        .expect("retrieve");

        let handles: Vec<&str> = bundle
            .capsules
            .iter()
            .filter_map(|c| c.expansion_handle.strip_prefix("memory:"))
            .collect();

        assert!(
            handles.contains(&"m_semantic"),
            "ANN must surface m_semantic (cosine=1 with oracle query) even though \
             FTS found nothing; got handles: {handles:?}"
        );
    }

    /// D1d test 3: a memory matched by both FTS and ANN appears exactly once.
    #[cfg(feature = "embeddings")]
    #[test]
    fn dedup_memory_matched_by_fts_and_ann_appears_once() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");

        let stub = embeddings::StubEmbedder::new();

        // This memory contains "ripgrep" (lexical) AND has a stub embedding
        // derived from its text, so the query "ripgrep" matches it both via
        // FTS and via ANN (same words → same stub bucket vector).
        insert_memory_with_embedding(&conn, "m_both", "use ripgrep for fast search", &stub);

        let weights = kimetsu_core::config::BrokerWeights::default();
        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "ripgrep".to_string(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &stub,
        )
        .expect("retrieve");

        let count = bundle
            .capsules
            .iter()
            .filter(|c| c.expansion_handle == "memory:m_both")
            .count();
        assert_eq!(
            count,
            1,
            "m_both (matched by both FTS and ANN) must appear exactly once; \
             bundle: {:?}",
            bundle
                .capsules
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );
    }

    // ---------------------------------------------------------------
    // D1e tests: embedding-MMR deduplication + semantic relevance floor
    // ---------------------------------------------------------------

    /// D1e-a (embeddings-gated): two paraphrased memories that share an
    /// almost-identical embedding vector (cosine = 1.0, so embedding-MMR
    /// sees them as maximally redundant) but have LOW Jaccard overlap on
    /// their summary tokens (different words, so the Jaccard-only capsule-
    /// stage MMR would NOT penalize the second one and both survive the
    /// budget with max_capsules=2).
    ///
    /// Key mechanic: embedding-MMR assigns the second near-duplicate a very
    /// negative MMR score (lambda * score - (1-lambda) * 1.0 < 0 when score
    /// is small). It therefore ends up LAST in the reordered candidate list.
    /// When max_capsules=1 it is excluded. With Jaccard-only (NoopEmbedder),
    /// the second paraphrase has low Jaccard overlap → survives when
    /// max_capsules=2.
    ///
    /// Expected result:
    ///   * OracleEmbedder + max_capsules=1: ONE paraphrase (embedding-MMR
    ///     collapsed the redundant one).
    ///   * NoopEmbedder + max_capsules=2: BOTH paraphrases survive (Jaccard
    ///     does not see them as redundant — different tokens).
    #[cfg(feature = "embeddings")]
    #[test]
    fn embedding_mmr_collapses_paraphrases_but_jaccard_does_not() {
        // OracleEmbedder: always returns [1,0,0,…] (dim=8).
        // cosine(any two texts) = 1.0 → maximal redundancy in embedding space.
        struct OracleEmbedder;
        impl embeddings::Embedder for OracleEmbedder {
            fn embed(&self, _text: &str) -> Result<Vec<f32>, embeddings::EmbedderError> {
                let mut v = vec![0.0f32; 8];
                v[0] = 1.0;
                Ok(v)
            }
            fn model_id(&self) -> &str {
                "oracle-d8"
            }
            fn dim(&self) -> usize {
                8
            }
        }

        // Setup: two memories with DIFFERENT words (low Jaccard) but
        // SAME oracle embedding (cosine = 1.0).
        let oracle = OracleEmbedder;
        let weights = kimetsu_core::config::BrokerWeights::default();

        // "prefer ripgrep" vs "rg is the fastest" — entirely different tokens.
        // Summary token-set overlap ≈ 0 ⟹ Jaccard ≈ 0.
        let m_rg1_text = "prefer ripgrep for searching source code";
        let m_rg2_text = "rg is the fastest way to locate patterns";

        // --- Embedding-MMR path (OracleEmbedder), max_capsules=1 ---
        // Under embedding-MMR: second paraphrase gets MMR score
        //   0.7 * score - 0.3 * 1.0  (overlap = cosine = 1.0)
        // For any small normalised score, this is negative → it is assigned
        // last in the MMR reordering. max_capsules=1 → only 1 included.
        let conn = rusqlite::Connection::open_in_memory().expect("in-memory");
        crate::schema::initialize(&conn).expect("init schema");
        insert_memory_with_embedding(&conn, "m_rg1", m_rg1_text, &oracle);
        insert_memory_with_embedding(&conn, "m_rg2", m_rg2_text, &oracle);

        let bundle_embedding = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                // Query that matches both via FTS so they survive pre-MMR scoring.
                query: "search source patterns".to_string(),
                budget_tokens: 20_000,
                max_capsules: 1, // tight cap: only 1 slot available
                ..Default::default()
            },
            &[],
            &oracle,
        )
        .expect("retrieve with oracle embedder");

        // Under embedding-MMR, the second paraphrase (cosine=1.0 with first)
        // is reranked last and excluded by max_capsules=1.
        let emb_in_capsules = bundle_embedding
            .capsules
            .iter()
            .filter(|c| {
                c.expansion_handle == "memory:m_rg1" || c.expansion_handle == "memory:m_rg2"
            })
            .count();
        assert_eq!(
            emb_in_capsules,
            1,
            "embedding-MMR must collapse cosine=1.0 paraphrases: with max_capsules=1 \
             only ONE should be included; capsule handles: {:?}; excluded: {:?}",
            bundle_embedding
                .capsules
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>(),
            bundle_embedding
                .excluded
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );

        // At least one is in excluded (the redundant near-duplicate).
        let emb_in_excluded = bundle_embedding
            .excluded
            .iter()
            .filter(|c| {
                c.expansion_handle == "memory:m_rg1" || c.expansion_handle == "memory:m_rg2"
            })
            .count();
        assert_eq!(
            emb_in_excluded,
            1,
            "the second near-duplicate must be in excluded under embedding-MMR; \
             excluded handles: {:?}",
            bundle_embedding
                .excluded
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );

        // --- Lean/Jaccard-only path (NoopEmbedder), max_capsules=2 ---
        // With Jaccard-only: summary tokens of m_rg1 and m_rg2 have ≈0
        // overlap (different words) → low redundancy penalty → BOTH score
        // high under MMR → both survive with max_capsules=2.
        let conn2 = rusqlite::Connection::open_in_memory().expect("in-memory 2");
        crate::schema::initialize(&conn2).expect("init schema 2");
        insert_memory_with_embedding(&conn2, "m_rg1", m_rg1_text, &oracle);
        insert_memory_with_embedding(&conn2, "m_rg2", m_rg2_text, &oracle);

        let bundle_lean = retrieve_context_with_embedder(
            &conn2,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "search source patterns".to_string(),
                budget_tokens: 20_000,
                max_capsules: 2, // room for both
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve with NoopEmbedder");

        let lean_in_capsules = bundle_lean
            .capsules
            .iter()
            .filter(|c| {
                c.expansion_handle == "memory:m_rg1" || c.expansion_handle == "memory:m_rg2"
            })
            .count();
        assert_eq!(
            lean_in_capsules,
            2,
            "Jaccard-only path must NOT collapse the two paraphrases (different words, \
             low token overlap → both survive MMR with max_capsules=2); capsule handles: {:?}",
            bundle_lean
                .capsules
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );
    }

    // ── v1.0.0: lexical relevance floor (A+B+C) ──────────────────────────

    #[test]
    fn content_tokens_strips_stopwords_keeps_topical_words() {
        let got = content_tokens("Tell me about kimetsu, what's the idea of the repo");
        // Stopwords (tell, me, about, what, the, of) dropped; "s" too short.
        // Topical words kept; deduped (no second "the").
        assert_eq!(got, vec!["kimetsu", "idea", "repo"]);
    }

    #[test]
    fn light_stem_strips_one_inflection_suffix() {
        assert_eq!(light_stem("benchmarked"), "benchmark");
        assert_eq!(light_stem("benchmarking"), "benchmark");
        assert_eq!(light_stem("repos"), "repo");
        // Too short after stripping → untouched.
        assert_eq!(light_stem("does"), "does");
        assert_eq!(light_stem("toml"), "toml");
    }

    /// Real-world regression: "Can you find out how kimetsu is benchmarked?"
    /// surfaced off-topic memories because the inflected "benchmarked"
    /// matched nothing (FTS prefix `benchmarked*` and IDF `%benchmarked%`
    /// both miss "benchmark"), zeroing the query's only discriminating
    /// token. With query-side stemming the benchmark memory surfaces and
    /// the off-topic ones stay below the floor.
    #[test]
    fn stemmed_query_matches_inflected_corpus_through_floor() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");
        let insert = |id: &str, text: &str| {
            let norm = kimetsu_core::memory::normalize_memory_text(text);
            conn.execute(
                "INSERT INTO memories (
                     memory_id, scope, kind, text, normalized_text, confidence,
                     source_event_id, provenance_snapshot_json, created_at,
                     use_count, usefulness_score, embedding, embedding_model
                 )
                 VALUES (?1, 'global_user', 'fact', ?2, ?3, 0.9, NULL, '{}',
                         '2026-06-01T00:00:00Z', 0, 0.0, NULL, NULL)",
                rusqlite::params![id, text, norm],
            )
            .expect("insert memory");
            conn.execute(
                "INSERT INTO memories_fts (memory_id, text, kind, scope)
                 VALUES (?1, ?2, 'fact', 'global_user')",
                rusqlite::params![id, text],
            )
            .expect("insert fts");
        };
        insert(
            "m_bench",
            "kimetsu benchmark runs go through the kbench binary and the Terminal-Bench driver",
        );
        insert(
            "m_doctor",
            "kimetsu doctor version-skew check parses process start times on Windows via CIM",
        );
        insert(
            "m_gc",
            "kimetsu runs auto-GC on run creation; keep the env guard at the trigger site",
        );

        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &kimetsu_core::config::BrokerWeights::default(),
            ContextRequest {
                stage: "localization".to_string(),
                query: "Can you find out how kimetsu is benchmarked?".to_string(),
                budget_tokens: 2000,
                max_capsules: 2,
                min_lexical_coverage: 0.5,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve");
        let handles: Vec<_> = bundle
            .capsules
            .iter()
            .map(|c| c.expansion_handle.as_str())
            .collect();
        assert!(
            handles.contains(&"memory:m_bench"),
            "stemmed 'benchmarked' must surface the benchmark memory; got {handles:?}"
        );
        assert!(
            !handles.contains(&"memory:m_doctor") && !handles.contains(&"memory:m_gc"),
            "off-topic memories sharing only 'kimetsu' must stay below the floor; got {handles:?}"
        );
    }

    #[test]
    fn weighted_coverage_ignores_zero_idf_tokens() {
        // "kimetsu" is corpus-ubiquitous (idf 0); "idea" is rare (high idf);
        // "repo" is mid. A summary that matches only the project name + a
        // mid-idf word covers a minority of the discriminating weight.
        let content = vec![
            "kimetsu".to_string(),
            "idea".to_string(),
            "repo".to_string(),
        ];
        let mut idf = HashMap::new();
        idf.insert("kimetsu".to_string(), 0.0);
        idf.insert("idea".to_string(), 1.386);
        idf.insert("repo".to_string(), 0.693);

        // Matches kimetsu + repo, NOT idea → 0.693 / (1.386+0.693) ≈ 0.333.
        let cov = weighted_coverage(
            &content,
            &idf,
            "global:fact - the git repo and kimetsu brain",
        );
        assert!((cov - 0.333).abs() < 0.01, "got {cov}");

        // Matches the rare topical word → high coverage.
        let cov_topical =
            weighted_coverage(&content, &idf, "global:fact - the core idea of kimetsu");
        assert!(cov_topical > 0.6, "got {cov_topical}");
    }

    /// The reported regression, reproduced end-to-end on the FTS-only path:
    /// a corpus of unrelated debugging war-stories that all happen to contain
    /// the project name "kimetsu", queried with a broad conceptual prompt.
    ///
    /// * floor disabled (min_lexical_coverage = 0.0) → all the noise surfaces
    ///   (pre-fix behaviour: incidental "kimetsu" overlap is enough).
    /// * floor enabled (0.5) → the memories whose ONLY match is the corpus-
    ///   ubiquitous project name (m2, m3) are dropped. m1 also contains the
    ///   real word "repo", so it's a genuine (if weak) lexical match and
    ///   survives — eliminating that kind of keyword-overlap-but-off-topic
    ///   hit needs the semantic path, not lexical filtering. The win here is
    ///   killing the pure-project-name matches, which were the bulk of the
    ///   injected noise.
    #[test]
    fn lexical_floor_drops_offtopic_memories_sharing_project_name() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");

        let insert = |id: &str, text: &str| {
            let norm = kimetsu_core::memory::normalize_memory_text(text);
            conn.execute(
                "INSERT INTO memories (
                     memory_id, scope, kind, text, normalized_text, confidence,
                     source_event_id, provenance_snapshot_json, created_at,
                     use_count, usefulness_score, embedding, embedding_model
                 )
                 VALUES (?1, 'global_user', 'fact', ?2, ?3, 0.9, NULL, '{}',
                         '2026-06-01T00:00:00Z', 0, 0.0, NULL, NULL)",
                rusqlite::params![id, text, norm],
            )
            .expect("insert memory");
            conn.execute(
                "INSERT INTO memories_fts (memory_id, text, kind, scope)
                 VALUES (?1, ?2, 'fact', 'global_user')",
                rusqlite::params![id, text],
            )
            .expect("insert fts");
        };

        // All three contain "kimetsu"; none contain "idea". Only m1 contains
        // "repo" (as in "git repo") — mirrors the real war-stories.
        insert(
            "m1",
            "When implementing a setup command that calls init_project, tests must call \
             git_init_boundary before setup_cmd so ProjectPaths discover resolves to the temp \
             dir instead of climbing to the real parent git repo including the user brain at kimetsu",
        );
        insert(
            "m2",
            "A member crate with default embeddings silently turned embeddings on for the entire \
             cargo test workspace build graph because cargo unifies features; kimetsu-chat \
             retrieval tests failed",
        );
        insert(
            "m3",
            "In toml 0.9 use toml from_str to parse a TOML document into a Value not str parse; \
             implementing config get and set in kimetsu-cli",
        );

        let query = "Tell me about kimetsu, what's the idea of the repo".to_string();
        let weights = kimetsu_core::config::BrokerWeights::default();
        let handles = |bundle: &ContextBundle| {
            bundle
                .capsules
                .iter()
                .map(|c| c.expansion_handle.clone())
                .collect::<Vec<_>>()
        };

        // Floor disabled: every off-topic memory surfaces (pre-fix behaviour).
        let no_floor = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: query.clone(),
                budget_tokens: 2000,
                max_capsules: 8,
                min_lexical_coverage: 0.0,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve without floor");
        let before = handles(&no_floor);
        assert!(
            before.contains(&"memory:m2".to_string()) && before.contains(&"memory:m3".to_string()),
            "sanity: without the floor the pure-project-name memories should surface; got {before:?}"
        );

        // Floor enabled: the pure-project-name matches (m2, m3) are dropped.
        let floored = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query,
                budget_tokens: 2000,
                max_capsules: 8,
                min_lexical_coverage: 0.5,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve with floor");
        let after = handles(&floored);
        assert!(
            !after.contains(&"memory:m2".to_string()) && !after.contains(&"memory:m3".to_string()),
            "the lexical floor must drop memories whose only match is the corpus-ubiquitous \
             project name; surviving: {after:?}"
        );
    }

    /// A genuinely on-topic query must NOT be over-pruned: a memory that
    /// covers the query's rare, discriminating word survives the floor.
    #[test]
    fn lexical_floor_keeps_ontopic_memory() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");

        let insert = |id: &str, text: &str| {
            let norm = kimetsu_core::memory::normalize_memory_text(text);
            conn.execute(
                "INSERT INTO memories (
                     memory_id, scope, kind, text, normalized_text, confidence,
                     source_event_id, provenance_snapshot_json, created_at,
                     use_count, usefulness_score, embedding, embedding_model
                 )
                 VALUES (?1, 'global_user', 'fact', ?2, ?3, 0.9, NULL, '{}',
                         '2026-06-01T00:00:00Z', 0, 0.0, NULL, NULL)",
                rusqlite::params![id, text, norm],
            )
            .expect("insert memory");
            conn.execute(
                "INSERT INTO memories_fts (memory_id, text, kind, scope)
                 VALUES (?1, ?2, 'fact', 'global_user')",
                rusqlite::params![id, text],
            )
            .expect("insert fts");
        };

        // Two memories so "distiller" is rare (df=1) → high idf.
        insert(
            "d1",
            "The distiller runs at session end and harvests durable lessons from the transcript",
        );
        insert(
            "n1",
            "Unrelated note about git rebase and squashing commits",
        );

        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &kimetsu_core::config::BrokerWeights::default(),
            ContextRequest {
                stage: "localization".to_string(),
                query: "how does the distiller work".to_string(),
                budget_tokens: 2000,
                min_lexical_coverage: 0.5,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve");

        assert!(
            bundle
                .capsules
                .iter()
                .any(|c| c.expansion_handle == "memory:d1"),
            "on-topic memory covering the rare query word must survive the floor; got: {:?}",
            bundle
                .capsules
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );
    }

    /// D1e-b: absolute semantic relevance floor (min_semantic_score).
    ///
    /// * With a positive floor and a query whose embedding is orthogonal
    ///   to every memory, the result must be `skipped: true` / 0 capsules.
    /// * With the same floor and a query that IS relevant, the memory
    ///   still surfaces (signal preserved).
    /// * With floor = 0.0 (default), the off-topic query still surfaces
    ///   the "best of a bad lot" (existing pre-D1e behaviour).
    #[cfg(feature = "embeddings")]
    #[test]
    fn min_semantic_score_floor_drops_off_topic_queries() {
        // DirectionalEmbedder: returns a specific unit vector based on
        // which "topic" the text is assigned to. Allows us to place the
        // query vector and memory vectors in known relative positions.
        //
        // dim=8. Topic A = [1,0,0,0,0,0,0,0]. Topic B = [0,1,0,0,0,0,0,0].
        // cosine(A, B) = 0.0 → perfectly orthogonal (unrelated).
        // cosine(A, A) = 1.0 → identical topic.
        //
        // We embed the query on topic A, the memory on topic B.
        // Cosine(query, memory) = 0.0 < any positive floor.
        struct DirectionalEmbedder {
            // Text containing "TOPIC_A" embeds as [1,0,…]; all others as [0,1,…].
            marker: &'static str,
        }
        impl embeddings::Embedder for DirectionalEmbedder {
            fn embed(&self, text: &str) -> Result<Vec<f32>, embeddings::EmbedderError> {
                let mut v = vec![0.0f32; 8];
                if text.contains(self.marker) {
                    v[0] = 1.0;
                } else {
                    v[1] = 1.0;
                }
                Ok(v)
            }
            fn model_id(&self) -> &str {
                "directional-d8"
            }
            fn dim(&self) -> usize {
                8
            }
        }

        let emb = DirectionalEmbedder { marker: "TOPIC_A" };

        let conn = rusqlite::Connection::open_in_memory().expect("in-memory");
        crate::schema::initialize(&conn).expect("init schema");

        // Memory is on topic B (does NOT contain "TOPIC_A").
        insert_memory_with_embedding(&conn, "m_b", "cookie recipe chocolate baking TOPIC_B", &emb);

        let weights = kimetsu_core::config::BrokerWeights::default();

        // 1. Off-topic query (TOPIC_A) with a positive floor: must be skipped.
        let bundle_off = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                // Query is on TOPIC_A (cosine with memory = 0.0).
                query: "TOPIC_A unrelated phosphorescent".to_string(),
                budget_tokens: 4000,
                min_semantic_score: 0.1, // positive floor
                ..Default::default()
            },
            &[],
            &emb,
        )
        .expect("retrieve off-topic");

        assert!(
            bundle_off.capsules.is_empty(),
            "off-topic query (cosine=0 < floor=0.1) must produce zero capsules; \
             got: {:?}",
            bundle_off
                .capsules
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );

        // 2. On-topic query (TOPIC_B): cosine = 1.0 ≥ floor → surfaces.
        // Insert a memory explicitly on topic B that FTS can also match.
        let conn2 = rusqlite::Connection::open_in_memory().expect("in-memory 2");
        crate::schema::initialize(&conn2).expect("init schema 2");
        insert_memory_with_embedding(
            &conn2,
            "m_b2",
            "cookie recipe chocolate TOPIC_B baking"
                .to_string()
                .as_str(),
            &emb,
        );

        let bundle_on = retrieve_context_with_embedder(
            &conn2,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                // Query is on TOPIC_B: cosine with m_b2 = 1.0 ≥ floor.
                query: "cookie chocolate TOPIC_B".to_string(),
                budget_tokens: 4000,
                min_semantic_score: 0.1,
                ..Default::default()
            },
            &[],
            &emb,
        )
        .expect("retrieve on-topic");

        assert!(
            bundle_on
                .capsules
                .iter()
                .any(|c| c.expansion_handle == "memory:m_b2"),
            "on-topic query (cosine=1.0 ≥ floor) must surface m_b2; \
             got capsules: {:?}",
            bundle_on
                .capsules
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );

        // 3. Off-topic query with floor=0.0 (disabled): memory still surfaces
        //    (existing pre-D1e behaviour — floor is a no-op at 0.0).
        let conn3 = rusqlite::Connection::open_in_memory().expect("in-memory 3");
        crate::schema::initialize(&conn3).expect("init schema 3");
        insert_memory_with_embedding(
            &conn3,
            "m_b3",
            "cookie chocolate TOPIC_B recipe".to_string().as_str(),
            &emb,
        );

        let bundle_noop_floor = retrieve_context_with_embedder(
            &conn3,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                // FTS: "cookie chocolate" matches m_b3.
                query: "cookie chocolate TOPIC_A".to_string(),
                budget_tokens: 4000,
                min_semantic_score: 0.0, // disabled
                ..Default::default()
            },
            &[],
            &emb,
        )
        .expect("retrieve noop floor");

        // With floor disabled, FTS match is enough — memory surfaces.
        assert!(
            bundle_noop_floor
                .capsules
                .iter()
                .any(|c| c.expansion_handle == "memory:m_b3"),
            "with floor=0.0 (disabled), off-topic-cosine memory must still surface via FTS; \
             got: {:?}",
            bundle_noop_floor
                .capsules
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );
    }

    // ---------------------------------------------------------------
    // D1f test: token-economy reduction proof
    // ---------------------------------------------------------------

    /// D1f: Prove that embedding-MMR + semantic floor reduces token usage
    /// while preserving signal.
    ///
    /// Setup: a corpus of 6 memories:
    ///   * 3 near-duplicate paraphrases on topic A (same OracleA vector)
    ///   * 1 genuinely relevant memory on topic A (same OracleA vector,
    ///     different words)
    ///   * 2 completely unrelated memories on topic B (OracleB vector)
    ///
    /// Query: topic A.
    ///
    /// WITHOUT D1e (NoopEmbedder + floor=0.0): all 6 memories potentially
    /// surface (no semantic dedup, no floor). With the budget large enough
    /// all 6 fit → many capsules, many tokens.
    ///
    /// WITH D1e (OracleEmbedder + positive floor):
    ///   * Floor (min_semantic_score > 0) drops the 2 topic-B memories.
    ///   * Embedding-MMR collapses the 3 near-duplicate topic-A memories
    ///     to 1 slot.
    ///   * The genuinely-relevant memory survives (it is the "seed" of MMR
    ///     or at least one slot per topic-A cluster remains).
    ///
    /// Assertion: WITH D1e → strictly fewer capsules AND the genuinely-
    /// relevant memory is still present (signal preserved, noise cut).
    #[cfg(feature = "embeddings")]
    #[test]
    fn d1f_token_economy_fewer_capsules_signal_preserved() {
        // OracleEmbedder: topic-A text gets [1,0,…]; everything else [0,1,…].
        struct OracleTopicEmbedder;
        impl embeddings::Embedder for OracleTopicEmbedder {
            fn embed(&self, text: &str) -> Result<Vec<f32>, embeddings::EmbedderError> {
                let mut v = vec![0.0f32; 8];
                if text.contains("TOPIC_A") {
                    v[0] = 1.0; // topic A
                } else {
                    v[1] = 1.0; // topic B
                }
                Ok(v)
            }
            fn model_id(&self) -> &str {
                "oracle-topic-d8"
            }
            fn dim(&self) -> usize {
                8
            }
        }

        let oracle = OracleTopicEmbedder;

        // Helper: set up the corpus on a fresh connection.
        let setup = |conn: &rusqlite::Connection| {
            // 3 near-duplicate paraphrases on topic A (same oracle vector,
            // different FTS words so they match the query but Jaccard is low).
            for (mid, text) in [
                ("m_dup1", "TOPIC_A prefer ripgrep for searching"),
                ("m_dup2", "TOPIC_A rg is the fastest searcher"),
                ("m_dup3", "TOPIC_A use rg tool to find patterns"),
                // 1 genuinely-relevant memory on topic A (the one we must keep).
                (
                    "m_relevant",
                    "TOPIC_A critical lesson about search performance",
                ),
                // 2 off-topic memories on topic B.
                ("m_noise1", "chocolate cookie baking TOPIC_B recipe"),
                ("m_noise2", "gardening tulip planting TOPIC_B spring"),
            ] {
                insert_memory_with_embedding(conn, mid, text, &oracle);
            }
        };

        let weights = kimetsu_core::config::BrokerWeights::default();

        // --- WITHOUT D1e: NoopEmbedder, floor=0.0 ---
        // FTS: "TOPIC_A" appears in m_dup1/2/3 + m_relevant; "search"
        // appears in m_dup1 and m_relevant. All 4 topic-A memories match
        // FTS. The 2 topic-B memories also have "recipe" and "spring"
        // which don't match — they may or may not appear via recency
        // fallback. Use a large budget so all matching memories fit.
        let conn_lean = rusqlite::Connection::open_in_memory().expect("in-memory lean");
        crate::schema::initialize(&conn_lean).expect("init schema lean");
        setup(&conn_lean);

        let bundle_lean = retrieve_context_with_embedder(
            &conn_lean,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "TOPIC_A search performance".to_string(),
                budget_tokens: 20_000,
                min_semantic_score: 0.0, // floor disabled
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve lean");

        let lean_count = bundle_lean
            .capsules
            .iter()
            .filter(|c| c.expansion_handle.starts_with("memory:"))
            .count();

        // --- WITH D1e: OracleEmbedder + positive floor ---
        let conn_emb = rusqlite::Connection::open_in_memory().expect("in-memory emb");
        crate::schema::initialize(&conn_emb).expect("init schema emb");
        setup(&conn_emb);

        let bundle_emb = retrieve_context_with_embedder(
            &conn_emb,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "TOPIC_A search performance".to_string(),
                budget_tokens: 20_000,
                min_semantic_score: 0.5, // positive floor: drops topic-B (cosine=0.0)
                ..Default::default()
            },
            &[],
            &oracle,
        )
        .expect("retrieve with embeddings");

        let emb_count = bundle_emb
            .capsules
            .iter()
            .filter(|c| c.expansion_handle.starts_with("memory:"))
            .count();

        // Token reduction: embedding path must produce strictly fewer capsules.
        assert!(
            emb_count < lean_count,
            "D1e must reduce capsule count: embedding path {emb_count} must be \
             < lean path {lean_count}. Embedding capsules: {:?}",
            bundle_emb
                .capsules
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );

        // Signal preservation: the genuinely-relevant memory must survive.
        assert!(
            bundle_emb
                .capsules
                .iter()
                .any(|c| c.expansion_handle == "memory:m_relevant"),
            "m_relevant must survive D1e selection (signal preserved); \
             embedding capsules: {:?}",
            bundle_emb
                .capsules
                .iter()
                .map(|c| &c.expansion_handle)
                .collect::<Vec<_>>()
        );

        // Token estimate: embedding path must use fewer or equal token budget.
        let lean_tokens: u32 = bundle_lean.capsules.iter().map(|c| c.token_estimate).sum();
        let emb_tokens: u32 = bundle_emb.capsules.iter().map(|c| c.token_estimate).sum();
        assert!(
            emb_tokens < lean_tokens,
            "D1e must reduce token usage: emb={emb_tokens} must be < lean={lean_tokens}"
        );
    }

    /// D1d test 4: lean-unchanged guarantee.
    ///
    /// With NoopEmbedder (query_embedding == None), memory_candidates
    /// takes the FTS-then-recency path exactly as before D1c. No vec
    /// table is touched; no panic occurs.
    #[test]
    fn lean_noop_embedder_uses_fts_then_recency_unchanged() {
        // The NoopEmbedder logic path never touches the ANN index — it must
        // work purely via FTS + recency on both lean and embeddings builds.
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");

        // Insert two plain memories (no embeddings).
        for (mid, text) in [
            ("m_x", "use git rebase to clean history"),
            ("m_y", "grep finds text quickly"),
        ] {
            let normalized = kimetsu_core::memory::normalize_memory_text(text);
            conn.execute(
                "INSERT INTO memories (
                     memory_id, scope, kind, text, normalized_text, confidence,
                     source_event_id, provenance_snapshot_json, created_at,
                     use_count, usefulness_score
                 )
                 VALUES (?1, 'global_user', 'fact', ?2, ?3, 1.0, NULL, '{}',
                         '2026-01-01T00:00:00Z', 0, 0.0)",
                rusqlite::params![mid, text, normalized],
            )
            .expect("insert");
            conn.execute(
                "INSERT INTO memories_fts (memory_id, text, kind, scope) VALUES (?1, ?2, 'fact', 'global_user')",
                rusqlite::params![mid, text],
            )
            .expect("insert fts");
        }

        let weights = kimetsu_core::config::BrokerWeights::default();
        // NoopEmbedder → query_embedding = None → FTS + recency path.
        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: "grep text".to_string(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve with NoopEmbedder must not panic");

        // m_y matches "grep text" lexically via FTS. m_x does not.
        let handles: Vec<&str> = bundle
            .capsules
            .iter()
            .filter_map(|c| c.expansion_handle.strip_prefix("memory:"))
            .collect();
        assert!(
            handles.contains(&"m_y"),
            "m_y must surface via FTS on lean path; got {handles:?}"
        );
        // Crucially: no panic, no ANN index access.
    }

    // ---------------------------------------------------------------
    // E3 tests: task-kind classification + adaptive retrieval routing
    // ---------------------------------------------------------------

    /// E3-1: classify_task is deterministic for each kind.
    #[test]
    fn classify_task_maps_each_kind_deterministically() {
        // Debug examples
        assert_eq!(
            classify_task("fix the panic in the parser"),
            TaskKind::Debug,
            "contains 'fix' and 'panic'"
        );
        assert_eq!(
            classify_task("there is a crash in auth when calling login"),
            TaskKind::Debug,
            "contains 'crash'"
        );
        assert_eq!(
            classify_task("debug the failing test"),
            TaskKind::Debug,
            "contains 'debug' and 'fail'"
        );

        // Investigation examples
        assert_eq!(
            classify_task("investigate why retrieval is slow"),
            TaskKind::Investigation,
            "contains 'investigate' and 'why'"
        );
        assert_eq!(
            classify_task("analyze the root cause of the latency"),
            TaskKind::Investigation,
            "contains 'analyze' and 'root cause'"
        );

        // Refactor examples
        assert_eq!(
            classify_task("refactor the auth module"),
            TaskKind::Refactor,
            "contains 'refactor'"
        );
        assert_eq!(
            classify_task("rename the config struct"),
            TaskKind::Refactor,
            "contains 'rename'"
        );
        assert_eq!(
            classify_task("simplify the retry handling logic"),
            TaskKind::Refactor,
            "contains 'simplify'"
        );

        // Docs examples
        assert_eq!(
            classify_task("document the API endpoints"),
            TaskKind::Docs,
            "contains 'document'"
        );
        assert_eq!(
            classify_task("update the readme with new instructions"),
            TaskKind::Docs,
            "contains 'readme'"
        );
        assert_eq!(
            classify_task("add a docstring to the main function"),
            TaskKind::Docs,
            "contains 'docstring'"
        );

        // Feature examples (default / fallback)
        assert_eq!(
            classify_task("add a dark mode toggle"),
            TaskKind::Feature,
            "no debug/refactor/docs/investigate keyword"
        );
        assert_eq!(
            classify_task("implement the new caching layer"),
            TaskKind::Feature,
            "no debug/refactor/docs/investigate keyword"
        );
        assert_eq!(
            classify_task("build the export pipeline"),
            TaskKind::Feature,
            "no debug/refactor/docs/investigate keyword"
        );
    }

    /// E3-1b: precedence — Debug > Investigation > Refactor > Docs > Feature.
    #[test]
    fn classify_task_respects_precedence_order() {
        // "fix" (Debug) + "refactor" (Refactor) → Debug wins
        assert_eq!(
            classify_task("fix and refactor the login module"),
            TaskKind::Debug,
            "Debug > Refactor"
        );
        // "investigate" (Investigation) + "refactor" (Refactor) → Investigation wins
        assert_eq!(
            classify_task("investigate and refactor the cache layer"),
            TaskKind::Investigation,
            "Investigation > Refactor"
        );
        // "investigate" (Investigation) + "document" (Docs) → Investigation wins
        assert_eq!(
            classify_task("investigate the docs and document the API"),
            TaskKind::Investigation,
            "Investigation > Docs"
        );
        // "refactor" (Refactor) + "docs" (Docs) → Refactor wins
        assert_eq!(
            classify_task("refactor and add docs"),
            TaskKind::Refactor,
            "Refactor > Docs"
        );
        // "fix" (Debug) + "investigate" (Investigation) → Debug wins
        assert_eq!(
            classify_task("fix the bug and investigate the regression"),
            TaskKind::Debug,
            "Debug > Investigation"
        );
    }

    /// E3-2: weight renormalization — weights_for_task_kind(w, Debug) sums
    /// to approximately the same total as the input weights.
    /// v2.6 (2b): build two candidates of different kinds where the memory is
    /// a strong match and the repo_file is a weak one.
    fn two_kinds_one_strong() -> Vec<Candidate> {
        let mk = |kind: &str, raw: f32| Candidate {
            capsule: ContextCapsule {
                id: format!("{kind}-1"),
                kind: kind.to_string(),
                summary: String::new(),
                token_estimate: 0,
                expansion_handle: String::new(),
                provenance: Vec::new(),
                confidence: 0.0,
                freshness: 0.0,
                relevance: 0.0,
                scope_weight: 0.0,
                score: 0.0,
                superseded_hint: false,
                rerank_policy_tier: 0,
                claim_revision: None,
                facts: vec![],
                rerank_usefulness: None,
                rerank_trust: None,
            },
            raw_relevance: raw,
            embedding: None,
            cosine: None,
            created_at: None,
        };
        vec![mk("memory", 0.9), mk("repo_file", 0.1)]
    }

    /// The behaviour 2b exists to describe: per-kind normalization promotes
    /// the best of an irrelevant kind to a perfect relevance.
    #[test]
    fn per_kind_normalization_flatters_the_best_of_a_weak_kind() {
        let mut candidates = two_kinds_one_strong();
        let weights = StageWeights {
            relevance: 1.0,
            confidence: 0.0,
            freshness: 0.0,
            scope: 0.0,
        };
        normalize_and_score(&mut candidates, weights, Normalization::PerKind);
        assert!((candidates[0].capsule.relevance - 1.0).abs() < 1e-6);
        assert!(
            (candidates[1].capsule.relevance - 1.0).abs() < 1e-6,
            "per-kind gives the lone weak repo_file relevance 1.0, got {}",
            candidates[1].capsule.relevance
        );
    }

    /// Global normalization keeps relevance comparable across kinds: the weak
    /// repo_file stays weak because it is measured against the same max.
    #[test]
    fn global_normalization_keeps_relevance_comparable_across_kinds() {
        let mut candidates = two_kinds_one_strong();
        let weights = StageWeights {
            relevance: 1.0,
            confidence: 0.0,
            freshness: 0.0,
            scope: 0.0,
        };
        normalize_and_score(&mut candidates, weights, Normalization::Global);
        assert!((candidates[0].capsule.relevance - 1.0).abs() < 1e-6);
        let weak = candidates[1].capsule.relevance;
        assert!(
            (weak - (0.1 / 0.9)).abs() < 1e-6,
            "global normalizes against the single max, got {weak}"
        );
        assert!(weak < candidates[0].capsule.relevance);
    }

    /// v2.7: candidate builder for the supersession tests — a memory with an
    /// embedding, a creation time, and a pre-set score.
    fn superseding_candidate(
        id: &str,
        embedding: Vec<f32>,
        created_at: &str,
        score: f32,
    ) -> Candidate {
        Candidate {
            capsule: ContextCapsule {
                id: id.to_string(),
                kind: "memory".to_string(),
                summary: id.to_string(),
                token_estimate: 0,
                expansion_handle: format!("memory:{id}"),
                provenance: Vec::new(),
                confidence: 0.0,
                freshness: 0.0,
                relevance: 0.0,
                scope_weight: 0.0,
                score,
                superseded_hint: false,
                rerank_policy_tier: 0,
                claim_revision: None,
                facts: vec![],
                rerank_usefulness: None,
                rerank_trust: None,
            },
            raw_relevance: score,
            embedding: Some(embedding),
            // Query relevance for relaxed, cue-qualified supersession tests.
            cosine: Some(score),
            created_at: Some(created_at.to_string()),
        }
    }

    /// v2.7: near-duplicate pair — the OLDER one is penalized so the newer
    /// statement of the topic outranks it even when citations boosted it.
    #[test]
    fn supersession_penalizes_the_older_near_duplicate() {
        let mut candidates = vec![
            // Old, cited, currently winning (score 0.94 > 0.87).
            superseding_candidate("old", vec![1.0, 0.0], "2026-08-01T10:00:00Z", 0.94),
            superseding_candidate("new", vec![0.99, 0.14], "2026-08-01T10:10:00Z", 0.87),
        ];
        apply_supersession_penalty(&mut candidates);
        let old_score = candidates[0].capsule.score;
        let new_score = candidates[1].capsule.score;
        assert!(
            (old_score - 0.94 * SUPERSESSION_PENALTY).abs() < 1e-6,
            "older twin must carry the penalty, got {old_score}"
        );
        assert!((new_score - 0.87).abs() < 1e-6, "newer twin untouched");
        assert!(
            new_score > old_score,
            "the update must now outrank the incumbent"
        );
    }

    /// Distinct memories (low mutual cosine) must not penalize each other,
    /// and the penalty applies at most once however many newer siblings exist.
    #[test]
    fn supersession_ignores_distinct_memories_and_applies_once() {
        let mut candidates = vec![
            superseding_candidate("old", vec![1.0, 0.0], "2026-08-01T10:00:00Z", 0.90),
            // Orthogonal embedding — different topic entirely.
            superseding_candidate("other", vec![0.0, 1.0], "2026-08-02T10:00:00Z", 0.80),
            // Two newer near-duplicates of `old`.
            superseding_candidate("new1", vec![0.99, 0.14], "2026-08-03T10:00:00Z", 0.70),
            superseding_candidate("new2", vec![0.98, 0.19], "2026-08-04T10:00:00Z", 0.60),
        ];
        apply_supersession_penalty(&mut candidates);
        assert!(
            (candidates[0].capsule.score - 0.90 * SUPERSESSION_PENALTY).abs() < 1e-6,
            "penalty applies exactly once, got {}",
            candidates[0].capsule.score
        );
        assert!(
            (candidates[1].capsule.score - 0.80).abs() < 1e-6,
            "orthogonal memory untouched"
        );
        // new1 is itself older than new2 and near-duplicate of it.
        assert!(
            (candidates[2].capsule.score - 0.70 * SUPERSESSION_PENALTY).abs() < 1e-6,
            "a middle sibling is old relative to a newer one"
        );
        assert!(
            (candidates[3].capsule.score - 0.60).abs() < 1e-6,
            "newest untouched"
        );
    }

    /// Lean builds (no embeddings) and unparseable timestamps are inert.
    #[test]
    fn supersession_is_inert_without_embeddings_or_timestamps() {
        let mut no_embedding = vec![
            Candidate {
                embedding: None,
                ..superseding_candidate("a", vec![], "2026-08-01T10:00:00Z", 0.9)
            },
            Candidate {
                embedding: None,
                ..superseding_candidate("b", vec![], "2026-08-02T10:00:00Z", 0.8)
            },
        ];
        apply_supersession_penalty(&mut no_embedding);
        assert!((no_embedding[0].capsule.score - 0.9).abs() < 1e-6);

        let mut bad_ts = vec![
            superseding_candidate("a", vec![1.0, 0.0], "not-a-date", 0.9),
            superseding_candidate("b", vec![1.0, 0.0], "2026-08-02T10:00:00Z", 0.8),
        ];
        apply_supersession_penalty(&mut bad_ts);
        assert!(
            (bad_ts[0].capsule.score - 0.9).abs() < 1e-6,
            "unparseable ts skipped"
        );
        assert!((bad_ts[1].capsule.score - 0.8).abs() < 1e-6);

        // Identical timestamps: no defensible "older", both untouched.
        let mut same_ts = vec![
            superseding_candidate("a", vec![1.0, 0.0], "2026-08-01T10:00:00Z", 0.9),
            superseding_candidate("b", vec![1.0, 0.0], "2026-08-01T10:00:00Z", 0.8),
        ];
        apply_supersession_penalty(&mut same_ts);
        assert!((same_ts[0].capsule.score - 0.9).abs() < 1e-6);
        assert!((same_ts[1].capsule.score - 0.8).abs() < 1e-6);

        // Sub-second gap: one authoring event (same batch ingest), not a
        // supersession — both untouched even though one is nominally older.
        let mut batch = vec![
            superseding_candidate("a", vec![1.0, 0.0], "2026-08-01T10:00:00.100Z", 0.9),
            superseding_candidate("b", vec![1.0, 0.0], "2026-08-01T10:00:00.900Z", 0.8),
        ];
        apply_supersession_penalty(&mut batch);
        assert!(
            (batch[0].capsule.score - 0.9).abs() < 1e-6,
            "millisecond-apart co-writes must not be penalized"
        );
        assert!((batch[1].capsule.score - 0.8).abs() < 1e-6);

        // A batch-imported correction can establish direction in its text.
        // Timestamp order is deliberately reversed here: the explicit cue,
        // not arbitrary JSONL order, identifies the replacement.
        let mut explicit_update = vec![
            superseding_candidate(
                "the project uses spaces (switched from tabs)",
                vec![1.0, 0.0],
                "2026-08-01T10:00:00.100Z",
                0.9,
            ),
            superseding_candidate(
                "the project uses tabs for indentation",
                // Cosine 0.83: below the ordinary 0.85 floor, above the
                // cue-qualified 0.82 floor.
                vec![0.83, 0.557_8],
                "2026-08-01T10:00:00.900Z",
                0.8,
            ),
        ];
        apply_supersession_penalty(&mut explicit_update);
        assert!((explicit_update[0].capsule.score - 0.9).abs() < 1e-6);
        assert!(
            (explicit_update[1].capsule.score - 0.8 * SUPERSESSION_PENALTY).abs() < 1e-6,
            "the unmarked incumbent must lose to the explicit correction"
        );
        assert!(explicit_update[1].capsule.superseded_hint);

        // Rewritten updates can move far in embedding space while retaining a
        // dense lexical identity. Correction cue + overlap recovers direction.
        let mut rewritten_update = vec![
            superseding_candidate(
                "as of v2 the preferred kimetsu embedder is jina, replacing bge",
                vec![1.0, 0.0],
                "2026-08-01T10:00:00.100Z",
                0.9,
            ),
            superseding_candidate(
                "the recommended kimetsu embedder for retrieval is bge",
                vec![0.71, 0.704_2],
                "2026-08-01T10:00:00.900Z",
                0.8,
            ),
        ];
        apply_supersession_penalty(&mut rewritten_update);
        assert!((rewritten_update[0].capsule.score - 0.9).abs() < 1e-6);
        assert!((rewritten_update[1].capsule.score - 0.8 * SUPERSESSION_PENALTY).abs() < 1e-6);

        // The same pair asked as a historical question favors the incumbent
        // by query cosine, so the relaxed relationship must not penalize it.
        let mut historical_query = vec![
            Candidate {
                cosine: Some(0.70),
                ..superseding_candidate(
                    "as of v2 the preferred kimetsu embedder is jina, replacing bge",
                    vec![1.0, 0.0],
                    "2026-08-01T10:00:00.100Z",
                    0.9,
                )
            },
            Candidate {
                cosine: Some(0.90),
                ..superseding_candidate(
                    "the recommended kimetsu embedder for retrieval is bge",
                    vec![0.71, 0.704_2],
                    "2026-08-01T10:00:00.900Z",
                    0.8,
                )
            },
        ];
        apply_supersession_penalty(&mut historical_query);
        assert!((historical_query[0].capsule.score - 0.9).abs() < 1e-6);
        assert!((historical_query[1].capsule.score - 0.8).abs() < 1e-6);

        // A cue is evidence of direction, not permission to join unrelated
        // topics: below the cue-qualified similarity floor both remain intact.
        let mut too_distant = vec![
            superseding_candidate(
                "the project now uses spaces",
                vec![1.0, 0.0],
                "2026-08-01T10:00:00.100Z",
                0.9,
            ),
            superseding_candidate(
                "database backup retention is seven days",
                vec![0.81, 0.586_4],
                "2026-08-01T10:00:00.900Z",
                0.8,
            ),
        ];
        apply_supersession_penalty(&mut too_distant);
        assert!((too_distant[0].capsule.score - 0.9).abs() < 1e-6);
        assert!((too_distant[1].capsule.score - 0.8).abs() < 1e-6);

        // Two update-like variants are ambiguous and remain untouched.
        let mut ambiguous = vec![
            superseding_candidate(
                "the setting is now cheap_model",
                vec![1.0, 0.0],
                "2026-08-01T10:00:00.100Z",
                0.9,
            ),
            superseding_candidate(
                "as of v2 the setting is cheap_model",
                vec![1.0, 0.0],
                "2026-08-01T10:00:00.900Z",
                0.8,
            ),
        ];
        apply_supersession_penalty(&mut ambiguous);
        assert!((ambiguous[0].capsule.score - 0.9).abs() < 1e-6);
        assert!((ambiguous[1].capsule.score - 0.8).abs() < 1e-6);
    }

    /// An unknown or empty value must not silently change ranking — a typo in
    /// project.toml falls back to the shipped rule.
    #[test]
    fn unknown_normalization_falls_back_to_per_kind() {
        assert_eq!(Normalization::from_config(""), Normalization::PerKind);
        assert_eq!(
            Normalization::from_config("per_kind"),
            Normalization::PerKind
        );
        assert_eq!(
            Normalization::from_config("nonsense"),
            Normalization::PerKind
        );
        assert_eq!(Normalization::from_config("global"), Normalization::Global);
        assert_eq!(
            Normalization::from_config("  GLOBAL "),
            Normalization::Global
        );
    }

    #[test]
    fn weights_for_task_kind_renormalizes_to_unit_sum() {
        let base = StageWeights {
            relevance: 0.50,
            confidence: 0.20,
            freshness: 0.20,
            scope: 0.10,
        };
        let original_sum = base.relevance + base.confidence + base.freshness + base.scope;

        for kind in [
            TaskKind::Debug,
            TaskKind::Refactor,
            TaskKind::Investigation,
            TaskKind::Docs,
        ] {
            let w = weights_for_task_kind(base.clone(), kind);
            let new_sum = w.relevance + w.confidence + w.freshness + w.scope;
            // Renormalized to 1.0; the original_sum is also 1.0 for these weights.
            assert!(
                (new_sum - original_sum).abs() < 1e-4,
                "weights_for_task_kind({kind:?}) sum {new_sum} differs from {original_sum}"
            );
        }
    }

    /// E3-2b: Feature is the neutral kind — weights unchanged.
    #[test]
    fn weights_for_task_kind_feature_is_unchanged() {
        let base = StageWeights {
            relevance: 0.40,
            confidence: 0.30,
            freshness: 0.20,
            scope: 0.10,
        };
        let w = weights_for_task_kind(base.clone(), TaskKind::Feature);
        assert!((w.relevance - base.relevance).abs() < f32::EPSILON);
        assert!((w.confidence - base.confidence).abs() < f32::EPSILON);
        assert!((w.freshness - base.freshness).abs() < f32::EPSILON);
        assert!((w.scope - base.scope).abs() < f32::EPSILON);
    }

    /// E3-2c: Debug biases toward freshness; after renorm, freshness
    /// fraction must be strictly larger than in the base weights.
    #[test]
    fn weights_for_task_kind_debug_up_freshness_fraction() {
        let base = StageWeights {
            relevance: 0.50,
            confidence: 0.20,
            freshness: 0.20,
            scope: 0.10,
        };
        let debug_w = weights_for_task_kind(base.clone(), TaskKind::Debug);
        // Freshness fraction = freshness / sum = freshness (since sum=1 after renorm).
        assert!(
            debug_w.freshness > base.freshness,
            "Debug must increase freshness fraction: {debug_w:?}"
        );
    }

    /// E3-2d: Refactor biases toward scope; after renorm, scope fraction
    /// must be strictly larger than in the base weights.
    #[test]
    fn weights_for_task_kind_refactor_up_scope_fraction() {
        let base = StageWeights {
            relevance: 0.50,
            confidence: 0.20,
            freshness: 0.20,
            scope: 0.10,
        };
        let refactor_w = weights_for_task_kind(base.clone(), TaskKind::Refactor);
        assert!(
            refactor_w.scope > base.scope,
            "Refactor must increase scope fraction: {refactor_w:?}"
        );
    }

    /// E3-3: Feature is truly neutral — retrieval with task_kind=Feature
    /// returns the same capsule set as with the default ContextRequest.
    #[test]
    fn task_kind_feature_is_retrieval_neutral() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");

        // Insert a few memories so retrieval has something to return.
        // DB columns: scope='project', kind=actual memory kind.
        // Broker formats summary as "{scope}:{kind} - {text}".
        for (mid, db_kind, text) in [
            ("m1", "failure_pattern", "linker not found error in build"),
            ("m2", "convention", "use snake_case for all identifiers"),
            ("m3", "fact", "the cache is invalidated on every deploy"),
        ] {
            let normalized = kimetsu_core::memory::normalize_memory_text(text);
            conn.execute(
                "INSERT INTO memories (
                     memory_id, scope, kind, text, normalized_text, confidence,
                     source_event_id, provenance_snapshot_json, created_at,
                     use_count, usefulness_score
                 )
                 VALUES (?1, 'project', ?2, ?3, ?4, 1.0, NULL, '{}',
                         '2026-01-01T00:00:00Z', 0, 0.0)",
                rusqlite::params![mid, db_kind, text, normalized],
            )
            .expect("insert memory");
            conn.execute(
                "INSERT INTO memories_fts (memory_id, text, kind, scope)
                 VALUES (?1, ?2, ?3, 'project')",
                rusqlite::params![mid, text, db_kind],
            )
            .expect("insert fts");
        }

        let weights = kimetsu_core::config::BrokerWeights::default();
        let query = "cache convention failure".to_string();

        // Baseline: no task_kind set (Default::default() → Feature)
        let baseline = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: query.clone(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("baseline retrieve");

        // Explicit Feature: must be identical to baseline
        let feature = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: query.clone(),
                budget_tokens: 4000,
                task_kind: TaskKind::Feature,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("feature retrieve");

        let baseline_ids: Vec<&str> = baseline
            .capsules
            .iter()
            .map(|c| c.expansion_handle.as_str())
            .collect();
        let feature_ids: Vec<&str> = feature
            .capsules
            .iter()
            .map(|c| c.expansion_handle.as_str())
            .collect();
        assert_eq!(
            baseline_ids, feature_ids,
            "task_kind=Feature must produce identical retrieval to default; \
             baseline={baseline_ids:?} feature={feature_ids:?}"
        );

        let baseline_scores: Vec<f32> = baseline.capsules.iter().map(|c| c.score).collect();
        let feature_scores: Vec<f32> = feature.capsules.iter().map(|c| c.score).collect();
        for (b, f) in baseline_scores.iter().zip(feature_scores.iter()) {
            assert!(
                (b - f).abs() < 1e-5,
                "scores must be identical: baseline={b} feature={f}"
            );
        }
    }

    /// E3-4: headline behavioral proof — Debug routes strictly more
    /// failure_pattern capsules than Docs over the same corpus + query.
    ///
    /// Setup: 4 failure_pattern memories + 4 convention/fact memories
    /// that all share a common topic keyword "auth". We cap at 4 capsules
    /// and compare how many are failure_pattern between Debug and Docs.
    ///
    /// Memory row layout: `scope='project'`, `kind='failure_pattern'` (or
    /// `'convention'`/`'fact'`). The broker formats the capsule summary as
    /// `"{scope}:{kind} - {text}"` so `capsule_matches_kind` can parse it.
    #[test]
    fn debug_surfaces_more_failure_pattern_than_docs() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");

        // Insert 4 failure_pattern memories.
        // DB columns: scope='project', kind='failure_pattern'
        // Broker formats summary as "project:failure_pattern - <text>".
        for (i, text) in [
            "auth token expired causes login failure",
            "auth service crash on null pointer",
            "auth regression after upgrade breaks sessions",
            "auth error when certificate is invalid",
        ]
        .iter()
        .enumerate()
        {
            let mid = format!("mfp{i}");
            let normalized = kimetsu_core::memory::normalize_memory_text(text);
            conn.execute(
                "INSERT INTO memories (
                     memory_id, scope, kind, text, normalized_text, confidence,
                     source_event_id, provenance_snapshot_json, created_at,
                     use_count, usefulness_score
                 )
                 VALUES (?1, 'project', 'failure_pattern', ?2, ?3, 1.0, NULL, '{}',
                         '2026-01-01T00:00:00Z', 0, 0.0)",
                rusqlite::params![mid, text, normalized],
            )
            .expect("insert failure_pattern");
            conn.execute(
                "INSERT INTO memories_fts (memory_id, text, kind, scope)
                 VALUES (?1, ?2, 'failure_pattern', 'project')",
                rusqlite::params![mid, text],
            )
            .expect("insert fts");
        }

        // Insert 4 convention/fact memories — also mention "auth".
        // DB columns: scope='project', kind='convention' or 'fact'.
        for (i, (db_kind, text)) in [
            ("convention", "auth module uses bearer tokens by convention"),
            ("convention", "auth scopes are documented in the API guide"),
            ("fact", "auth service runs on port 8443 in production"),
            ("fact", "auth uses JWT with RS256 signing for all tokens"),
        ]
        .iter()
        .enumerate()
        {
            let mid = format!("mconv{i}");
            let normalized = kimetsu_core::memory::normalize_memory_text(text);
            conn.execute(
                "INSERT INTO memories (
                     memory_id, scope, kind, text, normalized_text, confidence,
                     source_event_id, provenance_snapshot_json, created_at,
                     use_count, usefulness_score
                 )
                 VALUES (?1, 'project', ?2, ?3, ?4, 1.0, NULL, '{}',
                         '2026-01-01T00:00:00Z', 0, 0.0)",
                rusqlite::params![mid, db_kind, text, normalized],
            )
            .expect("insert convention/fact");
            conn.execute(
                "INSERT INTO memories_fts (memory_id, text, kind, scope)
                 VALUES (?1, ?2, ?3, 'project')",
                rusqlite::params![mid, text, db_kind],
            )
            .expect("insert fts");
        }

        let weights = kimetsu_core::config::BrokerWeights::default();
        let query = "auth token failure".to_string();

        // Retrieve with Debug task_kind
        let debug_bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: query.clone(),
                budget_tokens: 4000,
                max_capsules: 4,
                task_kind: TaskKind::Debug,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("debug retrieve");

        // Retrieve with Docs task_kind
        let docs_bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &weights,
            ContextRequest {
                stage: "localization".to_string(),
                query: query.clone(),
                budget_tokens: 4000,
                max_capsules: 4,
                task_kind: TaskKind::Docs,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("docs retrieve");

        // Count failure_pattern capsules in each result.
        // Memory capsules have kind="memory"; the real kind is in the summary prefix.
        let count_failure_pattern = |bundle: &ContextBundle| -> usize {
            bundle
                .capsules
                .iter()
                .filter(|c| capsule_matches_kind(c, "failure_pattern"))
                .count()
        };

        let debug_fp = count_failure_pattern(&debug_bundle);
        let docs_fp = count_failure_pattern(&docs_bundle);

        assert!(
            debug_fp > docs_fp,
            "Debug must surface strictly more failure_pattern capsules than Docs: \
             debug_fp={debug_fp} docs_fp={docs_fp}\n\
             Debug capsules: {:?}\n\
             Docs capsules: {:?}",
            debug_bundle
                .capsules
                .iter()
                .map(|c| format!("{}:{}", c.kind, &c.summary[..c.summary.len().min(60)]))
                .collect::<Vec<_>>(),
            docs_bundle
                .capsules
                .iter()
                .map(|c| format!("{}:{}", c.kind, &c.summary[..c.summary.len().min(60)]))
                .collect::<Vec<_>>(),
        );
    }

    // ── F2: resolve_capsule unit tests ────────────────────────────────────

    fn init_db_with_memory(memory_id: &str, text: &str) -> rusqlite::Connection {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");
        let normalized = kimetsu_core::memory::normalize_memory_text(text);
        conn.execute(
            "INSERT INTO memories (
                 memory_id, scope, kind, text, normalized_text, confidence,
                 source_event_id, provenance_snapshot_json, created_at,
                 use_count, usefulness_score
             )
             VALUES (?1, 'project', 'fact', ?2, ?3, 1.0, NULL, '{}',
                     '2026-01-01T00:00:00Z', 0, 0.0)",
            rusqlite::params![memory_id, text, normalized],
        )
        .expect("insert memory");
        conn
    }

    /// F2-1: memory:<id> resolves to the full memory text.
    #[test]
    fn resolve_capsule_memory_returns_full_text() {
        let conn = init_db_with_memory("test-mem-id", "Use rg over grep for speed");
        let repo_root = std::path::Path::new("/fake-repo");
        let result =
            resolve_capsule(&conn, repo_root, "memory:test-mem-id").expect("should resolve");
        assert_eq!(result, "Use rg over grep for speed");
    }

    /// F2-2: memory:<id> for a non-existent id returns Err.
    #[test]
    fn resolve_capsule_memory_missing_id_returns_err() {
        let conn = init_db_with_memory("real-id", "some text");
        let repo_root = std::path::Path::new("/fake-repo");
        let err = resolve_capsule(&conn, repo_root, "memory:nonexistent-id")
            .expect_err("should error for missing memory");
        assert!(
            err.to_string().contains("no active memory"),
            "error message should mention missing: {err}"
        );
    }

    /// F2-3: file:<path> returns a bounded slice of the file content.
    #[test]
    fn resolve_capsule_file_returns_bounded_content() {
        let dir = make_test_dir("f2_file_resolve");
        let content = "hello from the file\n";
        std::fs::write(dir.join("notes.txt"), content).expect("write");
        let result = resolve_capsule(
            // conn is unused for file: handles; pass an in-memory DB
            &rusqlite::Connection::open_in_memory().expect("open"),
            &dir,
            "file:notes.txt",
        )
        .expect("should resolve file");
        assert!(result.contains("hello from the file"));
        std::fs::remove_dir_all(&dir).ok();
    }

    /// F2-4: file:<path> for a large file is capped at FILE_EXPAND_CAP_BYTES.
    #[test]
    fn resolve_capsule_file_caps_large_file() {
        let dir = make_test_dir("f2_file_cap");
        let big = "A".repeat(FILE_EXPAND_CAP_BYTES * 3);
        std::fs::write(dir.join("big.txt"), &big).expect("write");
        let result = resolve_capsule(
            &rusqlite::Connection::open_in_memory().expect("open"),
            &dir,
            "file:big.txt",
        )
        .expect("should resolve large file");
        assert!(
            result.len() <= FILE_EXPAND_CAP_BYTES + 200,
            "result should be bounded: got {} bytes",
            result.len()
        );
        assert!(
            result.contains("truncated"),
            "truncation marker should be present"
        );
        std::fs::remove_dir_all(&dir).ok();
    }

    /// F2-5: unknown handle format returns Err.
    #[test]
    fn resolve_capsule_unknown_handle_returns_err() {
        let conn = rusqlite::Connection::open_in_memory().expect("open");
        let err = resolve_capsule(&conn, std::path::Path::new("/r"), "blob:abc123")
            .expect_err("should error");
        assert!(
            err.to_string().contains("unrecognised handle"),
            "got: {err}"
        );
    }

    /// F2-6: malformed handle (no colon) returns Err.
    #[test]
    fn resolve_capsule_malformed_handle_returns_err() {
        let conn = rusqlite::Connection::open_in_memory().expect("open");
        let err = resolve_capsule(&conn, std::path::Path::new("/r"), "justnocolon")
            .expect_err("should error");
        assert!(
            err.to_string().contains("unrecognised handle"),
            "got: {err}"
        );
    }

    /// F2-7: run:<id> returns the deferred-error message.
    #[test]
    fn resolve_capsule_run_handle_returns_deferred_err() {
        let conn = rusqlite::Connection::open_in_memory().expect("open");
        let err = resolve_capsule(&conn, std::path::Path::new("/r"), "run:some-run-id")
            .expect_err("run: should be deferred err");
        assert!(err.to_string().contains("not yet supported"), "got: {err}");
    }

    /// F2-8: file:<path> with absolute path is rejected.
    #[test]
    fn resolve_capsule_file_rejects_absolute_path() {
        let conn = rusqlite::Connection::open_in_memory().expect("open");
        let err = resolve_capsule(&conn, std::path::Path::new("/r"), "file:/etc/passwd")
            .expect_err("should reject absolute path");
        assert!(err.to_string().contains("absolute path"), "got: {err}");
    }

    // ── v1.0.0 rerank_capsules tests ─────────────────────────────────────────

    fn make_capsule(summary: &str, score: f32) -> ContextCapsule {
        ContextCapsule {
            id: new_id().to_string(),
            kind: "memory".to_string(),
            summary: summary.to_string(),
            token_estimate: 10,
            expansion_handle: format!("memory:{}", new_id()),
            provenance: vec![],
            confidence: 1.0,
            freshness: 1.0,
            relevance: 1.0,
            scope_weight: 1.0,
            score,
            superseded_hint: false,
            rerank_policy_tier: 0,
            claim_revision: None,
            facts: vec![],
            rerank_usefulness: None,
            rerank_trust: None,
        }
    }

    /// RR-1: capsule whose summary shares more query words ranks first and
    /// the score field is overwritten by the reranker's sigmoid-normalized score.
    #[test]
    fn rerank_capsules_reorders_by_query_overlap() {
        use crate::embeddings::StubReranker;

        // Two capsules: "rust async tokio" shares 3/3 query tokens;
        // "python django" shares 0/3.
        let query = "rust async tokio";
        let high_overlap = make_capsule("rust async tokio runtime", 0.0);
        let low_overlap = make_capsule("python django framework", 0.0);
        // Input order: low-overlap first to verify it gets pushed down.
        let capsules = vec![low_overlap.clone(), high_overlap.clone()];

        let ranked = rerank_capsules(query, capsules, &StubReranker, 0.0, 0);

        assert_eq!(ranked.len(), 2, "both capsules should survive (floor=0)");
        // The high-overlap capsule must rank first.
        assert!(
            ranked[0].summary.contains("rust"),
            "rust capsule must be first, got: {:?}",
            ranked[0].summary
        );
        // Score must be overwritten (was 0.0, now > 0.05 for the high-overlap one).
        assert!(
            ranked[0].score > 0.05,
            "score must be overwritten by reranker: {}",
            ranked[0].score
        );
        // High-overlap must score above low-overlap.
        assert!(
            ranked[0].score > ranked[1].score,
            "high overlap must score higher: {} vs {}",
            ranked[0].score,
            ranked[1].score
        );
    }

    /// RR-2: floor drops a zero-overlap capsule.
    /// StubReranker scores a zero-overlap doc at 0.05.
    /// A floor of 0.3 must drop it.
    #[test]
    fn rerank_capsules_floor_drops_zero_overlap() {
        use crate::embeddings::StubReranker;

        let query = "rust async tokio";
        let high = make_capsule("rust async tokio runtime", 0.0);
        let zero = make_capsule("completely unrelated document xyz", 0.0); // 0-overlap → 0.05

        let capsules = vec![high, zero];
        let ranked = rerank_capsules(query, capsules, &StubReranker, 0.3, 0);

        // The zero-overlap capsule (score 0.05) must be dropped by floor=0.3.
        assert_eq!(ranked.len(), 1, "zero-overlap capsule must be dropped");
        assert!(
            ranked[0].summary.contains("rust"),
            "only rust capsule should survive"
        );
    }

    /// RR-3: cap truncates the result.
    #[test]
    fn rerank_capsules_cap_truncates() {
        use crate::embeddings::StubReranker;

        let query = "alpha beta gamma";
        let capsules = vec![
            make_capsule("alpha beta gamma delta", 0.0),
            make_capsule("alpha beta", 0.0),
            make_capsule("alpha", 0.0),
            make_capsule("unrelated xyz", 0.0),
        ];

        let ranked = rerank_capsules(query, capsules, &StubReranker, 0.0, 2);
        assert_eq!(ranked.len(), 2, "cap=2 must truncate to 2 results");
        // The top-2 should be the higher-overlap ones.
        assert!(
            ranked[0].score >= ranked[1].score,
            "results must be sorted descending"
        );
    }

    #[test]
    fn hardening_usefulness_cannot_dominate_relevance() {
        let neutral = make_capsule("neutral", 0.0);
        let mut useful = make_capsule("useful", 0.0);
        useful.rerank_policy_tier = 1;
        let out = rerank_capsules(
            "q",
            vec![neutral, useful],
            &TwoScoreReranker(0.99, 0.31),
            0.30,
            0,
        );
        assert_eq!(out[0].summary, "neutral");
        assert!(out[1].score <= 0.410001);
    }

    #[test]
    fn hardening_rerank_preserves_decayed_usefulness_and_trust() {
        let neutral = make_capsule("neutral", 0.0);
        let mut stale_useful = make_capsule("stale", 0.0);
        stale_useful.rerank_policy_tier = 1;
        stale_useful.rerank_usefulness = Some(1.0001);
        let out = rerank_capsules(
            "q",
            vec![neutral.clone(), stale_useful],
            &TwoScoreReranker(0.9, 0.85),
            0.0,
            0,
        );
        assert_eq!(out[0].summary, "neutral");
        let mut imported = make_capsule("imported", 0.0);
        imported.rerank_usefulness = Some(1.5);
        imported.rerank_trust = Some(0.5);
        let out = rerank_capsules(
            "q",
            vec![neutral, imported],
            &TwoScoreReranker(0.8, 0.9),
            0.0,
            0,
        );
        assert_eq!(out[0].summary, "neutral");
        assert!((out[1].score - 0.5).abs() < 0.00001);
    }

    #[test]
    fn hardening_freshness_has_thirty_day_half_life() {
        let past = (OffsetDateTime::now_utc() - time::Duration::days(30))
            .format(&time::format_description::well_known::Rfc3339)
            .unwrap();
        assert!((freshness(&past) - 0.5).abs() < 0.0001);
    }

    #[test]
    fn rerank_reapplies_usefulness_but_not_to_superseded_capsules() {
        let neutral = make_capsule("neutral", 0.0);
        let mut useful = make_capsule("useful", 0.0);
        useful.rerank_policy_tier = 1;

        let out = rerank_capsules(
            "q",
            vec![neutral.clone(), useful.clone()],
            &TwoScoreReranker(0.59, 0.50),
            0.0,
            0,
        );
        assert_eq!(out[0].summary, "useful", "usefulness survives reranking");

        useful.superseded_hint = true;
        useful.rerank_policy_tier = 1;
        let out = rerank_capsules(
            "q",
            vec![neutral, useful],
            &TwoScoreReranker(0.59, 0.50),
            0.0,
            0,
        );
        assert_eq!(
            out[0].summary, "neutral",
            "superseded memories must not keep their historic usefulness boost"
        );
        assert!(
            (out[1].score - 0.40).abs() < 1e-6,
            "supersession must be reapplied to the raw rerank score"
        );
    }

    /// RR-4: fail-open — a broken reranker returns Err; input order is preserved.
    #[test]
    fn rerank_capsules_fail_open_preserves_input_order() {
        struct FailingReranker;
        impl crate::embeddings::Reranker for FailingReranker {
            fn rerank(
                &self,
                _query: &str,
                _docs: &[&str],
            ) -> Result<Vec<f32>, crate::embeddings::EmbedderError> {
                Err(crate::embeddings::EmbedderError::EmbedFailed(
                    "simulated failure".into(),
                ))
            }
            fn model_id(&self) -> &str {
                "fail-reranker"
            }
        }

        let query = "anything";
        let c1 = make_capsule("first capsule", 0.9);
        let c2 = make_capsule("second capsule", 0.5);
        let c3 = make_capsule("third capsule", 0.1);
        let capsules = vec![c1.clone(), c2.clone(), c3.clone()];

        let out = rerank_capsules(query, capsules, &FailingReranker, 0.0, 0);

        // On error: input order preserved, all 3 capsules returned.
        assert_eq!(out.len(), 3, "all capsules must be returned on error");
        assert_eq!(out[0].summary, c1.summary, "order must be preserved");
        assert_eq!(out[1].summary, c2.summary, "order must be preserved");
        assert_eq!(out[2].summary, c3.summary, "order must be preserved");
    }

    /// RR-0: empty input → empty output.
    #[test]
    fn rerank_capsules_empty_input_returns_empty() {
        use crate::embeddings::StubReranker;
        let out = rerank_capsules("query", vec![], &StubReranker, 0.0, 0);
        assert!(out.is_empty());
    }

    // ── v2.7: evidence-band arbitration ─────────────────────────────────────

    /// Reranker that returns one fixed score per doc, for band tests.
    struct FixedReranker(f32);
    impl crate::embeddings::Reranker for FixedReranker {
        fn rerank(
            &self,
            _query: &str,
            docs: &[&str],
        ) -> Result<Vec<f32>, crate::embeddings::EmbedderError> {
            Ok(vec![self.0; docs.len()])
        }
        fn model_id(&self) -> &str {
            "fixed-reranker"
        }
    }

    struct TwoScoreReranker(f32, f32);
    impl crate::embeddings::Reranker for TwoScoreReranker {
        fn rerank(
            &self,
            _query: &str,
            _docs: &[&str],
        ) -> Result<Vec<f32>, crate::embeddings::EmbedderError> {
            Ok(vec![self.0, self.1])
        }
        fn model_id(&self) -> &str {
            "two-score"
        }
    }

    fn band_bundle(top_abs_evidence: f32) -> ContextBundle {
        let mut capsule = make_capsule("a memory lesson", 0.9);
        capsule.kind = "memory".to_string();
        capsule.token_estimate = 10;
        ContextBundle {
            stage: "localization".into(),
            budget_tokens: 4000,
            used_tokens: 10,
            capsules: vec![capsule],
            excluded: vec![],
            skipped: false,
            top_score: 0.9,
            top_abs_evidence,
            evidence_coverage: 1.0,
            uncovered_terms: vec![],
            chronological: false,
            known_fact_conflicts: vec![],
        }
    }

    /// In-band + cross-encoder approves → injected (recall recovered).
    /// In-band + cross-encoder rejects → converted to a skipped bundle.
    #[test]
    fn band_arbitration_follows_the_cross_encoder() {
        let approve = FixedReranker(ABSTAIN_RERANK_FLOOR + 0.2);
        let out = rerank_and_arbitrate("q", band_bundle(0.50), Some(&approve), 0.55, 0.0, 0);
        assert!(!out.skipped, "approved band bundle must inject");
        assert_eq!(out.capsules.len(), 1);

        let reject = FixedReranker(ABSTAIN_RERANK_FLOOR - 0.2);
        let out = rerank_and_arbitrate("q", band_bundle(0.50), Some(&reject), 0.55, 0.0, 0);
        assert!(out.skipped, "rejected band bundle must convert to skipped");
        assert!(out.capsules.is_empty());
        assert_eq!(out.used_tokens, 0);
        assert_eq!(out.excluded.len(), 1, "rejected capsules land in excluded");
    }

    /// The evidence-band threshold is calibrated on raw cross-encoder scores,
    /// before the supersession policy is reapplied to ordering.
    #[test]
    fn band_arbitration_uses_raw_rerank_evidence() {
        let mut bundle = band_bundle(0.50);
        bundle.capsules[0].superseded_hint = true;
        bundle
            .capsules
            .push(make_capsule("irrelevant distractor", 1.0));

        let reranker = TwoScoreReranker(0.95, 0.0);
        let out = rerank_and_arbitrate("q", bundle, Some(&reranker), 0.55, 0.0, 0);
        assert!(!out.skipped, "raw rerank evidence above 0.9 must admit");
        assert_eq!(out.capsules[0].summary, "a memory lesson");
        assert!(
            out.capsules[0].score < ABSTAIN_RERANK_FLOOR,
            "the regression requires post-policy score below the raw-score floor"
        );
    }

    /// Admission evidence is computed before policy ordering and output cap.
    /// Bounded usefulness cannot displace clearly stronger raw evidence.
    #[test]
    fn band_arbitration_uses_raw_evidence_before_policy_cap() {
        let mut bundle = band_bundle(0.50);
        bundle.capsules[0].rerank_policy_tier = 1;
        bundle
            .capsules
            .push(make_capsule("high-confidence neutral", 1.0));

        let reranker = TwoScoreReranker(0.50, 0.95);
        let out = rerank_and_arbitrate("q", bundle, Some(&reranker), 0.55, 0.0, 1);
        assert!(!out.skipped, "raw evidence outside the cap must admit");
        assert_eq!(out.capsules.len(), 1);
        assert_eq!(out.capsules[0].summary, "high-confidence neutral");
    }

    /// Above the band the cross-encoder reorders but never converts, even
    /// when its scores are low.
    #[test]
    fn band_arbitration_never_converts_out_of_band_bundles() {
        let reject = FixedReranker(0.0);
        let out = rerank_and_arbitrate("q", band_bundle(0.70), Some(&reject), 0.55, 0.0, 0);
        assert!(
            !out.skipped,
            "evidence above the threshold is not arbitrated"
        );
        assert_eq!(out.capsules.len(), 1);
    }

    /// No reranker: the band FAILS CLOSED — equivalent to the plain hard gate.
    /// Out-of-band bundles pass through untouched.
    #[test]
    fn band_fails_closed_without_a_reranker() {
        let out = rerank_and_arbitrate("q", band_bundle(0.50), None, 0.55, 0.0, 0);
        assert!(out.skipped, "band without an arbiter must abstain");
        let out = rerank_and_arbitrate("q", band_bundle(0.70), None, 0.55, 0.0, 0);
        assert!(!out.skipped);
        // Gate disabled: nothing converts.
        let out = rerank_and_arbitrate("q", band_bundle(0.10), None, 0.0, 0.0, 0);
        assert!(!out.skipped);
    }

    /// Reranker that scores docs by position: first doc highest. Used to
    /// simulate the cross-encoder preferring the OLD twin's wording.
    struct PositionReranker;
    impl crate::embeddings::Reranker for PositionReranker {
        fn rerank(
            &self,
            _query: &str,
            docs: &[&str],
        ) -> Result<Vec<f32>, crate::embeddings::EmbedderError> {
            Ok((0..docs.len()).map(|i| 0.99 - 0.01 * i as f32).collect())
        }
        fn model_id(&self) -> &str {
            "position-reranker"
        }
    }

    /// The supersession penalty must survive reranking: the cross-encoder
    /// judges pure query relevance, so without reapplying the penalty on its
    /// scores an older twin whose wording matches the query better would be
    /// resurrected above its replacement (measured: resolution 0.58 → 0.36).
    #[test]
    fn supersession_penalty_survives_reranking() {
        let mut old = make_capsule("deploy via make deploy-staging", 0.7);
        old.superseded_hint = true; // marked by apply_supersession_penalty
        let new = make_capsule("deploy via make deploy-preview since the migration", 0.9);
        let mut bundle = band_bundle(0.70); // out of band: no conversion risk
        bundle.capsules = vec![old, new];

        // PositionReranker scores the OLD twin (first doc) highest: 0.99 vs
        // 0.98. The reapplied ×0.80 penalty must drop it below the new one.
        let out = rerank_and_arbitrate("q", bundle, Some(&PositionReranker), 0.55, 0.0, 0);
        assert!(!out.skipped);
        assert_eq!(out.capsules.len(), 2);
        assert!(
            out.capsules[0].summary.contains("deploy-preview"),
            "the replacement must outrank the penalized incumbent after reranking; got {:?}",
            out.capsules.iter().map(|c| &c.summary).collect::<Vec<_>>()
        );
        assert!(out.capsules[1].superseded_hint);
    }

    /// A bundle with a non-memory capsule is never converted: repo evidence
    /// stands on its own.
    #[test]
    fn band_spares_bundles_with_repo_evidence() {
        let mut bundle = band_bundle(0.50);
        let mut repo = make_capsule("README excerpt", 0.4);
        repo.kind = "repo_file".to_string();
        bundle.capsules.push(repo);
        let reject = FixedReranker(0.0);
        let out = rerank_and_arbitrate("q", bundle, Some(&reject), 0.55, 0.0, 0);
        assert!(!out.skipped, "repo capsules suppress band conversion");
    }

    // ── v1.5 Story 2.1: compress_for_render unit tests ──────────────────────

    /// CFR-1: short text (< 3 sentences) is returned unchanged (no truncation).
    #[test]
    fn compress_for_render_short_text_unchanged() {
        let text = "project:fact - Use cargo fmt before committing.";
        let out = compress_for_render(text, 3);
        assert_eq!(out, text, "short text must not be altered");
    }

    /// CFR-2: [tags: ...] prefix is stripped before capping.
    #[test]
    fn compress_for_render_strips_tags_prefix() {
        let text = "[tags: rust, cargo] Always run cargo clippy before submitting a PR.";
        let out = compress_for_render(text, 3);
        assert!(
            !out.starts_with('['),
            "tags prefix must be stripped, got: {out:?}"
        );
        assert!(
            out.contains("cargo clippy"),
            "body must remain, got: {out:?}"
        );
    }

    /// CFR-3: (context: ...) trailing suffix is stripped.
    #[test]
    fn compress_for_render_strips_context_suffix() {
        let text =
            "project:fact - Use cargo fmt. Always clippy clean. (context: Kimetsu brain lesson)";
        let out = compress_for_render(text, 5);
        assert!(
            !out.contains("(context:"),
            "context suffix must be stripped, got: {out:?}"
        );
        assert!(out.contains("cargo fmt"), "body must remain, got: {out:?}");
    }

    /// CFR-4: multi-sentence body is capped at max_sentences.
    #[test]
    fn compress_for_render_caps_sentences() {
        let text =
            "project:fact - First sentence. Second sentence. Third sentence. Fourth sentence.";
        let out = compress_for_render(text, 2);
        // Must contain "First" and "Second" but not "Third" or "Fourth".
        assert!(out.contains("First"), "first sentence must be present");
        assert!(out.contains("Second"), "second sentence must be present");
        assert!(
            !out.contains("Third"),
            "third sentence must be truncated, got: {out:?}"
        );
    }

    /// CFR-5: scope:kind prefix is preserved after compression.
    #[test]
    fn compress_for_render_preserves_scope_prefix() {
        let text = "global_user:convention - First rule. Second rule. Third rule. Fourth rule.";
        let out = compress_for_render(text, 2);
        assert!(
            out.starts_with("global_user:convention - "),
            "scope prefix must be preserved, got: {out:?}"
        );
        assert!(out.contains("First"), "first sentence must remain");
        assert!(!out.contains("Third"), "third sentence must be truncated");
    }

    /// CFR-6: empty string never panics and returns the original (empty) string.
    #[test]
    fn compress_for_render_empty_input_safe() {
        let out = compress_for_render("", 3);
        assert_eq!(out, "", "empty input must return empty string");
    }

    /// CFR-7: max_sentences=0 returns the original text unchanged (opt-out).
    #[test]
    fn compress_for_render_zero_max_sentences_returns_original() {
        let text = "project:fact - Some lesson that is quite long. It keeps going. And going.";
        let out = compress_for_render(text, 0);
        assert_eq!(out, text);
    }

    /// CFR-8: exotic UTF-8 (multi-byte characters) is handled safely.
    #[test]
    fn compress_for_render_utf8_safe() {
        let text = "project:fact - こんにちは世界. Hello world. Third sentence. Fourth sentence.";
        // Should not panic; body trimming is purely ASCII-safe (splitting on b'.')
        let out = compress_for_render(text, 2);
        assert!(!out.is_empty(), "UTF-8 text must not produce empty output");
        // The first Japanese sentence period is b'.', so cap at 2 means we cut after the 2nd.
        assert!(!out.contains("Third"), "third sentence must be truncated");
    }

    /// CFR-9: long memory (>60 tokens) is compressed by >=25%.
    /// Acceptance test for the Story 2.1 token-reduction gate.
    #[test]
    fn compress_for_render_long_memory_reduces_tokens_by_25_percent() {
        // Representative long memory text (8 sentences, well over 60 tokens).
        let long_summary = "project:fact - When a SQLite WAL file exists from a crashed process, \
            opening the DB causes the WAL to be replayed. The replayed WAL may contain \
            partial writes that corrupt the DB. Always check for WAL files before opening. \
            Delete the WAL only after verifying the DB is consistent. Use PRAGMA integrity_check \
            to validate after opening. If integrity_check fails, restore from backup. Never \
            truncate the WAL without replaying it first. This pattern applies to any \
            crash-recovery scenario.";

        let raw_tokens = estimate_tokens(long_summary);
        assert!(
            raw_tokens > 60,
            "test precondition: raw memory must be >60 tokens, got {raw_tokens}"
        );

        let compressed = compress_for_render(long_summary, 3);
        let compressed_tokens = estimate_tokens(&compressed);

        let reduction = 1.0 - (compressed_tokens as f64 / raw_tokens as f64);
        assert!(
            reduction >= 0.25,
            "compression must reduce tokens by >=25% on long memories; \
             raw={raw_tokens} compressed={compressed_tokens} reduction={reduction:.2}"
        );
    }
}

#[cfg(test)]
mod evidence_tests {
    use super::*;

    fn conn_with(texts: &[&str]) -> Connection {
        let conn = Connection::open_in_memory().expect("open");
        crate::schema::initialize(&conn).expect("schema");
        for (i, text) in texts.iter().enumerate() {
            conn.execute(
                "INSERT INTO memories
                 (memory_id, scope, kind, text, normalized_text, confidence,
                  provenance_snapshot_json, created_at)
                 VALUES (?1, 'project', 'fact', ?2, ?2, 0.9, '{}', '2026-01-01T00:00:00Z')",
                rusqlite::params![format!("m{i}"), text],
            )
            .expect("insert");
            conn.execute("INSERT INTO memories_fts(memory_id,text,kind,scope) VALUES (?1,?2,'fact','project')",
                params![format!("m{i}"),text]).unwrap();
        }
        conn
    }

    fn capsule(summary: &str) -> ContextCapsule {
        ContextCapsule {
            id: String::new(),
            kind: "memory".to_string(),
            summary: summary.to_string(),
            token_estimate: 10,
            expansion_handle: format!("memory:{summary}"),
            provenance: Vec::new(),
            confidence: 0.9,
            freshness: 0.5,
            relevance: 0.0,
            scope_weight: 0.9,
            score: 0.5,
            superseded_hint: false,
            rerank_policy_tier: 0,
            claim_revision: None,
            facts: vec![],
            rerank_usefulness: None,
            rerank_trust: None,
        }
    }

    fn bundle(capsules: Vec<ContextCapsule>, coverage: f32, uncovered: &[&str]) -> ContextBundle {
        ContextBundle {
            stage: "localization".to_string(),
            budget_tokens: 2000,
            used_tokens: 20,
            capsules,
            excluded: Vec::new(),
            skipped: false,
            top_score: 0.7,
            top_abs_evidence: 0.0,
            evidence_coverage: coverage,
            uncovered_terms: uncovered.iter().map(|s| s.to_string()).collect(),
            chronological: false,
            known_fact_conflicts: vec![],
        }
    }

    /// A bundle that answers the question fully must report full coverage and
    /// name nothing — a complete answer should cost zero extra tokens.
    #[test]
    fn full_coverage_names_nothing() {
        let conn = conn_with(&[
            "checkpoint the wal before copying brain.db",
            "vacuum reclaims dead pages",
        ]);
        let (coverage, uncovered) = evidence_coverage(
            &conn,
            "checkpoint wal",
            &[capsule(
                "project:fact - checkpoint the wal before copying brain.db",
            )],
        );
        assert!(coverage > 0.99, "got {coverage}");
        assert!(uncovered.is_empty(), "got {uncovered:?}");
    }

    /// The case that matters: capsules that touch part of the query. The
    /// reader must be told which part memory does not cover, rather than being
    /// left to infer it.
    #[test]
    fn partial_coverage_names_the_missing_terms() {
        let conn = conn_with(&[
            "checkpoint the wal before copying brain.db",
            "the migration runner snapshots before each step",
        ]);
        let (coverage, uncovered) = evidence_coverage(
            &conn,
            "checkpoint wal migration",
            &[capsule(
                "project:fact - checkpoint the wal before copying brain.db",
            )],
        );
        assert!(coverage < 1.0, "coverage should be partial: {coverage}");
        assert!(
            uncovered.iter().any(|t| t.starts_with("migrat")),
            "the uncovered term must be named: {uncovered:?}"
        );
    }

    /// Coverage is measured over the union of the capsules, not the best one:
    /// the question is whether the bundle answers the query.
    #[test]
    fn coverage_is_collective_not_per_capsule() {
        let conn = conn_with(&[
            "checkpoint the wal before copying brain.db",
            "the migration runner snapshots before each step",
        ]);
        let (coverage, uncovered) = evidence_coverage(
            &conn,
            "checkpoint migration",
            &[
                capsule("project:fact - checkpoint the wal before copying"),
                capsule("project:fact - the migration runner snapshots first"),
            ],
        );
        assert!(
            coverage > 0.99,
            "neither capsule covers both terms, but together they do: {coverage}"
        );
        assert!(uncovered.is_empty(), "got {uncovered:?}");
    }

    /// A query of nothing but stopwords has no content to measure. Claiming a
    /// gap there would make every vague question look like a memory failure.
    #[test]
    fn an_unmeasurable_query_does_not_claim_a_gap() {
        let conn = conn_with(&["checkpoint the wal"]);
        let (coverage, uncovered) =
            evidence_coverage(&conn, "the and of", &[capsule("project:fact - checkpoint")]);
        assert_eq!(coverage, 1.0);
        assert!(uncovered.is_empty());
    }

    /// The case that made this need its own IDF. A query term the corpus has
    /// never seen is the *strongest* evidence memory does not cover the
    /// question — but the per-memory floor's IDF zeroes exactly those, because
    /// there an out-of-corpus word would sink every candidate. Reusing it here
    /// made "checkpoint the wal during a kubernetes rollout" report full
    /// coverage on the strength of the WAL half alone.
    #[test]
    fn a_term_the_corpus_has_never_seen_counts_as_a_gap() {
        let conn = conn_with(&[
            "checkpoint the wal before copying brain.db",
            "vacuum reclaims dead pages",
        ]);
        let (coverage, uncovered) = evidence_coverage(
            &conn,
            "checkpoint the wal during a kubernetes rollout",
            &[capsule(
                "project:fact - checkpoint the wal before copying brain.db",
            )],
        );
        assert!(
            coverage <= PARTIAL_EVIDENCE_COVERAGE,
            "an unknown half of the question must read as thin, not complete: {coverage}"
        );
        assert!(
            uncovered.iter().any(|t| t.starts_with("kubernet")),
            "the unknown term must be named: {uncovered:?}"
        );
    }

    /// …and the mirror: a term in *every* memory (the project name) carries no
    /// signal either way and must not inflate coverage.
    #[test]
    fn a_ubiquitous_term_carries_no_weight() {
        let conn = conn_with(&["kimetsu checkpoint wal", "kimetsu vacuum pages"]);
        let (coverage, _) = evidence_coverage(
            &conn,
            "kimetsu vacuum",
            &[capsule("project:fact - kimetsu vacuum pages")],
        );
        assert!(coverage > 0.99, "got {coverage}");
    }

    #[test]
    fn an_empty_query_does_not_claim_a_gap() {
        let conn = conn_with(&["checkpoint the wal"]);
        assert_eq!(evidence_coverage(&conn, "", &[]).0, 1.0);
    }

    // ── The rendered notice ──────────────────────────────────────────────

    #[test]
    fn a_complete_bundle_gets_no_notice() {
        assert!(partial_evidence_notice(&bundle(vec![capsule("a")], 1.0, &[])).is_none());
        assert!(
            partial_evidence_notice(&bundle(vec![capsule("a")], 0.9, &["x"])).is_none(),
            "above the threshold is not partial"
        );
    }

    #[test]
    fn an_empty_or_skipped_bundle_gets_no_notice() {
        let mut skipped = bundle(Vec::new(), 0.0, &["x"]);
        skipped.skipped = true;
        assert!(
            partial_evidence_notice(&skipped).is_none(),
            "an empty bundle already says everything it can"
        );
        assert!(partial_evidence_notice(&bundle(Vec::new(), 0.0, &["x"])).is_none());
    }

    #[test]
    fn a_partial_bundle_names_what_is_missing_and_tells_the_reader_what_to_do() {
        let notice =
            partial_evidence_notice(&bundle(vec![capsule("a")], 0.3, &["migration", "rollback"]))
                .expect("a thin bundle must be flagged");
        assert!(notice.contains("migration"), "got: {notice}");
        assert!(notice.contains("rollback"), "got: {notice}");
        assert!(
            notice.contains("unknown"),
            "the notice must tell the reader to abstain, not just report a gap: {notice}"
        );
    }

    /// Naming twenty terms is noise.
    #[test]
    fn the_notice_caps_how_many_terms_it_names() {
        let terms: Vec<String> = (0..12).map(|i| format!("term{i}")).collect();
        let refs: Vec<&str> = terms.iter().map(String::as_str).collect();
        let notice =
            partial_evidence_notice(&bundle(vec![capsule("a")], 0.1, &refs)).expect("flagged");
        assert!(notice.contains("and 6 more"), "got: {notice}");
        assert!(!notice.contains("term9"), "got: {notice}");
    }

    // ── v2.6: light stemming ─────────────────────────────────────────────

    /// The defect BrainBench's sycophancy track surfaced: a query asking about
    /// `retry` treated a corpus saying `retries` as not mentioning it, because
    /// the two stemmed to `retry` and `retri` and neither prefixes the other.
    #[test]
    fn the_y_ies_pair_shares_a_stem() {
        for (a, b) in [
            ("retry", "retries"),
            ("query", "queries"),
            ("policy", "policies"),
            ("memory", "memories"),
            ("binary", "binaries"),
            ("registry", "registries"),
        ] {
            assert_eq!(
                light_stem(a),
                light_stem(b),
                "{a}/{b} stemmed to {:?}/{:?}",
                light_stem(a),
                light_stem(b)
            );
        }
    }

    /// Vowel-`y` is part of the word, not an inflection: `day` is not `da`.
    #[test]
    fn a_vowel_y_is_not_stripped() {
        assert_eq!(light_stem("delay"), "delay");
        assert_eq!(light_stem("gateway"), "gateway");
        // "journeys" strips the s (7 chars remain), and the y survives because
        // a vowel precedes it.
        assert_eq!(light_stem("journeys"), "journey");
    }

    /// Short words are left alone: over-stemming a four-letter token leaves a
    /// prefix that matches half the corpus.
    #[test]
    fn short_words_keep_their_ending() {
        assert_eq!(light_stem("body"), "body");
        assert_eq!(light_stem("copy"), "copy");
    }

    /// The pre-existing behaviour must be unchanged — this rule is additive.
    #[test]
    fn the_original_suffix_rules_still_hold() {
        assert_eq!(light_stem("benchmarked"), "benchmark");
        assert_eq!(light_stem("benchmarking"), "benchmark");
        assert_eq!(light_stem("migrations"), "migration");
        assert_eq!(light_stem("run"), "run");
    }

    /// End to end, which is the form the defect actually took: a bundle must
    /// not report a gap on a term the corpus inflects differently.
    #[test]
    fn an_inflected_corpus_term_counts_as_covered() {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");
        let text = "the ingest worker retries a failed batch three times before giving up";
        let normalized = kimetsu_core::memory::normalize_memory_text(text);
        conn.execute(
            "
            INSERT INTO memories (
                memory_id, scope, kind, text, normalized_text, confidence,
                source_event_id, provenance_snapshot_json, created_at
            )
            VALUES ('m_retry', 'project', 'fact', ?1, ?2, 1.0, NULL, '{}',
                    '2026-01-01T00:00:00Z')
            ",
            rusqlite::params![text, normalized],
        )
        .expect("insert memory");
        conn.execute(
            "INSERT INTO memories_fts (memory_id, text, kind, scope)
             VALUES ('m_retry', ?1, 'fact', 'project')",
            rusqlite::params![text],
        )
        .expect("insert fts");

        let bundle = retrieve_context_with_embedder(
            &conn,
            "/fake-repo",
            &kimetsu_core::config::BrokerWeights::default(),
            ContextRequest {
                stage: "localization".to_string(),
                query: "how many times does the ingest worker retry a failed batch".to_string(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve");

        assert!(
            !bundle.uncovered_terms.iter().any(|t| t.starts_with("retr")),
            "`retry` must match a corpus that says `retries`; uncovered: {:?}",
            bundle.uncovered_terms
        );
    }

    // ── v2.6: event ordering (crate::ordering) ──────────────────────────

    /// Seed two memories on the same topic, written months apart, and retrieve
    /// them. The end-to-end proof that `crate::ordering` is actually reachable
    /// from the broker — the unit tests there operate on capsules the broker
    /// never handed them.
    fn ordering_conn() -> rusqlite::Connection {
        let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
        crate::schema::initialize(&conn).expect("init schema");
        for (mid, created, text) in [
            (
                "m_late",
                "2026-06-01T09:00:00Z",
                "switched the error type to thiserror",
            ),
            (
                "m_early",
                "2026-01-15T10:00:00Z",
                "ran the thiserror schema migration",
            ),
        ] {
            let normalized = kimetsu_core::memory::normalize_memory_text(text);
            conn.execute(
                "
                INSERT INTO memories (
                    memory_id, scope, kind, text, normalized_text, confidence,
                    source_event_id, provenance_snapshot_json, created_at
                )
                VALUES (?1, 'project', 'fact', ?2, ?3, 1.0, NULL, '{}', ?4)
                ",
                rusqlite::params![mid, text, normalized, created],
            )
            .expect("insert memory");
            conn.execute(
                "INSERT INTO memories_fts (memory_id, text, kind, scope)
                 VALUES (?1, ?2, 'fact', 'project')",
                rusqlite::params![mid, text],
            )
            .expect("insert fts");
        }
        conn
    }

    fn ordering_bundle(conn: &rusqlite::Connection, query: &str) -> ContextBundle {
        retrieve_context_with_embedder(
            conn,
            "/fake-repo",
            &kimetsu_core::config::BrokerWeights::default(),
            ContextRequest {
                stage: "localization".to_string(),
                query: query.to_string(),
                budget_tokens: 4000,
                ..Default::default()
            },
            &[],
            &embeddings::NoopEmbedder,
        )
        .expect("retrieve")
    }

    /// The fix, end to end: asked which came first, the reader is handed the
    /// memories oldest-first with the dates it needs to answer.
    #[test]
    fn an_ordering_query_returns_a_dated_chronological_bundle() {
        let conn = ordering_conn();
        let bundle = ordering_bundle(&conn, "did we run the thiserror migration before or after");

        assert!(bundle.chronological, "the query asked about order");
        let order: Vec<&str> = bundle
            .capsules
            .iter()
            .filter_map(|c| c.expansion_handle.strip_prefix("memory:"))
            .collect();
        assert_eq!(order, vec!["m_early", "m_late"], "oldest first");
        for (capsule, date) in bundle.capsules.iter().zip(["2026-01-15", "2026-06-01"]) {
            assert!(
                capsule.summary.contains(&format!("[{date}]")),
                "every capsule carries its date; got: {}",
                capsule.summary
            );
        }
    }

    /// The narrow gate is the whole reason this is safe: an ordinary question
    /// keeps relevance order and spends no tokens on dates.
    #[test]
    fn an_ordinary_query_is_untouched() {
        let conn = ordering_conn();
        let bundle = ordering_bundle(&conn, "how do we handle thiserror errors");

        assert!(!bundle.chronological);
        for capsule in &bundle.capsules {
            assert!(
                !capsule.summary.contains('['),
                "no dates on a non-ordering query; got: {}",
                capsule.summary
            );
        }
    }

    /// Presentation, not selection: reordering runs after the budget loop, so
    /// the same capsules ship either way. If this ever diverges, ordering has
    /// started changing *what* the reader sees rather than how.
    #[test]
    fn ordering_changes_the_rendering_not_the_selection() {
        let conn = ordering_conn();
        let ordered = ordering_bundle(&conn, "did we run the thiserror migration before or after");
        let plain = ordering_bundle(&conn, "did we run the thiserror migration");

        let mut got: Vec<&str> = ordered
            .capsules
            .iter()
            .map(|c| c.expansion_handle.as_str())
            .collect();
        let mut want: Vec<&str> = plain
            .capsules
            .iter()
            .map(|c| c.expansion_handle.as_str())
            .collect();
        got.sort_unstable();
        want.sort_unstable();
        assert_eq!(got, want, "same capsules, different order");
    }

    /// The dates are real tokens and the bundle's accounting has to say so,
    /// or a budgeted caller under-counts what it just injected.
    #[test]
    fn the_dates_are_counted_against_the_budget() {
        let conn = ordering_conn();
        let ordered = ordering_bundle(&conn, "did we run the thiserror migration before or after");
        let plain = ordering_bundle(&conn, "did we run the thiserror migration");
        assert!(
            ordered.used_tokens > plain.used_tokens,
            "dated: {} vs plain: {}",
            ordered.used_tokens,
            plain.used_tokens
        );
        assert_eq!(
            ordered.used_tokens,
            ordered
                .capsules
                .iter()
                .map(|c| c.token_estimate)
                .sum::<u32>(),
            "used_tokens must match what was actually rendered"
        );
    }
}

#[cfg(test)]
mod hardening_tests {
    use super::*;

    fn corpus() -> Connection {
        let conn = Connection::open_in_memory().unwrap();
        crate::schema::initialize(&conn).unwrap();
        for (id, text) in [
            ("live", "routing routing routes"),
            ("future", "routing"),
            ("expired", "routing"),
            ("offset", "routing"),
            ("other", "rerouting unrelated"),
        ] {
            conn.execute("INSERT INTO memories (memory_id,scope,kind,text,normalized_text,confidence,created_at,provenance_snapshot_json)
                VALUES (?1,'project','fact',?2,?2,1,'2020-01-01T00:00:00Z','{}')", params![id,text]).unwrap();
            conn.execute("INSERT INTO memories_fts(memory_id,text,kind,scope) VALUES (?1,?2,'fact','project')",params![id,text]).unwrap();
        }
        conn
    }

    #[test]
    fn hardening_live_lexical_and_recency_apply_both_time_bounds() {
        let conn = corpus();
        let now = OffsetDateTime::now_utc();
        let fmt = &time::format_description::well_known::Rfc3339;
        let future = (now + time::Duration::hours(1)).format(fmt).unwrap();
        let expired = (now - time::Duration::seconds(2)).format(fmt).unwrap();
        let offset = (now - time::Duration::seconds(2))
            .to_offset(time::UtcOffset::from_hms(12, 0, 0).unwrap())
            .format(fmt)
            .unwrap();
        conn.execute(
            "UPDATE memories SET valid_from=?1 WHERE memory_id='future'",
            params![future],
        )
        .unwrap();
        conn.execute(
            "UPDATE memories SET valid_to=?1 WHERE memory_id='expired'",
            params![expired],
        )
        .unwrap();
        conn.execute(
            "UPDATE memories SET valid_to=?1 WHERE memory_id='offset'",
            params![offset],
        )
        .unwrap();
        for candidates in [
            memory_fts_candidates(
                &conn,
                &["routing".into()],
                "routing*",
                80,
                None,
                30.0,
                false,
            )
            .unwrap(),
            latest_memory_candidates(&conn, &["routing".into()], 200, None, 30.0, false).unwrap(),
        ] {
            let ids: Vec<_> = candidates
                .iter()
                .map(|c| c.capsule.expansion_handle.as_str())
                .collect();
            assert!(ids.contains(&"memory:live"));
            for id in ["memory:future", "memory:expired", "memory:offset"] {
                assert!(!ids.contains(&id), "returned {id}");
            }
        }
    }

    #[test]
    fn hardening_hydration_binds_text_revision_before_later_correction() {
        let conn = corpus();
        let candidates = memory_fts_candidates(
            &conn,
            &["routing".into()],
            "routing*",
            80,
            None,
            30.0,
            false,
        )
        .unwrap();
        let capsules: Vec<_> = candidates.into_iter().map(|c| c.capsule).collect();
        assert_eq!(memory_revision_bindings(&capsules)["live"], "baseline:live");
        conn.execute("INSERT INTO memory_revisions(memory_id,event_id,text,kind,known_at,effective_at,confidence,use_count,usefulness_score)
            VALUES ('live','corrected','changed claim','fact','2026-01-01T00:00:00Z','2026-01-01T00:00:00Z',1,0,0)",[]).unwrap();
        conn.execute(
            "UPDATE memories SET text='changed claim' WHERE memory_id='live'",
            [],
        )
        .unwrap();
        assert_eq!(
            crate::projector::claim_revision_at(&conn, "live", None).unwrap(),
            "corrected"
        );
        assert_eq!(memory_revision_bindings(&capsules)["live"], "baseline:live");
        assert!(
            capsules
                .iter()
                .find(|c| c.expansion_handle == "memory:live")
                .unwrap()
                .summary
                .contains("routing routing")
        );
    }

    #[cfg(feature = "embeddings")]
    #[test]
    fn hardening_ann_hydration_filters_time_bounds() {
        let conn = corpus();
        let blob = crate::embeddings::encode_embedding(&[1.0, 0.0]);
        conn.execute(
            "UPDATE memories SET embedding=?1,embedding_model='test'",
            params![blob],
        )
        .unwrap();
        conn.execute(
            "UPDATE memories SET valid_from='2099-01-01T00:00:00Z' WHERE memory_id='future'",
            [],
        )
        .unwrap();
        let expired = (OffsetDateTime::now_utc() - time::Duration::seconds(2))
            .to_offset(time::UtcOffset::from_hms(12, 0, 0).unwrap())
            .format(&time::format_description::well_known::Rfc3339)
            .unwrap();
        conn.execute(
            "UPDATE memories SET valid_to=?1 WHERE memory_id IN ('expired','offset')",
            params![expired],
        )
        .unwrap();
        let qe = QueryEmbedding {
            vector: vec![1.0, 0.0],
            model_id: "test".into(),
        };
        let out = memory_ann_candidates(&conn, &qe, 80, &["routing".into()], 30.0, false).unwrap();
        assert_eq!(out.len(), 2);
        for c in out {
            assert!(matches!(
                c.capsule.expansion_handle.as_str(),
                "memory:live" | "memory:other"
            ));
        }
    }

    #[test]
    fn hardening_idf_counts_prefix_documents_not_occurrences_or_substrings() {
        let conn = corpus();
        let tokens = vec!["rout".into(), "absent".into()];
        let coverage = coverage_token_idf(&conn, &tokens).unwrap();
        // Four prefix-matching documents out of five; repeated terms count once.
        assert!((coverage["rout"] - (6.0_f32 / 5.0).ln()).abs() < 0.00001);
        assert!((coverage["absent"] - 6.0_f32.ln()).abs() < 0.00001);
        assert_eq!(corpus_token_idf(&conn, &tokens).unwrap()["absent"], 0.0);
    }
}

#[cfg(test)]
mod structured_fact_hydration_tests {
    use super::*;
    use kimetsu_core::{event::Event, ids::RunId};

    #[test]
    fn lexical_and_recency_capsules_keep_their_delivered_fact_revision() {
        let c = Connection::open_in_memory().unwrap();
        crate::schema::initialize(&c).unwrap();
        crate::projector::apply_events(&c,&[Event::new(RunId::new(),"memory.accepted",serde_json::json!({
            "memory_id":"m","scope":"project","kind":"fact","text":"Orchid staging gateway port is 7319."
        }))]).unwrap();
        let mut delivered = Vec::new();
        for candidates in [
            memory_fts_candidates(&c, &["orchid".into()], "orchid*", 80, None, 30.0, true).unwrap(),
            latest_memory_candidates(&c, &["orchid".into()], 200, None, 30.0, true).unwrap(),
        ] {
            let capsule = &candidates[0].capsule;
            assert_eq!(capsule.facts.len(), 1);
            assert_eq!(capsule.facts[0].claim.value, "7319");
            assert_eq!(
                capsule.claim_revision.as_deref(),
                Some(capsule.facts[0].claim_revision.as_str())
            );
            delivered.push(capsule.clone());
        }
        crate::projector::apply_events(
            &c,
            &[Event::new(
                RunId::new(),
                "memory.corrected",
                serde_json::json!({
                    "memory_id":"m","text":"Orchid staging gateway port is 8420."
                }),
            )],
        )
        .unwrap();
        for capsule in delivered {
            assert!(capsule.summary.contains("7319"));
            assert_eq!(capsule.facts[0].claim.value, "7319");
        }
        let latest =
            latest_memory_candidates(&c, &["orchid".into()], 200, None, 30.0, true).unwrap();
        assert_eq!(latest[0].capsule.facts[0].claim.value, "8420");
    }
    #[test]
    fn legacy_wire_capsules_default_to_empty_fact_evidence() {
        let c = ContextCapsule::wire_minimal("hello".into(), "memory".into(), 1.0);
        let json = serde_json::to_value(&c).unwrap();
        assert!(json.get("facts").is_none());
        assert!(
            serde_json::from_value::<ContextCapsule>(json)
                .unwrap()
                .facts
                .is_empty()
        );
    }
}

#[cfg(test)]
mod disabled_fact_hydration_tests {
    use super::*;
    #[test]
    fn ordinary_retrieval_does_not_read_the_fact_projection() {
        let c = Connection::open_in_memory().unwrap();
        crate::schema::initialize(&c).unwrap();
        crate::projector::apply_events(
            &c,
            &[kimetsu_core::event::Event::new(
                kimetsu_core::ids::RunId::new(),
                "memory.accepted",
                serde_json::json!({"memory_id":"m","text":"Orchid gateway port is 7319."}),
            )],
        )
        .unwrap();
        c.execute_batch("DROP TABLE memory_facts").unwrap();
        for query in ["Orchid", ""] {
            let out =
                memory_candidates_flat(&c, query, None, 30.0, crate::fusion::Fusion::Linear, false)
                    .unwrap();
            assert_eq!(out.len(), 1);
            assert!(out[0].capsule.facts.is_empty());
        }
    }
}

#[cfg(test)]
mod deferred_fact_budget_tests {
    use super::*;
    #[test]
    fn initial_retrieval_budget_must_not_hide_an_eligible_conflicting_fact() {
        let c = Connection::open_in_memory().unwrap();
        crate::schema::initialize(&c).unwrap();
        for (id, value) in [("a", "7319"), ("b", "7320")] {
            let text = format!(
                "Orchid gateway port is {value}. Stable operation. Recorded settings. {}",
                "Operational notes remain available. ".repeat(350)
            );
            crate::projector::apply_events(
                &c,
                &[kimetsu_core::event::Event::new(
                    kimetsu_core::ids::RunId::new(),
                    "memory.accepted",
                    serde_json::json!({"memory_id":id,"scope":"project","kind":"fact","text":text}),
                )],
            )
            .unwrap();
        }
        let query = "What is the Orchid gateway port?";
        let policy = crate::serving::ServingPolicy {
            budget: 6000,
            cap: 1,
            explicit_fact_guard: true,
            ..Default::default()
        };
        let request = ContextRequest {
            stage: "localization".into(),
            query: query.into(),
            budget_tokens: 6000,
            ..Default::default()
        };
        let weights = BrokerWeights::default();
        let mut ordinary = request.clone();
        ordinary.max_capsules = 6;
        let ordinary = retrieve_context_with_embedder(
            &c,
            "/fake-repo",
            &weights,
            ordinary,
            &[],
            &crate::embeddings::NoopEmbedder,
        )
        .unwrap();
        assert_eq!(ordinary.capsules.len(), 1);
        assert!(ordinary.used_tokens <= 3000);
        let selected = retrieve_context_with_embedder(
            &c,
            "/fake-repo",
            &weights,
            policy.prepare(request, false),
            &[],
            &crate::embeddings::NoopEmbedder,
        )
        .unwrap();
        assert_eq!(
            selected.capsules.len(),
            2,
            "both eligible claims must reach arbitration before delivery budgeting"
        );
        let selected = policy.arbitrate(query, selected, None, 0.0);
        let delivered =
            policy.render_for_query(query, selected, true, crate::serving::EVAL_EXPOSURE_ID);
        assert_eq!(delivered.capsules.len(), 1);
        assert_eq!(delivered.payload["answerability"]["status"], "conflicting");
        assert!(delivered.payload["used_tokens"].as_u64().unwrap() <= 6000);
    }
}