feat(resolver): PR#6 target-aware ambiguity_groups membership

candidate_group_key was the bare callee name, so callers()/reference_impact's
unresolved-group caveat matched by name alone -- an unrelated same-named
symbol in another language/module (e.g. a Python `helper`) could inherit an
overflow-candidate caveat that was never about it (e.g. from an unrelated
Rust `helper` group). Same identity-collapse-to-a-scalar shape as the P0
formal-upgrade bug: the overflow branch already computed the real candidate
set, then discarded everything but its length.

Add ambiguity_group_candidates (group_id, candidate_qn, candidate_path),
thread the real (qualified_name, path) candidate set through
resolve_sites_to_edges instead of Some(t.len()), and switch both consumer
queries to join + match agc.candidate_qn = c.qualified_name instead of the
bare candidate_group_key. CASCADE off the parent row so the existing DELETE
scopes (rebuild_graph, incremental_graph_update) clear members for free.

New test ambiguity_group_membership_is_target_aware_not_bare_name proves the
cross-language non-leak DoD case. callers_reports_unresolved_ambiguity_groups
updated to insert a matching candidate row. Toolsnaps regenerated
(UPDATE_TOOLSNAPS=1) for the two doc-comment-only description changes.

Verified: 1306+400 tests green (calm-core + calm-server, full rebuild from
clean target/), zero regressions. Plan doc updated with Part E execution-ready
specs for PR#6-10 (docs/plans/2026-08-19-evidence-architecture-execution-plan.md).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Your Name

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

@@ -305,6 +305,28 @@ CREATE TABLE IF NOT EXISTS ambiguity_groups (
 CREATE INDEX IF NOT EXISTS idx_ambiguity_groups_call_site ON ambiguity_groups(call_site_id);
 CREATE INDEX IF NOT EXISTS idx_ambiguity_groups_from_path ON ambiguity_groups(from_path);
 
+-- PR#6 (target-aware ambiguity membership): the surviving candidate SET of an
+-- overflow group (too many same-named candidates to trust any single one) used
+-- to be DISCARDED -- only its length survived as ambiguity_groups.candidate_count,
+-- the same identity-collapse-to-a-scalar as the P0 formal-upgrade bug. Persisting
+-- the members lets callers()/reference_impact ask whether THIS symbol (by
+-- qualified_name) is one of the candidates, instead of matching any unrelated
+-- symbol that merely shares the bare name (a Python helper inheriting a Rust
+-- helper group's caveat). candidate_qn is exactly the resolver's target
+-- qualified_name -- same format as symbols.qualified_name / call_edges.to_symbol.
+-- CASCADE off ambiguity_groups(id) so the existing group DELETE scopes (full
+-- sweep in rebuild_graph, from_path-scoped in incremental_graph_update) clear
+-- members for free -- staleness structurally impossible, same lifecycle as parent.
+CREATE TABLE IF NOT EXISTS ambiguity_group_candidates (
+    id             INTEGER PRIMARY KEY AUTOINCREMENT,
+    group_id       INTEGER NOT NULL REFERENCES ambiguity_groups(id) ON DELETE CASCADE,
+    candidate_qn   TEXT NOT NULL,
+    candidate_path TEXT,
+    rank_hint      INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_ambiguity_group_candidates_group ON ambiguity_group_candidates(group_id);
+CREATE INDEX IF NOT EXISTS idx_ambiguity_group_candidates_qn ON ambiguity_group_candidates(candidate_qn);
+
 -- WS7 (evidence reconciliation): a provider (SCIP) proof that CONTRADICTS a
 -- confident static resolution of the SAME call site is a conflict, not a new
 -- target -- inserting it would manufacture a false-confidence edge (fixture I /

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

@@ -1292,12 +1292,21 @@ fn resolve_via_inheritance_closure(
 /// anywhere. `candidate_group_key` is the raw `callee_name` text (not a
 /// resolved qualified name — by definition none of the candidates were
 /// ever picked), so it's a grouping key for "sites stuck on this same
-/// ambiguous name," not an identity.
+/// ambiguous name," not an identity. `candidates` (PR#6) is the real
+/// identity: the actual (qualified_name, path) surviving-candidate SET, so
+/// `callers()`/`reference_impact` can match a queried symbol precisely
+/// instead of via the bare `candidate_group_key` (which let an unrelated
+/// same-named symbol in another language/module inherit this caveat).
 struct AmbiguityGroup {
     call_site_id: i64,
     from_path: String,
     candidate_group_key: String,
     candidate_count: usize,
+    // PR#6: the surviving candidate SET (qualified_name, path) pairs, persisted
+    // so callers()/reference_impact can match by real identity instead of the
+    // bare candidate_group_key above -- see ambiguity_group_candidates in
+    // db/schema.rs for why this kills the cross-language bare-name collision.
+    candidates: Vec<(String, String)>,
     reason: String,
 }
 
@@ -1380,11 +1389,15 @@ fn resolve_sites_to_edges(
     // `candidate_rank = 0` to the preferred (same-dir) subset and `1` to
     // every other surviving candidate, instead of the old behavior of
     // silently discarding them.
+    // PR#6: 4th field now carries the actual overflow candidate SET (not just
+    // its length) so ambiguity_groups can persist real (qualified_name, path)
+    // members instead of only a count -- callers()/reference_impact then match
+    // a queried symbol by identity, not by the group's bare candidate_group_key.
     type CandidateResult = (
         Vec<(String, String)>,
         bool,
         bool,
-        Option<usize>,
+        Option<Vec<(String, String)>>,
         Option<HashSet<(String, String)>>,
     );
     let candidates: Vec<CandidateResult> = sites
@@ -1831,7 +1844,7 @@ fn resolve_sites_to_edges(
                     // this specific case and record it as an ambiguity_groups row
                     // instead of silent zero-edge dropping -- previously
                     // indistinguishable from a genuinely unresolved site.
-                    (Vec::new(), false, false, Some(t.len()), None)
+                    (Vec::new(), false, false, Some(t.clone()), None)
                 }
             },
         )
@@ -1862,12 +1875,13 @@ fn resolve_sites_to_edges(
         (targets, namespace_confirmed, weak_receiver_fallback, overflow_count, preferred_subset),
     ) in sites.iter().zip(candidates.iter())
     {
-        if let Some(candidate_count) = overflow_count {
+        if let Some(overflow_candidates) = overflow_count {
             ambiguity_groups.push(AmbiguityGroup {
                 call_site_id: *call_site_id,
                 from_path: from_path.clone(),
                 candidate_group_key: callee.clone(),
-                candidate_count: *candidate_count,
+                candidate_count: overflow_candidates.len(),
+                candidates: overflow_candidates.clone(),
                 reason: "unscoped_candidates_exceeded_max_callee_candidates".to_string(),
             });
         }
@@ -1935,6 +1949,13 @@ fn insert_ambiguity_groups_batch(
         "INSERT INTO ambiguity_groups (call_site_id, from_path, candidate_group_key, candidate_count, reason) \
          VALUES (?1, ?2, ?3, ?4, ?5)",
     )?;
+    // PR#6: persist the real (qualified_name, path) candidate members alongside
+    // the parent row so callers()/reference_impact can match by identity --
+    // see ambiguity_group_candidates in db/schema.rs.
+    let mut candidate_stmt = tx.prepare(
+        "INSERT INTO ambiguity_group_candidates (group_id, candidate_qn, candidate_path) \
+         VALUES (?1, ?2, ?3)",
+    )?;
     for g in groups {
         stmt.execute(rusqlite::params![
             g.call_site_id,
@@ -1943,6 +1964,10 @@ fn insert_ambiguity_groups_batch(
             g.candidate_count as i64,
             g.reason,
         ])?;
+        let group_id = tx.last_insert_rowid();
+        for (qn, path) in &g.candidates {
+            candidate_stmt.execute(rusqlite::params![group_id, qn, path])?;
+        }
     }
     Ok(())
 }

crates/calm-server/src/__toolsnaps__/callers.snap

@@ -322,7 +322,7 @@
         "$ref": "#/$defs/ConfidenceBreakdown"
       },
       "unresolved_group_count": {
-        "description": "Count of `ambiguity_groups` rows (WS3) whose `candidate_group_key`\nmatches this symbol's bare name — call sites elsewhere that had more\nthan `MAX_CALLEE_CANDIDATES` same-named candidates and so produced\nno edge to ANY of them, this symbol possibly included. Neither\n`direct` nor `ambiguous` above can ever contain these — they are\ninvisible to both. See `Caveat::unresolved_ambiguity_groups`.",
+        "description": "Count of distinct `ambiguity_groups` rows (WS3) whose PERSISTED\ncandidate members (`ambiguity_group_candidates`, PR#6) include this\nsymbol's real `qualified_name` — call sites elsewhere that had more\nthan `MAX_CALLEE_CANDIDATES` same-named candidates, this symbol\ngenuinely among them, and so produced no edge to ANY of them. Target-\naware: an unrelated same-named symbol in another language/module can\nno longer inherit this caveat (pre-PR#6 it matched on bare name).\nNeither `direct` nor `ambiguous` above can ever contain these — they\nare invisible to both. See `Caveat::unresolved_ambiguity_groups`.",
         "type": "integer",
         "format": "uint",
         "minimum": 0

crates/calm-server/src/__toolsnaps__/reference_impact.snap

@@ -262,7 +262,7 @@
         "minimum": 0
       },
       "unresolved_many_count": {
-        "description": "Count of `ambiguity_groups` rows (WS3) whose `candidate_group_key`\nmatches this symbol's bare name — sibling of `review_count`, but for\ncall sites that never became any edge at all (too many same-named\ncandidates), so they cannot appear in `references` alongside the\nother four classifications. See `CallersOutput::unresolved_group_count`.",
+        "description": "Count of distinct `ambiguity_groups` rows (WS3) whose PERSISTED\ncandidate members include this symbol's real `qualified_name` (PR#6,\ntarget-aware) — sibling of `review_count`, but for call sites that\nnever became any edge at all (too many same-named candidates), so\nthey cannot appear in `references` alongside the other four\nclassifications. See `CallersOutput::unresolved_group_count`.",
         "type": "integer",
         "format": "uint",
         "minimum": 0

crates/calm-server/src/tools.rs

@@ -6200,6 +6200,15 @@ mod tests {
                 [],
             )
             .unwrap();
+            // PR#6: persisted member row -- 'a.rs::helper' is genuinely among
+            // the 25 overflow candidates, so callers() must match it by real
+            // qualified_name, not merely by the group's bare candidate_group_key.
+            conn.execute(
+                "INSERT INTO ambiguity_group_candidates (group_id, candidate_qn, candidate_path)
+                 VALUES (1, 'a.rs::helper', 'a.rs')",
+                [],
+            )
+            .unwrap();
         }
         let v = jv(
             server.callers(rmcp::handler::server::wrapper::Parameters(CallersParams {
@@ -6229,6 +6238,89 @@ mod tests {
 
         let _ = std::fs::remove_dir_all(&dir);
     }
+    /// PR#6 (docs/plans/2026-08-19-evidence-architecture-execution-plan.md
+    /// Part E): an unrelated same-named symbol in another language must NOT
+    /// inherit an `ambiguity_groups` caveat that was never about it -- pre-PR#6
+    /// the query matched on the group's bare `candidate_group_key` alone, so a
+    /// Python `helper` overflow group would leak onto an unrelated Rust
+    /// `helper`. Target-aware membership (`ambiguity_group_candidates`,
+    /// matched by real `qualified_name`) must keep the caveat scoped to
+    /// symbols the resolver actually saw as candidates.
+    #[test]
+    fn ambiguity_group_membership_is_target_aware_not_bare_name() {
+        let dir =
+            std::env::temp_dir().join(format!("ci_callers_ambgroup_xlang_{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let server = CalmServer::new(dir.clone(), dir.join("index.db")).unwrap();
+        {
+            let conn = server.db();
+            conn.execute(
+                "INSERT INTO symbols (qualified_name, name, kind, language, path, line_start, line_end, signature, docstring, name_tokens, caller_count, is_hub, is_entry_point)
+                 VALUES ('rust_mod.rs::helper', 'helper', 'function', 'rust', 'rust_mod.rs', 1, 1, 'fn helper()', '', 'helper', 0, 0, 0)",
+                [],
+            )
+            .unwrap();
+            conn.execute(
+                "INSERT INTO symbols (qualified_name, name, kind, language, path, line_start, line_end, signature, docstring, name_tokens, caller_count, is_hub, is_entry_point)
+                 VALUES ('py_mod.py::helper', 'helper', 'function', 'python', 'py_mod.py', 1, 1, 'def helper()', '', 'helper', 0, 0, 0)",
+                [],
+            )
+            .unwrap();
+            conn.execute(
+                "INSERT INTO call_sites (id, from_path, enclosing_qn, callee_name, call_line, identity_version, confidence, edge_kind)
+                 VALUES (1, 'caller.py', 'caller.py::use_it', 'helper', 9, 1, 'ambiguous', 'call')",
+                [],
+            )
+            .unwrap();
+            conn.execute(
+                "INSERT INTO ambiguity_groups (call_site_id, from_path, candidate_group_key, candidate_count, reason)
+                 VALUES (1, 'caller.py', 'helper', 25, 'unscoped_candidates_exceeded_max_callee_candidates')",
+                [],
+            )
+            .unwrap();
+            // The overflow candidate set is entirely Python -- the Rust `helper`
+            // symbol was never a real candidate at this call site, only its
+            // bare name coincides.
+            conn.execute(
+                "INSERT INTO ambiguity_group_candidates (group_id, candidate_qn, candidate_path)
+                 VALUES (1, 'py_mod.py::helper', 'py_mod.py')",
+                [],
+            )
+            .unwrap();
+        }
+        let rust_result = jv(
+            server.callers(rmcp::handler::server::wrapper::Parameters(CallersParams {
+                symbol: "helper".into(),
+                path: Some("rust_mod.rs".into()),
+                line: Some(1),
+                transitive: false,
+                max_depth: None,
+                if_none_match: None,
+            })),
+        );
+        assert_eq!(
+            rust_result["unresolved_group_count"], 0,
+            "the Rust helper was never a member of the Python overflow group -- must not inherit its caveat"
+        );
+
+        let py_result = jv(
+            server.callers(rmcp::handler::server::wrapper::Parameters(CallersParams {
+                symbol: "helper".into(),
+                path: Some("py_mod.py".into()),
+                line: Some(1),
+                transitive: false,
+                max_depth: None,
+                if_none_match: None,
+            })),
+        );
+        assert_eq!(
+            py_result["unresolved_group_count"], 1,
+            "the Python helper genuinely is a persisted member of the overflow group"
+        );
+
+        let _ = std::fs::remove_dir_all(&dir);
+    }
 
     /// WS5 (docs/plans/2026-08-18-context-intelligence-upgrade-plan.md):
     /// `callers()` must sort `ambiguous` by `candidate_rank` so a