tokensave 7.0.3

use tokensave::context::*;
use tokensave::types::*;

#[tokio::test]
async fn test_reranking_demotes_fixture_nodes() {
    use tempfile::TempDir;
    use tokensave::context::ContextBuilder;
    use tokensave::db::Database;

    let dir = TempDir::new().unwrap();
    let project = dir.path();

    let (db, _) = Database::initialize(&project.join(".tokensave/tokensave.db"))
        .await
        .unwrap();

    // Fixture node: enum variant in tests/fixtures/
    let fixture_node = Node {
        id: "enum_variant:fixture_debug".to_string(),
        kind: NodeKind::EnumVariant,
        name: "debug".to_string(),
        qualified_name: "tests/fixtures/sample.dart::LogLevel::debug".to_string(),
        file_path: "tests/fixtures/sample.dart".to_string(),
        start_line: 14,
        attrs_start_line: 14,
        end_line: 14,
        start_column: 0,
        end_column: 10,
        signature: Some("debug".to_string()),
        docstring: None,
        visibility: Visibility::Pub,
        is_async: false,
        branches: 0,
        loops: 0,
        returns: 0,
        max_nesting: 0,
        unsafe_blocks: 0,
        unchecked_calls: 0,
        assertions: 0,
        cognitive_complexity: 0,
        distinct_operators: 0,
        distinct_operands: 0,
        total_operators: 0,
        total_operands: 0,
        updated_at: 0,
        parent_id: None,
    };
    db.insert_node(&fixture_node).await.unwrap();

    // Source node: function in src/
    let source_node = Node {
        id: "function:debug_handler".to_string(),
        kind: NodeKind::Function,
        name: "debug_handler".to_string(),
        qualified_name: "src/debug.rs::debug_handler".to_string(),
        file_path: "src/debug.rs".to_string(),
        start_line: 1,
        attrs_start_line: 1,
        end_line: 10,
        start_column: 0,
        end_column: 1,
        signature: Some("pub fn debug_handler()".to_string()),
        docstring: None,
        visibility: Visibility::Pub,
        is_async: false,
        branches: 0,
        loops: 0,
        returns: 0,
        max_nesting: 0,
        unsafe_blocks: 0,
        unchecked_calls: 0,
        assertions: 0,
        cognitive_complexity: 0,
        distinct_operators: 0,
        distinct_operands: 0,
        total_operators: 0,
        total_operands: 0,
        updated_at: 0,
        parent_id: None,
    };
    db.insert_node(&source_node).await.unwrap();

    let builder = ContextBuilder::new(&db, project);
    let result = builder
        .build_context("debug", &BuildContextOptions::default())
        .await
        .unwrap();

    assert!(!result.entry_points.is_empty());
    assert_eq!(
        result.entry_points[0].id, "function:debug_handler",
        "source function should outrank fixture enum variant after re-ranking"
    );
}

#[test]
fn test_extract_symbols_from_query() {
    let symbols = extract_symbols_from_query("fix the process_request function");
    assert!(symbols.contains(&"process_request".to_string()));
}

#[test]
fn test_extract_camel_case_symbols() {
    let symbols = extract_symbols_from_query("update UserService handler");
    assert!(symbols.contains(&"UserService".to_string()));
}

#[test]
fn test_extract_qualified_symbols() {
    let symbols = extract_symbols_from_query("look at crate::types::Node");
    assert!(symbols.iter().any(|s| s.contains("Node")));
}

#[test]
fn test_extract_screaming_snake_symbols() {
    let symbols = extract_symbols_from_query("increase MAX_RETRIES");
    assert!(symbols.contains(&"MAX_RETRIES".to_string()));
}

#[test]
fn test_extract_no_symbols_from_plain_english() {
    let symbols = extract_symbols_from_query("the is in for to a an");
    assert!(symbols.is_empty());
}

#[test]
fn test_format_context_markdown() {
    let context = TaskContext {
        query: "test query".to_string(),
        summary: "Test summary".to_string(),
        subgraph: Subgraph::default(),
        entry_points: vec![],
        code_blocks: vec![],
        related_files: vec![],
        seen_node_ids: vec![],
    };
    let md = format_context_as_markdown(&context);
    assert!(md.contains("## Code Context"));
    assert!(md.contains("test query"));
}

#[test]
fn test_format_context_json() {
    let context = TaskContext {
        query: "test".to_string(),
        summary: "Summary".to_string(),
        subgraph: Subgraph::default(),
        entry_points: vec![],
        code_blocks: vec![],
        related_files: vec![],
        seen_node_ids: vec![],
    };
    let json = format_context_as_json(&context);
    let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
    assert_eq!(parsed["query"], "test");
}

#[tokio::test]
async fn test_build_context_with_db() {
    use std::fs;
    use tempfile::TempDir;
    use tokensave::context::ContextBuilder;
    use tokensave::db::Database;

    let dir = TempDir::new().unwrap();
    let project = dir.path();

    // Create a source file
    fs::create_dir_all(project.join("src")).unwrap();
    fs::write(project.join("src/lib.rs"), "pub fn process_data() {}\n").unwrap();

    // Init DB and insert a node
    let (db, _) = Database::initialize(&project.join(".tokensave/tokensave.db"))
        .await
        .unwrap();
    let node = Node {
        id: "function:test123".to_string(),
        kind: NodeKind::Function,
        name: "process_data".to_string(),
        qualified_name: "src/lib.rs::process_data".to_string(),
        file_path: "src/lib.rs".to_string(),
        start_line: 1,
        attrs_start_line: 1,
        end_line: 1,
        start_column: 0,
        end_column: 24,
        signature: Some("pub fn process_data()".to_string()),
        docstring: None,
        visibility: Visibility::Pub,
        is_async: false,
        branches: 0,
        loops: 0,
        returns: 0,
        max_nesting: 0,
        unsafe_blocks: 0,
        unchecked_calls: 0,
        assertions: 0,
        cognitive_complexity: 0,
        distinct_operators: 0,
        distinct_operands: 0,
        total_operators: 0,
        total_operands: 0,
        updated_at: 0,
        parent_id: None,
    };
    db.insert_node(&node).await.unwrap();

    let builder = ContextBuilder::new(&db, project);
    let result = builder
        .build_context("process_data", &BuildContextOptions::default())
        .await;
    assert!(result.is_ok());
    let ctx = result.unwrap();
    assert!(!ctx.entry_points.is_empty());
}

#[tokio::test]
async fn test_get_code_reads_source_file() {
    use std::fs;
    use tempfile::TempDir;
    use tokensave::context::ContextBuilder;
    use tokensave::db::Database;

    let dir = TempDir::new().unwrap();
    let project = dir.path();

    fs::create_dir_all(project.join("src")).unwrap();
    fs::write(
        project.join("src/main.rs"),
        "fn main() {\n    println!(\"hello\");\n}\n",
    )
    .unwrap();

    let (db, _) = Database::initialize(&project.join(".tokensave/tokensave.db"))
        .await
        .unwrap();

    let node = Node {
        id: "function:main123".to_string(),
        kind: NodeKind::Function,
        name: "main".to_string(),
        qualified_name: "src/main.rs::main".to_string(),
        file_path: "src/main.rs".to_string(),
        start_line: 1,
        attrs_start_line: 1,
        end_line: 3,
        start_column: 0,
        end_column: 1,
        signature: Some("fn main()".to_string()),
        docstring: None,
        visibility: Visibility::Private,
        is_async: false,
        branches: 0,
        loops: 0,
        returns: 0,
        max_nesting: 0,
        unsafe_blocks: 0,
        unchecked_calls: 0,
        assertions: 0,
        cognitive_complexity: 0,
        distinct_operators: 0,
        distinct_operands: 0,
        total_operators: 0,
        total_operands: 0,
        updated_at: 0,
        parent_id: None,
    };

    let builder = ContextBuilder::new(&db, project);
    let code = builder.get_code(&node).unwrap();
    assert!(code.is_some());
    let content = code.unwrap();
    assert!(content.contains("fn main()"));
    assert!(content.contains("println!"));
}

#[tokio::test]
async fn test_get_code_returns_none_for_missing_file() {
    use tempfile::TempDir;
    use tokensave::context::ContextBuilder;
    use tokensave::db::Database;

    let dir = TempDir::new().unwrap();
    let project = dir.path();

    let (db, _) = Database::initialize(&project.join(".tokensave/tokensave.db"))
        .await
        .unwrap();

    let node = Node {
        id: "function:missing".to_string(),
        kind: NodeKind::Function,
        name: "missing".to_string(),
        qualified_name: "nonexistent.rs::missing".to_string(),
        file_path: "nonexistent.rs".to_string(),
        start_line: 1,
        attrs_start_line: 1,
        end_line: 1,
        start_column: 0,
        end_column: 10,
        signature: None,
        docstring: None,
        visibility: Visibility::Private,
        is_async: false,
        branches: 0,
        loops: 0,
        returns: 0,
        max_nesting: 0,
        unsafe_blocks: 0,
        unchecked_calls: 0,
        assertions: 0,
        cognitive_complexity: 0,
        distinct_operators: 0,
        distinct_operands: 0,
        total_operators: 0,
        total_operands: 0,
        updated_at: 0,
        parent_id: None,
    };

    let builder = ContextBuilder::new(&db, project);
    let code = builder.get_code(&node).unwrap();
    assert!(code.is_none());
}

#[tokio::test]
async fn test_find_relevant_context() {
    use tempfile::TempDir;
    use tokensave::context::ContextBuilder;
    use tokensave::db::Database;

    let dir = TempDir::new().unwrap();
    let project = dir.path();

    let (db, _) = Database::initialize(&project.join(".tokensave/tokensave.db"))
        .await
        .unwrap();
    let node = Node {
        id: "function:ctx_test".to_string(),
        kind: NodeKind::Function,
        name: "compute".to_string(),
        qualified_name: "src/lib.rs::compute".to_string(),
        file_path: "src/lib.rs".to_string(),
        start_line: 1,
        attrs_start_line: 1,
        end_line: 5,
        start_column: 0,
        end_column: 1,
        signature: Some("pub fn compute()".to_string()),
        docstring: None,
        visibility: Visibility::Pub,
        is_async: false,
        branches: 0,
        loops: 0,
        returns: 0,
        max_nesting: 0,
        unsafe_blocks: 0,
        unchecked_calls: 0,
        assertions: 0,
        cognitive_complexity: 0,
        distinct_operators: 0,
        distinct_operands: 0,
        total_operators: 0,
        total_operands: 0,
        updated_at: 0,
        parent_id: None,
    };
    db.insert_node(&node).await.unwrap();

    let builder = ContextBuilder::new(&db, project);
    let subgraph = builder
        .find_relevant_context("compute", &BuildContextOptions::default())
        .await
        .unwrap();
    assert!(!subgraph.nodes.is_empty());
}

#[tokio::test]
async fn test_exclude_node_ids_deduplication() {
    use tempfile::TempDir;
    use tokensave::context::ContextBuilder;
    use tokensave::db::Database;

    let dir = TempDir::new().unwrap();
    let project = dir.path();

    let (db, _) = Database::initialize(&project.join(".tokensave/tokensave.db"))
        .await
        .unwrap();

    for (id, name) in [("fn:first", "compute"), ("fn:second", "compute_batch")] {
        db.insert_node(&Node {
            id: id.to_string(),
            kind: NodeKind::Function,
            name: name.to_string(),
            qualified_name: format!("src/lib.rs::{name}"),
            file_path: "src/lib.rs".to_string(),
            start_line: 1,
            attrs_start_line: 1,
            end_line: 5,
            start_column: 0,
            end_column: 1,
            signature: Some(format!("pub fn {name}()")),
            docstring: None,
            visibility: Visibility::Pub,
            is_async: false,
            branches: 0,
            loops: 0,
            returns: 0,
            max_nesting: 0,
            unsafe_blocks: 0,
            unchecked_calls: 0,
            assertions: 0,
            cognitive_complexity: 0,
            distinct_operators: 0,
            distinct_operands: 0,
            total_operators: 0,
            total_operands: 0,
            updated_at: 0,
            parent_id: None,
        })
        .await
        .unwrap();
    }

    let builder = ContextBuilder::new(&db, project);

    // First call — fn:first should appear
    let opts = BuildContextOptions::default();
    let ctx1 = builder.build_context("compute", &opts).await.unwrap();
    assert!(ctx1.entry_points.iter().any(|n| n.id == "fn:first"));

    // Second call — exclude fn:first
    let opts2 = BuildContextOptions {
        exclude_node_ids: vec!["fn:first".to_string()].into_iter().collect(),
        ..Default::default()
    };
    let ctx2 = builder.build_context("compute", &opts2).await.unwrap();
    assert!(
        !ctx2.entry_points.iter().any(|n| n.id == "fn:first"),
        "excluded node should not appear in second call"
    );
}

#[tokio::test]
async fn test_exact_name_match_wins_max_merge() {
    // Regression for #117: a node that matches BOTH an FTS term (with a tiny
    // BM25 score) and the exact-name lookup must carry the exact-match base
    // score, not the low FTS score it happened to be seen with first.
    use tempfile::TempDir;
    use tokensave::context::ContextBuilder;
    use tokensave::db::Database;

    let dir = TempDir::new().unwrap();
    let project = dir.path();

    let (db, _) = Database::initialize(&project.join(".tokensave/tokensave.db"))
        .await
        .unwrap();

    // Exact-match target: a low-boost node (enum variant, private). Without the
    // exact-match score it would rank dead last after structural re-ranking.
    // Name is camelCase so the query token is extracted as a symbol (a plain
    // lowercase word is not), which is what feeds the exact-name lookup.
    db.insert_node(&Node {
        id: "variant:validate".to_string(),
        kind: NodeKind::EnumVariant,
        name: "validateInput".to_string(),
        qualified_name: "src/lib.rs::Action::validateInput".to_string(),
        file_path: "src/lib.rs".to_string(),
        start_line: 1,
        attrs_start_line: 1,
        end_line: 1,
        start_column: 0,
        end_column: 10,
        signature: Some("validateInput".to_string()),
        docstring: None,
        visibility: Visibility::Private,
        is_async: false,
        branches: 0,
        loops: 0,
        returns: 0,
        max_nesting: 0,
        unsafe_blocks: 0,
        unchecked_calls: 0,
        assertions: 0,
        cognitive_complexity: 0,
        distinct_operators: 0,
        distinct_operands: 0,
        total_operators: 0,
        total_operands: 0,
        updated_at: 0,
        parent_id: None,
    })
    .await
    .unwrap();

    // Competitor: a high-boost node (public function) that only matches the FTS
    // "validate" prefix term, never the exact symbol names. Its structural boost
    // dwarfs the enum variant's, so under the old first-seen bug it ranks first.
    db.insert_node(&Node {
        id: "fn:validate_helper".to_string(),
        kind: NodeKind::Function,
        name: "validateRequest".to_string(),
        qualified_name: "src/lib.rs::validateRequest".to_string(),
        file_path: "src/lib.rs".to_string(),
        start_line: 2,
        attrs_start_line: 2,
        end_line: 6,
        start_column: 0,
        end_column: 1,
        signature: Some("pub fn validateRequest()".to_string()),
        docstring: None,
        visibility: Visibility::Pub,
        is_async: false,
        branches: 0,
        loops: 0,
        returns: 0,
        max_nesting: 0,
        unsafe_blocks: 0,
        unchecked_calls: 0,
        assertions: 0,
        cognitive_complexity: 0,
        distinct_operators: 0,
        distinct_operands: 0,
        total_operators: 0,
        total_operands: 0,
        updated_at: 0,
        parent_id: None,
    })
    .await
    .unwrap();

    let builder = ContextBuilder::new(&db, project);

    // Both nodes match the "validate" FTS term; only validateInput is an exact
    // name match for the query's extracted symbols.
    let ctx = builder
        .build_context("validateInput", &BuildContextOptions::default())
        .await
        .unwrap();

    // The exact-match node must carry the high base score and rank first,
    // despite its much weaker structural boost.
    assert_eq!(
        ctx.entry_points.first().map(|n| n.id.as_str()),
        Some("variant:validate"),
        "exact-name match should rank first via MAX-merge, not be buried by BM25"
    );

    // Excluding the exact-match node must still keep it out entirely.
    let opts_excl = BuildContextOptions {
        exclude_node_ids: vec!["variant:validate".to_string()].into_iter().collect(),
        ..Default::default()
    };
    let ctx_excl = builder
        .build_context("validateInput", &opts_excl)
        .await
        .unwrap();
    assert!(
        !ctx_excl
            .entry_points
            .iter()
            .any(|n| n.id == "variant:validate"),
        "excluded node must not reappear via the exact-name supplement"
    );
}

#[tokio::test]
async fn test_query_ignore_filters_context_entry_points() {
    use tempfile::TempDir;
    use tokensave::config::{load_query_ignore, QueryIgnore};
    use tokensave::context::ContextBuilder;
    use tokensave::db::Database;

    let dir = TempDir::new().unwrap();
    let project = dir.path();

    let (db, _) = Database::initialize(&project.join(".tokensave/tokensave.db"))
        .await
        .unwrap();

    // Two nodes with the same searchable name in different directories.
    for (id, file) in [
        ("fn:src", "src/widget.rs"),
        ("fn:gen", "generated/widget.rs"),
    ] {
        db.insert_node(&Node {
            id: id.to_string(),
            kind: NodeKind::Function,
            name: "widget".to_string(),
            qualified_name: format!("{file}::widget"),
            file_path: file.to_string(),
            start_line: 1,
            attrs_start_line: 1,
            end_line: 5,
            start_column: 0,
            end_column: 1,
            signature: Some("pub fn widget()".to_string()),
            docstring: None,
            visibility: Visibility::Pub,
            is_async: false,
            branches: 0,
            loops: 0,
            returns: 0,
            max_nesting: 0,
            unsafe_blocks: 0,
            unchecked_calls: 0,
            assertions: 0,
            cognitive_complexity: 0,
            distinct_operators: 0,
            distinct_operands: 0,
            total_operators: 0,
            total_operands: 0,
            updated_at: 0,
            parent_id: None,
        })
        .await
        .unwrap();
    }

    let builder = ContextBuilder::new(&db, project);

    // Without an ignore file, both nodes are reachable.
    let opts = BuildContextOptions::default();
    let ctx = builder.build_context("widget", &opts).await.unwrap();
    assert!(ctx.entry_points.iter().any(|n| n.id == "fn:gen"));

    // With a matching queryignore pattern, the generated node is filtered out.
    let ts_dir = project.join(".tokensave");
    std::fs::write(ts_dir.join("queryignore"), "generated\n").unwrap();
    let query_ignore = load_query_ignore(project);
    assert!(!query_ignore.is_empty());

    let opts_ignored = BuildContextOptions {
        query_ignore,
        ..Default::default()
    };
    let ctx_ignored = builder
        .build_context("widget", &opts_ignored)
        .await
        .unwrap();
    assert!(
        !ctx_ignored.entry_points.iter().any(|n| n.id == "fn:gen"),
        "queryignore-matched node should not appear as an entry point"
    );
    assert!(
        ctx_ignored.entry_points.iter().any(|n| n.id == "fn:src"),
        "non-matching node should still appear"
    );

    // Sanity: an empty QueryIgnore matches nothing.
    assert!(!QueryIgnore::default().is_ignored("generated/widget.rs"));
}

#[tokio::test]
async fn test_merge_adjacent_code_blocks() {
    use std::fs;
    use tempfile::TempDir;
    use tokensave::context::ContextBuilder;
    use tokensave::db::Database;

    let dir = TempDir::new().unwrap();
    let project = dir.path();
    fs::create_dir_all(project.join("src")).unwrap();
    fs::write(
        project.join("src/lib.rs"),
        "fn alpha() {}\n\nfn beta() {}\n\nfn gamma() {}\n",
    )
    .unwrap();

    let (db, _) = Database::initialize(&project.join(".tokensave/tokensave.db"))
        .await
        .unwrap();

    // Two adjacent functions in same file
    db.insert_node(&Node {
        id: "fn:alpha".to_string(),
        kind: NodeKind::Function,
        name: "alpha".to_string(),
        qualified_name: "src/lib.rs::alpha".to_string(),
        file_path: "src/lib.rs".to_string(),
        start_line: 1,
        attrs_start_line: 1,
        end_line: 1,
        start_column: 0,
        end_column: 13,
        signature: Some("fn alpha()".to_string()),
        docstring: None,
        visibility: Visibility::Pub,
        is_async: false,
        branches: 0,
        loops: 0,
        returns: 0,
        max_nesting: 0,
        unsafe_blocks: 0,
        unchecked_calls: 0,
        assertions: 0,
        cognitive_complexity: 0,
        distinct_operators: 0,
        distinct_operands: 0,
        total_operators: 0,
        total_operands: 0,
        updated_at: 0,
        parent_id: None,
    })
    .await
    .unwrap();

    db.insert_node(&Node {
        id: "fn:beta".to_string(),
        kind: NodeKind::Function,
        name: "beta".to_string(),
        qualified_name: "src/lib.rs::beta".to_string(),
        file_path: "src/lib.rs".to_string(),
        start_line: 3,
        attrs_start_line: 3,
        end_line: 3,
        start_column: 0,
        end_column: 12,
        signature: Some("fn beta()".to_string()),
        docstring: None,
        visibility: Visibility::Pub,
        is_async: false,
        branches: 0,
        loops: 0,
        returns: 0,
        max_nesting: 0,
        unsafe_blocks: 0,
        unchecked_calls: 0,
        assertions: 0,
        cognitive_complexity: 0,
        distinct_operators: 0,
        distinct_operands: 0,
        total_operators: 0,
        total_operands: 0,
        updated_at: 0,
        parent_id: None,
    })
    .await
    .unwrap();

    let builder = ContextBuilder::new(&db, project);
    let ctx = builder
        .build_context(
            "alpha beta",
            &BuildContextOptions {
                include_code: true,
                merge_adjacent: true,
                max_code_blocks: 10,
                ..Default::default()
            },
        )
        .await
        .unwrap();

    // With merge_adjacent, the two adjacent blocks should merge into one
    assert_eq!(
        ctx.code_blocks.len(),
        1,
        "adjacent blocks should merge into one, got {}",
        ctx.code_blocks.len()
    );
    assert!(ctx.code_blocks[0].content.contains("alpha"));
    assert!(ctx.code_blocks[0].content.contains("beta"));
}

#[tokio::test]
async fn test_entry_points_capped_to_search_limit() {
    // Regression test for #120: when many candidates match, the number of
    // entry points (BFS roots) must be bounded by `search_limit` so each
    // root's traversal budget stays meaningful.
    use std::fs;
    use tempfile::TempDir;
    use tokensave::context::ContextBuilder;
    use tokensave::db::Database;

    let dir = TempDir::new().unwrap();
    let project = dir.path();
    fs::create_dir_all(project.join("src")).unwrap();

    let (db, _) = Database::initialize(&project.join(".tokensave/tokensave.db"))
        .await
        .unwrap();

    // Insert many distinct nodes, each matching a distinct keyword. Each
    // per-keyword FTS search surfaces its node, so the candidate pool greatly
    // exceeds `search_limit`.
    const NUM_NODES: usize = 12;
    let keywords: Vec<String> = (0..NUM_NODES).map(|i| format!("widgetkind{i}")).collect();
    let mut nodes = Vec::new();
    for (i, kw) in keywords.iter().enumerate() {
        nodes.push(Node {
            id: format!("function:{kw}"),
            kind: NodeKind::Function,
            name: kw.clone(),
            qualified_name: format!("src/file{i}.rs::{kw}"),
            file_path: format!("src/file{i}.rs"),
            start_line: 1,
            attrs_start_line: 1,
            end_line: 5,
            start_column: 0,
            end_column: 1,
            signature: Some(format!("pub fn {kw}()")),
            docstring: None,
            visibility: Visibility::Pub,
            is_async: false,
            branches: 0,
            loops: 0,
            returns: 0,
            max_nesting: 0,
            unsafe_blocks: 0,
            unchecked_calls: 0,
            assertions: 0,
            cognitive_complexity: 0,
            distinct_operators: 0,
            distinct_operands: 0,
            total_operators: 0,
            total_operands: 0,
            updated_at: 0,
            parent_id: None,
        });
    }
    db.insert_nodes(&nodes).await.unwrap();

    const SEARCH_LIMIT: usize = 5;
    let opts = BuildContextOptions {
        search_limit: SEARCH_LIMIT,
        max_nodes: 100, // large, so search_limit is the binding cap on roots
        max_per_file: Some(100),
        extra_keywords: keywords.clone(),
        ..Default::default()
    };

    let builder = ContextBuilder::new(&db, project);
    // Query the first keyword; the rest surface via extra_keywords, producing
    // far more candidates than `search_limit`.
    let ctx = builder.build_context(&keywords[0], &opts).await.unwrap();

    assert!(
        ctx.entry_points.len() > 1,
        "expected multiple matching candidates, got {}",
        ctx.entry_points.len()
    );
    assert!(
        ctx.entry_points.len() <= SEARCH_LIMIT,
        "entry points (BFS roots) must be capped to search_limit ({}), got {}",
        SEARCH_LIMIT,
        ctx.entry_points.len()
    );
}