sigmap 8.19.0 → 8.21.0

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.19.0 | Benchmark: sigmap-v8.19-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.19-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) | 86.7% (2.02× lift) |
-| Token reduction | — | 96.9% average |
-| Task-success proxy (modeled) | — | 68.9% |
-| Prompts per task | 2.84 | 1.44 (49.2% fewer) |
+| Retrieval hit@5 | 42.7% (single-shot grep) | 85.6% (2.00× lift) |
+| Token reduction | — | 96.8% average |
+| 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 |
@@ -123,6 +123,8 @@ sigmap ask "<query>" --squeeze-threshold N  Min reduction %% to prompt (default
 sigmap evidence "<query>"                Build a deterministic Evidence Pack (JSON) → .context/evidence-pack.json
 sigmap evidence "<query>" --markdown     Emit the Markdown handoff rendering to stdout
 sigmap evidence "<query>" --top <n> --budget <n> --out <path>   Tune ranked files / token budget / write rendered output
+sigmap memory                            List cross-session stores (.context/) — entries, size, age
+sigmap memory --clear <store>            Clear one store: session|notes|weights|evidence|all (--json supported)
 sigmap note "<text>"                     Append a note to the cross-session decision log
 sigmap note                              List recent notes (also: note --list <N>)
 sigmap status                            Show repo state — branch, dirty files, index freshness, notes
@@ -343,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.19.0 | Benchmark: sigmap-v8.19-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.19-main, 2026-07-19)
+## Core metrics (benchmark: sigmap-v8.21-main, 2026-07-19)
 
-- hit@5 retrieval: 86.7% vs 42.7% single-shot grep baseline (2.02× lift)
-- Token reduction: 96.9% average across benchmark repos
-- Task-success proxy: 68.9% (modeled from retrieval tiers, not measured LLM sessions)
-- Prompts per task: 1.44 vs 2.84 baseline (49.2% fewer, modeled)
+- 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: 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.19.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.19.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.19.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/javascript.js

@@ -14,7 +14,12 @@ function extract(src) {
   if (!src || typeof src !== 'string') return [];
   const sigs = [];
   const anchors = [];
+  // docHintFor[i] is the doc-comment hint for sigs[i] (top-level functions
+  // only), appended after the anchor as `  # <hint>` — same convention as the
+  // Python extractor's extractDocHint.
+  const docHintFor = [];
   const returnHints = buildReturnHints(src);
+  const docHints = buildDocHints(src);
 
   // Block comments are blanked newline-by-newline (non-newline chars → spaces)
   // so character offsets AND line numbers stay exact for anchors.
@@ -49,6 +54,7 @@ function extract(src) {
     const retStr = formatReturnHint(returnHints.get(m[1]));
     const startLn = lineAt(stripped, m.index);
     sigs.push(`export ${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
+    docHintFor[sigs.length - 1] = docHints.get(m[1]);
     anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
   }
 
@@ -58,6 +64,7 @@ function extract(src) {
     const retStr = formatReturnHint(returnHints.get(m[1]));
     const startLn = lineAt(stripped, m.index);
     sigs.push(`export const ${m[1]} = ${asyncKw}(${normalizeParams(m[2])}) =>${retStr}`);
+    docHintFor[sigs.length - 1] = docHints.get(m[1]);
     anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
   }
 
@@ -78,10 +85,14 @@ function extract(src) {
     const retStr = formatReturnHint(returnHints.get(m[1]));
     const startLn = lineAt(stripped, m.index);
     sigs.push(`${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
+    docHintFor[sigs.length - 1] = docHints.get(m[1]);
     anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
   }
 
-  const withAnchors = sigs.map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s));
+  const withAnchors = sigs.map((s, i) => {
+    const anchored = anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s;
+    return docHintFor[i] ? `${anchored}  # ${docHintFor[i]}` : anchored;
+  });
   return capWithNotice(withAnchors, 25, 'signatures');
 }
 
@@ -130,6 +141,36 @@ function buildReturnHints(src) {
   return hints;
 }
 
+// First prose sentence of the JSDoc block immediately preceding a top-level
+// function (same three shapes as buildReturnHints). Mirrors the Python
+// extractor's extractDocHint: first sentence only, 60-char cap.
+function buildDocHints(src) {
+  const hints = new Map();
+  // Body may not contain `*/` — otherwise a failed adjacency check would let
+  // the match expand across a whole function to the next comment block and
+  // misattribute the hint.
+  const patterns = [
+    /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/g,
+    /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*export\s+const\s+(\w+)\s*=\s*(?:async\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 JSDoc 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);
+}
+
 function normalizeType(type) {
   if (!type) return '';
   return type.trim().replace(/\s+/g, ' ').slice(0, 25);

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/extractors/typescript.js

@@ -13,6 +13,11 @@ const { capWithNotice, capMembersWithNotice } = require('../util/truncate');
 function extract(src) {
   if (!src || typeof src !== 'string') return [];
   const sigs = [];
+  // docHintFor[i] is the doc-comment hint for sigs[i] (exported top-level
+  // functions only), appended after the anchor as `  # <hint>` — same
+  // convention as the Python extractor's extractDocHint.
+  const docHintFor = [];
+  const docHints = buildDocHints(src);
   // anchors[i] is [start, end] for a top-level sig, or null for an indented member.
   // Kept parallel to `sigs` so existing push/mutation logic stays untouched;
   // anchors are applied once at return.
@@ -80,6 +85,7 @@ function extract(src) {
     const retStr = retType ? ` → ${retType}` : '';
     const bodyStart = m.index + m[0].length;
     sigs.push(`export ${asyncKw}function ${m[1]}(${params})${retStr}`);
+    docHintFor[sigs.length - 1] = docHints.get(m[1]);
     anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
 
     // Hooks: capture compact return object shape for use* functions.
@@ -104,6 +110,7 @@ function extract(src) {
     const asyncKw = /=\s*async\s+/.test(m[0]) ? 'async ' : '';
     const params = normalizeParams(m[2]);
     sigs.push(`export const ${m[1]} = ${asyncKw}(${params}) =>`);
+    docHintFor[sigs.length - 1] = docHints.get(m[1]);
     const bodyStart = stripped.indexOf('{', m.index + m[0].length);
     const endLn = bodyStart !== -1
       ? lineAt(stripped, blockEndIdx(bodyStart + 1))
@@ -153,7 +160,10 @@ function extract(src) {
     }
   }
 
-  const withAnchors = sigs.map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s));
+  const withAnchors = sigs.map((s, i) => {
+    const anchored = anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s;
+    return docHintFor[i] ? `${anchored}  # ${docHintFor[i]}` : anchored;
+  });
   return capWithNotice(withAnchors, 35, 'signatures');
 }
 
@@ -218,4 +228,34 @@ function normalizeParams(params) {
   return params.trim().replace(/\s+/g, ' ').replace(/:[^,)]+/g, '').trim();
 }
 
+// First prose sentence of the JSDoc block immediately preceding an exported
+// top-level function (function or arrow-const form). Mirrors the Python
+// extractor's extractDocHint: first sentence only, 60-char cap.
+function buildDocHints(src) {
+  const hints = new Map();
+  // Body may not contain `*/` — otherwise a failed adjacency check would let
+  // the match expand across a whole function to the next comment block and
+  // misattribute the hint.
+  const patterns = [
+    /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*export\s+(?:async\s+)?function\s+(\w+)\s*[<(]/g,
+    /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*export\s+const\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 JSDoc 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/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.19.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 };