fix(read-tools): dedup derived-edge tables + sharpen search/edit-context precision

Implements the fixes from the 2026-07-28 CALM read-tool self-audit (round-2
meta-audit corrections C1–C5, plus F3–F7). All findings were re-grounded
against .calm/index.db directly before fixing.

C1–C4 — derived-edge duplication (the severe one, ~62% of call_edges were
byte-duplicate rows on a long-lived index):
- Root cause: the SCIP overlay (scip::ingest::insert_missing_edges) re-inserts
  the same formal edge every run — its within-run dedup set keys on the
  target's symbols.line_start while the next run reloads under the SCIP
  def-occurrence line (key-space mismatch), and neither call_edges nor
  import_edges had a UNIQUE constraint. import_edges had an independent
  instance of the same class (extractor emits byte-identical rows).
- Defense-in-depth fix: UNIQUE indexes on both tables
  (call_edges: from_symbol,to_symbol,COALESCE(call_site_line,-1),edge_kind;
  import_edges: from_path,COALESCE(to_path,''),module_name,COALESCE(symbols_used,'[]'))
  make every insert path idempotent; all three production inserts now use
  INSERT OR IGNORE, and insert_missing_edges counts only rows the constraint
  accepted. One-off, guarded cleanup migration collapses pre-existing dups
  (kept MIN(id) per logical edge). Verified on a copy of this repo's real DB:
  call_edges 10412→10126, import_edges 584→551, both unique indexes created.
  Payoff: correct edit_context risk + callers counts (stored caller_count was
  already COUNT(DISTINCT)-protected, so hub/coreness were never affected) and
  large token savings on affected symbols.

C5 — search precision: search_symbol now guarantees exact-whole-name
candidacy (a dedicated idx_symbols_name lookup, since a short exact name like
`path` could fall outside the FTS fetch window entirely) and folds coreness +
a decisive exact-name bonus into ranking, gated behind the existing noise
check. `search("path")` now surfaces the symbol literally named `path` (the
repo's highest-coreness hub) on top instead of PathMatcher/PathCache.
rank_multiplier / rrf_merge_n and their tests are untouched.

F3 — edit_context.blast_radius now confidence-filters `ambiguous` edges,
matching risk_assessment (they were disagreeing on the same response).
F4 — the shared NOT_FOUND caveat now names the stdlib/builtin/third-party
scope boundary and warns that hybrid surfaces usages, not definitions.
F5 — weak_cross_reference_languages gains an indexed_file_count denominator
and suppresses low-match-rate flags below a 10-file sample floor (a handful of
incidental scripts is not a cross-reference-quality signal).
F6 — c/cpp install_hint now explains build/translation-unit coverage, the
real lever on scip-clang match rate (per benchmarks/resolution).
F7 — direct test coverage for the CalmServer::search handler (kind dispatch,
suggested_next DAG, include_tests hard-filter) — previously only the core
algorithm was tested, not the server-layer glue.

Tests: cargo test --workspace green; all-languages+overlays green; clippy
-D warnings clean (default + all-languages); fmt clean; tool schema snapshots
regenerated for the new optional repo_overview/indexing_status field.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Your Name

crates/calm-core/src/analysis/martin.rs

@@ -267,7 +267,9 @@ mod tests {
 
     fn insert_import(conn: &Connection, from_path: &str, to_path: &str) {
         conn.execute(
-            "INSERT INTO import_edges (from_path, to_path, module_name) VALUES (?1, ?2, 'x')",
+            // OR IGNORE mirrors production (indexer::edges): the UNIQUE index
+            // on import_edges makes a duplicate insert a silent no-op.
+            "INSERT OR IGNORE INTO import_edges (from_path, to_path, module_name) VALUES (?1, ?2, 'x')",
             rusqlite::params![from_path, to_path],
         )
         .unwrap();
@@ -334,11 +336,14 @@ mod tests {
         insert_symbol(&conn, "a.rs", "function", "rust", "f");
         insert_symbol(&conn, "b.rs", "function", "rust", "g");
         insert_import(&conn, "a.rs", "b.rs");
-        insert_import(&conn, "a.rs", "b.rs"); // duplicate, as seen in this repo's own table
+        insert_import(&conn, "a.rs", "b.rs"); // duplicate attempt — dropped by the UNIQUE index
 
         let summary = compute_martin_metrics(&conn).unwrap();
         let a = summary.files.iter().find(|f| f.path == "a.rs").unwrap();
-        assert_eq!(a.ce, 1, "DISTINCT must collapse the duplicate edge");
+        // The UNIQUE index on import_edges (2026-07-28) prevents the duplicate
+        // from ever landing; compute_martin_metrics' own COUNT(DISTINCT) is
+        // retained as defense-in-depth. Either way, coupling stays at 1.
+        assert_eq!(a.ce, 1, "duplicate import edge must not inflate coupling");
     }
 
     #[test]

crates/calm-core/src/db/schema.rs

@@ -358,6 +358,72 @@ fn run_migrations(conn: &Connection) -> rusqlite::Result<()> {
     migrate_add_column(conn, "symbols", "arity", "INTEGER")?;
     migrate_fts_add_signature(conn)?;
     migrate_add_project_memory_fts(conn)?;
+    dedup_edges_and_add_unique_indexes(conn)?;
+    Ok(())
+}
+
+/// One-off cleanup + hardening for the two derived-edge tables (`call_edges`,
+/// `import_edges`), added 2026-07-28 after a self-audit found ~62% of
+/// `call_edges` rows on a long-lived index were byte-duplicate copies.
+///
+/// Root cause: the SCIP overlay (`scip::ingest::insert_missing_edges`) is a
+/// separate background pass with no pre-clear, and its within-run dedup set —
+/// keyed on the target's `symbols.line_start` — never matched the *next* run's
+/// reload, keyed on the SCIP def-occurrence line, so every overlay run
+/// re-inserted the same `formal` edge. `import_edges` had an independent
+/// instance of the same class (the per-file extractor can emit byte-identical
+/// rows). Neither table had a UNIQUE constraint to catch it.
+///
+/// Fix is defense-in-depth: a UNIQUE index makes *every* insert path
+/// idempotent regardless of per-path delete discipline (all three production
+/// inserts now use `INSERT OR IGNORE`). This first collapses any pre-existing
+/// duplicates — keeping the lowest `id` per logical edge; the copies are
+/// byte-identical so which survivor is kept is immaterial — then creates the
+/// indexes. Guarded on the (last-created) import index's existence so the
+/// whole-table cleanup scan runs exactly once, on the first open after
+/// upgrade; every later open short-circuits. Re-running is safe either way
+/// (both DELETEs and both `CREATE ... IF NOT EXISTS` are idempotent).
+///
+/// `call_site_line` / `to_path` / `symbols_used` are wrapped in `COALESCE`
+/// because SQLite treats NULLs as *distinct* in a UNIQUE index, which would
+/// otherwise let NULL-keyed duplicates slip past the constraint. The key
+/// deliberately excludes `edge_confidence`/`formal_source`/`ruled_out_by_scip`:
+/// those are attributes the overlay mutates in place on the *same* logical
+/// edge (`from_symbol`,`to_symbol`,`call_site_line`,`edge_kind`), never a
+/// second row.
+fn dedup_edges_and_add_unique_indexes(conn: &Connection) -> rusqlite::Result<()> {
+    let already_hardened: i64 = conn.query_row(
+        "SELECT COUNT(*) FROM sqlite_master \
+         WHERE type = 'index' AND name = 'idx_import_edges_unique'",
+        [],
+        |r| r.get(0),
+    )?;
+    if already_hardened > 0 {
+        return Ok(());
+    }
+
+    // Collapse pre-constraint duplicates, keeping one row per logical edge.
+    conn.execute(
+        "DELETE FROM call_edges WHERE id NOT IN ( \
+            SELECT MIN(id) FROM call_edges \
+            GROUP BY from_symbol, to_symbol, COALESCE(call_site_line, -1), edge_kind)",
+        [],
+    )?;
+    conn.execute(
+        "DELETE FROM import_edges WHERE id NOT IN ( \
+            SELECT MIN(id) FROM import_edges \
+            GROUP BY from_path, COALESCE(to_path, ''), module_name, COALESCE(symbols_used, '[]'))",
+        [],
+    )?;
+
+    // call_edges index first, import index last: the guard above keys on the
+    // import index, so a crash between the two CREATEs re-runs both cleanly.
+    conn.execute_batch(
+        "CREATE UNIQUE INDEX IF NOT EXISTS idx_call_edges_unique \
+             ON call_edges(from_symbol, to_symbol, COALESCE(call_site_line, -1), edge_kind); \
+         CREATE UNIQUE INDEX IF NOT EXISTS idx_import_edges_unique \
+             ON import_edges(from_path, COALESCE(to_path, ''), module_name, COALESCE(symbols_used, '[]'));",
+    )?;
     Ok(())
 }
 
@@ -486,6 +552,96 @@ mod tests {
         assert_eq!(count, 0);
     }
 
+    #[test]
+    fn dedup_migration_collapses_duplicate_edge_rows_and_blocks_new_dups() {
+        // Simulate a pre-hardening DB: base tables exist (SCHEMA_SQL) but the
+        // unique edge indexes / dedup migration have not run yet. This is the
+        // 2026-07-28 self-audit repro (`boundaries.rs::PathMatcher` had 113
+        // duplicate caller rows) reduced to its data-layer essence.
+        let conn = Connection::open_in_memory().unwrap();
+        conn.execute_batch(SCHEMA_SQL).unwrap();
+
+        // Three byte-identical call edges for one logical edge, plus a
+        // genuinely-distinct edge (different to_symbol) that must survive.
+        for _ in 0..3 {
+            conn.execute(
+                "INSERT INTO call_edges (from_symbol, to_symbol, call_site_line, edge_confidence, edge_kind) \
+                 VALUES ('a::f', 'b::g', 10, 'formal', 'call')",
+                [],
+            )
+            .unwrap();
+        }
+        conn.execute(
+            "INSERT INTO call_edges (from_symbol, to_symbol, call_site_line, edge_confidence, edge_kind) \
+             VALUES ('a::f', 'c::h', 10, 'formal', 'call')",
+            [],
+        )
+        .unwrap();
+        // Two byte-identical imports + one distinct (different symbols_used).
+        for _ in 0..2 {
+            conn.execute(
+                "INSERT INTO import_edges (from_path, to_path, module_name, symbols_used) \
+                 VALUES ('x.rs', 'y.rs', 'y', '[\"A\"]')",
+                [],
+            )
+            .unwrap();
+        }
+        conn.execute(
+            "INSERT INTO import_edges (from_path, to_path, module_name, symbols_used) \
+             VALUES ('x.rs', 'y.rs', 'y', '[\"B\"]')",
+            [],
+        )
+        .unwrap();
+
+        dedup_edges_and_add_unique_indexes(&conn).unwrap();
+
+        let call_rows: i64 = conn
+            .query_row("SELECT COUNT(*) FROM call_edges", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(call_rows, 2, "3 identical + 1 distinct call edge -> 2");
+        let import_rows: i64 = conn
+            .query_row("SELECT COUNT(*) FROM import_edges", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(import_rows, 2, "2 identical + 1 distinct import edge -> 2");
+
+        // The constraint now makes further duplicate inserts idempotent, even
+        // at a different confidence (the key excludes edge_confidence).
+        let changed = conn
+            .execute(
+                "INSERT OR IGNORE INTO call_edges (from_symbol, to_symbol, call_site_line, edge_confidence, edge_kind) \
+                 VALUES ('a::f', 'b::g', 10, 'textual', 'call')",
+                [],
+            )
+            .unwrap();
+        assert_eq!(changed, 0, "duplicate (from,to,line,kind) is ignored");
+
+        // NULL call_site_line duplicates are caught too (COALESCE in the key).
+        conn.execute(
+            "INSERT OR IGNORE INTO call_edges (from_symbol, to_symbol, edge_confidence, edge_kind) \
+             VALUES ('a::f', 'd::k', 'textual', 'call')",
+            [],
+        )
+        .unwrap();
+        let null_dup = conn
+            .execute(
+                "INSERT OR IGNORE INTO call_edges (from_symbol, to_symbol, edge_confidence, edge_kind) \
+                 VALUES ('a::f', 'd::k', 'textual', 'call')",
+                [],
+            )
+            .unwrap();
+        assert_eq!(null_dup, 0, "NULL-line duplicate ignored via COALESCE key");
+
+        // Idempotent: re-running the migration is a cheap no-op.
+        dedup_edges_and_add_unique_indexes(&conn).unwrap();
+        let call_rows_final: i64 = conn
+            .query_row("SELECT COUNT(*) FROM call_edges", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(
+            call_rows_final, 3,
+            "2 survivors + 1 new distinct null-line edge"
+        );
+    }
+
     #[test]
     fn migration_adds_boundary_ambiguous_column_defaulting_to_zero() {
         let conn = Connection::open_in_memory().unwrap();

crates/calm-core/src/indexer/edges.rs

@@ -51,8 +51,12 @@ pub fn insert_symbols_batch(tx: &Transaction, symbols: &[ParsedSymbol]) -> rusql
 }
 
 pub fn insert_call_edges_batch(tx: &Transaction, edges: &[CallEdge]) -> rusqlite::Result<()> {
+    // OR IGNORE: the UNIQUE index on call_edges (see db::schema
+    // dedup_edges_and_add_unique_indexes) makes every insert path idempotent,
+    // so a redundant re-insert (e.g. the same edge extracted twice in one
+    // pass) collapses to a no-op instead of a duplicate row.
     let mut stmt = tx.prepare(
-        "INSERT INTO call_edges (from_symbol, to_symbol, call_site_line, edge_confidence, from_path, to_path, edge_kind)
+        "INSERT OR IGNORE INTO call_edges (from_symbol, to_symbol, call_site_line, edge_confidence, from_path, to_path, edge_kind)
          VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)"
     )?;
     for e in edges {
@@ -70,8 +74,10 @@ pub fn insert_call_edges_batch(tx: &Transaction, edges: &[CallEdge]) -> rusqlite
 }
 
 pub fn insert_import_edges_batch(tx: &Transaction, edges: &[ImportEdge]) -> rusqlite::Result<()> {
+    // OR IGNORE: byte-identical import rows collapse via the UNIQUE index
+    // (see db::schema dedup_edges_and_add_unique_indexes).
     let mut stmt = tx.prepare(
-        "INSERT INTO import_edges (from_path, to_path, module_name, symbols_used)
+        "INSERT OR IGNORE INTO import_edges (from_path, to_path, module_name, symbols_used)
          VALUES (?1, ?2, ?3, ?4)",
     )?;
     for e in edges {

crates/calm-core/src/scip/ingest.rs

@@ -327,8 +327,16 @@ fn insert_missing_edges(
     }
 
     let mut inserted = 0usize;
+    // OR IGNORE + the UNIQUE index on call_edges (db::schema
+    // dedup_edges_and_add_unique_indexes) are what actually keep this pass
+    // idempotent across overlay runs. `already_represented` is keyed on the
+    // target's `symbols.line_start` (from the JOIN in `ingest_occurrences`),
+    // but the re-resolved SCIP def-occurrence line often differs from it, so
+    // the in-memory check below can fail to recognize an edge inserted on a
+    // prior run. The constraint backstops that miss: a re-insert becomes a
+    // no-op instead of the duplicate that once inflated caller counts ~19x.
     let mut insert_stmt = conn.prepare(
-        "INSERT INTO call_edges \
+        "INSERT OR IGNORE INTO call_edges \
             (from_symbol, to_symbol, call_site_line, edge_confidence, from_path, to_path, \
              formal_source, ruled_out_by_scip) \
          VALUES (?1, ?2, ?3, 'formal', ?4, ?5, 'scip', 0)",
@@ -345,7 +353,9 @@ fn insert_missing_edges(
             let Some(to_qn) = resolve_unique_symbol_at(conn, def_path, def_line as i64)? else {
                 continue;
             };
-            insert_stmt.execute(rusqlite::params![
+            // Count only rows the constraint actually accepted — an IGNOREd
+            // duplicate returns 0, keeping `inserted`/telemetry honest.
+            let n = insert_stmt.execute(rusqlite::params![
                 enc_qn,
                 to_qn,
                 call_line as i64,
@@ -354,7 +364,7 @@ fn insert_missing_edges(
             ])?;
             already_represented.insert((from_path, call_line, def_path, def_line as i64));
             satisfied_sites.insert((from_path.to_string(), call_line));
-            inserted += 1;
+            inserted += n;
         }
     }
     Ok(inserted)