edda_ask/

lib.rs

use edda_core::Event;
use edda_ledger::DecisionView;
use edda_ledger::Ledger;
use serde::{Deserialize, Serialize};

pub mod staleness;

const SEMANTIC_CANDIDATE_LIMIT: usize = 500;

#[derive(Debug)]
struct ScoredDecision {
    row: DecisionView,
    score: f64,
}

// ── Input type detection ─────────────────────────────────────────────

/// Detected input type for a query string.
#[derive(Debug, PartialEq)]
pub enum InputType {
    /// "db.engine" — contains '.' matching word.word
    ExactKey(String),
    /// "db" — matches a known domain
    Domain(String),
    /// "postgres" — default keyword search
    Keyword(String),
    /// Empty query — show all active decisions
    Overview,
}

/// Classify a query string into one of the four input types.
pub fn detect_input_type(query: &str, known_domains: &[String]) -> InputType {
    let q = query.trim();
    if q.is_empty() {
        return InputType::Overview;
    }
    // Check for exact key pattern: word.word (e.g. "db.engine")
    if q.contains('.') && q.split('.').count() >= 2 && q.split('.').all(|p| !p.is_empty()) {
        return InputType::ExactKey(q.to_string());
    }
    // Check if query matches a known domain (case-insensitive)
    let q_lower = q.to_lowercase();
    if known_domains.iter().any(|d| d.to_lowercase() == q_lower) {
        return InputType::Domain(q.to_string());
    }
    InputType::Keyword(q.to_string())
}

// ── Result types ─────────────────────────────────────────────────────

#[derive(Debug, Default, Serialize)]
pub struct AskResult {
    pub query: String,
    pub input_type: String,
    pub decisions: Vec<DecisionHit>,
    pub timeline: Vec<DecisionHit>,
    pub related_commits: Vec<CommitHit>,
    pub related_notes: Vec<NoteHit>,
    pub conversations: Vec<ConversationHit>,
    /// Tasks whose title/receipt/reason match the query — the rail's answer to
    /// "what shipped about X, verified how" (GH-404).
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub tasks: Vec<TaskHit>,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub dependents: Vec<DependentHit>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub override_risk: Option<OverrideRisk>,
    /// Count of total events in the workspace ledger, if known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace_event_count: Option<u64>,
    /// Count of total decisions in the workspace ledger, if known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace_decision_count: Option<u64>,
}

/// A task matched by `ask`. The receipt is the point — it is where a finished
/// task records what it did and how it was verified.
#[derive(Debug, Clone, Serialize)]
pub struct TaskHit {
    pub task_id: u64,
    pub title: String,
    pub status: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub receipt: Option<String>,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub evidence_paths: Vec<String>,
}

/// Decision governance status (GH-806).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DecisionGovernance {
    /// "ratified" | "unratified"
    pub status: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub ratified_by: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub ratified_at: Option<String>,
}

impl Default for DecisionGovernance {
    fn default() -> Self {
        Self {
            status: "unratified".to_string(),
            ratified_by: None,
            ratified_at: None,
        }
    }
}

#[derive(Debug, Clone, Serialize)]
pub struct DecisionHit {
    pub event_id: String,
    pub key: String,
    pub value: String,
    pub reason: String,
    pub domain: String,
    pub branch: String,
    pub ts: String,
    pub is_active: bool,
    /// Governance status (GH-806).
    pub governance: DecisionGovernance,
    /// Tags parsed from JSON array in the decision row.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    /// Village scope identifier.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub village_id: Option<String>,
    /// Decision-code freshness (q334 EDDA-STALENESS1). None ⇒ not checked
    /// (feature off, or repo_root missing at query time). Serialized only when
    /// present so existing JSON consumers stay unaffected.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub staleness: Option<crate::staleness::DecisionStaleness>,
}

#[derive(Debug, Clone, Serialize)]
pub struct CommitHit {
    pub event_id: String,
    pub title: String,
    pub purpose: String,
    pub ts: String,
    pub branch: String,
    pub match_type: String,
}

#[derive(Debug, Clone, Serialize)]
pub struct NoteHit {
    pub event_id: String,
    pub text: String,
    pub ts: String,
    pub branch: String,
}

#[derive(Debug, Clone, Serialize)]
pub struct ConversationHit {
    pub doc_id: String,
    pub session_id: String,
    pub ts: String,
    pub snippet: String,
    pub rank: f64,
}

// ── Impact types ────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize)]
pub struct DependentHit {
    pub key: String,
    pub value: String,
    pub dep_type: String,
    /// Hop distance from the queried key (1 = direct dependent).
    pub depth: usize,
}

#[derive(Debug, Clone, Serialize)]
pub struct OverrideRisk {
    pub level: String,
    pub dependent_count: usize,
    pub suggestion: Option<String>,
}

// ── Options ──────────────────────────────────────────────────────────

pub struct AskOptions {
    pub limit: usize,
    pub include_superseded: bool,
    pub branch: Option<String>,
    pub impact: bool,
    /// ISO 8601 lower bound (inclusive) for temporal filtering.
    pub after: Option<String>,
    /// ISO 8601 upper bound (inclusive) for temporal filtering.
    pub before: Option<String>,
    /// Filter decisions whose tags contain any of these values (OR semantics).
    pub tags: Vec<String>,
    /// Filter decisions belonging to a specific village.
    pub village_id: Option<String>,
}

impl Default for AskOptions {
    fn default() -> Self {
        Self {
            limit: 20,
            include_superseded: false,
            branch: None,
            impact: false,
            after: None,
            before: None,
            tags: vec![],
            village_id: None,
        }
    }
}

/// Transcript search callback type.
pub type TranscriptSearchFn = dyn Fn(&str, usize) -> Vec<ConversationHit>;

// ── Core ask function ────────────────────────────────────────────────

#[allow(clippy::too_many_lines)] // 264 lines at #779; split tracked in none
pub fn ask(
    ledger: &Ledger,
    query: &str,
    opts: &AskOptions,
    transcript_search: Option<&TranscriptSearchFn>,
) -> anyhow::Result<AskResult> {
    let domains = ledger.list_domains()?;
    let input_type = detect_input_type(query, &domains);

    // Branch filter helper: keep only decisions matching the requested branch
    let branch_filter = |hits: Vec<DecisionHit>| -> Vec<DecisionHit> {
        match &opts.branch {
            Some(b) => hits.into_iter().filter(|d| d.branch == *b).collect(),
            None => hits,
        }
    };

    // Tags filter helper: keep only decisions that have at least one matching tag (OR semantics)
    let tags_filter = |hits: Vec<DecisionHit>| -> Vec<DecisionHit> {
        if opts.tags.is_empty() {
            return hits;
        }
        hits.into_iter()
            .filter(|d| d.tags.iter().any(|t| opts.tags.contains(t)))
            .collect()
    };

    // Village filter helper: keep only decisions belonging to the specified village
    let village_filter = |hits: Vec<DecisionHit>| -> Vec<DecisionHit> {
        match &opts.village_id {
            Some(v) => hits
                .into_iter()
                .filter(|d| d.village_id.as_deref() == Some(v.as_str()))
                .collect(),
            None => hits,
        }
    };

    let after_ref = opts.after.as_deref();
    let before_ref = opts.before.as_deref();

    let (decisions, timeline) = match &input_type {
        InputType::ExactKey(key) => {
            let all = ledger
                .decision_timeline(key, after_ref, before_ref)?
                .into_iter()
                .map(|r| to_decision_hit(&r))
                .collect::<Vec<_>>();
            let all = branch_filter(all);
            let active: Vec<DecisionHit> = if opts.include_superseded {
                all.clone()
            } else {
                all.iter().filter(|d| d.is_active).cloned().collect()
            };
            (active, all)
        }
        InputType::Domain(domain) => {
            let active = branch_filter(
                ledger
                    .active_decisions_limited(
                        Some(domain),
                        None,
                        after_ref,
                        before_ref,
                        opts.limit,
                    )?
                    .into_iter()
                    .map(|r| to_decision_hit(&r))
                    .collect(),
            );
            let tl = branch_filter(
                ledger
                    .domain_timeline(domain, after_ref, before_ref)?
                    .into_iter()
                    .map(|r| to_decision_hit(&r))
                    .collect(),
            );
            (active, tl)
        }
        InputType::Keyword(kw) => {
            let mut semantic_hits = semantic_decision_search(
                ledger,
                kw,
                opts.branch.as_deref(),
                after_ref,
                before_ref,
                opts.limit,
            )?;

            let lexical_fallback = ledger
                .active_decisions_limited(None, Some(kw), after_ref, before_ref, opts.limit)?
                .into_iter()
                .map(|r| to_decision_hit(&r));

            for hit in lexical_fallback {
                if !semantic_hits.iter().any(|h| h.event_id == hit.event_id) {
                    semantic_hits.push(hit);
                }
            }

            let mut hits = branch_filter(semantic_hits);
            if hits.len() > opts.limit {
                hits.truncate(opts.limit);
            }

            if opts.include_superseded {
                // Scan only note events for superseded decisions matching keyword
                let events = ledger.iter_events_by_type("note")?;
                let kw_lower = kw.to_lowercase();
                for event in &events {
                    if let Some(ref b) = opts.branch {
                        if event.branch != *b {
                            continue;
                        }
                    }
                    if event.event_type == "note"
                        && edda_core::decision::is_decision(&event.payload)
                    {
                        if let Some(dp) = edda_core::decision::extract_decision(&event.payload) {
                            let reason_str = dp.reason.as_deref().unwrap_or("").to_string();
                            if (dp.key.to_lowercase().contains(&kw_lower)
                                || dp.value.to_lowercase().contains(&kw_lower)
                                || reason_str.to_lowercase().contains(&kw_lower))
                                && !hits.iter().any(|h| h.event_id == event.event_id)
                            {
                                let domain = edda_core::decision::extract_domain(&dp.key);
                                hits.push(DecisionHit {
                                    event_id: event.event_id.clone(),
                                    key: dp.key,
                                    value: dp.value,
                                    reason: reason_str,
                                    domain,
                                    branch: event.branch.clone(),
                                    ts: event.ts.clone(),
                                    is_active: false,
                                    governance: DecisionGovernance::default(),
                                    tags: dp.tags.unwrap_or_default(),
                                    village_id: dp.village_id,
                                    staleness: None,
                                });
                            }
                        }
                    }
                }
            }
            (hits, vec![])
        }
        InputType::Overview => {
            let active = branch_filter(
                ledger
                    .active_decisions_limited(None, None, after_ref, before_ref, opts.limit)?
                    .into_iter()
                    .map(|r| to_decision_hit(&r))
                    .collect(),
            );
            (active, vec![])
        }
    };

    // Apply tags filter (OR semantics) across all code paths
    let decisions = tags_filter(decisions);
    let timeline = tags_filter(timeline);

    // Apply village filter across all code paths
    let mut decisions = village_filter(decisions);
    let mut timeline = village_filter(timeline);

    // Annotate governance status (GH-806)
    let ratifications = ledger.ratified_decisions_map()?;
    annotate_governance(&mut decisions, &ratifications);
    annotate_governance(&mut timeline, &ratifications);

    // Collect decision event_ids for evidence chain matching
    let decision_event_ids: Vec<&str> = decisions
        .iter()
        .map(|d| d.event_id.as_str())
        .chain(timeline.iter().map(|d| d.event_id.as_str()))
        .collect();

    let q = query.trim();
    // SQL push-down: find related commits and notes via targeted queries
    let commit_events =
        ledger.find_related_commits(opts.branch.as_deref(), q, &decision_event_ids, opts.limit)?;
    let related_commits = to_commit_hits(&commit_events, &decision_event_ids, q, opts.limit);
    let note_events = ledger.find_related_notes(opts.branch.as_deref(), q, opts.limit)?;
    let mut related_notes = find_checkpoint_notes(ledger, q, opts)?;
    related_notes.extend(to_note_hits(&note_events, opts.limit));
    related_notes.truncate(opts.limit);

    let conversations = match transcript_search {
        Some(search_fn) if !q.is_empty() => search_fn(q, opts.limit),
        _ => vec![],
    };

    // Tasks whose text matches the query. What a reader is after is "what
    // shipped about X, verified how", so a task matches when the query appears
    // in its title, receipt, or failure reason — the receipt being the point.
    // Newest first, since a rail answer is usually a recent one (GH-404).
    //
    // Deliberately not branch-filtered, unlike decisions above: the task rail is
    // a workspace-global queue, not a per-branch record, so `--branch` narrowing
    // the decisions but not the tasks is the intended asymmetry.
    let tasks: Vec<TaskHit> = if q.is_empty() {
        vec![]
    } else {
        let needle = q.to_lowercase();
        let mut views = ledger.task_views()?;
        views.sort_by_key(|t| std::cmp::Reverse(t.task_id)); // newest first
        views
            .into_iter()
            .filter(|t| {
                let hay = format!(
                    "{} {} {}",
                    t.title,
                    t.receipt.as_deref().unwrap_or(""),
                    t.failure_reason.as_deref().unwrap_or("")
                )
                .to_lowercase();
                hay.contains(&needle)
            })
            .take(opts.limit)
            .map(|t| TaskHit {
                task_id: t.task_id,
                title: t.title,
                status: t.status.to_string(),
                receipt: t.receipt,
                evidence_paths: t.evidence_paths,
            })
            .collect()
    };

    let input_type_str = match &input_type {
        InputType::ExactKey(_) => "exact_key",
        InputType::Domain(_) => "domain",
        InputType::Keyword(_) => "keyword",
        InputType::Overview => "overview",
    };

    // Impact analysis: ExactKey or Domain queries with --impact
    let (dependents, override_risk) = if opts.impact {
        match &input_type {
            InputType::ExactKey(key) => compute_impact(ledger, key)?,
            InputType::Domain(domain) => compute_domain_impact(ledger, domain)?,
            _ => (vec![], None),
        }
    } else {
        (vec![], None)
    };

    let workspace_event_count = ledger.count_events().ok();
    let workspace_decision_count = ledger.count_decisions().ok();

    Ok(AskResult {
        query: q.to_string(),
        input_type: input_type_str.to_string(),
        decisions,
        timeline,
        related_commits,
        related_notes,
        conversations,
        tasks,
        dependents,
        override_risk,
        workspace_event_count,
        workspace_decision_count,
    })
}

// ── Impact analysis helpers ──────────────────────────────────────────

fn compute_impact(
    ledger: &Ledger,
    key: &str,
) -> anyhow::Result<(Vec<DependentHit>, Option<OverrideRisk>)> {
    let transitive_deps = ledger.transitive_dependents_of(key, 3)?;
    let dependents: Vec<DependentHit> = transitive_deps
        .iter()
        .map(|(dep, decision, depth)| DependentHit {
            key: decision.key.clone(),
            value: decision.value.clone(),
            dep_type: dep.dep_type.clone(),
            depth: *depth,
        })
        .collect();
    let risk = compute_override_risk(&dependents);
    Ok((dependents, Some(risk)))
}

fn compute_override_risk(dependents: &[DependentHit]) -> OverrideRisk {
    let count = dependents.len();

    // Weighted scoring:
    //   explicit direct deps  x3
    //   auto_domain direct    x1
    //   transitive deps       x2  (depth > 1)
    //   cross-domain spread   x2
    let explicit_direct: usize = dependents
        .iter()
        .filter(|d| d.dep_type == "explicit" && d.depth == 1)
        .count();
    let auto_domain_direct: usize = dependents
        .iter()
        .filter(|d| d.dep_type == "auto_domain" && d.depth == 1)
        .count();
    let transitive: usize = dependents.iter().filter(|d| d.depth > 1).count();

    // Count distinct domains among dependents
    let mut domains: std::collections::HashSet<&str> = std::collections::HashSet::new();
    for d in dependents {
        if let Some(dom) = d.key.split('.').next() {
            domains.insert(dom);
        }
    }
    let cross_domain_bonus = if domains.len() > 1 { domains.len() } else { 0 };

    let score = explicit_direct * 3 + auto_domain_direct + transitive * 2 + cross_domain_bonus * 2;

    let level = if score <= 2 {
        "LOW"
    } else if score <= 6 {
        "MEDIUM"
    } else {
        "HIGH"
    };

    // Suggestion: reverse BFS order = override leaves first
    let suggestion = if count > 0 {
        let mut sorted: Vec<&DependentHit> = dependents.iter().collect();
        sorted.sort_by_key(|dependent| std::cmp::Reverse(dependent.depth));
        let keys: Vec<&str> = sorted.iter().map(|d| d.key.as_str()).collect();
        Some(format!("建議覆蓋順序: {}", keys.join(" → ")))
    } else {
        None
    };

    OverrideRisk {
        level: level.to_string(),
        dependent_count: count,
        suggestion,
    }
}

/// Aggregate impact across all active keys in a domain.
fn compute_domain_impact(
    ledger: &Ledger,
    domain: &str,
) -> anyhow::Result<(Vec<DependentHit>, Option<OverrideRisk>)> {
    let keys_in_domain = ledger.active_decisions(Some(domain), None, None, None)?;
    if keys_in_domain.is_empty() {
        return Ok((vec![], None));
    }

    let mut all_dependents: Vec<DependentHit> = Vec::new();
    let mut seen_keys: std::collections::HashSet<String> = std::collections::HashSet::new();

    for decision in &keys_in_domain {
        let (deps, _) = compute_impact(ledger, &decision.key)?;
        for d in deps {
            if seen_keys.insert(d.key.clone()) {
                all_dependents.push(d);
            }
        }
    }

    let risk = if all_dependents.is_empty() {
        Some(OverrideRisk {
            level: "LOW".to_string(),
            dependent_count: 0,
            suggestion: None,
        })
    } else {
        Some(compute_override_risk(&all_dependents))
    };

    Ok((all_dependents, risk))
}

// ── Related event helpers ────────────────────────────────────────────

/// Convert SQL-prefiltered commit events into `CommitHit` with match_type classification.
/// Events are already filtered by SQL (branch, keyword/evidence); this determines the
/// specific match_type ("evidence" or "title") for each.
fn to_commit_hits(
    events: &[Event],
    decision_event_ids: &[&str],
    query: &str,
    limit: usize,
) -> Vec<CommitHit> {
    let mut hits: Vec<CommitHit> = Vec::new();
    let q_lower = query.to_lowercase();

    for event in events {
        let title = event
            .payload
            .get("title")
            .and_then(|v| v.as_str())
            .unwrap_or("");
        let purpose = event
            .payload
            .get("purpose")
            .and_then(|v| v.as_str())
            .unwrap_or("");

        // Determine match type
        let mut match_type = None;
        for ref_id in &event.refs.events {
            if decision_event_ids.contains(&ref_id.as_str()) {
                match_type = Some("evidence");
                break;
            }
        }
        if match_type.is_none() {
            for prov in &event.refs.provenance {
                if decision_event_ids.contains(&prov.target.as_str()) {
                    match_type = Some("evidence");
                    break;
                }
            }
        }
        if match_type.is_none()
            && !query.is_empty()
            && (title.to_lowercase().contains(&q_lower)
                || purpose.to_lowercase().contains(&q_lower))
        {
            match_type = Some("title");
        }

        if let Some(mt) = match_type {
            if !hits.iter().any(|h| h.event_id == event.event_id) {
                hits.push(CommitHit {
                    event_id: event.event_id.clone(),
                    title: title.to_string(),
                    purpose: purpose.to_string(),
                    ts: event.ts.clone(),
                    branch: event.branch.clone(),
                    match_type: mt.to_string(),
                });
                if hits.len() >= limit {
                    break;
                }
            }
        }
    }

    hits
}

/// Convert SQL-prefiltered note events into `NoteHit`.
/// Events are already filtered by SQL (branch, keyword, excluding decisions/digests).
fn to_note_hits(events: &[Event], limit: usize) -> Vec<NoteHit> {
    events
        .iter()
        .take(limit)
        .map(|event| {
            let text = event
                .payload
                .get("text")
                .and_then(|v| v.as_str())
                .unwrap_or("");
            NoteHit {
                event_id: event.event_id.clone(),
                text: text.to_string(),
                ts: event.ts.clone(),
                branch: event.branch.clone(),
            }
        })
        .collect()
}

fn semantic_decision_search(
    ledger: &Ledger,
    query: &str,
    branch: Option<&str>,
    after: Option<&str>,
    before: Option<&str>,
    limit: usize,
) -> anyhow::Result<Vec<DecisionHit>> {
    if limit == 0 {
        return Ok(vec![]);
    }

    let candidates =
        ledger.active_decisions_limited(None, None, after, before, SEMANTIC_CANDIDATE_LIMIT)?;

    let scored = rank_decisions_by_similarity(query, candidates, branch);
    Ok(scored
        .into_iter()
        .take(limit)
        .map(|s| to_decision_hit(&s.row))
        .collect())
}

fn rank_decisions_by_similarity(
    query: &str,
    candidates: Vec<DecisionView>,
    branch: Option<&str>,
) -> Vec<ScoredDecision> {
    let query_tokens = tokenize_for_similarity(query);
    if query_tokens.is_empty() {
        return vec![];
    }

    let mut tokenized_docs: Vec<(DecisionView, Vec<String>)> = Vec::new();
    for row in candidates {
        if branch.is_some_and(|b| row.branch != b) {
            continue;
        }
        let text = format!("{} {} {} {}", row.domain, row.key, row.value, row.reason);
        let tokens = tokenize_for_similarity(&text);
        if !tokens.is_empty() {
            tokenized_docs.push((row, tokens));
        }
    }

    if tokenized_docs.is_empty() {
        return vec![];
    }

    let mut doc_freq: std::collections::HashMap<String, usize> = std::collections::HashMap::new();
    for (_, tokens) in &tokenized_docs {
        let unique: std::collections::HashSet<&str> = tokens.iter().map(|t| t.as_str()).collect();
        for token in unique {
            *doc_freq.entry(token.to_string()).or_insert(0) += 1;
        }
    }

    let n_docs = tokenized_docs.len() as f64;
    let query_tf = term_freq(&query_tokens);
    let query_norm = vector_norm(&query_tf, &doc_freq, n_docs);

    let mut scored: Vec<ScoredDecision> = Vec::new();
    for (row, tokens) in tokenized_docs {
        let tf = term_freq(&tokens);
        let doc_norm = vector_norm(&tf, &doc_freq, n_docs);
        if doc_norm <= f64::EPSILON || query_norm <= f64::EPSILON {
            continue;
        }

        let mut dot = 0.0;
        for (token, q_tf) in &query_tf {
            if let Some(d_tf) = tf.get(token) {
                let idf = inv_doc_freq(doc_freq.get(token).copied().unwrap_or(0), n_docs);
                dot += (*q_tf as f64 * idf) * (*d_tf as f64 * idf);
            }
        }

        let score = dot / (query_norm * doc_norm);
        if score > 0.0 {
            scored.push(ScoredDecision { row, score });
        }
    }

    scored.sort_by(|a, b| {
        b.score
            .partial_cmp(&a.score)
            .unwrap_or(std::cmp::Ordering::Equal)
    });
    scored
}

fn tokenize_for_similarity(text: &str) -> Vec<String> {
    text.split(|c: char| !c.is_alphanumeric())
        .filter_map(|t| {
            let normalized = t.trim().to_lowercase();
            if normalized.len() >= 2 {
                Some(normalized)
            } else {
                None
            }
        })
        .collect()
}

fn term_freq(tokens: &[String]) -> std::collections::HashMap<String, usize> {
    let mut tf = std::collections::HashMap::new();
    for token in tokens {
        *tf.entry(token.clone()).or_insert(0) += 1;
    }
    tf
}

fn inv_doc_freq(df: usize, n_docs: f64) -> f64 {
    ((n_docs + 1.0) / (df as f64 + 1.0)).ln() + 1.0
}

fn vector_norm(
    tf: &std::collections::HashMap<String, usize>,
    doc_freq: &std::collections::HashMap<String, usize>,
    n_docs: f64,
) -> f64 {
    let mut sum_sq = 0.0;
    for (token, count) in tf {
        let idf = inv_doc_freq(doc_freq.get(token).copied().unwrap_or(0), n_docs);
        let weight = *count as f64 * idf;
        sum_sq += weight * weight;
    }
    sum_sq.sqrt()
}

// ── Human-readable formatting ────────────────────────────────────────

pub fn format_human(result: &AskResult) -> String {
    let mut out = String::new();

    if !result.decisions.is_empty() {
        out.push_str("── Decisions ──────────────────────────\n");
        for d in &result.decisions {
            let status = if d.is_active { "active" } else { "superseded" };
            let gov = match d.governance.status.as_str() {
                "ratified" => {
                    if let Some(by) = &d.governance.ratified_by {
                        format!("ratified (by {by})")
                    } else {
                        "ratified".to_string()
                    }
                }
                _ => "unratified".to_string(),
            };
            out.push_str(&format!(
                "  {} = {} — {}\n  branch: {} | {} | {} | {}\n",
                d.key, d.value, d.reason, d.branch, d.ts, status, gov
            ));
            if let Some(st) = &d.staleness {
                if st.is_stale {
                    let bad: Vec<String> = st
                        .paths
                        .iter()
                        .filter(|p| {
                            p.status != staleness::PathStatus::Fresh
                                && p.status != staleness::PathStatus::Unknown
                        })
                        .map(|p| format!("{} ({:?})", p.path, p.status))
                        .collect();
                    if !bad.is_empty() {
                        out.push_str(&format!("  ⚠ stale-code hint: {}\n", bad.join(", ")));
                    }
                }
            }
            out.push('\n');
        }
    }

    if !result.timeline.is_empty() {
        out.push_str("── Timeline ───────────────────────────\n");
        for d in &result.timeline {
            let status = if d.is_active { "active" } else { "superseded" };
            let gov = &d.governance.status;
            out.push_str(&format!(
                "  {}  {} = {}  ({}, {})\n",
                d.ts, d.key, d.value, status, gov
            ));
        }
        out.push('\n');
    }

    if !result.related_commits.is_empty() {
        out.push_str("── Related Commits ────────────────────\n");
        for c in &result.related_commits {
            out.push_str(&format!(
                "  {} ({}, {})\n  match: {}\n\n",
                c.title, c.ts, c.branch, c.match_type
            ));
        }
    }

    if !result.related_notes.is_empty() {
        out.push_str("── Related Notes ──────────────────────\n");
        for n in &result.related_notes {
            if n.text.len() > 120 {
                let end = n.text.floor_char_boundary(117);
                out.push_str(&format!(
                    "  \"{}...\" ({}, {})\n\n",
                    &n.text[..end],
                    n.ts,
                    n.branch
                ));
            } else {
                out.push_str(&format!("  \"{}\" ({}, {})\n\n", n.text, n.ts, n.branch));
            }
        }
    }

    if !result.tasks.is_empty() {
        out.push_str("── Tasks ──────────────────────────────\n");
        for t in &result.tasks {
            out.push_str(&format!("  #{} [{}] {}\n", t.task_id, t.status, t.title));
            if let Some(r) = &t.receipt {
                let excerpt = if r.len() > 120 {
                    format!("{}...", &r[..r.floor_char_boundary(117)])
                } else {
                    r.clone()
                };
                out.push_str(&format!("     receipt: {excerpt}\n"));
            }
            if !t.evidence_paths.is_empty() {
                out.push_str(&format!("     evidence: {}\n", t.evidence_paths.join(", ")));
            }
            out.push('\n');
        }
    }

    if !result.dependents.is_empty() {
        out.push_str("── Dependents ─────────────────────────\n");
        for d in &result.dependents {
            out.push_str(&format!(
                "  \u{2192} {} = {} ({}, depth {})\n",
                d.key, d.value, d.dep_type, d.depth
            ));
        }
        out.push('\n');
    }

    if let Some(ref risk) = result.override_risk {
        out.push_str("── Override Risk ──────────────────────\n");
        let emoji = match risk.level.as_str() {
            "HIGH" => "\u{1f534}",
            "MEDIUM" => "\u{1f7e1}",
            _ => "\u{1f7e2}",
        };
        out.push_str(&format!(
            "  {} {} ({} dependents)\n",
            emoji, risk.level, risk.dependent_count
        ));
        if let Some(ref suggestion) = risk.suggestion {
            out.push_str(&format!("  {suggestion}\n"));
        }
        out.push('\n');
    }

    if !result.conversations.is_empty() {
        out.push_str("── Conversations ──────────────────────\n");
        for c in &result.conversations {
            out.push_str(&format!(
                "  [{}] {}\n  rank: {:.2}\n\n",
                c.session_id, c.snippet, c.rank
            ));
        }
    }

    if out.is_empty() {
        if result.workspace_event_count == Some(0) {
            out.push_str("No results found (workspace ledger is empty; 0 events recorded).\n");
        } else if result.workspace_decision_count == Some(0) {
            out.push_str(
                "No results found (workspace ledger has 0 decisions recorded; run `edda decide` to record decisions).\n",
            );
        } else {
            out.push_str("No results found.\n");
        }
    }

    out
}

// ── Internal helpers ─────────────────────────────────────────────────

fn to_decision_hit(row: &DecisionView) -> DecisionHit {
    DecisionHit {
        event_id: row.event_id.clone(),
        key: row.key.clone(),
        value: row.value.clone(),
        reason: row.reason.clone(),
        domain: row.domain.clone(),
        branch: row.branch.clone(),
        ts: row.ts.clone().unwrap_or_default(),
        is_active: matches!(row.status.as_str(), "active" | "experimental"),
        governance: DecisionGovernance::default(),
        tags: row.tags.clone(),
        village_id: row.village_id.clone(),
        staleness: None,
    }
}

fn annotate_governance(
    hits: &mut [DecisionHit],
    ratifications: &std::collections::BTreeMap<String, edda_ledger::RatificationInfo>,
) {
    for hit in hits {
        if let Some(info) = ratifications.get(&hit.event_id) {
            hit.governance = DecisionGovernance {
                status: "ratified".to_string(),
                ratified_by: Some(info.ratified_by.clone()),
                ratified_at: Some(info.ts.clone()),
            };
        } else {
            hit.governance = DecisionGovernance {
                status: "unratified".to_string(),
                ratified_by: None,
                ratified_at: None,
            };
        }
    }
}

fn find_checkpoint_notes(
    ledger: &Ledger,
    query: &str,
    opts: &AskOptions,
) -> anyhow::Result<Vec<NoteHit>> {
    let query = query.trim().to_lowercase();
    let terms: Vec<&str> = query
        .split(" or ")
        .map(str::trim)
        .filter(|term| !term.is_empty())
        .collect();

    let mut events = ledger.iter_events_by_type("checkpoint")?;
    events.reverse();
    Ok(events
        .into_iter()
        .filter(|event| {
            opts.branch
                .as_deref()
                .is_none_or(|branch| branch == event.branch)
        })
        .filter(|event| {
            opts.after
                .as_deref()
                .is_none_or(|after| event.ts.as_str() >= after)
                && opts
                    .before
                    .as_deref()
                    .is_none_or(|before| event.ts.as_str() <= before)
        })
        .filter_map(|event| {
            let payload: edda_core::event::CheckpointPayload =
                serde_json::from_value(event.payload.clone()).ok()?;
            let searchable = serde_json::to_string(&payload).ok()?.to_lowercase();
            if !terms.is_empty() && !terms.iter().any(|term| searchable.contains(term)) {
                return None;
            }
            let rejected = payload
                .rejected
                .iter()
                .map(|item| format!("{} — {}", item.hypothesis, item.reason))
                .collect::<Vec<_>>();
            let text = format!(
                "checkpoint: hypotheses=[{}]; rejected=[{}]; open=[{}]; next={}",
                payload.hypotheses.join(" | "),
                rejected.join(" | "),
                payload.open.join(" | "),
                payload.next,
            );
            Some(NoteHit {
                event_id: event.event_id,
                text,
                ts: event.ts,
                branch: event.branch,
            })
        })
        .take(opts.limit)
        .collect())
}

/// Return the affected_paths carried by each decision in `result.decisions`,
/// looked up from the ledger by event_id. Position-aligned with the input;
/// missing/unreadable rows return empty Vec (best-effort).
pub fn affected_paths_for_hits(ledger: &Ledger, hits: &[DecisionHit]) -> Vec<Vec<String>> {
    hits.iter()
        .map(|h| {
            ledger
                .get_decision_by_event_id(&h.event_id)
                .ok()
                .flatten()
                .map(|row| row.affected_paths)
                .unwrap_or_default()
        })
        .collect()
}

// Decision helpers centralized in edda_core::decision.

// ── Tests ────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use edda_core::event::{
        finalize_event, new_checkpoint_event, new_note_event, CheckpointPayload, RejectedHypothesis,
    };
    use edda_core::Provenance;
    use edda_ledger::ledger::{init_branches_json, init_head, init_workspace};
    use edda_ledger::paths::EddaPaths;
    use std::sync::atomic::{AtomicU64, Ordering};

    static TEST_COUNTER: AtomicU64 = AtomicU64::new(0);

    struct TestLedger(Ledger);

    impl std::ops::Deref for TestLedger {
        type Target = Ledger;

        fn deref(&self) -> &Self::Target {
            &self.0
        }
    }

    impl TestLedger {
        fn append_event(&self, event: &Event) -> anyhow::Result<()> {
            let mut chained = event.clone();
            chained.parent_hash = self.0.last_event_hash()?;
            finalize_event(&mut chained)?;
            self.0.append_event(&chained)
        }
    }

    fn setup() -> (std::path::PathBuf, TestLedger) {
        let n = TEST_COUNTER.fetch_add(1, Ordering::SeqCst);
        let tmp = std::env::temp_dir().join(format!("edda_ask_test_{}_{n}", std::process::id()));
        let _ = std::fs::remove_dir_all(&tmp);
        let paths = EddaPaths::discover(&tmp);
        init_workspace(&paths).unwrap();
        init_head(&paths, "main").unwrap();
        init_branches_json(&paths, "main").unwrap();
        let ledger = TestLedger(Ledger::open(&tmp).unwrap());
        (tmp, ledger)
    }

    /// A finished task's receipt is the fleet's answer to "what shipped about X,
    /// verified how" — and before GH-404 `ask` had no Tasks section at all, so
    /// it never surfaced. Matching on the receipt is the point: that is where
    /// the verification lives.
    #[test]
    fn ask_surfaces_a_task_whose_receipt_matches_the_query() {
        let (_tmp, ledger) = setup();

        let created =
            edda_core::event::new_task_created_event(&edda_core::event::TaskCreatedParams {
                branch: "main",
                parent_hash: None,
                task_id: 7,
                title: "run the onboarding drill",
                assignee: None,
                agent_kind: None,
                after: &[],
                plan_id: None,
                work_unit_ref: None,
                brief_ref: None,
                idempotency_key: None,
                scope_paths: &[],
            })
            .unwrap();
        ledger.append_event(&created).unwrap();
        let done = edda_core::event::new_task_done_event(
            "main",
            None,
            7,
            "drill passed: 9/9 green, artifact in dist/drill.json",
            &["dist/drill.json".to_string()],
        )
        .unwrap();
        ledger.append_event(&done).unwrap();

        // A second task that does NOT mention "drill". Without it, the test
        // could not tell a working filter from one that returns every task —
        // with a single task, "the match is present" and "everything is
        // present" are the same assertion.
        let other =
            edda_core::event::new_task_created_event(&edda_core::event::TaskCreatedParams {
                branch: "main",
                parent_hash: None,
                task_id: 8,
                title: "write the changelog",
                assignee: None,
                agent_kind: None,
                after: &[],
                plan_id: None,
                work_unit_ref: None,
                brief_ref: None,
                idempotency_key: None,
                scope_paths: &[],
            })
            .unwrap();
        ledger.append_event(&other).unwrap();

        let opts = AskOptions {
            limit: 10,
            ..Default::default()
        };
        let result = ask(&ledger, "drill", &opts, None).unwrap();

        assert_eq!(
            result.tasks.len(),
            1,
            "only the drill task matches — the changelog task must be filtered out: {:?}",
            result.tasks
        );
        let hit = &result.tasks[0];
        assert_eq!(hit.task_id, 7);
        assert!(hit.title.contains("drill"), "title: {}", hit.title);
        assert_eq!(hit.status, "done");
        assert!(
            hit.receipt.as_deref().unwrap_or("").contains("9/9 green"),
            "the receipt is the point: {:?}",
            hit.receipt
        );
        assert_eq!(hit.evidence_paths, vec!["dist/drill.json".to_string()]);
    }

    #[test]
    fn ask_recalls_checkpoint_judgment_state() {
        let (_tmp, ledger) = setup();
        let checkpoint = CheckpointPayload {
            hypotheses: vec!["cache invalidation is the cause".to_string()],
            rejected: vec![RejectedHypothesis {
                hypothesis: "database corruption".to_string(),
                reason: "integrity check passes".to_string(),
            }],
            open: vec!["confirm the next rebuild".to_string()],
            next: "run the rebuild check".to_string(),
        };
        let event = new_checkpoint_event("main", None, "agent", &checkpoint).unwrap();
        ledger.append_event(&event).unwrap();

        let result = ask(&ledger, "rebuild", &AskOptions::default(), None).unwrap();

        assert_eq!(result.related_notes.len(), 1);
        assert!(result.related_notes[0]
            .text
            .contains("next=run the rebuild check"));
        assert!(result.related_notes[0]
            .text
            .contains("integrity check passes"));
    }

    fn make_decision(
        branch: &str,
        key: &str,
        value: &str,
        reason: Option<&str>,
        supersedes: Option<&str>,
    ) -> Event {
        let text = match reason {
            Some(r) => format!("{key}: {value} — {r}"),
            None => format!("{key}: {value}"),
        };
        let tags = vec!["decision".to_string()];
        let mut event = new_note_event(branch, None, "system", &text, &tags).unwrap();
        let decision_obj = match reason {
            Some(r) => serde_json::json!({"key": key, "value": value, "reason": r}),
            None => serde_json::json!({"key": key, "value": value}),
        };
        event.payload["decision"] = decision_obj;
        if let Some(target) = supersedes {
            event.refs.provenance.push(Provenance {
                target: target.to_string(),
                rel: "supersedes".to_string(),
                note: Some(format!("key '{key}' re-decided")),
            });
        }
        finalize_event(&mut event).unwrap();
        event
    }

    fn make_commit(branch: &str, title: &str, purpose: &str, evidence: &[&str]) -> Event {
        use edda_core::event::finalize_event;
        let payload = serde_json::json!({
            "title": title,
            "purpose": purpose,
            "sha": "abc123",
        });
        let mut event = Event {
            event_id: format!("evt_{}", ulid::Ulid::new().to_string().to_lowercase()),
            ts: time_now(),
            event_type: "commit".to_string(),
            branch: branch.to_string(),
            parent_hash: None,
            hash: String::new(),
            payload,
            refs: edda_core::Refs {
                events: evidence.iter().map(|s| s.to_string()).collect(),
                ..Default::default()
            },
            schema_version: 1,
            digests: vec![],
            event_family: None,
            event_level: None,
        };
        finalize_event(&mut event).unwrap();
        event
    }

    fn make_note(branch: &str, text: &str) -> Event {
        new_note_event(branch, None, "user", text, &[]).unwrap()
    }

    fn time_now() -> String {
        let now = time::OffsetDateTime::now_utc();
        now.format(&time::format_description::well_known::Rfc3339)
            .expect("rfc3339")
    }

    // ── detect_input_type tests ──────────────────────────────────────

    #[test]
    fn detect_exact_key() {
        let domains = vec!["db".into(), "auth".into()];
        assert_eq!(
            detect_input_type("db.engine", &domains),
            InputType::ExactKey("db.engine".into())
        );
    }

    #[test]
    fn detect_domain() {
        let domains = vec!["db".into(), "auth".into()];
        assert_eq!(
            detect_input_type("db", &domains),
            InputType::Domain("db".into())
        );
    }

    #[test]
    fn detect_domain_case_insensitive() {
        let domains = vec!["db".into()];
        assert_eq!(
            detect_input_type("DB", &domains),
            InputType::Domain("DB".into())
        );
    }

    #[test]
    fn detect_keyword() {
        let domains = vec!["db".into()];
        assert_eq!(
            detect_input_type("postgres", &domains),
            InputType::Keyword("postgres".into())
        );
    }

    #[test]
    fn detect_overview() {
        assert_eq!(detect_input_type("", &[]), InputType::Overview);
        assert_eq!(detect_input_type("  ", &[]), InputType::Overview);
    }

    // ── ask() tests ──────────────────────────────────────────────────

    #[test]
    fn ask_exact_key() {
        let (tmp, ledger) = setup();
        let d1 = make_decision("main", "db.engine", "sqlite", Some("MVP"), None);
        let d1_id = d1.event_id.clone();
        ledger.append_event(&d1).unwrap();

        let d2 = make_decision("main", "db.engine", "postgres", Some("JSONB"), Some(&d1_id));
        ledger.append_event(&d2).unwrap();

        let result = ask(&ledger, "db.engine", &AskOptions::default(), None).unwrap();
        assert_eq!(result.input_type, "exact_key");
        // decisions = only active (default)
        assert_eq!(result.decisions.len(), 1);
        assert_eq!(result.decisions[0].value, "postgres");
        // timeline = both
        assert_eq!(result.timeline.len(), 2);

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn ask_domain() {
        let (tmp, ledger) = setup();
        ledger
            .append_event(&make_decision("main", "db.engine", "postgres", None, None))
            .unwrap();
        ledger
            .append_event(&make_decision("main", "db.pool", "10", None, None))
            .unwrap();
        ledger
            .append_event(&make_decision("main", "auth.method", "JWT", None, None))
            .unwrap();

        let result = ask(&ledger, "db", &AskOptions::default(), None).unwrap();
        assert_eq!(result.input_type, "domain");
        assert_eq!(result.decisions.len(), 2);
        assert!(result.timeline.len() >= 2);

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn ask_keyword() {
        let (tmp, ledger) = setup();
        ledger
            .append_event(&make_decision(
                "main",
                "db.engine",
                "postgres",
                Some("JSONB"),
                None,
            ))
            .unwrap();
        ledger
            .append_event(&make_decision("main", "auth.method", "JWT", None, None))
            .unwrap();

        let result = ask(&ledger, "postgres", &AskOptions::default(), None).unwrap();
        assert_eq!(result.input_type, "keyword");
        assert_eq!(result.decisions.len(), 1);
        assert_eq!(result.decisions[0].key, "db.engine");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn ask_overview() {
        let (tmp, ledger) = setup();
        ledger
            .append_event(&make_decision("main", "db.engine", "postgres", None, None))
            .unwrap();
        ledger
            .append_event(&make_decision("main", "auth.method", "JWT", None, None))
            .unwrap();

        let result = ask(&ledger, "", &AskOptions::default(), None).unwrap();
        assert_eq!(result.input_type, "overview");
        assert_eq!(result.decisions.len(), 2);

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn ask_with_transcript_callback() {
        let (tmp, ledger) = setup();
        ledger
            .append_event(&make_decision("main", "db.engine", "postgres", None, None))
            .unwrap();

        let callback = |_query: &str, _limit: usize| -> Vec<ConversationHit> {
            vec![ConversationHit {
                doc_id: "t1".into(),
                session_id: "s1".into(),
                ts: "2026-02-14T10:00:00Z".into(),
                snippet: "discussed postgres JSONB".into(),
                rank: 5.0,
            }]
        };

        let result = ask(&ledger, "postgres", &AskOptions::default(), Some(&callback)).unwrap();
        assert_eq!(result.conversations.len(), 1);
        assert_eq!(result.conversations[0].snippet, "discussed postgres JSONB");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn ask_without_transcript_callback() {
        let (tmp, ledger) = setup();
        ledger
            .append_event(&make_decision("main", "db.engine", "postgres", None, None))
            .unwrap();

        let result = ask(&ledger, "postgres", &AskOptions::default(), None).unwrap();
        assert!(result.conversations.is_empty());

        let _ = std::fs::remove_dir_all(&tmp);
    }

    // ── Related events tests ─────────────────────────────────────────

    #[test]
    fn find_related_commits_evidence_chain() {
        let (tmp, ledger) = setup();
        let d1 = make_decision("main", "db.engine", "postgres", Some("JSONB"), None);
        let d1_id = d1.event_id.clone();
        ledger.append_event(&d1).unwrap();

        let c1 = make_commit(
            "main",
            "feat: migrate to postgres",
            "db migration",
            &[&d1_id],
        );
        ledger.append_event(&c1).unwrap();

        let result = ask(&ledger, "db.engine", &AskOptions::default(), None).unwrap();
        assert_eq!(result.related_commits.len(), 1);
        assert_eq!(result.related_commits[0].match_type, "evidence");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn find_related_commits_title_match() {
        let (tmp, ledger) = setup();
        ledger
            .append_event(&make_decision("main", "db.engine", "postgres", None, None))
            .unwrap();

        // Commit not linked via evidence, but title matches
        let c1 = make_commit("main", "fix: postgres connection pool", "pool fix", &[]);
        ledger.append_event(&c1).unwrap();

        let result = ask(&ledger, "postgres", &AskOptions::default(), None).unwrap();
        assert!(result
            .related_commits
            .iter()
            .any(|c| c.match_type == "title"));

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn find_related_notes_text_match() {
        let (tmp, ledger) = setup();
        ledger
            .append_event(&make_decision("main", "db.engine", "postgres", None, None))
            .unwrap();

        // Regular note (not a decision)
        ledger
            .append_event(&make_note(
                "main",
                "discussed mysql but rejected for licensing",
            ))
            .unwrap();

        let result = ask(&ledger, "mysql", &AskOptions::default(), None).unwrap();
        assert_eq!(result.related_notes.len(), 1);
        assert!(result.related_notes[0].text.contains("mysql"));

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn find_related_notes_excludes_decision_notes() {
        let (tmp, ledger) = setup();
        ledger
            .append_event(&make_decision(
                "main",
                "db.engine",
                "postgres",
                Some("JSONB"),
                None,
            ))
            .unwrap();

        let result = ask(&ledger, "postgres", &AskOptions::default(), None).unwrap();
        // Decision note should NOT appear in related_notes
        assert!(result.related_notes.is_empty());

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn ask_annotates_governance_tier() {
        let (tmp, ledger) = setup();

        // 1. Ratified decision: db.engine = postgres, ratified by alice
        ledger
            .append_event(&make_decision(
                "main",
                "db.engine",
                "postgres",
                Some("JSONB"),
                None,
            ))
            .unwrap();
        let ratify_ev =
            edda_core::event::new_decision_ratify_event("main", None, "db.engine", "alice", None)
                .unwrap();
        ledger.append_event(&ratify_ev).unwrap();

        // 2. Unratified decision: auth.method = jwt
        ledger
            .append_event(&make_decision(
                "main",
                "auth.method",
                "jwt",
                Some("stateless"),
                None,
            ))
            .unwrap();

        // Check db.engine hit
        let r1 = ask(&ledger, "db.engine", &AskOptions::default(), None).unwrap();
        assert_eq!(r1.decisions.len(), 1);
        let d1 = &r1.decisions[0];
        assert_eq!(d1.key, "db.engine");
        assert_eq!(d1.governance.status, "ratified");
        assert_eq!(d1.governance.ratified_by.as_deref(), Some("alice"));
        assert!(d1.governance.ratified_at.is_some());

        // Check human formatting includes ratification
        let human1 = format_human(&r1);
        assert!(human1.contains("ratified (by alice)"));

        // Check auth.method hit
        let r2 = ask(&ledger, "auth.method", &AskOptions::default(), None).unwrap();
        assert_eq!(r2.decisions.len(), 1);
        let d2 = &r2.decisions[0];
        assert_eq!(d2.key, "auth.method");
        assert_eq!(d2.governance.status, "unratified");
        assert_eq!(d2.governance.ratified_by, None);
        assert_eq!(d2.governance.ratified_at, None);

        let human2 = format_human(&r2);
        assert!(human2.contains("unratified"));

        // 3. Re-decide db.engine = sqlite after ratify -> resets to unratified
        ledger
            .append_event(&make_decision(
                "main",
                "db.engine",
                "sqlite",
                Some("local dev"),
                None,
            ))
            .unwrap();

        let r3 = ask(&ledger, "db.engine", &AskOptions::default(), None).unwrap();
        assert_eq!(r3.decisions.len(), 1);
        let d3 = &r3.decisions[0];
        assert_eq!(d3.value, "sqlite");
        assert_eq!(d3.governance.status, "unratified");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn ask_branch_filter() {
        let (tmp, ledger) = setup();
        ledger
            .append_event(&make_decision(
                "main",
                "db.engine",
                "postgres",
                Some("prod"),
                None,
            ))
            .unwrap();
        ledger
            .append_event(&make_decision(
                "dev",
                "db.engine",
                "sqlite",
                Some("dev speed"),
                None,
            ))
            .unwrap();

        // No branch filter → both
        let result = ask(&ledger, "", &AskOptions::default(), None).unwrap();
        assert_eq!(result.decisions.len(), 2);

        // Filter to dev → only sqlite
        let opts = AskOptions {
            branch: Some("dev".into()),
            ..Default::default()
        };
        let result = ask(&ledger, "", &opts, None).unwrap();
        assert_eq!(result.decisions.len(), 1);
        assert_eq!(result.decisions[0].value, "sqlite");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn format_human_contains_sections() {
        let result = AskResult {
            query: "postgres".into(),
            input_type: "keyword".into(),
            decisions: vec![DecisionHit {
                event_id: "e1".into(),
                key: "db.engine".into(),
                value: "postgres".into(),
                reason: "JSONB".into(),
                domain: "db".into(),
                branch: "main".into(),
                ts: "2026-02-15".into(),
                is_active: true,
                governance: DecisionGovernance::default(),
                tags: vec![],
                village_id: None,
                staleness: None,
            }],
            timeline: vec![],
            related_commits: vec![CommitHit {
                event_id: "c1".into(),
                title: "feat: migrate".into(),
                purpose: "migration".into(),
                ts: "2026-02-15".into(),
                branch: "main".into(),
                match_type: "evidence".into(),
            }],
            related_notes: vec![],
            conversations: vec![],
            tasks: vec![],
            dependents: vec![],
            override_risk: None,
            ..Default::default()
        };

        let output = format_human(&result);
        assert!(output.contains("Decisions"));
        assert!(output.contains("postgres"));
        assert!(output.contains("Related Commits"));
        assert!(output.contains("feat: migrate"));
    }

    #[test]
    fn find_related_notes_excludes_session_digests() {
        let (tmp, ledger) = setup();
        // Create a session digest note containing a keyword
        let tags = vec!["session_digest".to_string()];
        let mut digest = new_note_event(
            "main",
            None,
            "system",
            "discussed postgres migration",
            &tags,
        )
        .unwrap();
        digest.payload["session_stats"] = serde_json::json!({
            "tool_calls": 10,
            "tasks_snapshot": [{"subject": "Fix postgres pool", "status": "completed"}],
        });
        finalize_event(&mut digest).unwrap();
        ledger.append_event(&digest).unwrap();

        let result = ask(&ledger, "postgres", &AskOptions::default(), None).unwrap();
        // Session digest note should NOT appear in related_notes
        assert!(
            result.related_notes.is_empty(),
            "session digest should be filtered: {:?}",
            result.related_notes
        );

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn format_human_truncates_long_notes() {
        let long_text = "a".repeat(200);
        let result = AskResult {
            query: "test".into(),
            input_type: "keyword".into(),
            decisions: vec![],
            timeline: vec![],
            related_commits: vec![],
            related_notes: vec![NoteHit {
                event_id: "n1".into(),
                text: long_text,
                ts: "2026-02-26".into(),
                branch: "main".into(),
            }],
            conversations: vec![],
            tasks: vec![],
            dependents: vec![],
            override_risk: None,
            ..Default::default()
        };

        let output = format_human(&result);
        assert!(output.contains("..."), "long note should be truncated");
        // Should not contain the full 200-char string
        assert!(
            !output.contains(&"a".repeat(200)),
            "should not contain full text"
        );
    }

    #[test]
    fn format_human_empty_result() {
        let result = AskResult {
            query: "nonexistent".into(),
            input_type: "keyword".into(),
            decisions: vec![],
            timeline: vec![],
            related_commits: vec![],
            related_notes: vec![],
            conversations: vec![],
            tasks: vec![],
            dependents: vec![],
            override_risk: None,
            workspace_event_count: Some(5),
            workspace_decision_count: Some(2),
        };

        let output = format_human(&result);
        assert_eq!(output, "No results found.\n");
    }

    #[test]
    fn format_human_empty_ledger_distinguished_from_empty_results() {
        let result_empty_ledger = AskResult {
            query: "test".into(),
            workspace_event_count: Some(0),
            workspace_decision_count: Some(0),
            ..Default::default()
        };
        assert_eq!(
            format_human(&result_empty_ledger),
            "No results found (workspace ledger is empty; 0 events recorded).\n"
        );

        let result_zero_decisions = AskResult {
            query: "test".into(),
            workspace_event_count: Some(1),
            workspace_decision_count: Some(0),
            ..Default::default()
        };
        assert_eq!(
            format_human(&result_zero_decisions),
            "No results found (workspace ledger has 0 decisions recorded; run `edda decide` to record decisions).\n"
        );
    }

    // ── Impact analysis tests ───────────────────────────────────────

    #[test]
    fn impact_no_dependents() {
        let (tmp, ledger) = setup();
        let d1 = make_decision("main", "db.engine", "postgres", Some("JSONB"), None);
        ledger.append_event(&d1).unwrap();

        let opts = AskOptions {
            impact: true,
            ..Default::default()
        };
        let result = ask(&ledger, "db.engine", &opts, None).unwrap();
        assert!(result.dependents.is_empty());
        assert_eq!(result.override_risk.as_ref().unwrap().level, "LOW");
        assert_eq!(result.override_risk.as_ref().unwrap().dependent_count, 0);

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn impact_single_explicit_dep() {
        let (tmp, ledger) = setup();
        let d1 = make_decision("main", "db.engine", "postgres", Some("JSONB"), None);
        ledger.append_event(&d1).unwrap();

        let d2 = make_decision("main", "db.schema", "JSONB", Some("needs postgres"), None);
        ledger.append_event(&d2).unwrap();

        // db.schema depends on db.engine (explicit)
        ledger
            .insert_dep("db.schema", "db.engine", "explicit", None)
            .unwrap();

        let opts = AskOptions {
            impact: true,
            ..Default::default()
        };
        let result = ask(&ledger, "db.engine", &opts, None).unwrap();
        assert_eq!(result.dependents.len(), 1);
        assert_eq!(result.dependents[0].key, "db.schema");
        assert_eq!(result.dependents[0].dep_type, "explicit");
        assert_eq!(result.dependents[0].depth, 1);
        // 1 explicit direct dep => score = 3 => MEDIUM
        assert_eq!(result.override_risk.as_ref().unwrap().level, "MEDIUM");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn impact_multiple_auto_domain() {
        let (tmp, ledger) = setup();
        let d1 = make_decision("main", "db.engine", "postgres", None, None);
        ledger.append_event(&d1).unwrap();
        let d2 = make_decision("main", "db.pool", "10", None, None);
        ledger.append_event(&d2).unwrap();
        let d3 = make_decision("main", "db.timeout", "30s", None, None);
        ledger.append_event(&d3).unwrap();

        // auto_domain deps
        ledger
            .insert_dep("db.pool", "db.engine", "auto_domain", None)
            .unwrap();
        ledger
            .insert_dep("db.timeout", "db.engine", "auto_domain", None)
            .unwrap();

        let opts = AskOptions {
            impact: true,
            ..Default::default()
        };
        let result = ask(&ledger, "db.engine", &opts, None).unwrap();
        assert_eq!(result.dependents.len(), 2);
        // 2 auto_domain direct deps => score = 2 => LOW
        assert_eq!(result.override_risk.as_ref().unwrap().level, "LOW");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn impact_transitive_chain() {
        let (tmp, ledger) = setup();
        let d1 = make_decision("main", "db.engine", "postgres", None, None);
        ledger.append_event(&d1).unwrap();
        let d2 = make_decision("main", "db.schema", "JSONB", None, None);
        ledger.append_event(&d2).unwrap();
        let d3 = make_decision("main", "api.format", "JSON", None, None);
        ledger.append_event(&d3).unwrap();

        // db.schema -> db.engine, api.format -> db.schema
        ledger
            .insert_dep("db.schema", "db.engine", "explicit", None)
            .unwrap();
        ledger
            .insert_dep("api.format", "db.schema", "explicit", None)
            .unwrap();

        let opts = AskOptions {
            impact: true,
            ..Default::default()
        };
        let result = ask(&ledger, "db.engine", &opts, None).unwrap();
        assert_eq!(result.dependents.len(), 2);

        // Check depths
        let schema_hit = result
            .dependents
            .iter()
            .find(|d| d.key == "db.schema")
            .unwrap();
        assert_eq!(schema_hit.depth, 1);
        let api_hit = result
            .dependents
            .iter()
            .find(|d| d.key == "api.format")
            .unwrap();
        assert_eq!(api_hit.depth, 2);

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn impact_cross_domain() {
        let (tmp, ledger) = setup();
        let d1 = make_decision("main", "db.engine", "postgres", None, None);
        ledger.append_event(&d1).unwrap();
        let d2 = make_decision("main", "db.schema", "JSONB", None, None);
        ledger.append_event(&d2).unwrap();
        let d3 = make_decision("main", "api.format", "JSON", None, None);
        ledger.append_event(&d3).unwrap();
        let d4 = make_decision("main", "cache.strategy", "redis", None, None);
        ledger.append_event(&d4).unwrap();

        // All depend on db.engine via explicit
        ledger
            .insert_dep("db.schema", "db.engine", "explicit", None)
            .unwrap();
        ledger
            .insert_dep("api.format", "db.engine", "explicit", None)
            .unwrap();
        ledger
            .insert_dep("cache.strategy", "db.engine", "explicit", None)
            .unwrap();

        let opts = AskOptions {
            impact: true,
            ..Default::default()
        };
        let result = ask(&ledger, "db.engine", &opts, None).unwrap();
        assert_eq!(result.dependents.len(), 3);
        // 3 explicit direct (9) + cross_domain: 3 domains × 2 (6) => score = 15 => HIGH
        assert_eq!(result.override_risk.as_ref().unwrap().level, "HIGH");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn impact_high_risk_scenario() {
        let (tmp, ledger) = setup();
        let d1 = make_decision("main", "db.engine", "postgres", None, None);
        ledger.append_event(&d1).unwrap();

        // Create 4 explicit dependents + 1 transitive
        for (i, key) in ["db.schema", "db.pool", "api.format", "auth.store"]
            .iter()
            .enumerate()
        {
            let d = make_decision("main", key, &format!("val{i}"), None, None);
            ledger.append_event(&d).unwrap();
            ledger
                .insert_dep(key, "db.engine", "explicit", None)
                .unwrap();
        }
        // Transitive: cache.ttl -> api.format -> db.engine
        let d_cache = make_decision("main", "cache.ttl", "60s", None, None);
        ledger.append_event(&d_cache).unwrap();
        ledger
            .insert_dep("cache.ttl", "api.format", "explicit", None)
            .unwrap();

        let opts = AskOptions {
            impact: true,
            ..Default::default()
        };
        let result = ask(&ledger, "db.engine", &opts, None).unwrap();
        assert_eq!(result.dependents.len(), 5);
        assert_eq!(result.override_risk.as_ref().unwrap().level, "HIGH");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn impact_domain_query() {
        let (tmp, ledger) = setup();
        let d1 = make_decision("main", "db.engine", "postgres", None, None);
        ledger.append_event(&d1).unwrap();
        let d2 = make_decision("main", "db.pool", "10", None, None);
        ledger.append_event(&d2).unwrap();

        // api.format depends on db.engine
        let d3 = make_decision("main", "api.format", "JSON", None, None);
        ledger.append_event(&d3).unwrap();
        ledger
            .insert_dep("api.format", "db.engine", "explicit", None)
            .unwrap();

        let opts = AskOptions {
            impact: true,
            ..Default::default()
        };
        let result = ask(&ledger, "db", &opts, None).unwrap();
        assert_eq!(result.input_type, "domain");
        // api.format is a dependent of db.engine
        assert!(
            result.dependents.iter().any(|d| d.key == "api.format"),
            "domain impact should find api.format as dependent"
        );
        assert!(result.override_risk.is_some());

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn impact_flag_ignored_for_keyword() {
        let (tmp, ledger) = setup();
        let d1 = make_decision("main", "db.engine", "postgres", Some("JSONB"), None);
        ledger.append_event(&d1).unwrap();

        let opts = AskOptions {
            impact: true,
            ..Default::default()
        };
        let result = ask(&ledger, "postgres", &opts, None).unwrap();
        assert_eq!(result.input_type, "keyword");
        // Impact should be empty for keyword queries
        assert!(result.dependents.is_empty());
        assert!(result.override_risk.is_none());

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn ask_keyword_semantic_similarity() {
        let (tmp, ledger) = setup();
        ledger
            .append_event(&make_decision(
                "main",
                "pricing.discount_policy",
                "daytime_revenue_shield",
                Some("avoid aggressive daytime markdowns"),
                None,
            ))
            .unwrap();
        ledger
            .append_event(&make_decision(
                "main",
                "inventory.reorder_buffer",
                "40_percent",
                Some("protect stock for midnight spikes"),
                None,
            ))
            .unwrap();

        let query = "similar daytime discount outcome for chiefs";
        let result = ask(&ledger, query, &AskOptions::default(), None).unwrap();

        assert_eq!(result.input_type, "keyword");
        assert!(
            result
                .decisions
                .iter()
                .any(|d| d.key == "pricing.discount_policy"),
            "semantic search should retrieve discount precedent"
        );

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn format_human_with_impact() {
        let result = AskResult {
            query: "db.engine".into(),
            input_type: "exact_key".into(),
            decisions: vec![DecisionHit {
                event_id: "e1".into(),
                key: "db.engine".into(),
                value: "postgres".into(),
                reason: "JSONB".into(),
                domain: "db".into(),
                branch: "main".into(),
                ts: "2026-02-15".into(),
                is_active: true,
                governance: DecisionGovernance::default(),
                tags: vec![],
                village_id: None,
                staleness: None,
            }],
            timeline: vec![],
            related_commits: vec![],
            related_notes: vec![],
            conversations: vec![],
            tasks: vec![],
            dependents: vec![
                DependentHit {
                    key: "db.schema".into(),
                    value: "JSONB".into(),
                    dep_type: "explicit".into(),
                    depth: 1,
                },
                DependentHit {
                    key: "api.format".into(),
                    value: "JSON".into(),
                    dep_type: "auto_domain".into(),
                    depth: 2,
                },
            ],
            override_risk: Some(OverrideRisk {
                level: "HIGH".to_string(),
                dependent_count: 2,
                suggestion: Some("建議覆蓋順序: api.format → db.schema".into()),
            }),
            ..Default::default()
        };

        let output = format_human(&result);
        assert!(
            output.contains("Dependents"),
            "should have Dependents section"
        );
        assert!(
            output.contains("depth 1"),
            "should show depth for dependents"
        );
        assert!(
            output.contains("depth 2"),
            "should show depth for transitive"
        );
        assert!(
            output.contains("Override Risk"),
            "should have Override Risk section"
        );
        assert!(output.contains("HIGH"), "should show HIGH risk level");
        assert!(
            output.contains("建議覆蓋順序"),
            "should show override order suggestion"
        );
    }

    #[test]
    fn ask_filters_by_village_id() {
        let (_tmp, ledger) = setup();

        // Create two decisions: one with village_id, one without
        let mut ev1 = make_decision("main", "db.engine", "sqlite", Some("embedded"), None);
        ev1.payload["decision"]["village_id"] = serde_json::json!("village-a");
        finalize_event(&mut ev1).unwrap();
        ledger.append_event(&ev1).unwrap();

        let ev2 = make_decision("main", "cache.ttl", "3600", Some("perf"), None);
        ledger.append_event(&ev2).unwrap();

        // Without village filter: should find both
        let opts_all = AskOptions::default();
        let result_all = ask(&ledger, "db OR cache", &opts_all, None).unwrap();
        assert!(
            result_all.decisions.len() >= 2,
            "expected at least 2 decisions without village filter, got {}",
            result_all.decisions.len()
        );

        // With village filter: should find only village-a
        let opts_village = AskOptions {
            village_id: Some("village-a".to_string()),
            ..Default::default()
        };
        let result_village = ask(&ledger, "db OR cache", &opts_village, None).unwrap();
        assert_eq!(
            result_village.decisions.len(),
            1,
            "expected 1 decision with village filter"
        );
        assert_eq!(result_village.decisions[0].key, "db.engine");
        assert_eq!(
            result_village.decisions[0].village_id.as_deref(),
            Some("village-a")
        );

        // Non-existent village: should find none
        let opts_empty = AskOptions {
            village_id: Some("no-such-village".to_string()),
            ..Default::default()
        };
        let result_empty = ask(&ledger, "db OR cache", &opts_empty, None).unwrap();
        assert!(
            result_empty.decisions.is_empty(),
            "expected 0 decisions for non-existent village"
        );
    }
}