lantern 0.2.4

//! Keyword search over ingested chunks, backed by SQLite FTS5.
//!
//! Each hit carries enough provenance for an agent to explain the result:
//! the source URI and path, the chunk ordinal, its byte range in the source,
//! the BM25 score, a highlighted snippet, and the full chunk text.

use anyhow::Result;
use rusqlite::ToSql;
use serde::Serialize;
use std::cmp::Ordering;
use std::fmt::Write as _;

use crate::embed::{
    DEFAULT_EMBED_MODEL, EmbedRole, EmbeddingBackend, OllamaClient, VEC_MIRROR_DIM, blob_to_f32s,
    cosine_similarity, embedding_stats, f32s_to_blob, prepare_embedding_text,
};
use crate::inspect::now_unix;
use crate::store::{Store, VEC_MIRROR_TABLE};

/// Which timestamp drove the freshness signal in a [`ConfidenceBreakdown`].
///
/// `last_accessed_at` is preferred when present; the source's `timestamp_unix`
/// is the fallback; `none` means neither existed and freshness was pinned to
/// the 0.25 floor. Surfaced so callers can tell an ancient-but-recently-touched
/// chunk from a brand-new one without inspecting the raw timestamps.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum FreshnessSource {
    LastAccessedAt,
    TimestampUnix,
    None,
}

impl FreshnessSource {
    /// Stable string form, identical to the JSON serialization. Used by the
    /// human-readable formatter so the token in `breakdown=...` matches the
    /// JSON contract one-for-one.
    pub fn as_str(self) -> &'static str {
        match self {
            FreshnessSource::LastAccessedAt => "last_accessed_at",
            FreshnessSource::TimestampUnix => "timestamp_unix",
            FreshnessSource::None => "none",
        }
    }
}

/// Component breakdown of a [`SearchHit`]'s confidence score.
///
/// Every field reflects an intermediate value computed inside
/// [`compute_confidence`]; the final score is `SearchHit::confidence`.
/// Surfaces in JSON output so callers can explain why a hit ranked where it did.
#[derive(Debug, Clone, Serialize)]
pub struct ConfidenceBreakdown {
    /// Freshness signal: exponential decay on age with a 30-day time constant,
    /// floored at 0.25.  Range: [0.25, 1.0].
    pub freshness: f64,
    /// Which timestamp the freshness signal was computed from. See
    /// [`FreshnessSource`] for the precedence rule.
    pub freshness_source: FreshnessSource,
    /// Access-saturation signal: `1 - exp(-access_count / 5)`.  Range: [0, 1).
    pub access_boost: f64,
    /// Combined pre-feedback score: `freshness + (1 - freshness) * access_boost`,
    /// clamped to [0, 1].
    pub base: f64,
    /// Feedback signal mapped through `tanh(feedback_score / 5)`.  Range: (-1, 1).
    /// Zero when no feedback has been recorded.
    pub feedback_factor: f64,
    /// Positive-only query-success signal: `1 - exp(-query_success_count / 5)`.
    /// Range: [0, 1). Zero when no query successes have been recorded, leaving
    /// confidence equal to the post-feedback `adjusted` value — that is the
    /// neutral default the v11 migration relies on.
    pub query_success_factor: f64,
}

#[derive(Debug, Clone, Serialize)]
pub struct SearchHit {
    pub chunk_id: String,
    pub source_id: String,
    pub uri: String,
    pub path: Option<String>,
    pub kind: String,
    pub ordinal: i64,
    pub byte_start: i64,
    pub byte_end: i64,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub role: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub session_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub turn_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_name: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub timestamp_unix: Option<i64>,
    pub access_count: i64,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub last_accessed_at: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub access_decay_at: Option<i64>,
    pub feedback_score: i64,
    pub query_success_count: i64,
    pub score: f64,
    pub confidence: f64,
    pub confidence_breakdown: ConfidenceBreakdown,
    pub snippet: String,
    pub text: String,
}

#[derive(Debug, Clone)]
pub struct SearchOptions {
    pub limit: usize,
    /// Exact match on the source `kind` column (e.g. `text/markdown`,
    /// `application/jsonl`). Useful for narrowing a query to a single
    /// format without writing SQL.
    pub kind: Option<String>,
    /// Substring that must appear in the source `path` or `uri`.
    pub path_contains: Option<String>,
    /// Drop hits whose blended [`compute_confidence`] score is below this
    /// threshold. Applied after ranking and just before access-metadata
    /// bumping, so filtered-out chunks do not count as retrievals. `None`
    /// is the pre-filter default and leaves every ranked hit intact.
    pub min_confidence: Option<f64>,
}

impl Default for SearchOptions {
    fn default() -> Self {
        Self {
            limit: 10,
            kind: None,
            path_contains: None,
            min_confidence: None,
        }
    }
}

/// Deterministic confidence score for a hit, in `[0, 1]`.
///
/// Five independent signals are blended so the number is meaningful whether a
/// chunk was just ingested, has been read many times, has been explicitly
/// rated by a user, has helped answer queries successfully, or any combination
/// of those:
///
/// * **Freshness** — exponential decay on age with a 30-day time constant,
///   floored at 0.25 so ancient chunks don't collapse to zero. `last_accessed_at`
///   is preferred when present (a chunk the agent has recently touched is
///   considered fresh, even if its underlying source is old); otherwise we fall
///   back to the source's `timestamp_unix`, and if neither exists we use the
///   0.25 floor.
/// * **Access saturation** — `1 - exp(-access_count / 5)`, a bounded lift that
///   rewards repeated use without letting one heavily-accessed chunk drown out
///   newer ones.
/// * **User feedback** — a signed net vote count mapped through `tanh(n/5)` into
///   `(-1, 1)`. Positive votes pull the blended score toward `1`, negative votes
///   pull it toward `0`, and the neutral default (`feedback_score == 0`)
///   produces `factor == 0`, leaving the result identical to the pre-feedback
///   formula. This makes the migration a no-op for any chunk nobody has rated.
/// * **Query success** — a positive-only count of "this chunk helped answer a
///   query successfully" events, mapped through `1 - exp(-q / 5)` into `[0, 1)`.
///   Distinct from feedback so an implicit, observed-success signal stays
///   separate from an explicit thumbs-up. The neutral default
///   (`query_success_count == 0`) produces `factor == 0`, leaving the
///   post-feedback score untouched — the v11 migration is a ranking no-op.
///
/// Freshness and access saturation are combined as
/// `base = freshness + (1 - freshness) * access_boost`, then feedback is applied
/// symmetrically: `adjusted = base + (1 - base) * factor` when `factor >= 0`,
/// and `adjusted = base * (1 + factor)` when `factor < 0`. Finally the
/// query-success boost lifts toward 1: `adjusted + (1 - adjusted) * q_factor`.
/// The whole expression stays in `[0, 1]`.
///
/// `now_unix` is taken as a parameter so tests can pin time without reaching
/// for a clock abstraction.
/// Inner computation that returns both the final confidence and its component breakdown.
fn compute_confidence_breakdown(
    now_unix: i64,
    last_accessed_at: Option<i64>,
    timestamp_unix: Option<i64>,
    access_count: i64,
    feedback_score: i64,
    query_success_count: i64,
) -> (f64, ConfidenceBreakdown) {
    const DECAY_SECS: f64 = 30.0 * 24.0 * 3600.0;
    const ACCESS_SCALE: f64 = 5.0;
    const FEEDBACK_SCALE: f64 = 5.0;
    const QUERY_SUCCESS_SCALE: f64 = 5.0;

    let (reference, freshness_source) = match (last_accessed_at, timestamp_unix) {
        (Some(t), _) => (Some(t), FreshnessSource::LastAccessedAt),
        (None, Some(t)) => (Some(t), FreshnessSource::TimestampUnix),
        (None, None) => (None, FreshnessSource::None),
    };
    let freshness = match reference {
        Some(ts) => {
            let age_secs = (now_unix - ts).max(0) as f64;
            (0.25 + 0.75 * (-age_secs / DECAY_SECS).exp()).clamp(0.0, 1.0)
        }
        None => 0.25,
    };
    let n = access_count.max(0) as f64;
    let access_boost = 1.0 - (-n / ACCESS_SCALE).exp();
    let base = (freshness + (1.0 - freshness) * access_boost).clamp(0.0, 1.0);

    let feedback_factor = (feedback_score as f64 / FEEDBACK_SCALE).tanh();
    let adjusted = if feedback_factor >= 0.0 {
        base + (1.0 - base) * feedback_factor
    } else {
        base * (1.0 + feedback_factor)
    };

    let q = query_success_count.max(0) as f64;
    let query_success_factor = 1.0 - (-q / QUERY_SUCCESS_SCALE).exp();
    let confidence = (adjusted + (1.0 - adjusted) * query_success_factor).clamp(0.0, 1.0);
    (
        confidence,
        ConfidenceBreakdown {
            freshness,
            freshness_source,
            access_boost,
            base,
            feedback_factor,
            query_success_factor,
        },
    )
}

// Test-only thin wrapper around `compute_confidence_breakdown` that returns
// just the scalar score. Production callers go through `hit_confidence`, which
// always wants both the score and the breakdown together; the breakdown-only
// helper would otherwise be dead code outside `#[cfg(test)]`.
#[cfg(test)]
fn compute_confidence(
    now_unix: i64,
    last_accessed_at: Option<i64>,
    timestamp_unix: Option<i64>,
    access_count: i64,
    feedback_score: i64,
    query_success_count: i64,
) -> f64 {
    compute_confidence_breakdown(
        now_unix,
        last_accessed_at,
        timestamp_unix,
        access_count,
        feedback_score,
        query_success_count,
    )
    .0
}

fn hit_confidence(
    last_accessed_at: Option<i64>,
    timestamp_unix: Option<i64>,
    access_count: i64,
    feedback_score: i64,
    query_success_count: i64,
) -> (f64, ConfidenceBreakdown) {
    compute_confidence_breakdown(
        now_unix(),
        last_accessed_at,
        timestamp_unix,
        access_count,
        feedback_score,
        query_success_count,
    )
}

/// Drop hits whose `confidence` is below `min`, preserving the ranked order of
/// everything that passes. Kept as a free function so each search path can
/// apply the floor right before [`bump_access_metadata`] — filtered chunks
/// must not count as retrievals.
fn apply_confidence_floor(hits: &mut Vec<SearchHit>, min: Option<f64>) {
    if let Some(floor) = min {
        hits.retain(|h| h.confidence >= floor);
    }
}

fn sort_hits_by_score_then_confidence(hits: &mut [SearchHit], score_descending: bool) {
    hits.sort_by(|a, b| {
        let primary = if score_descending {
            b.score.partial_cmp(&a.score)
        } else {
            a.score.partial_cmp(&b.score)
        }
        .unwrap_or(Ordering::Equal);
        if primary != Ordering::Equal {
            return primary;
        }

        let secondary = b
            .confidence
            .partial_cmp(&a.confidence)
            .unwrap_or(Ordering::Equal);
        if secondary != Ordering::Equal {
            return secondary;
        }

        a.chunk_id.cmp(&b.chunk_id)
    });
}

fn bump_access_metadata(store: &Store, hits: &[SearchHit]) -> Result<()> {
    if hits.is_empty() {
        return Ok(());
    }

    let now = now_unix();
    let conn = store.conn();
    for hit in hits {
        conn.execute(
            "UPDATE chunks
             SET access_count = access_count + 1,
                 last_accessed_at = ?1,
                 access_decay_at = ?1
             WHERE id = ?2",
            rusqlite::params![now, &hit.chunk_id],
        )?;
    }
    Ok(())
}

pub fn search(store: &Store, query: &str, opts: SearchOptions) -> Result<Vec<SearchHit>> {
    let mut hits = search_candidates(store, query, &opts)?;
    apply_confidence_floor(&mut hits, opts.min_confidence);
    bump_access_metadata(store, &hits)?;
    Ok(hits)
}

/// Keyword search without confidence-floor or access-metadata bumping.
///
/// Public callers should use [`search`]; this helper exists so the hybrid path
/// can fuse keyword and semantic candidates and then enforce the floor on the
/// blended output — bumping inside the inner pass would let chunks the floor
/// later drops still count as retrievals.
fn search_candidates(store: &Store, query: &str, opts: &SearchOptions) -> Result<Vec<SearchHit>> {
    let fts_query = build_fts_query(query);
    if fts_query.is_empty() {
        return Ok(Vec::new());
    }

    let mut sql = String::from(
        "SELECT
            c.id, c.source_id, c.ordinal, c.byte_start, c.byte_end, c.text,
            c.role, c.session_id, c.turn_id, c.tool_name, c.timestamp_unix,
            c.access_count, c.last_accessed_at, c.access_decay_at, c.feedback_score,
            c.query_success_count,
            s.uri, s.path, s.kind,
            bm25(chunks_fts) AS score,
            snippet(chunks_fts, 0, '<<', '>>', '…', 16) AS snippet
         FROM chunks_fts
         JOIN chunks  c ON c.rowid = chunks_fts.rowid
         JOIN sources s ON s.id = c.source_id
         WHERE chunks_fts MATCH ?",
    );
    let mut args: Vec<Box<dyn ToSql>> = vec![Box::new(fts_query)];

    if let Some(kind) = &opts.kind {
        sql.push_str(" AND s.kind = ?");
        args.push(Box::new(kind.clone()));
    }

    if let Some(path) = &opts.path_contains {
        sql.push_str(" AND (s.path LIKE ? OR s.uri LIKE ?)");
        let like = format!("%{path}%");
        args.push(Box::new(like.clone()));
        args.push(Box::new(like));
    }

    sql.push_str(" ORDER BY score LIMIT ?");
    args.push(Box::new(opts.limit as i64));

    let conn = store.conn();
    let mut stmt = conn.prepare(&sql)?;
    let rows = stmt.query_map(rusqlite::params_from_iter(args.iter()), |row| {
        let timestamp_unix: Option<i64> = row.get(10)?;
        let access_count: i64 = row.get(11)?;
        let last_accessed_at: Option<i64> = row.get(12)?;
        let access_decay_at: Option<i64> = row.get(13)?;
        let feedback_score: i64 = row.get(14)?;
        let query_success_count: i64 = row.get(15)?;
        let (confidence, confidence_breakdown) = hit_confidence(
            last_accessed_at,
            timestamp_unix,
            access_count,
            feedback_score,
            query_success_count,
        );
        Ok(SearchHit {
            chunk_id: row.get(0)?,
            source_id: row.get(1)?,
            ordinal: row.get(2)?,
            byte_start: row.get(3)?,
            byte_end: row.get(4)?,
            text: row.get(5)?,
            role: row.get(6)?,
            session_id: row.get(7)?,
            turn_id: row.get(8)?,
            tool_name: row.get(9)?,
            timestamp_unix,
            access_count,
            last_accessed_at,
            access_decay_at,
            feedback_score,
            query_success_count,
            uri: row.get(16)?,
            path: row.get(17)?,
            kind: row.get(18)?,
            score: row.get(19)?,
            confidence,
            confidence_breakdown,
            snippet: row.get(20)?,
        })
    })?;
    let mut hits = rows.collect::<Result<Vec<_>, _>>()?;
    sort_hits_by_score_then_confidence(&mut hits, false);
    Ok(hits)
}

/// Options for semantic / hybrid search. Reuses the keyword filters so the
/// same `--kind` and `--path` narrowing works across all three modes.
#[derive(Debug, Clone)]
pub struct SemanticOptions {
    pub limit: usize,
    pub kind: Option<String>,
    pub path_contains: Option<String>,
    pub model: String,
    pub ollama_url: String,
    pub instruction: Option<String>,
    /// See [`SearchOptions::min_confidence`]; applied to the outer hit list
    /// (post-blend for hybrid) so inner kw/sem passes still contribute all
    /// their candidates to the rank fusion before the floor is enforced.
    pub min_confidence: Option<f64>,
}

impl Default for SemanticOptions {
    fn default() -> Self {
        Self {
            limit: 10,
            kind: None,
            path_contains: None,
            model: crate::embed::DEFAULT_EMBED_MODEL.to_string(),
            ollama_url: crate::embed::DEFAULT_OLLAMA_URL.to_string(),
            instruction: None,
            min_confidence: None,
        }
    }
}

/// Brute-force semantic search: embed `query`, read every stored embedding
/// for `opts.model`, rank by cosine similarity. Fine for the initial
/// milestone — there are no external vector indexes and the data fits in
/// memory. A future version can swap in an ANN index behind the same API.
pub fn semantic_search(
    store: &Store,
    query: &str,
    opts: &SemanticOptions,
) -> Result<Vec<SearchHit>> {
    let client = OllamaClient::new(&opts.ollama_url, &opts.model)?;
    semantic_search_with(store, query, opts, &client)
}

/// Same as [`semantic_search`] but uses a caller-supplied embedding backend.
/// Lets tests rank against deterministic mock vectors without talking to
/// Ollama; production callers should keep using [`semantic_search`].
///
/// When `opts` is vec-eligible (default model, no filters) this routes to
/// [`vec_semantic_search_with`] so the vec0 ANN path is used by default. The
/// brute-force path still runs for non-default models or filtered queries,
/// where the mirror can't serve the request.
pub fn semantic_search_with(
    store: &Store,
    query: &str,
    opts: &SemanticOptions,
    backend: &dyn EmbeddingBackend,
) -> Result<Vec<SearchHit>> {
    let mut hits = semantic_search_candidates(store, query, opts, backend)?;
    apply_confidence_floor(&mut hits, opts.min_confidence);
    bump_access_metadata(store, &hits)?;
    Ok(hits)
}

/// Semantic search without confidence-floor or access-metadata bumping.
///
/// See [`search_candidates`] for why hybrid needs a non-bumping path.
fn semantic_search_candidates(
    store: &Store,
    query: &str,
    opts: &SemanticOptions,
    backend: &dyn EmbeddingBackend,
) -> Result<Vec<SearchHit>> {
    if query.trim().is_empty() {
        return Ok(Vec::new());
    }
    if vec_eligible(opts) {
        return vec_semantic_search_candidates(store, query, opts, backend);
    }
    preflight_embeddings(store, &opts.model)?;
    let query = prepare_embedding_text(
        &opts.model,
        EmbedRole::Query,
        query,
        opts.instruction.as_deref(),
    );
    let query_vec = backend.embed(&query)?;
    let candidates = load_embedded_chunks(store, &opts.model, &opts.kind, &opts.path_contains)?;
    rank_by_cosine(&query_vec, candidates, opts.limit)
}

/// True when `opts` can be served by the vec0 mirror. The mirror only covers
/// the default embedding model, and the current helper does not push kind or
/// path filters into its KNN query — so any caller that needs either must
/// stay on the brute-force path. Kept private: callers route through
/// [`semantic_search_with`], which checks this internally.
pub(crate) fn vec_eligible(opts: &SemanticOptions) -> bool {
    opts.model == DEFAULT_EMBED_MODEL && opts.kind.is_none() && opts.path_contains.is_none()
}

/// Opt-in vec0-backed semantic search for the default embedding model.
///
/// Queries the `chunks_vec_nomic_768` mirror that `embed_missing_with` keeps
/// in sync with `embeddings` for the default model. Because the mirror stores
/// the same vectors and the mirror is declared with `distance_metric=cosine`,
/// ordering by `distance` ASC matches the brute-force path's cosine-similarity
/// DESC — callers can swap this in and get identical rankings.
///
/// This helper is intentionally narrow for now: it errors for any non-default
/// model (the mirror doesn't exist for other models), and it ignores the
/// `kind` / `path_contains` filters on [`SemanticOptions`]. Callers that need
/// filtering or a non-default model should stay on [`semantic_search_with`].
pub fn vec_semantic_search_with(
    store: &Store,
    query: &str,
    opts: &SemanticOptions,
    backend: &dyn EmbeddingBackend,
) -> Result<Vec<SearchHit>> {
    let mut hits = vec_semantic_search_candidates(store, query, opts, backend)?;
    apply_confidence_floor(&mut hits, opts.min_confidence);
    bump_access_metadata(store, &hits)?;
    Ok(hits)
}

/// Vec-backed semantic search without confidence-floor or access-metadata
/// bumping. See [`search_candidates`] for why hybrid needs a non-bumping path.
fn vec_semantic_search_candidates(
    store: &Store,
    query: &str,
    opts: &SemanticOptions,
    backend: &dyn EmbeddingBackend,
) -> Result<Vec<SearchHit>> {
    if opts.model != DEFAULT_EMBED_MODEL {
        anyhow::bail!(
            "vec-backed semantic search only supports the default model '{}' (got '{}'); \
             use semantic_search_with for other models",
            DEFAULT_EMBED_MODEL,
            opts.model,
        );
    }
    if query.trim().is_empty() {
        return Ok(Vec::new());
    }
    preflight_embeddings(store, &opts.model)?;
    let query = prepare_embedding_text(
        &opts.model,
        EmbedRole::Query,
        query,
        opts.instruction.as_deref(),
    );
    let query_vec = backend.embed(&query)?;
    if query_vec.len() != VEC_MIRROR_DIM {
        anyhow::bail!(
            "query embedding has {} dims but vec mirror is {} dims",
            query_vec.len(),
            VEC_MIRROR_DIM,
        );
    }
    let blob = f32s_to_blob(&query_vec);

    // The KNN call has to live in its own subquery so the LIMIT binds directly
    // to the vec0 table — vec0 requires an explicit LIMIT (or `k = ?`) on the
    // MATCH query itself, and the planner won't push one down through a JOIN.
    let sql = format!(
        "SELECT c.id, c.source_id, c.ordinal, c.byte_start, c.byte_end, c.text,
                c.role, c.session_id, c.turn_id, c.tool_name, c.timestamp_unix,
                c.access_count, c.last_accessed_at, c.access_decay_at, c.feedback_score,
                c.query_success_count,
                s.uri, s.path, s.kind, v.distance
         FROM (
             SELECT rowid, distance
             FROM {VEC_MIRROR_TABLE}
             WHERE embedding MATCH ?1
             ORDER BY distance
             LIMIT ?2
         ) v
         JOIN chunks  c ON c.rowid = v.rowid
         JOIN sources s ON s.id = c.source_id
         ORDER BY v.distance"
    );
    let conn = store.conn();
    let mut stmt = conn.prepare(&sql)?;
    let rows = stmt.query_map(rusqlite::params![blob, opts.limit as i64], |row| {
        let text: String = row.get(5)?;
        let timestamp_unix: Option<i64> = row.get(10)?;
        let access_count: i64 = row.get(11)?;
        let last_accessed_at: Option<i64> = row.get(12)?;
        let access_decay_at: Option<i64> = row.get(13)?;
        let feedback_score: i64 = row.get(14)?;
        let query_success_count: i64 = row.get(15)?;
        let distance: f64 = row.get(19)?;
        let (confidence, confidence_breakdown) = hit_confidence(
            last_accessed_at,
            timestamp_unix,
            access_count,
            feedback_score,
            query_success_count,
        );
        Ok(SearchHit {
            chunk_id: row.get(0)?,
            source_id: row.get(1)?,
            ordinal: row.get(2)?,
            byte_start: row.get(3)?,
            byte_end: row.get(4)?,
            snippet: truncate_snippet(&text, 160),
            text,
            role: row.get(6)?,
            session_id: row.get(7)?,
            turn_id: row.get(8)?,
            tool_name: row.get(9)?,
            timestamp_unix,
            access_count,
            last_accessed_at,
            access_decay_at,
            feedback_score,
            query_success_count,
            uri: row.get(16)?,
            path: row.get(17)?,
            kind: row.get(18)?,
            // vec0 cosine `distance` is 1 - cosine_similarity; invert so the
            // caller sees the same similarity scale as semantic_search_with.
            score: 1.0 - distance,
            confidence,
            confidence_breakdown,
        })
    })?;
    let hits = rows.collect::<Result<Vec<_>, _>>()?;
    Ok(hits)
}

/// Hybrid search: Reciprocal Rank Fusion of keyword and semantic hits.
///
/// Each side is ranked independently, then every chunk's final score is the
/// sum of `1 / (k + rank)` (with `k = 60`) over the lists it appears in.
/// A chunk that shows up in both lists gets both contributions — no weight
/// knob, no score-scale assumptions.
pub fn hybrid_search(store: &Store, query: &str, opts: &SemanticOptions) -> Result<Vec<SearchHit>> {
    let client = OllamaClient::new(&opts.ollama_url, &opts.model)?;
    hybrid_search_with(store, query, opts, &client)
}

/// Same as [`hybrid_search`] but with a caller-supplied embedding backend.
pub fn hybrid_search_with(
    store: &Store,
    query: &str,
    opts: &SemanticOptions,
    backend: &dyn EmbeddingBackend,
) -> Result<Vec<SearchHit>> {
    if query.trim().is_empty() {
        return Ok(Vec::new());
    }
    preflight_embeddings(store, &opts.model)?;

    let kw_opts = SearchOptions {
        // Pull extra keyword candidates so the blend has enough to rank.
        limit: opts.limit.max(10) * 4,
        kind: opts.kind.clone(),
        path_contains: opts.path_contains.clone(),
        // Intentionally unfiltered: the confidence floor is enforced on
        // the blended output so rank-fusion sees every candidate.
        min_confidence: None,
    };
    let kw_hits = search_candidates(store, query, &kw_opts)?;
    let sem_opts = SemanticOptions {
        limit: opts.limit.max(10) * 4,
        min_confidence: None,
        ..opts.clone()
    };
    let sem_hits = semantic_search_candidates(store, query, &sem_opts, backend)?;

    let mut hits = blend_hits(kw_hits, sem_hits, opts.limit);
    apply_confidence_floor(&mut hits, opts.min_confidence);
    bump_access_metadata(store, &hits)?;
    Ok(hits)
}

struct CandidateRow {
    chunk_id: String,
    source_id: String,
    ordinal: i64,
    byte_start: i64,
    byte_end: i64,
    text: String,
    role: Option<String>,
    session_id: Option<String>,
    turn_id: Option<String>,
    tool_name: Option<String>,
    timestamp_unix: Option<i64>,
    access_count: i64,
    last_accessed_at: Option<i64>,
    access_decay_at: Option<i64>,
    feedback_score: i64,
    query_success_count: i64,
    uri: String,
    path: Option<String>,
    kind: String,
    embedding: Vec<f32>,
}

fn load_embedded_chunks(
    store: &Store,
    model: &str,
    kind: &Option<String>,
    path_contains: &Option<String>,
) -> Result<Vec<CandidateRow>> {
    let mut sql = String::from(
        "SELECT c.id, c.source_id, c.ordinal, c.byte_start, c.byte_end, c.text,
                c.role, c.session_id, c.turn_id, c.tool_name, c.timestamp_unix,
                c.access_count, c.last_accessed_at, c.access_decay_at, c.feedback_score,
                c.query_success_count,
                s.uri, s.path, s.kind, e.embedding
         FROM embeddings e
         JOIN chunks  c ON c.id = e.chunk_id
         JOIN sources s ON s.id = c.source_id
         WHERE e.model = ?",
    );
    let mut args: Vec<Box<dyn ToSql>> = vec![Box::new(model.to_string())];
    if let Some(k) = kind {
        sql.push_str(" AND s.kind = ?");
        args.push(Box::new(k.clone()));
    }
    if let Some(p) = path_contains {
        sql.push_str(" AND (s.path LIKE ? OR s.uri LIKE ?)");
        let like = format!("%{p}%");
        args.push(Box::new(like.clone()));
        args.push(Box::new(like));
    }
    let conn = store.conn();
    let mut stmt = conn.prepare(&sql)?;
    let rows = stmt.query_map(rusqlite::params_from_iter(args.iter()), |row| {
        let blob: Vec<u8> = row.get(19)?;
        Ok((
            row.get::<_, String>(0)?,
            row.get::<_, String>(1)?,
            row.get::<_, i64>(2)?,
            row.get::<_, i64>(3)?,
            row.get::<_, i64>(4)?,
            row.get::<_, String>(5)?,
            row.get::<_, Option<String>>(6)?,
            row.get::<_, Option<String>>(7)?,
            row.get::<_, Option<String>>(8)?,
            row.get::<_, Option<String>>(9)?,
            row.get::<_, Option<i64>>(10)?,
            row.get::<_, i64>(11)?,
            row.get::<_, Option<i64>>(12)?,
            row.get::<_, Option<i64>>(13)?,
            row.get::<_, i64>(14)?,
            row.get::<_, i64>(15)?,
            row.get::<_, String>(16)?,
            row.get::<_, Option<String>>(17)?,
            row.get::<_, String>(18)?,
            blob,
        ))
    })?;
    let mut out = Vec::new();
    for r in rows {
        let (
            chunk_id,
            source_id,
            ordinal,
            byte_start,
            byte_end,
            text,
            role,
            session_id,
            turn_id,
            tool_name,
            timestamp_unix,
            access_count,
            last_accessed_at,
            access_decay_at,
            feedback_score,
            query_success_count,
            uri,
            path,
            kind,
            blob,
        ) = r?;
        let embedding = blob_to_f32s(&blob)?;
        out.push(CandidateRow {
            chunk_id,
            source_id,
            ordinal,
            byte_start,
            byte_end,
            text,
            role,
            session_id,
            turn_id,
            tool_name,
            timestamp_unix,
            access_count,
            last_accessed_at,
            access_decay_at,
            feedback_score,
            query_success_count,
            uri,
            path,
            kind,
            embedding,
        });
    }
    Ok(out)
}

fn preflight_embeddings(store: &Store, model: &str) -> Result<()> {
    let stats = embedding_stats(store)?;
    if stats.iter().any(|stat| stat.model == model) {
        return Ok(());
    }

    let available = if stats.is_empty() {
        String::from("none exist")
    } else {
        stats
            .into_iter()
            .map(|stat| format!("{} (dim {}, count {})", stat.model, stat.dim, stat.count))
            .collect::<Vec<_>>()
            .join(", ")
    };

    anyhow::bail!("no stored embeddings for model '{model}'; available models: {available}");
}

fn rank_by_cosine(
    query_vec: &[f32],
    candidates: Vec<CandidateRow>,
    limit: usize,
) -> Result<Vec<SearchHit>> {
    let mut hits: Vec<SearchHit> = candidates
        .into_iter()
        .map(|c| {
            let score = cosine_similarity(query_vec, &c.embedding);
            let (confidence, confidence_breakdown) = hit_confidence(
                c.last_accessed_at,
                c.timestamp_unix,
                c.access_count,
                c.feedback_score,
                c.query_success_count,
            );
            SearchHit {
                chunk_id: c.chunk_id,
                source_id: c.source_id,
                uri: c.uri,
                path: c.path,
                kind: c.kind,
                ordinal: c.ordinal,
                byte_start: c.byte_start,
                byte_end: c.byte_end,
                role: c.role,
                session_id: c.session_id,
                turn_id: c.turn_id,
                tool_name: c.tool_name,
                timestamp_unix: c.timestamp_unix,
                access_count: c.access_count,
                last_accessed_at: c.last_accessed_at,
                access_decay_at: c.access_decay_at,
                feedback_score: c.feedback_score,
                query_success_count: c.query_success_count,
                score: score as f64,
                confidence,
                confidence_breakdown,
                snippet: truncate_snippet(&c.text, 160),
                text: c.text,
            }
        })
        .collect();
    sort_hits_by_score_then_confidence(&mut hits, true);
    hits.truncate(limit);
    Ok(hits)
}

fn truncate_snippet(text: &str, max_chars: usize) -> String {
    let mut out: String = text.chars().take(max_chars).collect();
    if text.chars().count() > max_chars {
        out.push('…');
    }
    out
}

/// Blend keyword and semantic hits via Reciprocal Rank Fusion.
///
/// Each input list is already ranked (index 0 = best). For every chunk, we
/// sum `1 / (k + rank)` across the lists it appears in, with `k = 60` — the
/// standard RRF constant. A chunk in both lists earns two contributions and
/// naturally floats above one-sided hits; a chunk in only one list still
/// scores, so a strong semantic match isn't dropped just because the query
/// tokens don't appear verbatim. Raw score magnitudes never enter the math,
/// which is the point: BM25 and cosine live on incompatible scales.
fn blend_hits(kw: Vec<SearchHit>, sem: Vec<SearchHit>, limit: usize) -> Vec<SearchHit> {
    use std::collections::HashMap;

    const K: f64 = 60.0;

    let mut combined: HashMap<String, (f64, SearchHit)> = HashMap::new();
    for (rank, hit) in kw.into_iter().enumerate() {
        let contribution = 1.0 / (K + (rank + 1) as f64);
        combined.insert(hit.chunk_id.clone(), (contribution, hit));
    }
    for (rank, hit) in sem.into_iter().enumerate() {
        let contribution = 1.0 / (K + (rank + 1) as f64);
        combined
            .entry(hit.chunk_id.clone())
            .and_modify(|slot| slot.0 += contribution)
            .or_insert((contribution, hit));
    }

    let mut hits: Vec<SearchHit> = combined
        .into_values()
        .map(|(score, mut hit)| {
            hit.score = score;
            hit
        })
        .collect();
    sort_hits_by_score_then_confidence(&mut hits, true);
    hits.truncate(limit);
    hits
}

/// Translate a user query into a safe FTS5 MATCH expression.
///
/// Each whitespace-delimited token is stripped of punctuation (FTS5 special
/// characters would otherwise either error or change the query semantics),
/// then emitted as a prefix term so `lantern` matches `Lanterns`. Tokens are
/// space-joined, which FTS5 interprets as an implicit AND.
pub(crate) fn build_fts_query(q: &str) -> String {
    q.split_whitespace()
        .filter_map(|t| {
            let cleaned: String = t
                .chars()
                .filter(|c| c.is_alphanumeric() || *c == '_')
                .collect();
            if cleaned.is_empty() {
                None
            } else {
                Some(format!("{cleaned}*"))
            }
        })
        .collect::<Vec<_>>()
        .join(" ")
}

/// Compact human-readable summary: one line of header plus one preview line
/// per hit. Intended to be the default when an agent or human runs `search`
/// interactively without asking for a specific format.
pub fn format_summary(query: &str, hits: &[SearchHit]) -> String {
    let mut out = String::new();
    let _ = writeln!(out, "query: {query:?}  hits: {}", hits.len());
    for (i, hit) in hits.iter().enumerate() {
        let source = hit.path.as_deref().unwrap_or(hit.uri.as_str());
        let _ = writeln!(
            out,
            "  {rank}. [{score:.3} conf={confidence:.2}] {source}  #{ord}",
            rank = i + 1,
            score = hit.score,
            confidence = hit.confidence,
            source = source,
            ord = hit.ordinal,
        );
        let preview = snippet_preview(&hit.snippet, 96);
        if !preview.is_empty() {
            let _ = writeln!(out, "     {preview}");
        }
        if let Some(meta) = hit_metadata_line(hit) {
            let _ = writeln!(out, "     {meta}");
        }
    }
    out
}

/// Thin print wrapper around [`format_summary`].
pub fn print_summary(query: &str, hits: &[SearchHit]) {
    print!("{}", format_summary(query, hits));
}

fn snippet_preview(snippet: &str, max_chars: usize) -> String {
    let first = snippet.lines().next().unwrap_or("").trim();
    let char_count = first.chars().count();
    let mut out: String = first.chars().take(max_chars).collect();
    if char_count > max_chars {
        out.push('…');
    }
    out
}

fn hit_metadata_line(hit: &SearchHit) -> Option<String> {
    let mut parts = Vec::new();
    if let Some(role) = &hit.role {
        parts.push(format!("role={role}"));
    }
    if let Some(session_id) = &hit.session_id {
        parts.push(format!("session={session_id}"));
    }
    if let Some(turn_id) = &hit.turn_id {
        parts.push(format!("turn={turn_id}"));
    }
    if let Some(tool_name) = &hit.tool_name {
        parts.push(format!("tool={tool_name}"));
    }
    if let Some(ts) = hit.timestamp_unix {
        parts.push(format!("ts={ts}"));
    }
    parts.push(format!("access_count={}", hit.access_count));
    if let Some(last) = hit.last_accessed_at {
        parts.push(format!("last_accessed={last}"));
    }
    if let Some(decay_at) = hit.access_decay_at {
        parts.push(format!("access_decay_at={decay_at}"));
    }
    parts.push(format!("feedback_score={}", hit.feedback_score));
    parts.push(format!("query_success_count={}", hit.query_success_count));
    let cb = &hit.confidence_breakdown;
    parts.push(format!(
        "breakdown=freshness:{:.2},freshness_source:{},access_boost:{:.2},base:{:.2},feedback_factor:{:.2},query_success_factor:{:.2}",
        cb.freshness,
        cb.freshness_source.as_str(),
        cb.access_boost,
        cb.base,
        cb.feedback_factor,
        cb.query_success_factor,
    ));
    if parts.is_empty() {
        None
    } else {
        Some(parts.join(" "))
    }
}

pub fn format_text(query: &str, hits: &[SearchHit]) -> String {
    let mut out = String::new();
    if hits.is_empty() {
        let _ = writeln!(out, "no results for {query:?}");
        return out;
    }
    for (i, hit) in hits.iter().enumerate() {
        let _ = writeln!(
            out,
            "[{rank}] score={score:.4} conf={confidence:.2} chunk={ordinal} bytes={start}-{end} uri={uri}",
            rank = i + 1,
            score = hit.score,
            confidence = hit.confidence,
            ordinal = hit.ordinal,
            start = hit.byte_start,
            end = hit.byte_end,
            uri = hit.uri,
        );
        let _ = writeln!(out, "    {}", hit.snippet);
        if let Some(meta) = hit_metadata_line(hit) {
            let _ = writeln!(out, "    {meta}");
        }
    }
    let _ = writeln!(out, "summary query={query:?} results={}", hits.len());
    out
}

/// Thin print wrapper around [`format_text`].
pub fn print_text(query: &str, hits: &[SearchHit]) {
    print!("{}", format_text(query, hits));
}

pub fn format_json(query: &str, model: Option<&str>, hits: &[SearchHit]) -> Result<String> {
    #[derive(Serialize)]
    struct Envelope<'a> {
        query: &'a str,
        #[serde(skip_serializing_if = "Option::is_none")]
        model: Option<&'a str>,
        results: &'a [SearchHit],
    }
    let env = Envelope {
        query,
        model,
        results: hits,
    };
    Ok(serde_json::to_string_pretty(&env)?)
}

/// Thin print wrapper around [`format_json`].
pub fn print_json(query: &str, model: Option<&str>, hits: &[SearchHit]) -> Result<()> {
    print!("{}", format_json(query, model, hits)?);
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::{
        ConfidenceBreakdown, FreshnessSource, SearchHit, build_fts_query, compute_confidence,
        compute_confidence_breakdown, format_json, format_summary, format_text, snippet_preview,
    };

    fn sample_hit() -> SearchHit {
        SearchHit {
            chunk_id: "chunk-1".into(),
            source_id: "source-1".into(),
            uri: "file:///tmp/needle.txt".into(),
            path: Some("/tmp/needle.txt".into()),
            kind: "text/plain".into(),
            ordinal: 0,
            byte_start: 0,
            byte_end: 12,
            role: None,
            session_id: None,
            turn_id: None,
            tool_name: None,
            timestamp_unix: None,
            access_count: 0,
            last_accessed_at: None,
            access_decay_at: None,
            feedback_score: 0,
            query_success_count: 0,
            score: 0.99,
            confidence: 0.5,
            confidence_breakdown: ConfidenceBreakdown {
                freshness: 0.5,
                freshness_source: FreshnessSource::None,
                access_boost: 0.0,
                base: 0.5,
                feedback_factor: 0.0,
                query_success_factor: 0.0,
            },
            snippet: "needle snippet".into(),
            text: "needle text".into(),
        }
    }

    fn sample_hit_with_metadata() -> SearchHit {
        let base = sample_hit();
        SearchHit {
            role: Some("assistant".into()),
            session_id: Some("sess-7".into()),
            turn_id: Some("turn-9".into()),
            tool_name: Some("search".into()),
            timestamp_unix: Some(1_700_000_003),
            access_count: 7,
            last_accessed_at: Some(1_700_000_500),
            access_decay_at: Some(1_700_000_800),
            feedback_score: 2,
            query_success_count: 5,
            // Override the breakdown so query_success_factor reflects the
            // fixture's `query_success_count == 5`: 1 - exp(-5/5) ≈ 0.632.
            confidence_breakdown: ConfidenceBreakdown {
                query_success_factor: 1.0 - (-1.0_f64).exp(),
                ..base.confidence_breakdown.clone()
            },
            ..base
        }
    }

    #[test]
    fn empty_query_produces_empty_match() {
        assert_eq!(build_fts_query(""), "");
        assert_eq!(build_fts_query("   "), "");
    }

    #[test]
    fn single_token_is_prefix_matched() {
        assert_eq!(build_fts_query("hello"), "hello*");
    }

    #[test]
    fn multiple_tokens_are_and_joined() {
        assert_eq!(build_fts_query("foo bar"), "foo* bar*");
    }

    #[test]
    fn preview_takes_first_line_and_truncates_with_ellipsis() {
        assert_eq!(snippet_preview("", 10), "");
        assert_eq!(snippet_preview("short line", 40), "short line");
        assert_eq!(snippet_preview("line one\nline two", 40), "line one");
        assert_eq!(snippet_preview("abcdefghij", 5), "abcde…");
        // Multibyte: each CJK char is one character, not one byte.
        let preview = snippet_preview("世界世界世界世界", 4);
        assert_eq!(preview, "世界世界…");
    }

    #[test]
    fn punctuation_and_special_chars_are_stripped() {
        assert_eq!(build_fts_query("hello, world!"), "hello* world*");
        assert_eq!(build_fts_query(r#"he"llo"#), "hello*");
        assert_eq!(build_fts_query("!!!"), "");
    }

    #[test]
    fn summary_formatter_includes_query_hit_and_metadata() {
        let output = format_summary("needle", &[sample_hit_with_metadata()]);
        assert!(output.contains("query: \"needle\"  hits: 1"), "{output}");
        assert!(
            output.contains("[0.990 conf=0.50] /tmp/needle.txt  #0"),
            "{output}"
        );
        assert!(output.contains("needle snippet"), "{output}");
        assert!(output.contains("role=assistant"), "{output}");
        assert!(output.contains("session=sess-7"), "{output}");
        assert!(output.contains("turn=turn-9"), "{output}");
        assert!(output.contains("tool=search"), "{output}");
        assert!(output.contains("ts=1700000003"), "{output}");
        assert!(output.contains("access_count=7"), "{output}");
        assert!(output.contains("last_accessed=1700000500"), "{output}");
        assert!(output.contains("access_decay_at=1700000800"), "{output}");
        assert!(output.contains("feedback_score=2"), "{output}");
        assert!(output.contains("query_success_count=5"), "{output}");
    }

    #[test]
    fn text_formatter_includes_detailed_hit_block() {
        let output = format_text("needle", &[sample_hit_with_metadata()]);
        assert!(
            output.contains(
                "[1] score=0.9900 conf=0.50 chunk=0 bytes=0-12 uri=file:///tmp/needle.txt"
            ),
            "{output}"
        );
        assert!(output.contains("needle snippet"), "{output}");
        assert!(output.contains("role=assistant"), "{output}");
        assert!(output.contains("access_count=7"), "{output}");
        assert!(output.contains("last_accessed=1700000500"), "{output}");
        assert!(output.contains("access_decay_at=1700000800"), "{output}");
        assert!(output.contains("feedback_score=2"), "{output}");
        assert!(output.contains("query_success_count=5"), "{output}");
        assert!(
            output.contains("summary query=\"needle\" results=1"),
            "{output}"
        );
    }

    #[test]
    fn formatters_surface_confidence_breakdown() {
        // The populated fixture's breakdown is freshness=0.50, freshness_source=none,
        // access_boost=0.00, base=0.50, feedback_factor=0.00,
        // query_success_factor=0.63; pinning the exact serialized form keeps
        // the human-readable output stable across both formatters.
        let expected = "breakdown=freshness:0.50,freshness_source:none,access_boost:0.00,base:0.50,feedback_factor:0.00,query_success_factor:0.63";
        let summary = format_summary("needle", &[sample_hit_with_metadata()]);
        assert!(
            summary.contains(expected),
            "summary missing breakdown: {summary}"
        );
        let text = format_text("needle", &[sample_hit_with_metadata()]);
        assert!(text.contains(expected), "text missing breakdown: {text}");
        // Sanity check: the breakdown ships even on a bare hit with no other
        // optional metadata, and the neutral query-success default stays at 0.00.
        let bare_expected = "breakdown=freshness:0.50,freshness_source:none,access_boost:0.00,base:0.50,feedback_factor:0.00,query_success_factor:0.00";
        let bare = format_summary("needle", &[sample_hit()]);
        assert!(
            bare.contains(bare_expected),
            "bare summary missing breakdown: {bare}"
        );
    }

    #[test]
    fn formatters_omit_last_accessed_when_never_accessed() {
        // A never-retrieved chunk should not leak a stale `last_accessed=`
        // token into the metadata line; the absence is meaningful for
        // confidence explanations.
        let summary = format_summary("needle", &[sample_hit()]);
        assert!(
            !summary.contains("last_accessed="),
            "summary should omit last_accessed when None: {summary}"
        );
        let text = format_text("needle", &[sample_hit()]);
        assert!(
            !text.contains("last_accessed="),
            "text should omit last_accessed when None: {text}"
        );
        assert!(
            !text.contains("access_decay_at="),
            "text should omit access_decay_at when None: {text}"
        );
    }

    #[test]
    fn json_formatter_includes_model_when_present() {
        let json = format_json(
            "needle",
            Some("nomic-embed-text"),
            &[sample_hit_with_metadata()],
        )
        .unwrap();
        let value: serde_json::Value = serde_json::from_str(&json).unwrap();
        assert_eq!(value["query"], "needle");
        assert_eq!(value["model"], "nomic-embed-text");
        assert_eq!(value["results"].as_array().unwrap().len(), 1);
        assert_eq!(value["results"][0]["access_decay_at"], 1_700_000_800);
        assert_eq!(value["results"][0]["confidence_breakdown"]["base"], 0.5);
        assert_eq!(
            value["results"][0]["confidence_breakdown"]["feedback_factor"],
            0.0
        );
    }

    #[test]
    fn json_formatter_omits_model_when_absent() {
        let json = format_json("needle", None, &[sample_hit()]).unwrap();
        let value: serde_json::Value = serde_json::from_str(&json).unwrap();
        assert_eq!(value["query"], "needle");
        assert!(value.get("model").is_none());
    }

    #[test]
    fn json_formatter_pins_full_confidence_breakdown_contract() {
        // The JSON envelope is the contract callers rely on to explain why a
        // hit's confidence landed where it did. The other JSON test only
        // spot-checks `base` and `feedback_factor`; this one pins every field
        // and the exact snake_case key names so an accidental serde rename
        // (e.g. `#[serde(rename_all = "camelCase")]`) or a dropped field is
        // caught immediately. Use a hit with all confidence components
        // non-trivial so the values themselves carry information.
        let mut hit = sample_hit();
        hit.confidence = 0.875;
        hit.confidence_breakdown = ConfidenceBreakdown {
            freshness: 0.75,
            freshness_source: FreshnessSource::TimestampUnix,
            access_boost: 0.5,
            base: 0.875,
            feedback_factor: 0.0,
            query_success_factor: 0.0,
        };
        let json = format_json("needle", None, &[hit]).unwrap();
        let value: serde_json::Value = serde_json::from_str(&json).unwrap();
        let cb = value["results"][0]["confidence_breakdown"]
            .as_object()
            .expect("confidence_breakdown must serialize as an object");
        let keys: std::collections::BTreeSet<&str> = cb.keys().map(String::as_str).collect();
        assert_eq!(
            keys,
            [
                "access_boost",
                "base",
                "feedback_factor",
                "freshness",
                "freshness_source",
                "query_success_factor",
            ]
            .into_iter()
            .collect(),
            "confidence_breakdown keys drifted from the documented contract: {keys:?}"
        );
        assert_eq!(cb["freshness"], 0.75);
        assert_eq!(cb["freshness_source"], "timestamp_unix");
        assert_eq!(cb["access_boost"], 0.5);
        assert_eq!(cb["base"], 0.875);
        assert_eq!(cb["feedback_factor"], 0.0);
        assert_eq!(cb["query_success_factor"], 0.0);
    }

    // One fixed epoch second used as "now" for all determinism tests below.
    const NOW: i64 = 1_800_000_000;
    const DAY: i64 = 24 * 3600;

    #[test]
    fn confidence_floor_when_no_timestamps_or_access() {
        let c = compute_confidence(NOW, None, None, 0, 0, 0);
        assert!((c - 0.25).abs() < 1e-9, "got {c}");
    }

    #[test]
    fn confidence_fresh_chunk_near_one() {
        let c = compute_confidence(NOW, None, Some(NOW), 0, 0, 0);
        assert!((c - 1.0).abs() < 1e-9, "got {c}");
    }

    #[test]
    fn confidence_decays_with_age_toward_floor() {
        let recent = compute_confidence(NOW, None, Some(NOW - DAY), 0, 0, 0);
        let week_old = compute_confidence(NOW, None, Some(NOW - 7 * DAY), 0, 0, 0);
        let year_old = compute_confidence(NOW, None, Some(NOW - 365 * DAY), 0, 0, 0);
        assert!(recent > week_old, "recent {recent} vs week {week_old}");
        assert!(week_old > year_old, "week {week_old} vs year {year_old}");
        assert!(
            year_old >= 0.25 && year_old < 0.26,
            "year-old should hit the floor, got {year_old}"
        );
    }

    #[test]
    fn confidence_future_timestamps_clamp_to_fresh() {
        // Clock skew or bad data shouldn't drop confidence below the fresh peak.
        let c = compute_confidence(NOW, None, Some(NOW + 10 * DAY), 0, 0, 0);
        assert!((c - 1.0).abs() < 1e-9, "got {c}");
    }

    #[test]
    fn confidence_last_accessed_preferred_over_timestamp() {
        // An old source that was just accessed should look fresh.
        let c = compute_confidence(NOW, Some(NOW), Some(NOW - 365 * DAY), 0, 0, 0);
        assert!((c - 1.0).abs() < 1e-9, "got {c}");
    }

    #[test]
    fn confidence_last_accessed_wins_even_when_stale() {
        // The asymmetric side of the precedence rule: freshness comes from
        // `last_accessed_at.or(timestamp_unix)`, so once last_accessed_at is
        // present it shadows timestamp_unix unconditionally — even when the
        // source is newer than the last touch. A stale access on a fresh
        // source must still decay like a stale access, not inherit the
        // source's freshness. Pinning this down guards against an accidental
        // "max" rewrite of the reference-picking logic.
        let fresh_source_stale_access =
            compute_confidence(NOW, Some(NOW - 365 * DAY), Some(NOW), 0, 0, 0);
        let stale_access_only = compute_confidence(NOW, Some(NOW - 365 * DAY), None, 0, 0, 0);
        assert!(
            (fresh_source_stale_access - stale_access_only).abs() < 1e-9,
            "last_accessed_at must shadow timestamp_unix: \
             fresh-source {fresh_source_stale_access} vs stale-only {stale_access_only}"
        );
        // And the result really is the decayed floor region, not the fresh peak.
        assert!(
            fresh_source_stale_access < 0.26,
            "stale last_accessed should decay to the floor, got {fresh_source_stale_access}"
        );
    }

    #[test]
    fn confidence_access_lifts_above_freshness() {
        let no_access = compute_confidence(NOW, None, Some(NOW - 365 * DAY), 0, 0, 0);
        let some_access = compute_confidence(NOW, None, Some(NOW - 365 * DAY), 3, 0, 0);
        let many_access = compute_confidence(NOW, None, Some(NOW - 365 * DAY), 50, 0, 0);
        assert!(some_access > no_access, "{some_access} vs {no_access}");
        assert!(many_access > some_access, "{many_access} vs {some_access}");
        assert!(many_access <= 1.0, "must stay in [0,1]: {many_access}");
    }

    #[test]
    fn confidence_access_count_zero_preserves_legacy_behavior() {
        // When access_count is 0, confidence should match the old
        // timestamp-only curve: 0.25 + 0.75 * exp(-age / 30 days).
        let age = 10 * DAY;
        let c = compute_confidence(NOW, None, Some(NOW - age), 0, 0, 0);
        let expected = 0.25 + 0.75 * (-(age as f64) / (30.0 * DAY as f64)).exp();
        assert!((c - expected).abs() < 1e-9, "got {c}, expected {expected}");
    }

    #[test]
    fn confidence_negative_access_count_treated_as_zero() {
        let c = compute_confidence(NOW, None, Some(NOW - 365 * DAY), -7, 0, 0);
        let baseline = compute_confidence(NOW, None, Some(NOW - 365 * DAY), 0, 0, 0);
        assert!((c - baseline).abs() < 1e-9, "got {c}");
    }

    #[test]
    fn confidence_feedback_neutral_matches_legacy() {
        // The whole point of the neutral default: existing stores that never
        // record feedback see the exact same confidence as before the signal
        // was introduced.
        for &(last, ts, access) in &[
            (None, None, 0),
            (None, Some(NOW - 10 * DAY), 0),
            (Some(NOW - DAY), Some(NOW - 365 * DAY), 3),
            (None, Some(NOW - 30 * DAY), 12),
        ] {
            let with_feedback = compute_confidence(NOW, last, ts, access, 0, 0);
            let legacy_base = {
                const DECAY_SECS: f64 = 30.0 * 24.0 * 3600.0;
                const ACCESS_SCALE: f64 = 5.0;
                let reference = last.or(ts);
                let freshness = match reference {
                    Some(t) => {
                        let age_secs = (NOW - t).max(0) as f64;
                        (0.25 + 0.75 * (-age_secs / DECAY_SECS).exp()).clamp(0.0, 1.0)
                    }
                    None => 0.25,
                };
                let n = access.max(0) as f64;
                let access_boost = 1.0 - (-n / ACCESS_SCALE).exp();
                (freshness + (1.0 - freshness) * access_boost).clamp(0.0, 1.0)
            };
            assert!(
                (with_feedback - legacy_base).abs() < 1e-12,
                "feedback=0 must be a no-op (last={last:?}, ts={ts:?}, access={access}): \
                 got {with_feedback}, expected {legacy_base}"
            );
        }
    }

    #[test]
    fn confidence_breakdown_feedback_zero_equals_base() {
        // Regression: with no feedback recorded, the feedback_factor must be
        // exactly 0 and the returned confidence must equal `base`. Anything
        // else means the neutral default is silently shifting scores.
        let (confidence, cb) =
            compute_confidence_breakdown(NOW, Some(NOW - DAY), Some(NOW - 30 * DAY), 4, 0, 0);
        assert_eq!(cb.feedback_factor, 0.0, "feedback_factor must be 0: {cb:?}");
        assert!(
            (confidence - cb.base).abs() < 1e-12,
            "confidence {confidence} must equal base {} when feedback_score=0",
            cb.base,
        );
    }

    #[test]
    fn confidence_positive_feedback_lifts_toward_one() {
        let ts = Some(NOW - 365 * DAY);
        let base = compute_confidence(NOW, None, ts, 0, 0, 0);
        let one_up = compute_confidence(NOW, None, ts, 0, 1, 0);
        let many_up = compute_confidence(NOW, None, ts, 0, 100, 0);
        assert!(one_up > base, "one up {one_up} vs base {base}");
        assert!(many_up > one_up, "many up {many_up} vs one {one_up}");
        assert!(many_up <= 1.0, "must stay <= 1: {many_up}");
        assert!((many_up - 1.0).abs() < 1e-6, "saturation: {many_up}");
    }

    #[test]
    fn confidence_query_success_lifts_toward_one() {
        let ts = Some(NOW - 365 * DAY);
        let base = compute_confidence(NOW, None, ts, 0, 0, 0);
        let one_success = compute_confidence(NOW, None, ts, 0, 0, 1);
        let many_success = compute_confidence(NOW, None, ts, 0, 0, 100);
        assert!(
            one_success > base,
            "one success {one_success} vs base {base}"
        );
        assert!(
            many_success > one_success,
            "many successes {many_success} vs one {one_success}"
        );
        assert!(many_success <= 1.0, "must stay <= 1: {many_success}");
        assert!(
            (many_success - 1.0).abs() < 1e-6,
            "saturation: {many_success}"
        );
    }

    #[test]
    fn confidence_negative_feedback_pulls_toward_zero() {
        let ts = Some(NOW);
        let base = compute_confidence(NOW, None, ts, 0, 0, 0);
        let one_down = compute_confidence(NOW, None, ts, 0, -1, 0);
        let many_down = compute_confidence(NOW, None, ts, 0, -100, 0);
        assert!(one_down < base, "one down {one_down} vs base {base}");
        assert!(
            many_down < one_down,
            "many down {many_down} vs one {one_down}"
        );
        assert!(many_down >= 0.0, "must stay >= 0: {many_down}");
        assert!(many_down < 1e-6, "saturation: {many_down}");
    }

    #[test]
    fn confidence_breakdown_components_reconstruct_confidence() {
        // Pins the contract that JSON/text consumers rely on: the five
        // breakdown fields, blended via the documented formula, must equal
        // the returned `confidence`. A future refactor that changes the
        // blend without updating the breakdown (or vice versa) would let
        // explanations drift away from the actual score — this test fails
        // fast in that case.
        let cases = [
            (NOW, None, None, 0i64, 0i64, 0i64),
            (NOW, None, Some(NOW), 0, 0, 0),
            (NOW, None, Some(NOW - 30 * DAY), 3, 0, 0),
            (NOW, Some(NOW - DAY), Some(NOW - 365 * DAY), 12, 4, 0),
            (NOW, None, Some(NOW - 7 * DAY), 0, -3, 7),
            (NOW, Some(NOW - 365 * DAY), None, 50, -100, 0),
        ];
        for &(now, last, ts, access, feedback, query_success) in &cases {
            let (confidence, cb) =
                compute_confidence_breakdown(now, last, ts, access, feedback, query_success);

            // Every component must lie in its documented range.
            assert!(
                (0.25..=1.0).contains(&cb.freshness),
                "freshness out of [0.25, 1.0]: {cb:?}"
            );
            assert!(
                (0.0..1.0).contains(&cb.access_boost),
                "access_boost out of [0, 1): {cb:?}"
            );
            assert!((0.0..=1.0).contains(&cb.base), "base out of [0, 1]: {cb:?}");
            assert!(
                (0.0..1.0).contains(&cb.query_success_factor),
                "query_success_factor out of [0, 1): {cb:?}"
            );
            // Mathematically `tanh` lives in (-1, 1), but for extreme inputs
            // f64 saturates to exactly ±1.0; the practical runtime range is
            // therefore the closed interval.
            assert!(
                (-1.0..=1.0).contains(&cb.feedback_factor),
                "feedback_factor out of [-1, 1]: {cb:?}"
            );

            // `base` must equal the documented blend of freshness and access_boost.
            let expected_base =
                (cb.freshness + (1.0 - cb.freshness) * cb.access_boost).clamp(0.0, 1.0);
            assert!(
                (cb.base - expected_base).abs() < 1e-12,
                "base drift: got {got}, expected {expected} (cb={cb:?})",
                got = cb.base,
                expected = expected_base,
            );

            // Reconstruct the final confidence from the breakdown using the
            // documented sign-asymmetric formula, then apply the positive-only
            // query-success lift, and assert it matches.
            let post_feedback = if cb.feedback_factor >= 0.0 {
                cb.base + (1.0 - cb.base) * cb.feedback_factor
            } else {
                cb.base * (1.0 + cb.feedback_factor)
            }
            .clamp(0.0, 1.0);
            let reconstructed =
                (post_feedback + (1.0 - post_feedback) * cb.query_success_factor).clamp(0.0, 1.0);
            assert!(
                (confidence - reconstructed).abs() < 1e-12,
                "reconstruction drift for case (last={last:?}, ts={ts:?}, \
                 access={access}, feedback={feedback}, query_success={query_success}): \
                 confidence={confidence}, reconstructed={reconstructed}, cb={cb:?}"
            );

            // And the public single-return helper must agree exactly.
            let scalar = compute_confidence(now, last, ts, access, feedback, query_success);
            assert!(
                (confidence - scalar).abs() < 1e-12,
                "scalar/breakdown disagreement: scalar={scalar}, \
                 breakdown_confidence={confidence}"
            );
        }
    }

    #[test]
    fn confidence_feedback_cancels_out() {
        // +3 and -3 land on different curves (the tanh branches are symmetric
        // about the base, not equal), but the sign symmetry still has to hold:
        // equal-magnitude votes must move the score equally far from the base.
        let ts = Some(NOW - 30 * DAY);
        let base = compute_confidence(NOW, None, ts, 0, 0, 0);
        let up = compute_confidence(NOW, None, ts, 0, 3, 0);
        let down = compute_confidence(NOW, None, ts, 0, -3, 0);
        let factor = (3.0_f64 / 5.0).tanh();
        assert!((up - (base + (1.0 - base) * factor)).abs() < 1e-9);
        assert!((down - (base * (1.0 - factor))).abs() < 1e-9);
    }
}