@esneiderbravo/speclaw 0.4.0 → 1.0.0

package/dist/modules/compass/indexer.js

@@ -1,11 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { openDb, clearNeedsReindex } from "./db.js";
+import { openDb, clearNeedsReindex, needsReindex } from "./db.js";
 import { langForPath } from "./languages.js";
 import { extract } from "./extract.js";
 import { getEmbedder, toBlob } from "./embedder.js";
+import { contentHashFor, defaultEmbedText } from "./embed-input.js";
+import { buildDirHashMap } from "./merkle.js";
 import { loadAffectedConfig, isTestPath, inferModule } from "./affected-config.js";
+import { personalizedPageRank, edgeWeightMul } from "./pagerank.js";
 const SKIP_DIRS = new Set([
     ".git",
     "node_modules",
@@ -30,6 +33,8 @@ const MAX_FILE_BYTES = 1_500_000;
 function hashOf(content) {
     return createHash("sha256").update(content).digest("hex");
 }
+const DEFAULT_MAX_CACHE_MB = 256;
+const DEFAULT_RETENTION_DAYS = 30;
 /**
  * Point import edges at a representative node in the imported file so reverse
  * reachability can walk file-level dependencies (not just calls).
@@ -177,73 +182,117 @@ function* walkFiles(root) {
 /**
  * Build or incrementally refresh the index for a project.
  *
- * Walks the project's source files (skipping vendored/build directories and
- * oversized files), and for each file whose content hash changed, re-parses it,
- * replacing its nodes and edges and re-embedding each node. Files whose hash is
- * unchanged are skipped; files that disappeared are pruned. Finally resolves
- * call edges to their target node definitions by name. The whole run executes
- * in a single transaction, rolled back on any error.
+ * Uses a stat prefilter and directory Merkle tree to avoid unnecessary reads,
+ * and an embedding cache keyed by embedder-input hash so renames/moves do not
+ * recompute vectors. The whole run executes in a single transaction.
  *
  * @param projectPath - Absolute path to the project root.
- * @param onProgress - Optional callback invoked once per scanned file.
- * @returns Counts of files, nodes, edges, embeddings, and pruned/unchanged files.
- * @throws Re-throws any error encountered mid-run after rolling back the transaction.
+ * @param onProgressOrOpts - Progress callback (legacy) or {@link BuildIndexOptions}.
  */
-export async function buildIndex(projectPath, onProgress) {
+export async function buildIndex(projectPath, onProgressOrOpts) {
+    const opts = typeof onProgressOrOpts === "function"
+        ? { onProgress: onProgressOrOpts }
+        : (onProgressOrOpts ?? {});
+    const onProgress = opts.onProgress;
+    const prune = Boolean(opts.prune);
+    const maxCacheMB = opts.maxCacheMB ?? DEFAULT_MAX_CACHE_MB;
+    const retentionDays = opts.retentionDays ?? DEFAULT_RETENTION_DAYS;
     const db = openDb(projectPath);
+    const force = Boolean(opts.force) || needsReindex(db);
     const embedder = getEmbedder();
     const stats = {
         files: 0,
         nodes: 0,
         edges: 0,
         embeddings: 0,
+        computed: 0,
+        fromCache: 0,
         unchanged: 0,
+        skippedByStat: 0,
         removed: 0,
+        rootUnchanged: false,
         embedder: embedder.id,
     };
     const cfg = loadAffectedConfig(projectPath);
     const existing = new Map();
-    for (const row of db.prepare("SELECT id, path, hash FROM files").all()) {
-        existing.set(row.path, { id: row.id, hash: row.hash });
+    for (const row of db.prepare("SELECT id, path, hash, mtime_ms, size FROM files").all()) {
+        existing.set(row.path, {
+            id: row.id,
+            hash: row.hash,
+            mtime_ms: row.mtime_ms,
+            size: row.size,
+        });
     }
+    const prevRoot = db.prepare("SELECT hash FROM dir_hashes WHERE path = ''").get();
     const seen = new Set();
-    const insFile = db.prepare("INSERT INTO files(path, hash, lang, is_test, module) VALUES (?, ?, ?, ?, ?)");
-    const updFile = db.prepare("UPDATE files SET hash = ?, lang = ?, is_test = ?, module = ? WHERE id = ?");
+    const fileHashes = new Map();
+    const insFile = db.prepare("INSERT INTO files(path, hash, lang, is_test, module, mtime_ms, size) VALUES (?, ?, ?, ?, ?, ?, ?)");
+    const updFile = db.prepare("UPDATE files SET hash = ?, lang = ?, is_test = ?, module = ?, mtime_ms = ?, size = ? WHERE id = ?");
     const delNodes = db.prepare("DELETE FROM nodes WHERE file_id = ?");
     const delEdges = db.prepare("DELETE FROM edges WHERE src_file_id = ?");
     const delCoverage = db.prepare("DELETE FROM coverage_links WHERE file_path = ?");
-    const insNode = db.prepare(`INSERT INTO nodes(file_id, name, kind, start_line, end_line, start_byte, end_byte, parent_id, signature, body_hash, norm_hash)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const insNode = db.prepare(`INSERT INTO nodes(file_id, name, kind, start_line, end_line, start_byte, end_byte, parent_id, signature, body_hash, norm_hash, content_hash)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
     const insMetrics = db.prepare(`INSERT INTO node_metrics(node_id, loc, max_nesting, branches) VALUES (?, ?, ?, ?)`);
     const insEdge = db.prepare(`INSERT INTO edges(src_node_id, src_file_id, dst_name, kind, line) VALUES (?, ?, ?, ?, ?)`);
     const insCoverage = db.prepare(`INSERT OR REPLACE INTO coverage_links(
        artifact_type, name, revision, kind, file_path, line, node_id, source_type, origin
      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
-    const insEmbed = db.prepare(`INSERT OR REPLACE INTO node_embeddings(node_id, dim, model, vec) VALUES (?, ?, ?, ?)`);
+    const insCache = db.prepare(`INSERT INTO embedding_cache(content_hash, model, dim, vec, created_at, last_seen_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(content_hash, model) DO UPDATE SET last_seen_at = excluded.last_seen_at`);
+    const hasCache = db.prepare(`SELECT 1 AS ok FROM embedding_cache WHERE content_hash = ? AND model = ?`);
+    const insNodeText = db.prepare(`INSERT INTO node_text(node_id, name, subtokens, signature, doc) VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(node_id) DO UPDATE SET
+       name = excluded.name,
+       subtokens = excluded.subtokens,
+       signature = excluded.signature,
+       doc = excluded.doc`);
     const allFiles = [...walkFiles(projectPath)];
     db.exec("BEGIN");
     try {
         let done = 0;
         for (const filePath of allFiles) {
-            const rel = path.relative(projectPath, filePath);
+            const rel = path.relative(projectPath, filePath).split(path.sep).join("/");
             done++;
             if (onProgress)
                 onProgress({ file: rel, done, total: allFiles.length });
             seen.add(rel);
             const lang = langForPath(filePath);
-            let content;
+            let stat;
             try {
-                const stat = fs.statSync(filePath);
+                stat = fs.statSync(filePath);
                 if (stat.size > MAX_FILE_BYTES)
                     continue;
+            }
+            catch {
+                continue;
+            }
+            const prior = existing.get(rel);
+            const mtimeMs = Math.trunc(stat.mtimeMs);
+            const size = stat.size;
+            if (!force &&
+                prior &&
+                prior.mtime_ms != null &&
+                prior.size != null &&
+                prior.mtime_ms === mtimeMs &&
+                prior.size === size) {
+                fileHashes.set(rel, prior.hash);
+                stats.skippedByStat++;
+                stats.unchanged++;
+                continue;
+            }
+            let content;
+            try {
                 content = fs.readFileSync(filePath, "utf8");
             }
             catch {
                 continue;
             }
             const hash = hashOf(content);
-            const prior = existing.get(rel);
-            if (prior && prior.hash === hash) {
+            fileHashes.set(rel, hash);
+            if (!force && prior && prior.hash === hash) {
+                updFile.run(hash, lang.id, isTestPath(rel, cfg.testGlobs) ? 1 : 0, inferModule(rel), mtimeMs, size, prior.id);
                 stats.unchanged++;
                 continue;
             }
@@ -251,28 +300,45 @@ export async function buildIndex(projectPath, onProgress) {
             const isTest = isTestPath(rel, cfg.testGlobs) ? 1 : 0;
             const mod = inferModule(rel);
             if (prior) {
-                updFile.run(hash, lang.id, isTest, mod, prior.id);
+                updFile.run(hash, lang.id, isTest, mod, mtimeMs, size, prior.id);
                 delNodes.run(prior.id);
                 delEdges.run(prior.id);
                 delCoverage.run(rel);
                 fileId = prior.id;
             }
             else {
-                fileId = Number(insFile.run(rel, hash, lang.id, isTest, mod).lastInsertRowid);
+                fileId = Number(insFile.run(rel, hash, lang.id, isTest, mod, mtimeMs, size).lastInsertRowid);
             }
             const { symbols, refs, coverage } = await extract(content, lang);
             const nodeIds = [];
+            const now = Date.now();
+            const touchCache = db.prepare(`UPDATE embedding_cache SET last_seen_at = ? WHERE content_hash = ? AND model = ?`);
             for (const s of symbols) {
                 const parentId = s.parentIndex !== null ? nodeIds[s.parentIndex] : null;
-                const id = Number(insNode.run(fileId, s.name, s.kind, s.startLine, s.endLine, s.startByte, s.endByte, parentId, s.signature, s.bodyHash, s.normHash).lastInsertRowid);
+                const embedText = defaultEmbedText(s.kind, s.name, s.signature);
+                const ch = contentHashFor({
+                    lang: lang.id,
+                    kind: s.kind,
+                    name: s.name,
+                    signature: s.signature,
+                    embedText,
+                });
+                const id = Number(insNode.run(fileId, s.name, s.kind, s.startLine, s.endLine, s.startByte, s.endByte, parentId, s.signature, s.bodyHash, s.normHash, ch).lastInsertRowid);
                 nodeIds.push(id);
                 insMetrics.run(id, s.loc, s.maxNesting, s.branches);
-                // embed the node from its name + signature (cheap, meaningful text)
-                const vec = await embedder.embed(`${s.kind} ${s.name} ${s.signature ?? ""}`);
-                insEmbed.run(id, embedder.dim, embedder.id, toBlob(vec));
+                insNodeText.run(id, s.name, s.subtokens, s.signature ?? "", s.docstring);
+                const hit = hasCache.get(ch, embedder.id);
+                if (hit) {
+                    touchCache.run(now, ch, embedder.id);
+                    stats.fromCache++;
+                }
+                else {
+                    const vec = await embedder.embed(embedText);
+                    insCache.run(ch, embedder.id, embedder.dim, toBlob(vec), now, now);
+                    stats.computed++;
+                }
                 stats.embeddings++;
             }
-            // Prefer a real symbol as import owner when the AST leaves imports file-scoped.
             const fileOwner = nodeIds[0] ?? null;
             for (const r of refs) {
                 let srcId = r.ownerIndex !== null ? nodeIds[r.ownerIndex] : null;
@@ -289,14 +355,25 @@ export async function buildIndex(projectPath, onProgress) {
             stats.files++;
             stats.nodes += symbols.length;
         }
-        // prune files that no longer exist
         for (const [rel, row] of existing) {
             if (!seen.has(rel)) {
                 db.prepare("DELETE FROM files WHERE id = ?").run(row.id);
                 stats.removed++;
             }
+            else if (!fileHashes.has(rel)) {
+                fileHashes.set(rel, row.hash);
+            }
+        }
+        const dirMap = buildDirHashMap(fileHashes);
+        const rootHash = dirMap.get("") ?? "";
+        stats.rootUnchanged = Boolean(prevRoot && prevRoot.hash === rootHash && !force && stats.files === 0);
+        const now = Date.now();
+        db.prepare("DELETE FROM dir_hashes").run();
+        const insDir = db.prepare("INSERT INTO dir_hashes(path, hash, n_files, updated_at) VALUES (?, ?, ?, ?)");
+        for (const [dir, hash] of dirMap) {
+            const nFiles = [...fileHashes.keys()].filter((f) => dir === "" ? true : f === dir || f.startsWith(dir + "/")).length;
+            insDir.run(dir, hash, nFiles, now);
         }
-        // Prefer same-file callees so colliding names across files do not share one id.
         db.exec(`
       UPDATE edges SET dst_node_id = (
         SELECT n.id FROM nodes n
@@ -307,6 +384,18 @@ export async function buildIndex(projectPath, onProgress) {
       WHERE kind = 'call' AND dst_node_id IS NULL
     `);
         resolveImportEdges(db, projectPath);
+        recomputeGlobalPagerank(db);
+        // Touch last_seen for all live content hashes under active model
+        db.prepare(`UPDATE embedding_cache SET last_seen_at = ?
+       WHERE model = ?
+         AND content_hash IN (SELECT content_hash FROM nodes WHERE content_hash IS NOT NULL)`).run(now, embedder.id);
+        if (prune) {
+            const cutoff = now - retentionDays * 24 * 60 * 60 * 1000;
+            db.prepare(`DELETE FROM embedding_cache
+         WHERE last_seen_at < ?
+           AND content_hash NOT IN (SELECT content_hash FROM nodes WHERE content_hash IS NOT NULL)`).run(cutoff);
+        }
+        evictCacheBySize(db, maxCacheMB);
         db.prepare("INSERT INTO meta(key, value) VALUES ('indexed_at', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(new Date().toISOString());
         clearNeedsReindex(db);
         db.exec("COMMIT");
@@ -318,7 +407,6 @@ export async function buildIndex(projectPath, onProgress) {
     finally {
         db.close();
     }
-    // Compact map in committed docs/compass.md (between markers) — zero tool-call cost.
     try {
         const { writeCompactMap } = await import("./map.js");
         writeCompactMap(projectPath);
@@ -328,3 +416,86 @@ export async function buildIndex(projectPath, onProgress) {
     }
     return stats;
 }
+function evictCacheBySize(db, maxCacheMB) {
+    const limitBytes = maxCacheMB * 1024 * 1024;
+    const row = db
+        .prepare("SELECT COALESCE(SUM(LENGTH(vec)), 0) AS bytes FROM embedding_cache")
+        .get();
+    if (row.bytes <= limitBytes)
+        return;
+    const target = Math.floor(limitBytes * 0.8);
+    let bytes = row.bytes;
+    const oldest = db
+        .prepare("SELECT content_hash, model, LENGTH(vec) AS len FROM embedding_cache ORDER BY last_seen_at ASC")
+        .all();
+    const del = db.prepare("DELETE FROM embedding_cache WHERE content_hash = ? AND model = ?");
+    for (const e of oldest) {
+        if (bytes <= target)
+            break;
+        del.run(e.content_hash, e.model);
+        bytes -= e.len;
+    }
+}
+/**
+ * Recompute global (non-personalized) PageRank over the bipartite file↔symbol
+ * graph and replace the `pagerank` table.
+ *
+ * @param db - Open index database.
+ */
+export function recomputeGlobalPagerank(db) {
+    const files = db.prepare("SELECT id, path FROM files").all();
+    const nodes = db.prepare("SELECT id, name, file_id FROM nodes").all();
+    if (nodes.length === 0) {
+        db.exec("DELETE FROM pagerank");
+        return;
+    }
+    // Use negative ids for files so they never collide with node ids.
+    const fileNodeId = (fileId) => -fileId;
+    const nodeIds = [];
+    for (const f of files)
+        nodeIds.push(fileNodeId(f.id));
+    for (const n of nodes)
+        nodeIds.push(n.id);
+    const defCount = new Map();
+    for (const n of nodes)
+        defCount.set(n.name, (defCount.get(n.name) ?? 0) + 1);
+    const refCount = new Map();
+    const callEdges = db
+        .prepare(`SELECT e.src_node_id, e.dst_node_id, e.dst_name, f.path AS src_path
+       FROM edges e
+       JOIN files f ON f.id = e.src_file_id
+       WHERE e.kind = 'call' AND e.src_node_id IS NOT NULL`)
+        .all();
+    for (const e of callEdges) {
+        refCount.set(e.dst_name, (refCount.get(e.dst_name) ?? 0) + 1);
+    }
+    const ctx = {
+        mentionedIdents: new Set(),
+        focusFiles: new Set(),
+        defCount,
+        refCount,
+    };
+    const edges = [];
+    for (const n of nodes) {
+        edges.push({ from: fileNodeId(n.file_id), to: n.id, weight: 1 });
+    }
+    for (const e of callEdges) {
+        if (e.dst_node_id == null)
+            continue;
+        const w = edgeWeightMul(e.dst_name, e.src_path, ctx);
+        edges.push({ from: e.src_node_id, to: e.dst_node_id, weight: w });
+    }
+    const scores = personalizedPageRank(nodeIds, edges, []);
+    db.exec("DELETE FROM pagerank");
+    const ins = db.prepare("INSERT INTO pagerank(node_id, score) VALUES (?, ?)");
+    for (const n of nodes) {
+        ins.run(n.id, scores.get(n.id) ?? 0);
+    }
+}
+/** @internal exported for tests */
+export async function embedSymbol(embedder, lang, kind, name, signature) {
+    const embedText = defaultEmbedText(kind, name, signature);
+    const contentHash = contentHashFor({ lang, kind, name, signature, embedText });
+    const vec = await embedder.embed(embedText);
+    return { contentHash, vec };
+}

package/dist/modules/compass/merkle.js

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+/** Stable hash of an empty directory (or fully excluded contents). */
+export const HASH_EMPTY = createHash("sha256").update("").digest("hex");
+/**
+ * Directory Merkle hash: sha256 of sorted `name\\0childHash\\n` lines.
+ * Sort uses UTF-8 byte order (never localeCompare) for cross-platform stability.
+ *
+ * @param children - Immediate children (files or subdirs) with their hashes.
+ */
+export function dirHash(children) {
+    if (children.length === 0)
+        return HASH_EMPTY;
+    const sorted = [...children].sort((a, b) => Buffer.compare(Buffer.from(a.name, "utf8"), Buffer.from(b.name, "utf8")));
+    const h = createHash("sha256");
+    for (const c of sorted)
+        h.update(`${c.name}\0${c.hash}\n`);
+    return h.digest("hex");
+}
+/**
+ * Rebuild directory hashes bottom-up from relative file paths → content hashes.
+ *
+ * @param fileHashes - Project-relative paths using `/` separators.
+ * @returns Map including every ancestor directory; `""` is the project root.
+ */
+export function buildDirHashMap(fileHashes) {
+    /** dir path → list of direct children {name, hash} (hash filled later for dirs). */
+    const children = new Map();
+    const addChild = (parent, name, hash) => {
+        if (!children.has(parent))
+            children.set(parent, new Map());
+        children.get(parent).set(name, hash);
+    };
+    // Ensure root exists even with zero files
+    if (!children.has(""))
+        children.set("", new Map());
+    for (const [rel, hash] of fileHashes) {
+        const parts = rel.split("/").filter(Boolean);
+        if (parts.length === 0)
+            continue;
+        let parent = "";
+        for (let i = 0; i < parts.length; i++) {
+            const name = parts[i];
+            if (i === parts.length - 1) {
+                addChild(parent, name, hash);
+            }
+            else {
+                const next = parent ? `${parent}/${name}` : name;
+                if (!children.has(next))
+                    children.set(next, new Map());
+                // placeholder — overwritten when we hash the child dir
+                if (!children.get(parent).has(name))
+                    addChild(parent, name, "");
+                parent = next;
+            }
+        }
+    }
+    const hashes = new Map();
+    const dirs = [...children.keys()].sort((a, b) => b.split("/").filter(Boolean).length - a.split("/").filter(Boolean).length);
+    for (const dir of dirs) {
+        const kids = children.get(dir) ?? new Map();
+        const list = [];
+        for (const [name, fileHash] of kids) {
+            const childPath = dir ? `${dir}/${name}` : name;
+            if (children.has(childPath)) {
+                list.push({ name, hash: hashes.get(childPath) ?? HASH_EMPTY });
+            }
+            else {
+                list.push({ name, hash: fileHash });
+            }
+        }
+        hashes.set(dir, dirHash(list));
+    }
+    if (!hashes.has(""))
+        hashes.set("", HASH_EMPTY);
+    return hashes;
+}

package/dist/modules/compass/pagerank.js

@@ -0,0 +1,122 @@
+/**
+ * Personalized PageRank over a bipartite file↔symbol graph (query-time and
+ * global precompute). Pure numeric iteration — callers supply adjacency.
+ */
+/**
+ * Run personalized PageRank.
+ *
+ * @param nodeIds - All node ids in the graph (files and/or symbols).
+ * @param edges - Weighted directed edges.
+ * @param personalize - Focus node ids; empty → uniform over `nodeIds`.
+ * @param opts - Iteration controls.
+ * @returns Map of node id → score (approximately sums to 1).
+ */
+export function personalizedPageRank(nodeIds, edges, personalize = [], opts = {}) {
+    const alpha = opts.alpha ?? 0.85;
+    const maxIter = opts.maxIter ?? 20;
+    const tol = opts.tol ?? 1e-6;
+    const ids = [...new Set(nodeIds)];
+    if (ids.length === 0)
+        return new Map();
+    const index = new Map();
+    ids.forEach((id, i) => index.set(id, i));
+    const n = ids.length;
+    const p = new Float64Array(n);
+    const focus = personalize.filter((id) => index.has(id));
+    if (focus.length === 0) {
+        const u = 1 / n;
+        for (let i = 0; i < n; i++)
+            p[i] = u;
+    }
+    else {
+        const u = 1 / focus.length;
+        for (const id of focus)
+            p[index.get(id)] = u;
+    }
+    const outW = new Float64Array(n);
+    const adj = Array.from({ length: n }, () => []);
+    for (const e of edges) {
+        const fi = index.get(e.from);
+        const ti = index.get(e.to);
+        if (fi === undefined || ti === undefined)
+            continue;
+        const w = Math.max(e.weight, 0);
+        if (w === 0)
+            continue;
+        adj[fi].push({ to: ti, w });
+        outW[fi] += w;
+    }
+    // Self-loop 0.1 for nodes with no outbound mass so they stay in the walk.
+    for (let i = 0; i < n; i++) {
+        if (outW[i] === 0) {
+            adj[i].push({ to: i, w: 0.1 });
+            outW[i] = 0.1;
+        }
+    }
+    let pr = new Float64Array(p);
+    let next = new Float64Array(n);
+    for (let iter = 0; iter < maxIter; iter++) {
+        next.fill(0);
+        let dangling = 0;
+        for (let i = 0; i < n; i++) {
+            if (outW[i] === 0)
+                dangling += pr[i];
+        }
+        for (let i = 0; i < n; i++) {
+            next[i] += (1 - alpha) * p[i];
+            next[i] += alpha * dangling * p[i];
+        }
+        for (let i = 0; i < n; i++) {
+            const ow = outW[i];
+            if (ow === 0)
+                continue;
+            const share = (alpha * pr[i]) / ow;
+            for (const { to, w } of adj[i]) {
+                next[to] += share * w;
+            }
+        }
+        let delta = 0;
+        for (let i = 0; i < n; i++)
+            delta += Math.abs(next[i] - pr[i]);
+        const tmp = pr;
+        pr = next;
+        next = tmp;
+        if (delta < tol)
+            break;
+    }
+    const out = new Map();
+    for (let i = 0; i < n; i++)
+        out.set(ids[i], pr[i]);
+    return out;
+}
+/**
+ * Heuristic: identifiers that look meaningful (camel/snake, length ≥ 8).
+ *
+ * @param name - Symbol name.
+ */
+export function isMeaningfulIdent(name) {
+    if (name.length < 8)
+        return false;
+    return /[a-z][A-Z]/.test(name) || name.includes("_");
+}
+/**
+ * Edge weight multiplier adapted from aider's repo-map heuristics.
+ *
+ * @param dstName - Destination symbol name.
+ * @param srcFilePath - Source file path (for focus ×50).
+ * @param ctx - Ranking context bags.
+ */
+export function edgeWeightMul(dstName, srcFilePath, ctx) {
+    let mul = 1.0;
+    if (ctx.mentionedIdents.has(dstName))
+        mul *= 10;
+    if (isMeaningfulIdent(dstName))
+        mul *= 10;
+    if (dstName.startsWith("_"))
+        mul *= 0.1;
+    if ((ctx.defCount.get(dstName) ?? 0) > 5)
+        mul *= 0.1;
+    if (ctx.focusFiles.has(srcFilePath))
+        mul *= 50;
+    return mul * Math.sqrt(ctx.refCount.get(dstName) ?? 1);
+}

package/dist/modules/compass/rank.js

@@ -0,0 +1,95 @@
+/**
+ * Hybrid retrieval ranking primitives: query routing, RRF fusion, name boost,
+ * and structural rerank multipliers. Pure functions — no I/O.
+ */
+/** Reciprocal Rank Fusion constant (Cormack et al., SIGIR 2009). */
+export const RRF_K = 60;
+/** Max neighbours expanded per hub node during ego-graph growth. */
+export const MAX_DEGREE = 200;
+/**
+ * True when `q` looks like a single identifier (optionally dotted), not prose.
+ *
+ * @param q - Raw user query.
+ */
+export function isSymbolQuery(q) {
+    const t = q.trim();
+    return /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/.test(t) && t.split(/\s+/).length === 1;
+}
+/**
+ * Route list weights from query shape (PL→PL sparse-heavy; NL→PL dense-heavy).
+ *
+ * @param q - Raw user query.
+ */
+export function routeWeights(q) {
+    return isSymbolQuery(q) ? { bm25: 1.0, knn: 0.3, name: 1.0 } : { bm25: 0.7, knn: 1.0, name: 0.5 };
+}
+/**
+ * Reciprocal Rank Fusion over named ranked lists.
+ *
+ * @param lists - Map of list name → ordered node ids (best first).
+ * @param weights - Per-list multipliers (missing → 1).
+ * @param k - RRF constant (default {@link RRF_K}).
+ * @returns Map of node id → fused score (higher is better).
+ */
+export function rrfFuse(lists, weights = {}, k = RRF_K) {
+    const scores = new Map();
+    for (const [name, ranked] of Object.entries(lists)) {
+        const w = weights[name] ?? 1;
+        ranked.forEach((id, i) => {
+            const rank = i + 1;
+            scores.set(id, (scores.get(id) ?? 0) + w / (k + rank));
+        });
+    }
+    return scores;
+}
+/**
+ * Multiplicative name-match boost after RRF.
+ *
+ * @param name - Candidate symbol name.
+ * @param query - Original query string.
+ * @returns Multiplier ≥ 1.
+ */
+export function nameBoost(name, query) {
+    const q = query.trim();
+    if (!q)
+        return 1;
+    let boost = 1;
+    if (name === q)
+        boost += 2.0;
+    else if (name.toLowerCase() === q.toLowerCase())
+        boost += 0.5;
+    if (name.startsWith(q) || name.toLowerCase().startsWith(q.toLowerCase()))
+        boost += 0.25;
+    return boost;
+}
+/**
+ * Structural rerank multiplier (PageRank, churn, hops, kind). Never uses
+ * directory path-distance.
+ *
+ * @param seed - Fused seed score (already includes name boost).
+ * @param s - Structural signals for the candidate.
+ */
+export function structuralScore(seed, s) {
+    const pr = Math.max(s.pagerank, 1e-12);
+    const churn = 1 + Math.log1p(Math.max(0, s.commits30d)) / Math.log(30);
+    const hops = 1 / (1 + Math.max(0, s.hopsToFocus));
+    const kind = s.isDefinition ? 1.0 : 0.4;
+    const testBoost = s.coveredByBrokenTest ? 1.5 : 1.0;
+    return seed * Math.sqrt(pr) * churn * hops * kind * testBoost;
+}
+/**
+ * Escape a free-text query for FTS5 MATCH by quoting each term.
+ *
+ * @param q - Raw user query (may contain AND, quotes, NEAR, *).
+ * @returns Safe MATCH expression, or empty string when no terms remain.
+ */
+export function escapeFtsQuery(q) {
+    const terms = q
+        .trim()
+        .split(/\s+/)
+        .map((t) => t.replace(/"/g, '""'))
+        .filter((t) => t.length > 0);
+    if (terms.length === 0)
+        return "";
+    return terms.map((t) => `"${t}"`).join(" ");
+}