sigmap 8.20.0 → 8.21.0

package/CHANGELOG.md

@@ -10,6 +10,19 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.21.0] — 2026-07-19
+
+Minor release — **"Semantic Bridge II" (v8.21)**: doc-comment hints reach Go, Rust, and Java, and the import graph gains a principled centrality prior for ranking — flag-gated and measured.
+
+### Added
+- **Go/Rust/Java doc-comment hints (#501, PR #502):** `buildDocHints` in the Go extractor (godoc `//` blocks above top-level `func`/`type`, compiler directives `//go:`/`nolint` skipped), the Rust extractor (`///` blocks above `pub fn`/`struct`/`enum`/`trait` and impl methods, `#[attr]` lines between doc and declaration tolerated), and the Java extractor (Javadoc on type declarations **and** public/protected members; tag-only blocks produce no hint). First prose sentence, 60-char cap, appended after the line anchor as `  # <hint>` — byte-format identical to the Python/JS/TS hints. Hints are mined from the original source since `extract()` strips comments before matching; undocumented signatures are byte-identical to before.
+- **Centrality rank blend (#501, PR #502, opt-in `retrieval.centralityBlend`):** new `src/graph/centrality.js` — zero-dependency power iteration over the forward import graph (damping 0.85, 20 iterations, sorted nodes, dangling mass redistributed; deterministic), max-normalized to (0,1]. `rank()` blends `0.3 × centrality` as a small additive prior onto **positively-scored files only** (`signals.centrality`) — a tie-breaker among matches, never a way to surface non-matches. Wired like `callGraphBoost`: MCP `query_context` + CLI `ask`/`--query`, all non-fatal. New A/B measure gate `scripts/run-centrality-blend-benchmark.mjs` (`npm run benchmark:centrality-blend`).
+
+### Changed
+- **Measured and gated off by default:** the centrality A/B over 90 tasks / 18 repos scored both arms at 77.8% hit@5 (+0 tasks) — non-regressing but neutral on the lexical-favoring corpus, so `retrieval.centralityBlend` ships **off** per the measure gate; the v8.22 hard-split corpus (A3) is the next chance to show a real delta. 11 new integration tests (127 test files).
+
+---
+
 ## [8.20.0] — 2026-07-19
 
 Minor release — **"Semantic Bridge I" (v8.20)**: the JS/TS extractors gain the same doc-comment hints Python has carried for releases, and the cross-session stores get a single inspect/prune surface.

package/README.md

@@ -61,8 +61,8 @@ That map is exactly what agentic grep is worst at: reproducible, auditable conte
 <!--SM:whyMetrics-->
 - **85.6% hit@5** — right file in top 5 results (vs 42.7% single-shot grep baseline — 2.00× lift)
 - **96.8% token reduction** — average across 21 real repos
-- **67.8% task-success proxy** — modeled from retrieval tiers, not measured LLM sessions
-- **1.47 prompts per task** — down from 2.84 (48.4% fewer retries, modeled)
+- **66.7% task-success proxy** — modeled from retrieval tiers, not measured LLM sessions
+- **1.48 prompts per task** — down from 2.84 (48.0% fewer retries, modeled)
 <!--/SM:whyMetrics-->
 - **<!--SM:languages-->33<!--/SM:languages--> languages supported** — TypeScript, Python, Go, Rust, Java, R, and more
 - **No vendor lock-in** — works with any AI assistant or local LLM
@@ -122,13 +122,13 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.20-main (21 repositories, including R language)
+Benchmark : sigmap-v8.21-main (21 repositories, including R language)
 Date      : 2026-07-19
 
 Hit@5          : 85.6%   (grep-agent baseline 42.7%  — 2.00× lift)
 Token reduction: 96.8%   (across 21 repos)
-Prompt reduction : 48.4% (2.84 → 1.47 prompts per task, modeled)
-Task success   : 67.8%   (proxy — modeled from retrieval tiers)
+Prompt reduction : 48.0% (2.84 → 1.48 prompts per task, modeled)
+Task success   : 66.7%   (proxy — modeled from retrieval tiers)
 Repos tested   : 21 (JavaScript, Python, Go, Rust, Java, R, C++, C#, Dart, Swift, Ruby, PHP, Scala, Kotlin, and more)
 ```
 <!--/SM:benchmarkBlock-->

package/gen-context.js

@@ -1533,6 +1533,8 @@ __factories["./src/config/defaults"] = function(module, exports) {
       recencyBoost: 1.5,
       // Boost files call-graph-connected to query matches (opt-in, measure-gated)
       callGraphBoost: false,
+      // Blend import-graph centrality into ranking as a small prior (opt-in, measure-gated)
+      centralityBlend: false,
       // Append route pseudo-signatures to the rankable index (opt-in, measure-gated)
       surfaceEnrichment: false,
     },
@@ -5928,6 +5930,10 @@ __factories["./src/extractors/go"] = function(module, exports) {
   function extract(src) {
     if (!src || typeof src !== 'string') return [];
     const sigs = [];
+    const docHints = buildDocHints(src);
+    // Append the godoc hint after the anchor as `  # <hint>` — same convention
+    // as the Python/JS extractors' doc hints.
+    const hinted = (sig, name) => (docHints.has(name) ? `${sig}  # ${docHints.get(name)}` : sig);
 
     const stripped = src
       .replace(/\/\/.*$/gm, '')
@@ -5939,14 +5945,14 @@ __factories["./src/extractors/go"] = function(module, exports) {
     // Structs
     for (const m of stripped.matchAll(/^type\s+(\w+)\s+struct\s*\{/gm)) {
       const end = blockEndIdx(m.index + m[0].length);
-      sigs.push(withAnchor(`type ${m[1]} struct`, lineAt(stripped, m.index), lineAt(stripped, end)));
+      sigs.push(hinted(withAnchor(`type ${m[1]} struct`, lineAt(stripped, m.index), lineAt(stripped, end)), m[1]));
     }
 
     // Interfaces
     for (const m of stripped.matchAll(/^type\s+(\w+)\s+interface\s*\{/gm)) {
       const bodyStart = m.index + m[0].length;
       const block = extractBlock(stripped, bodyStart);
-      sigs.push(withAnchor(`type ${m[1]} interface`, lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)));
+      sigs.push(hinted(withAnchor(`type ${m[1]} interface`, lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)), m[1]));
       for (const meth of extractInterfaceMethods(block)) {
         sigs.push(withAnchor(`  ${meth.text}`, lineAt(stripped, bodyStart + meth.declIdx), lineAt(stripped, bodyStart + meth.endIdx)));
       }
@@ -5958,7 +5964,7 @@ __factories["./src/extractors/go"] = function(module, exports) {
       const retType = m[4] ? m[4].trim().replace(/\s+/g, ' ') : '';
       const retStr = retType ? ` → ${retType.slice(0, 30)}` : '';
       const end = blockEndIdx(m.index + m[0].length);
-      sigs.push(withAnchor(`func ${receiver}${m[2]}(${normalizeParams(m[3])})${retStr}`, lineAt(stripped, m.index), lineAt(stripped, end)));
+      sigs.push(hinted(withAnchor(`func ${receiver}${m[2]}(${normalizeParams(m[3])})${retStr}`, lineAt(stripped, m.index), lineAt(stripped, end)), m[2]));
     }
 
     return sigs.slice(0, 25);
@@ -5994,6 +6000,30 @@ __factories["./src/extractors/go"] = function(module, exports) {
     return params.trim().replace(/\s+/g, ' ');
   }
 
+  // Godoc: the `//` comment block directly above a top-level func/type/method
+  // declaration → first prose sentence, 60-char cap. Runs on the ORIGINAL src
+  // (extract strips comments before matching). Compiler directives (`//go:...`)
+  // carry no prose and are skipped.
+  function buildDocHints(src) {
+    const hints = new Map();
+    const re = /((?:^\/\/[^\n]*\n)+)(?:func\s+(?:\(\w+\s+[\w*]+\)\s+)?(\w+)\s*\(|type\s+(\w+)\s+(?:struct|interface)\b)/gm;
+    for (const m of src.matchAll(re)) {
+      const name = m[2] || m[3];
+      const hint = firstDocSentence(m[1]);
+      if (hint && !hints.has(name)) hints.set(name, hint);
+    }
+    return hints;
+  }
+
+  // First non-directive prose line of a `//` block → first sentence, 60-char cap.
+  function firstDocSentence(block) {
+    const line = String(block).split('\n')
+      .map((l) => l.replace(/^\/\/\s?/, '').trim())
+      .find((l) => l && !l.startsWith('go:') && !l.startsWith('nolint'));
+    if (!line) return '';
+    return line.split(/[.!?]/)[0].trim().slice(0, 60);
+  }
+
   module.exports = { extract };
   
 };
@@ -6126,6 +6156,10 @@ __factories["./src/extractors/java"] = function(module, exports) {
   function extract(src) {
     if (!src || typeof src !== 'string') return [];
     const sigs = [];
+    const docHints = buildDocHints(src);
+    // Append the Javadoc hint after the anchor as `  # <hint>` — same convention
+    // as the Python/JS extractors' doc hints.
+    const hinted = (sig, name) => (docHints.has(name) ? `${sig}  # ${docHints.get(name)}` : sig);
 
     const stripped = src
       .replace(/\/\/.*$/gm, '')
@@ -6136,9 +6170,9 @@ __factories["./src/extractors/java"] = function(module, exports) {
     for (const m of stripped.matchAll(typeRegex)) {
       const bodyStart = m.index + m[0].length;
       const block = extractBlock(stripped, bodyStart);
-      sigs.push(withAnchor(`${m[1]} ${m[2]}`, lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)));
+      sigs.push(hinted(withAnchor(`${m[1]} ${m[2]}`, lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)), m[2]));
       for (const meth of extractMembers(block)) {
-        sigs.push(withAnchor(`  ${meth.text}`, lineAt(stripped, bodyStart + meth.declIdx), lineAt(stripped, bodyStart + meth.endIdx)));
+        sigs.push(hinted(withAnchor(`  ${meth.text}`, lineAt(stripped, bodyStart + meth.declIdx), lineAt(stripped, bodyStart + meth.endIdx)), meth.name));
       }
     }
 
@@ -6165,6 +6199,7 @@ __factories["./src/extractors/java"] = function(module, exports) {
       const retStr = ret ? ` → ${ret}` : '';
       members.push({
         text: `${m[2]}(${normalizeParams(m[3])})${retStr}`,
+        name: m[2],
         declIdx: m.index + (m[0].length - m[0].trimStart().length),
         endIdx: m.index + m[0].length,
       });
@@ -6182,6 +6217,36 @@ __factories["./src/extractors/java"] = function(module, exports) {
     return type.trim().replace(/\s+/g, ' ').slice(0, 30);
   }
 
+  // Javadoc: the `/** ... */` block directly above a type or public/protected
+  // member declaration → first prose sentence, 60-char cap. Runs on the
+  // ORIGINAL src (extract strips comments before matching). Annotation lines
+  // (`@Override` etc.) between the doc block and the declaration are tolerated.
+  // Body may not contain `*/` so a failed adjacency check can't expand across
+  // code to the next comment block and misattribute the hint.
+  function buildDocHints(src) {
+    const hints = new Map();
+    const patterns = [
+      /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*(?:@\w+(?:\([^)]*\))?\s*)*(?:public\s+|protected\s+)?(?:abstract\s+|final\s+)?(?:class|interface|enum)\s+(\w+)/g,
+      /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*(?:@\w+(?:\([^)]*\))?\s*)*(?:public|protected)\s+(?:static\s+)?(?:final\s+)?(?:synchronized\s+)?(?:<[^>]+>\s+)?[\w<>\[\], ?.]+\s+(\w+)\s*\(/g,
+    ];
+    for (const re of patterns) {
+      for (const m of src.matchAll(re)) {
+        const hint = firstDocSentence(m[1]);
+        if (hint && !hints.has(m[2])) hints.set(m[2], hint);
+      }
+    }
+    return hints;
+  }
+
+  // First non-tag prose line of a Javadoc body → first sentence, 60-char cap.
+  function firstDocSentence(body) {
+    const line = String(body).split('\n')
+      .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+      .find((l) => l && !l.startsWith('@'));
+    if (!line) return '';
+    return line.split(/[.!?]/)[0].trim().slice(0, 60);
+  }
+
   module.exports = { extract };
   
 };
@@ -7680,6 +7745,10 @@ __factories["./src/extractors/rust"] = function(module, exports) {
   function extract(src) {
     if (!src || typeof src !== 'string') return [];
     const sigs = [];
+    const docHints = buildDocHints(src);
+    // Append the doc-comment hint after the anchor as `  # <hint>` — same
+    // convention as the Python/JS extractors' doc hints.
+    const hinted = (sig, name) => (docHints.has(name) ? `${sig}  # ${docHints.get(name)}` : sig);
 
     const stripped = src
       .replace(/\/\/.*$/gm, '')
@@ -7701,19 +7770,19 @@ __factories["./src/extractors/rust"] = function(module, exports) {
     // Structs
     for (const m of stripped.matchAll(/^pub\s+struct\s+(\w+)(?:<[^{]*>)?/gm)) {
       const [s, e] = rangeFor(m.index, m.index + m[0].length);
-      sigs.push(withAnchor(`pub struct ${m[1]}`, s, e));
+      sigs.push(hinted(withAnchor(`pub struct ${m[1]}`, s, e), m[1]));
     }
 
     // Enums
     for (const m of stripped.matchAll(/^pub\s+enum\s+(\w+)(?:<[^{]*>)?/gm)) {
       const [s, e] = rangeFor(m.index, m.index + m[0].length);
-      sigs.push(withAnchor(`pub enum ${m[1]}`, s, e));
+      sigs.push(hinted(withAnchor(`pub enum ${m[1]}`, s, e), m[1]));
     }
 
     // Traits
     for (const m of stripped.matchAll(/^pub\s+trait\s+(\w+)(?:<[^{]*>)?/gm)) {
       const [s, e] = rangeFor(m.index, m.index + m[0].length);
-      sigs.push(withAnchor(`pub trait ${m[1]}`, s, e));
+      sigs.push(hinted(withAnchor(`pub trait ${m[1]}`, s, e), m[1]));
     }
 
     // impl blocks
@@ -7722,7 +7791,7 @@ __factories["./src/extractors/rust"] = function(module, exports) {
       const block = extractBlock(stripped, bodyStart);
       sigs.push(withAnchor(`impl ${m[1]}`, lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)));
       for (const fn of extractMethods(block)) {
-        sigs.push(withAnchor(`  ${fn.text}`, lineAt(stripped, bodyStart + fn.declIdx), lineAt(stripped, bodyStart + fn.endIdx)));
+        sigs.push(hinted(withAnchor(`  ${fn.text}`, lineAt(stripped, bodyStart + fn.declIdx), lineAt(stripped, bodyStart + fn.endIdx)), fn.name));
       }
     }
 
@@ -7731,7 +7800,7 @@ __factories["./src/extractors/rust"] = function(module, exports) {
       const asyncKw = m[0].includes('async') ? 'async ' : '';
       const retStr = extractReturnType(m[3]);
       const [s, e] = rangeFor(m.index, m.index + m[0].length);
-      sigs.push(withAnchor(`pub ${asyncKw}fn ${m[1]}(${normalizeParams(m[2])})${retStr}`, s, e));
+      sigs.push(hinted(withAnchor(`pub ${asyncKw}fn ${m[1]}(${normalizeParams(m[2])})${retStr}`, s, e), m[1]));
     }
 
     return sigs.slice(0, 25);
@@ -7755,6 +7824,7 @@ __factories["./src/extractors/rust"] = function(module, exports) {
       const retStr = extractReturnType(m[3]);
       methods.push({
         text: `pub ${asyncKw}fn ${m[1]}(${normalizeParams(m[2])})${retStr}`,
+        name: m[1],
         declIdx: m.index + (m[0].length - m[0].trimStart().length),
         endIdx: m.index + m[0].length,
       });
@@ -7775,6 +7845,29 @@ __factories["./src/extractors/rust"] = function(module, exports) {
     return ` → ${rt.length > 30 ? rt.slice(0, 27) + '...' : rt}`;
   }
 
+  // Rustdoc: the `///` block directly above a declaration → first prose
+  // sentence, 60-char cap. Runs on the ORIGINAL src (extract strips comments
+  // before matching). Attribute lines (`#[...]`) between the doc block and the
+  // declaration are tolerated.
+  function buildDocHints(src) {
+    const hints = new Map();
+    const re = /((?:^[ \t]*\/\/\/[^\n]*\n)+)(?:[ \t]*#\[[^\n]*\n)*[ \t]*pub(?:\s+async)?\s+(?:fn|struct|enum|trait)\s+(\w+)/gm;
+    for (const m of src.matchAll(re)) {
+      const hint = firstDocSentence(m[1]);
+      if (hint && !hints.has(m[2])) hints.set(m[2], hint);
+    }
+    return hints;
+  }
+
+  // First prose line of a `///` block → first sentence, 60-char cap.
+  function firstDocSentence(block) {
+    const line = String(block).split('\n')
+      .map((l) => l.replace(/^[ \t]*\/\/\/\s?/, '').trim())
+      .find((l) => l);
+    if (!line) return '';
+    return line.split(/[.!?]/)[0].trim().slice(0, 60);
+  }
+
   module.exports = { extract };
   
 };
@@ -11806,6 +11899,71 @@ __factories["./src/graph/call-graph"] = function(module, exports) {
   
 };
 
+// ── ./src/graph/centrality ──
+__factories["./src/graph/centrality"] = function(module, exports) {
+  
+  /**
+   * Zero-dependency import-graph centrality (Semantic Bridge II, B3).
+   *
+   * Power iteration over the forward dependency graph: rank flows from each
+   * importer to the files it imports, so heavily-referenced files accumulate
+   * centrality and one-off helpers do not. Deterministic — fixed damping,
+   * fixed iteration count, nodes processed in sorted order.
+   *
+   * The result feeds the opt-in `retrieval.centralityBlend` ranking prior
+   * (see src/retrieval/ranker.js) — a principled deepening of the existing
+   * graph-boost idea, not a replacement for query relevance.
+   */
+
+  const DAMPING = 0.85;
+  const ITERATIONS = 20;
+
+  /**
+   * Compute a normalized centrality score for every file in a dependency graph.
+   *
+   * @param {{ forward: Map<string, string[]> }} graph - forward dependency graph
+   *        (file → files it imports), as built by src/graph/builder.js
+   * @returns {Map<string, number>} file → centrality in (0, 1], max-normalized;
+   *          empty Map when the graph is missing or empty
+   */
+  function computeCentrality(graph) {
+    if (!graph || !(graph.forward instanceof Map) || graph.forward.size === 0) return new Map();
+
+    const nodes = new Set(graph.forward.keys());
+    for (const deps of graph.forward.values()) {
+      for (const dep of deps || []) nodes.add(dep);
+    }
+    const nodeList = [...nodes].sort();
+    const n = nodeList.length;
+    const indexOf = new Map(nodeList.map((file, i) => [file, i]));
+    const outLinks = nodeList.map((file) =>
+      (graph.forward.get(file) || []).map((dep) => indexOf.get(dep)).filter((i) => i !== undefined));
+
+    let ranks = new Array(n).fill(1 / n);
+    for (let iter = 0; iter < ITERATIONS; iter++) {
+      const next = new Array(n).fill((1 - DAMPING) / n);
+      let dangling = 0;
+      for (let i = 0; i < n; i++) {
+        if (outLinks[i].length === 0) { dangling += ranks[i]; continue; }
+        const share = (DAMPING * ranks[i]) / outLinks[i].length;
+        for (const j of outLinks[i]) next[j] += share;
+      }
+      // Dangling mass (files that import nothing) is redistributed uniformly.
+      const danglingShare = (DAMPING * dangling) / n;
+      for (let i = 0; i < n; i++) next[i] += danglingShare;
+      ranks = next;
+    }
+
+    const max = Math.max(...ranks) || 1;
+    const result = new Map();
+    for (let i = 0; i < n; i++) result.set(nodeList[i], ranks[i] / max);
+    return result;
+  }
+
+  module.exports = { computeCentrality, DAMPING, ITERATIONS };
+  
+};
+
 // ── ./src/graph/impact ──
 __factories["./src/graph/impact"] = function(module, exports) {
   
@@ -13963,8 +14121,9 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
       // Build dependency graph for neighbor boost — non-fatal if it fails
       let graph = null;
       try { graph = buildFromCwd(cwd); } catch (_) {}
-      // Opt-in call-graph neighbor boost + surface enrichment — non-fatal
+      // Opt-in call-graph neighbor boost + surface enrichment + centrality blend — non-fatal
       let callGraph = null;
+      let centrality = null;
       try {
         const { loadConfig } = __require('./src/config/loader');
         const retrieval = loadConfig(cwd).retrieval;
@@ -13974,8 +14133,11 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
         if (retrieval && retrieval.surfaceEnrichment) {
           __require('./src/retrieval/enrich-from-maps').enrichWithSurfaces(index, cwd);
         }
+        if (retrieval && retrieval.centralityBlend && graph) {
+          centrality = __require('./src/graph/centrality').computeCentrality(graph);
+        }
       } catch (_) {}
-      const results = rank(args.query, index, { topK, cwd, graph, callGraph });
+      const results = rank(args.query, index, { topK, cwd, graph, callGraph, centrality });
       return formatRankTable(results, args.query);
     } catch (err) {
       return `_query_context failed: ${err.message}_`;
@@ -14688,7 +14850,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '8.20.0',
+    version: '8.21.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -15818,6 +15980,9 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     callHop: 0.30, // call-graph file neighbor (opt-in retrieval.callGraphBoost)
   };
 
+  // Max additive prior for import-graph centrality (opt-in retrieval.centralityBlend)
+  const CENTRALITY_BLEND_WEIGHT = 0.3;
+
   // Intent-specific weight adjustments
   const INTENT_WEIGHTS = {
     search:     DEFAULT_WEIGHTS,
@@ -15950,6 +16115,8 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
    * @param {{ forward: Map<string,string[]> }} [opts.graph] - dependency graph for neighbor boost
    * @param {{ forward: Map<string,string[]> }} [opts.callGraph] - file-level call-graph edges
    *        (from buildCallFileGraph) for the opt-in call-neighbor boost
+   * @param {Map<string,number>} [opts.centrality] - absolute file → normalized
+   *        centrality (from computeCentrality) for the opt-in centrality blend
    * @returns {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]}
    */
   function rank(query, sigIndex, opts) {
@@ -16098,6 +16265,26 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
       }
     }
 
+    // Centrality blend (opt-in via retrieval.centralityBlend): a small additive
+    // prior from import-graph centrality so heavily-referenced files rank above
+    // one-off helpers on ambiguous queries. Applied only to positively-scored
+    // files — a tie-breaker among matches, never a way to surface non-matches.
+    const centrality = (opts && opts.centrality instanceof Map && opts.centrality.size > 0) ? opts.centrality : null;
+    if (centrality && cwd) {
+      const path = require('path');
+      for (const entry of scored) {
+        if (entry.score <= 0) continue;
+        const abs = path.resolve(cwd, entry.file);
+        // The graph builder lowercases paths (normalizePath) — probe both forms.
+        const c = centrality.get(abs) || centrality.get(abs.toLowerCase());
+        if (c) {
+          const bonus = CENTRALITY_BLEND_WEIGHT * c;
+          entry.score += bonus;
+          entry.signals.centrality = bonus;
+        }
+      }
+    }
+
     // Compute confidence levels based on score distribution
     if (scored.length > 0) {
       const scores = scored.map(s => s.score);
@@ -16373,7 +16560,7 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     return 'search';
   }
 
-  module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, GRAPH_BOOST_AMOUNTS, detectIntent };
+  module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, GRAPH_BOOST_AMOUNTS, CENTRALITY_BLEND_WEIGHT, detectIntent };
   
 };
 
@@ -19881,7 +20068,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '8.20.0';
+const VERSION = '8.21.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -22215,8 +22402,16 @@ function main() {
     if (config && config.retrieval && config.retrieval.surfaceEnrichment) {
       try { requireSourceOrBundled('./src/retrieval/enrich-from-maps').enrichWithSurfaces(sigIndex, cwd); } catch (_) {}
     }
+    // Opt-in import-graph centrality blend (retrieval.centralityBlend) — non-fatal
+    let askCentrality = null;
+    if (config && config.retrieval && config.retrieval.centralityBlend) {
+      try {
+        const askCentralityGraph = requireSourceOrBundled('./src/graph/builder').buildFromCwd(cwd);
+        askCentrality = requireSourceOrBundled('./src/graph/centrality').computeCentrality(askCentralityGraph);
+      } catch (_) {}
+    }
 
-    let ranked = rank(query, sigIndex, { topK: 5, weights: intentWeights, cwd, callGraph: askCallGraph });
+    let ranked = rank(query, sigIndex, { topK: 5, weights: intentWeights, cwd, callGraph: askCallGraph, centrality: askCentrality });
 
     // v6.10: Workspace scoping — infer package from query and apply boost
     const workspaces = detectWorkspaces(cwd);
@@ -24447,7 +24642,15 @@ function main() {
       if (config && config.retrieval && config.retrieval.surfaceEnrichment) {
         try { requireSourceOrBundled('./src/retrieval/enrich-from-maps').enrichWithSurfaces(index, cwd); } catch (_) {}
       }
-      const results = rank(query, index, { topK, recencyBoost, cwd, callGraph: queryCallGraph });
+      // Opt-in import-graph centrality blend (retrieval.centralityBlend) — non-fatal
+      let queryCentrality = null;
+      if (config && config.retrieval && config.retrieval.centralityBlend) {
+        try {
+          const centralityGraph = requireSourceOrBundled('./src/graph/builder').buildFromCwd(cwd);
+          queryCentrality = requireSourceOrBundled('./src/graph/centrality').computeCentrality(centralityGraph);
+        } catch (_) {}
+      }
+      const results = rank(query, index, { topK, recencyBoost, cwd, callGraph: queryCallGraph, centrality: queryCentrality });
       if (args.includes('--context')) {
         const miniCtx  = buildMiniContext(results, cwd);
         const ctxOut   = path.join(cwd, '.context', 'query-context.md');

package/llms-full.txt

@@ -11,20 +11,20 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.20.0 | Benchmark: sigmap-v8.20-main (2026-07-19)
+# Version: 8.21.0 | Benchmark: sigmap-v8.21-main (2026-07-19)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
 ---
 
-## Core metrics (benchmark: sigmap-v8.20-main, 2026-07-19)
+## Core metrics (benchmark: sigmap-v8.21-main, 2026-07-19)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
 | Retrieval hit@5 | 42.7% (single-shot grep) | 85.6% (2.00× lift) |
 | Token reduction | — | 96.8% average |
-| Task-success proxy (modeled) | — | 67.8% |
-| Prompts per task | 2.84 | 1.47 (48.4% fewer) |
+| Task-success proxy (modeled) | — | 66.7% |
+| Prompts per task | 2.84 | 1.48 (48.0% fewer) |
 | Supported languages | — | 33 |
 | MCP tools | — | 20 |
 | npm runtime dependencies | — | 0 |
@@ -345,7 +345,7 @@ testCoverage = false
 testDirs = ["tests","test","__tests__","spec"]
 sigCache = false
 impactRadius = false
-retrieval = {"topK":10,"recencyBoost":1.5,"callGraphBoost":false,"surfaceEnrichment":false}
+retrieval = {"topK":10,"recencyBoost":1.5,"callGraphBoost":false,"centralityBlend":false,"surfaceEnrichment":false}
 impact = {"depth":3,"includeSigs":true}
 ```
 

package/llms.txt

@@ -11,7 +11,7 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.20.0 | Benchmark: sigmap-v8.20-main (2026-07-19)
+# Version: 8.21.0 | Benchmark: sigmap-v8.21-main (2026-07-19)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -23,12 +23,12 @@ Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 - No blast-radius awareness before editing a hub file — `--impact` shows every file a change touches.
 - Pasted stack traces, CI logs, and JSON bloat the prompt — `squeeze` minimizes them and enriches the top frame from the symbol index.
 
-## Core metrics (benchmark: sigmap-v8.20-main, 2026-07-19)
+## Core metrics (benchmark: sigmap-v8.21-main, 2026-07-19)
 
 - hit@5 retrieval: 85.6% vs 42.7% single-shot grep baseline (2.00× lift)
 - Token reduction: 96.8% average across benchmark repos
-- Task-success proxy: 67.8% (modeled from retrieval tiers, not measured LLM sessions)
-- Prompts per task: 1.47 vs 2.84 baseline (48.4% fewer, modeled)
+- Task-success proxy: 66.7% (modeled from retrieval tiers, not measured LLM sessions)
+- Prompts per task: 1.48 vs 2.84 baseline (48.0% fewer, modeled)
 - Languages: 33 supported · MCP tools: 20
 - Dependencies: zero npm runtime dependencies · fully offline
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "8.20.0",
+  "version": "8.21.0",
   "description": "The deterministic, verifiable grounding layer for AI code work — a zero-dependency signature-and-evidence map that grounds Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP agents against your real code (repo + installed libraries) so they stop hallucinating files, imports & APIs. Runs offline via npx; byte-stable output; ~97% token reduction as proof.",
   "main": "packages/core/index.js",
   "exports": {
@@ -31,6 +31,7 @@
     "benchmark:test-discovery": "node scripts/run-test-discovery-benchmark.mjs --save",
     "benchmark:terse": "node scripts/run-terse-benchmark.mjs --save",
     "benchmark:callgraph-boost": "node scripts/run-callgraph-boost-benchmark.mjs --save",
+    "benchmark:centrality-blend": "node scripts/run-centrality-blend-benchmark.mjs --save",
     "benchmark:surface-enrichment": "node scripts/run-surface-enrichment-benchmark.mjs --save",
     "validate:squeeze": "node scripts/run-squeeze-benchmark.mjs --gate",
     "health": "node gen-context.js --health",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "8.20.0",
+  "version": "8.21.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "8.20.0",
+  "version": "8.21.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/config/defaults.js

@@ -149,6 +149,8 @@ const DEFAULTS = {
     recencyBoost: 1.5,
     // Boost files call-graph-connected to query matches (opt-in, measure-gated)
     callGraphBoost: false,
+    // Blend import-graph centrality into ranking as a small prior (opt-in, measure-gated)
+    centralityBlend: false,
     // Append route pseudo-signatures to the rankable index (opt-in, measure-gated)
     surfaceEnrichment: false,
   },

package/src/extractors/go.js

@@ -12,6 +12,10 @@ const { lineAt, withAnchor } = require('./line-anchor');
 function extract(src) {
   if (!src || typeof src !== 'string') return [];
   const sigs = [];
+  const docHints = buildDocHints(src);
+  // Append the godoc hint after the anchor as `  # <hint>` — same convention
+  // as the Python/JS extractors' doc hints.
+  const hinted = (sig, name) => (docHints.has(name) ? `${sig}  # ${docHints.get(name)}` : sig);
 
   const stripped = src
     .replace(/\/\/.*$/gm, '')
@@ -23,14 +27,14 @@ function extract(src) {
   // Structs
   for (const m of stripped.matchAll(/^type\s+(\w+)\s+struct\s*\{/gm)) {
     const end = blockEndIdx(m.index + m[0].length);
-    sigs.push(withAnchor(`type ${m[1]} struct`, lineAt(stripped, m.index), lineAt(stripped, end)));
+    sigs.push(hinted(withAnchor(`type ${m[1]} struct`, lineAt(stripped, m.index), lineAt(stripped, end)), m[1]));
   }
 
   // Interfaces
   for (const m of stripped.matchAll(/^type\s+(\w+)\s+interface\s*\{/gm)) {
     const bodyStart = m.index + m[0].length;
     const block = extractBlock(stripped, bodyStart);
-    sigs.push(withAnchor(`type ${m[1]} interface`, lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)));
+    sigs.push(hinted(withAnchor(`type ${m[1]} interface`, lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)), m[1]));
     for (const meth of extractInterfaceMethods(block)) {
       sigs.push(withAnchor(`  ${meth.text}`, lineAt(stripped, bodyStart + meth.declIdx), lineAt(stripped, bodyStart + meth.endIdx)));
     }
@@ -42,7 +46,7 @@ function extract(src) {
     const retType = m[4] ? m[4].trim().replace(/\s+/g, ' ') : '';
     const retStr = retType ? ` → ${retType.slice(0, 30)}` : '';
     const end = blockEndIdx(m.index + m[0].length);
-    sigs.push(withAnchor(`func ${receiver}${m[2]}(${normalizeParams(m[3])})${retStr}`, lineAt(stripped, m.index), lineAt(stripped, end)));
+    sigs.push(hinted(withAnchor(`func ${receiver}${m[2]}(${normalizeParams(m[3])})${retStr}`, lineAt(stripped, m.index), lineAt(stripped, end)), m[2]));
   }
 
   return sigs.slice(0, 25);
@@ -78,4 +82,28 @@ function normalizeParams(params) {
   return params.trim().replace(/\s+/g, ' ');
 }
 
+// Godoc: the `//` comment block directly above a top-level func/type/method
+// declaration → first prose sentence, 60-char cap. Runs on the ORIGINAL src
+// (extract strips comments before matching). Compiler directives (`//go:...`)
+// carry no prose and are skipped.
+function buildDocHints(src) {
+  const hints = new Map();
+  const re = /((?:^\/\/[^\n]*\n)+)(?:func\s+(?:\(\w+\s+[\w*]+\)\s+)?(\w+)\s*\(|type\s+(\w+)\s+(?:struct|interface)\b)/gm;
+  for (const m of src.matchAll(re)) {
+    const name = m[2] || m[3];
+    const hint = firstDocSentence(m[1]);
+    if (hint && !hints.has(name)) hints.set(name, hint);
+  }
+  return hints;
+}
+
+// First non-directive prose line of a `//` block → first sentence, 60-char cap.
+function firstDocSentence(block) {
+  const line = String(block).split('\n')
+    .map((l) => l.replace(/^\/\/\s?/, '').trim())
+    .find((l) => l && !l.startsWith('go:') && !l.startsWith('nolint'));
+  if (!line) return '';
+  return line.split(/[.!?]/)[0].trim().slice(0, 60);
+}
+
 module.exports = { extract };

package/src/extractors/java.js

@@ -12,6 +12,10 @@ const { lineAt, withAnchor } = require('./line-anchor');
 function extract(src) {
   if (!src || typeof src !== 'string') return [];
   const sigs = [];
+  const docHints = buildDocHints(src);
+  // Append the Javadoc hint after the anchor as `  # <hint>` — same convention
+  // as the Python/JS extractors' doc hints.
+  const hinted = (sig, name) => (docHints.has(name) ? `${sig}  # ${docHints.get(name)}` : sig);
 
   const stripped = src
     .replace(/\/\/.*$/gm, '')
@@ -22,9 +26,9 @@ function extract(src) {
   for (const m of stripped.matchAll(typeRegex)) {
     const bodyStart = m.index + m[0].length;
     const block = extractBlock(stripped, bodyStart);
-    sigs.push(withAnchor(`${m[1]} ${m[2]}`, lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)));
+    sigs.push(hinted(withAnchor(`${m[1]} ${m[2]}`, lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)), m[2]));
     for (const meth of extractMembers(block)) {
-      sigs.push(withAnchor(`  ${meth.text}`, lineAt(stripped, bodyStart + meth.declIdx), lineAt(stripped, bodyStart + meth.endIdx)));
+      sigs.push(hinted(withAnchor(`  ${meth.text}`, lineAt(stripped, bodyStart + meth.declIdx), lineAt(stripped, bodyStart + meth.endIdx)), meth.name));
     }
   }
 
@@ -51,6 +55,7 @@ function extractMembers(block) {
     const retStr = ret ? ` → ${ret}` : '';
     members.push({
       text: `${m[2]}(${normalizeParams(m[3])})${retStr}`,
+      name: m[2],
       declIdx: m.index + (m[0].length - m[0].trimStart().length),
       endIdx: m.index + m[0].length,
     });
@@ -68,4 +73,34 @@ function normalizeType(type) {
   return type.trim().replace(/\s+/g, ' ').slice(0, 30);
 }
 
+// Javadoc: the `/** ... */` block directly above a type or public/protected
+// member declaration → first prose sentence, 60-char cap. Runs on the
+// ORIGINAL src (extract strips comments before matching). Annotation lines
+// (`@Override` etc.) between the doc block and the declaration are tolerated.
+// Body may not contain `*/` so a failed adjacency check can't expand across
+// code to the next comment block and misattribute the hint.
+function buildDocHints(src) {
+  const hints = new Map();
+  const patterns = [
+    /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*(?:@\w+(?:\([^)]*\))?\s*)*(?:public\s+|protected\s+)?(?:abstract\s+|final\s+)?(?:class|interface|enum)\s+(\w+)/g,
+    /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*(?:@\w+(?:\([^)]*\))?\s*)*(?:public|protected)\s+(?:static\s+)?(?:final\s+)?(?:synchronized\s+)?(?:<[^>]+>\s+)?[\w<>\[\], ?.]+\s+(\w+)\s*\(/g,
+  ];
+  for (const re of patterns) {
+    for (const m of src.matchAll(re)) {
+      const hint = firstDocSentence(m[1]);
+      if (hint && !hints.has(m[2])) hints.set(m[2], hint);
+    }
+  }
+  return hints;
+}
+
+// First non-tag prose line of a Javadoc body → first sentence, 60-char cap.
+function firstDocSentence(body) {
+  const line = String(body).split('\n')
+    .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+    .find((l) => l && !l.startsWith('@'));
+  if (!line) return '';
+  return line.split(/[.!?]/)[0].trim().slice(0, 60);
+}
+
 module.exports = { extract };

package/src/extractors/rust.js

@@ -12,6 +12,10 @@ const { lineAt, withAnchor } = require('./line-anchor');
 function extract(src) {
   if (!src || typeof src !== 'string') return [];
   const sigs = [];
+  const docHints = buildDocHints(src);
+  // Append the doc-comment hint after the anchor as `  # <hint>` — same
+  // convention as the Python/JS extractors' doc hints.
+  const hinted = (sig, name) => (docHints.has(name) ? `${sig}  # ${docHints.get(name)}` : sig);
 
   const stripped = src
     .replace(/\/\/.*$/gm, '')
@@ -33,19 +37,19 @@ function extract(src) {
   // Structs
   for (const m of stripped.matchAll(/^pub\s+struct\s+(\w+)(?:<[^{]*>)?/gm)) {
     const [s, e] = rangeFor(m.index, m.index + m[0].length);
-    sigs.push(withAnchor(`pub struct ${m[1]}`, s, e));
+    sigs.push(hinted(withAnchor(`pub struct ${m[1]}`, s, e), m[1]));
   }
 
   // Enums
   for (const m of stripped.matchAll(/^pub\s+enum\s+(\w+)(?:<[^{]*>)?/gm)) {
     const [s, e] = rangeFor(m.index, m.index + m[0].length);
-    sigs.push(withAnchor(`pub enum ${m[1]}`, s, e));
+    sigs.push(hinted(withAnchor(`pub enum ${m[1]}`, s, e), m[1]));
   }
 
   // Traits
   for (const m of stripped.matchAll(/^pub\s+trait\s+(\w+)(?:<[^{]*>)?/gm)) {
     const [s, e] = rangeFor(m.index, m.index + m[0].length);
-    sigs.push(withAnchor(`pub trait ${m[1]}`, s, e));
+    sigs.push(hinted(withAnchor(`pub trait ${m[1]}`, s, e), m[1]));
   }
 
   // impl blocks
@@ -54,7 +58,7 @@ function extract(src) {
     const block = extractBlock(stripped, bodyStart);
     sigs.push(withAnchor(`impl ${m[1]}`, lineAt(stripped, m.index), lineAt(stripped, bodyStart + block.length)));
     for (const fn of extractMethods(block)) {
-      sigs.push(withAnchor(`  ${fn.text}`, lineAt(stripped, bodyStart + fn.declIdx), lineAt(stripped, bodyStart + fn.endIdx)));
+      sigs.push(hinted(withAnchor(`  ${fn.text}`, lineAt(stripped, bodyStart + fn.declIdx), lineAt(stripped, bodyStart + fn.endIdx)), fn.name));
     }
   }
 
@@ -63,7 +67,7 @@ function extract(src) {
     const asyncKw = m[0].includes('async') ? 'async ' : '';
     const retStr = extractReturnType(m[3]);
     const [s, e] = rangeFor(m.index, m.index + m[0].length);
-    sigs.push(withAnchor(`pub ${asyncKw}fn ${m[1]}(${normalizeParams(m[2])})${retStr}`, s, e));
+    sigs.push(hinted(withAnchor(`pub ${asyncKw}fn ${m[1]}(${normalizeParams(m[2])})${retStr}`, s, e), m[1]));
   }
 
   return sigs.slice(0, 25);
@@ -87,6 +91,7 @@ function extractMethods(block) {
     const retStr = extractReturnType(m[3]);
     methods.push({
       text: `pub ${asyncKw}fn ${m[1]}(${normalizeParams(m[2])})${retStr}`,
+      name: m[1],
       declIdx: m.index + (m[0].length - m[0].trimStart().length),
       endIdx: m.index + m[0].length,
     });
@@ -107,4 +112,27 @@ function extractReturnType(afterParen) {
   return ` → ${rt.length > 30 ? rt.slice(0, 27) + '...' : rt}`;
 }
 
+// Rustdoc: the `///` block directly above a declaration → first prose
+// sentence, 60-char cap. Runs on the ORIGINAL src (extract strips comments
+// before matching). Attribute lines (`#[...]`) between the doc block and the
+// declaration are tolerated.
+function buildDocHints(src) {
+  const hints = new Map();
+  const re = /((?:^[ \t]*\/\/\/[^\n]*\n)+)(?:[ \t]*#\[[^\n]*\n)*[ \t]*pub(?:\s+async)?\s+(?:fn|struct|enum|trait)\s+(\w+)/gm;
+  for (const m of src.matchAll(re)) {
+    const hint = firstDocSentence(m[1]);
+    if (hint && !hints.has(m[2])) hints.set(m[2], hint);
+  }
+  return hints;
+}
+
+// First prose line of a `///` block → first sentence, 60-char cap.
+function firstDocSentence(block) {
+  const line = String(block).split('\n')
+    .map((l) => l.replace(/^[ \t]*\/\/\/\s?/, '').trim())
+    .find((l) => l);
+  if (!line) return '';
+  return line.split(/[.!?]/)[0].trim().slice(0, 60);
+}
+
 module.exports = { extract };

package/src/graph/centrality.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * Zero-dependency import-graph centrality (Semantic Bridge II, B3).
+ *
+ * Power iteration over the forward dependency graph: rank flows from each
+ * importer to the files it imports, so heavily-referenced files accumulate
+ * centrality and one-off helpers do not. Deterministic — fixed damping,
+ * fixed iteration count, nodes processed in sorted order.
+ *
+ * The result feeds the opt-in `retrieval.centralityBlend` ranking prior
+ * (see src/retrieval/ranker.js) — a principled deepening of the existing
+ * graph-boost idea, not a replacement for query relevance.
+ */
+
+const DAMPING = 0.85;
+const ITERATIONS = 20;
+
+/**
+ * Compute a normalized centrality score for every file in a dependency graph.
+ *
+ * @param {{ forward: Map<string, string[]> }} graph - forward dependency graph
+ *        (file → files it imports), as built by src/graph/builder.js
+ * @returns {Map<string, number>} file → centrality in (0, 1], max-normalized;
+ *          empty Map when the graph is missing or empty
+ */
+function computeCentrality(graph) {
+  if (!graph || !(graph.forward instanceof Map) || graph.forward.size === 0) return new Map();
+
+  const nodes = new Set(graph.forward.keys());
+  for (const deps of graph.forward.values()) {
+    for (const dep of deps || []) nodes.add(dep);
+  }
+  const nodeList = [...nodes].sort();
+  const n = nodeList.length;
+  const indexOf = new Map(nodeList.map((file, i) => [file, i]));
+  const outLinks = nodeList.map((file) =>
+    (graph.forward.get(file) || []).map((dep) => indexOf.get(dep)).filter((i) => i !== undefined));
+
+  let ranks = new Array(n).fill(1 / n);
+  for (let iter = 0; iter < ITERATIONS; iter++) {
+    const next = new Array(n).fill((1 - DAMPING) / n);
+    let dangling = 0;
+    for (let i = 0; i < n; i++) {
+      if (outLinks[i].length === 0) { dangling += ranks[i]; continue; }
+      const share = (DAMPING * ranks[i]) / outLinks[i].length;
+      for (const j of outLinks[i]) next[j] += share;
+    }
+    // Dangling mass (files that import nothing) is redistributed uniformly.
+    const danglingShare = (DAMPING * dangling) / n;
+    for (let i = 0; i < n; i++) next[i] += danglingShare;
+    ranks = next;
+  }
+
+  const max = Math.max(...ranks) || 1;
+  const result = new Map();
+  for (let i = 0; i < n; i++) result.set(nodeList[i], ranks[i] / max);
+  return result;
+}
+
+module.exports = { computeCentrality, DAMPING, ITERATIONS };

package/src/mcp/handlers.js

@@ -421,8 +421,9 @@ function queryContext(args, cwd) {
     // Build dependency graph for neighbor boost — non-fatal if it fails
     let graph = null;
     try { graph = buildFromCwd(cwd); } catch (_) {}
-    // Opt-in call-graph neighbor boost + surface enrichment — non-fatal
+    // Opt-in call-graph neighbor boost + surface enrichment + centrality blend — non-fatal
     let callGraph = null;
+    let centrality = null;
     try {
       const { loadConfig } = require('../config/loader');
       const retrieval = loadConfig(cwd).retrieval;
@@ -432,8 +433,11 @@ function queryContext(args, cwd) {
       if (retrieval && retrieval.surfaceEnrichment) {
         require('../retrieval/enrich-from-maps').enrichWithSurfaces(index, cwd);
       }
+      if (retrieval && retrieval.centralityBlend && graph) {
+        centrality = require('../graph/centrality').computeCentrality(graph);
+      }
     } catch (_) {}
-    const results = rank(args.query, index, { topK, cwd, graph, callGraph });
+    const results = rank(args.query, index, { topK, cwd, graph, callGraph, centrality });
     return formatRankTable(results, args.query);
   } catch (err) {
     return `_query_context failed: ${err.message}_`;

package/src/mcp/server.js

@@ -18,7 +18,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '8.20.0',
+  version: '8.21.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 

package/src/retrieval/ranker.js

@@ -40,6 +40,9 @@ const GRAPH_BOOST_AMOUNTS = {
   callHop: 0.30, // call-graph file neighbor (opt-in retrieval.callGraphBoost)
 };
 
+// Max additive prior for import-graph centrality (opt-in retrieval.centralityBlend)
+const CENTRALITY_BLEND_WEIGHT = 0.3;
+
 // Intent-specific weight adjustments
 const INTENT_WEIGHTS = {
   search:     DEFAULT_WEIGHTS,
@@ -172,6 +175,8 @@ function scoreFile(filePath, sigs, queryTokens, weights) {
  * @param {{ forward: Map<string,string[]> }} [opts.graph] - dependency graph for neighbor boost
  * @param {{ forward: Map<string,string[]> }} [opts.callGraph] - file-level call-graph edges
  *        (from buildCallFileGraph) for the opt-in call-neighbor boost
+ * @param {Map<string,number>} [opts.centrality] - absolute file → normalized
+ *        centrality (from computeCentrality) for the opt-in centrality blend
  * @returns {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]}
  */
 function rank(query, sigIndex, opts) {
@@ -320,6 +325,26 @@ function rank(query, sigIndex, opts) {
     }
   }
 
+  // Centrality blend (opt-in via retrieval.centralityBlend): a small additive
+  // prior from import-graph centrality so heavily-referenced files rank above
+  // one-off helpers on ambiguous queries. Applied only to positively-scored
+  // files — a tie-breaker among matches, never a way to surface non-matches.
+  const centrality = (opts && opts.centrality instanceof Map && opts.centrality.size > 0) ? opts.centrality : null;
+  if (centrality && cwd) {
+    const path = require('path');
+    for (const entry of scored) {
+      if (entry.score <= 0) continue;
+      const abs = path.resolve(cwd, entry.file);
+      // The graph builder lowercases paths (normalizePath) — probe both forms.
+      const c = centrality.get(abs) || centrality.get(abs.toLowerCase());
+      if (c) {
+        const bonus = CENTRALITY_BLEND_WEIGHT * c;
+        entry.score += bonus;
+        entry.signals.centrality = bonus;
+      }
+    }
+  }
+
   // Compute confidence levels based on score distribution
   if (scored.length > 0) {
     const scores = scored.map(s => s.score);
@@ -595,4 +620,4 @@ function detectIntent(query) {
   return 'search';
 }
 
-module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, GRAPH_BOOST_AMOUNTS, detectIntent };
+module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, GRAPH_BOOST_AMOUNTS, CENTRALITY_BLEND_WEIGHT, detectIntent };