@optave/codegraph 3.11.0 → 3.11.2

package/src/domain/search/generator.ts

@@ -8,6 +8,19 @@ import { embed, getModelConfig } from './models.js';
 import { buildSourceText } from './strategies/source.js';
 import { buildStructuredText } from './strategies/structured.js';
 
+type EmbeddingNode = NodeRow & { id: number };
+type EmbeddingStrategy = 'structured' | 'source';
+
+interface PreparedEmbeddings {
+  texts: string[];
+  nodeIds: number[];
+  nodeNames: string[];
+  previews: string[];
+  overflowCount: number;
+  filesRead: number;
+  filesSkipped: number;
+}
+
 /**
  * Rough token estimate (~4 chars per token for code/English).
  * Conservative — avoids adding a tokenizer dependency.
@@ -47,47 +60,22 @@ function initEmbeddingsSchema(db: BetterSqlite3Database): void {
   `);
 }
 
-export interface BuildEmbeddingsOptions {
-  strategy?: 'structured' | 'source';
-}
-
 /**
- * Build embeddings for all functions/methods/classes in the graph.
+ * Resolve the repo root for embedding. Prefer the root recorded at build time;
+ * fall back to `<dbParent>` only when the DB lives at the conventional
+ * `<root>/.codegraph/graph.db` layout — otherwise trust the caller's rootDir.
  */
-export async function buildEmbeddings(
-  rootDir: string,
-  modelKey: string,
-  customDbPath?: string,
-  options: BuildEmbeddingsOptions = {},
-): Promise<void> {
-  const strategy = options.strategy || 'structured';
-  const dbPath = customDbPath || findDbPath(undefined);
-
-  if (!fs.existsSync(dbPath)) {
-    throw new DbError(
-      `No codegraph database found at ${dbPath}.\nRun "codegraph build" first to analyze your codebase.`,
-      { file: dbPath },
-    );
-  }
-
-  const db = openDb(dbPath) as BetterSqlite3Database;
-  initEmbeddingsSchema(db);
-
-  // Prefer the repo root recorded at build time — embed may be invoked from a
-  // different cwd (e.g. `codegraph embed --db /abs/path/graph.db`) and the
-  // positional rootDir will be wrong in that case. For legacy DBs without
-  // root_dir metadata, fall back to `<dbParent>` only when the DB lives at
-  // the conventional `<root>/.codegraph/graph.db` layout — otherwise trust
-  // the caller-provided rootDir (which may be an explicit positional arg).
-  // `path.dirname(...)` is always non-empty (`'.'` at minimum), so the
-  // conventional-layout check is required to keep the rootDir path reachable.
+function resolveRoot(db: BetterSqlite3Database, dbPath: string, rootDir: string): string {
   const metaRoot = getBuildMeta(db, 'root_dir');
   const resolvedDbPath = path.resolve(dbPath);
   const dbDirName = path.basename(path.dirname(resolvedDbPath));
   const dbParent =
     dbDirName === '.codegraph' ? path.dirname(path.dirname(resolvedDbPath)) : undefined;
-  const resolvedRoot = metaRoot || dbParent || rootDir;
+  return metaRoot || dbParent || rootDir;
+}
 
+/** Reset embedding tables and load eligible symbols grouped by file. */
+function loadNodesByFile(db: BetterSqlite3Database): Map<string, EmbeddingNode[]> {
   db.exec('DELETE FROM embeddings');
   db.exec('DELETE FROM embedding_meta');
   db.exec('DELETE FROM fts_index');
@@ -96,22 +84,52 @@ export async function buildEmbeddings(
     .prepare(
       `SELECT * FROM nodes WHERE kind IN ('function', 'method', 'class') ORDER BY file, line`,
     )
-    .all() as Array<NodeRow & { id: number }>;
+    .all() as EmbeddingNode[];
 
-  console.log(`Building embeddings for ${nodes.length} symbols (strategy: ${strategy})...`);
-
-  const byFile = new Map<string, typeof nodes>();
+  const byFile = new Map<string, EmbeddingNode[]>();
   for (const node of nodes) {
     if (!byFile.has(node.file)) byFile.set(node.file, []);
     byFile.get(node.file)?.push(node);
   }
+  return byFile;
+}
+
+/** Build embedding text for a single node, truncating if it would overflow. */
+function buildNodeText(
+  node: EmbeddingNode,
+  file: string,
+  lines: string[],
+  db: BetterSqlite3Database,
+  strategy: EmbeddingStrategy,
+  contextWindow: number,
+): { text: string; overflowed: boolean } {
+  let text =
+    strategy === 'structured'
+      ? buildStructuredText(node, file, lines, db)
+      : buildSourceText(node, file, lines);
+  const tokens = estimateTokens(text);
+  if (tokens > contextWindow) {
+    text = text.slice(0, contextWindow * 4);
+    return { text, overflowed: true };
+  }
+  return { text, overflowed: false };
+}
 
+/**
+ * Walk files in the graph, read source, and produce parallel arrays of
+ * texts / nodeIds / nodeNames / previews ready for embedding.
+ */
+function prepareEmbeddingTexts(
+  byFile: Map<string, EmbeddingNode[]>,
+  db: BetterSqlite3Database,
+  resolvedRoot: string,
+  strategy: EmbeddingStrategy,
+  contextWindow: number,
+): PreparedEmbeddings {
   const texts: string[] = [];
   const nodeIds: number[] = [];
   const nodeNames: string[] = [];
   const previews: string[] = [];
-  const config = getModelConfig(modelKey);
-  const contextWindow = config.contextWindow;
   let overflowCount = 0;
   let filesRead = 0;
   let filesSkipped = 0;
@@ -129,19 +147,8 @@ export async function buildEmbeddings(
     }
 
     for (const node of fileNodes) {
-      let text =
-        strategy === 'structured'
-          ? buildStructuredText(node, file, lines, db)
-          : buildSourceText(node, file, lines);
-
-      // Detect and handle context window overflow
-      const tokens = estimateTokens(text);
-      if (tokens > contextWindow) {
-        overflowCount++;
-        const maxChars = contextWindow * 4;
-        text = text.slice(0, maxChars);
-      }
-
+      const { text, overflowed } = buildNodeText(node, file, lines, db, strategy, contextWindow);
+      if (overflowed) overflowCount++;
       texts.push(text);
       nodeIds.push(node.id);
       nodeNames.push(node.name);
@@ -149,28 +156,19 @@ export async function buildEmbeddings(
     }
   }
 
-  if (overflowCount > 0) {
-    warn(
-      `${overflowCount} symbol(s) exceeded model context window (${contextWindow} tokens) and were truncated`,
-    );
-  }
-
-  // If there were symbols to embed but every file failed to read, the DB was
-  // almost certainly built from a different location than the current cwd.
-  // Surface this clearly instead of emitting a silent "Stored 0 embeddings".
-  if (byFile.size > 0 && filesRead === 0) {
-    closeDb(db);
-    throw new DbError(
-      `embed: could not read any of the ${filesSkipped} source files recorded in the graph — the DB may have been built from a different location than the current working directory.\n` +
-        `Tried resolving against: ${resolvedRoot}\n` +
-        'Pass a positional <dir> argument pointing at the original repo root, or re-run "codegraph build" from that directory.',
-      { file: dbPath },
-    );
-  }
-
-  console.log(`Embedding ${texts.length} symbols...`);
-  const { vectors, dim } = await embed(texts, modelKey);
+  return { texts, nodeIds, nodeNames, previews, overflowCount, filesRead, filesSkipped };
+}
 
+/** Persist vectors, FTS rows, and embedding metadata in a single transaction. */
+function persistEmbeddings(
+  db: BetterSqlite3Database,
+  prepared: PreparedEmbeddings,
+  vectors: Float32Array[],
+  dim: number,
+  modelName: string,
+  strategy: EmbeddingStrategy,
+): void {
+  const { nodeIds, nodeNames, previews, texts, overflowCount } = prepared;
   const insert = db.prepare(
     'INSERT OR REPLACE INTO embeddings (node_id, vector, text_preview, full_text) VALUES (?, ?, ?, ?)',
   );
@@ -182,7 +180,7 @@ export async function buildEmbeddings(
       insert.run(nodeIds[i], Buffer.from(vec.buffer), previews[i], texts[i]);
       insertFts.run(nodeIds[i], nodeNames[i], texts[i]);
     }
-    insertMeta.run('model', config.name);
+    insertMeta.run('model', modelName);
     insertMeta.run('dim', String(dim));
     insertMeta.run('count', String(vectors.length));
     insertMeta.run('fts_count', String(vectors.length));
@@ -193,6 +191,66 @@ export async function buildEmbeddings(
     }
   });
   insertAll();
+}
+
+export interface BuildEmbeddingsOptions {
+  strategy?: EmbeddingStrategy;
+}
+
+/**
+ * Build embeddings for all functions/methods/classes in the graph.
+ */
+export async function buildEmbeddings(
+  rootDir: string,
+  modelKey: string,
+  customDbPath?: string,
+  options: BuildEmbeddingsOptions = {},
+): Promise<void> {
+  const strategy = options.strategy || 'structured';
+  const dbPath = customDbPath || findDbPath(undefined);
+
+  if (!fs.existsSync(dbPath)) {
+    throw new DbError(
+      `No codegraph database found at ${dbPath}.\nRun "codegraph build" first to analyze your codebase.`,
+      { file: dbPath },
+    );
+  }
+
+  const db = openDb(dbPath) as BetterSqlite3Database;
+  initEmbeddingsSchema(db);
+
+  const resolvedRoot = resolveRoot(db, dbPath, rootDir);
+  const byFile = loadNodesByFile(db);
+
+  const nodeCount = [...byFile.values()].reduce((acc, list) => acc + list.length, 0);
+  console.log(`Building embeddings for ${nodeCount} symbols (strategy: ${strategy})...`);
+
+  const config = getModelConfig(modelKey);
+  const prepared = prepareEmbeddingTexts(byFile, db, resolvedRoot, strategy, config.contextWindow);
+
+  if (prepared.overflowCount > 0) {
+    warn(
+      `${prepared.overflowCount} symbol(s) exceeded model context window (${config.contextWindow} tokens) and were truncated`,
+    );
+  }
+
+  // If there were symbols to embed but every file failed to read, the DB was
+  // almost certainly built from a different location than the current cwd.
+  // Surface this clearly instead of emitting a silent "Stored 0 embeddings".
+  if (byFile.size > 0 && prepared.filesRead === 0) {
+    closeDb(db);
+    throw new DbError(
+      `embed: could not read any of the ${prepared.filesSkipped} source files recorded in the graph — the DB may have been built from a different location than the current working directory.\n` +
+        `Tried resolving against: ${resolvedRoot}\n` +
+        'Pass a positional <dir> argument pointing at the original repo root, or re-run "codegraph build" from that directory.',
+      { file: dbPath },
+    );
+  }
+
+  console.log(`Embedding ${prepared.texts.length} symbols...`);
+  const { vectors, dim } = await embed(prepared.texts, modelKey);
+
+  persistEmbeddings(db, prepared, vectors as Float32Array[], dim, config.name, strategy);
 
   console.log(
     `\nStored ${vectors.length} embeddings (${dim}d, ${config.name}, strategy: ${strategy}) in graph.db`,

package/src/domain/search/models.ts

@@ -41,6 +41,8 @@ export interface ModelConfig {
   contextWindow: number;
   desc: string;
   quantized: boolean;
+  /** Pooling strategy passed to the transformers pipeline. Defaults to 'mean'. */
+  pooling?: 'mean' | 'cls';
 }
 
 // Lazy-load transformers (heavy, optional module)
@@ -91,7 +93,7 @@ export const MODELS: Record<string, ModelConfig> = {
     name: 'nomic-ai/nomic-embed-text-v1.5',
     dim: 768,
     contextWindow: 8192,
-    desc: 'Improved nomic (~137MB). Matryoshka dimensions, 8192 context.',
+    desc: 'Matryoshka MRL trained (~137MB). 8192 context. Codegraph stores full 768d (no truncation); v1 scores higher on our benchmark.',
     quantized: false,
   },
   'bge-large': {
@@ -101,11 +103,41 @@ export const MODELS: Record<string, ModelConfig> = {
     desc: 'Best general retrieval (~335MB). Top MTEB scores.',
     quantized: false,
   },
+  'mxbai-xsmall': {
+    name: 'mixedbread-ai/mxbai-embed-xsmall-v1',
+    dim: 384,
+    contextWindow: 4096,
+    desc: 'Tiny model with long context (~50MB). 4096 ctx.',
+    quantized: false,
+    pooling: 'cls',
+  },
+  'mxbai-large': {
+    name: 'mixedbread-ai/mxbai-embed-large-v1',
+    dim: 1024,
+    contextWindow: 512,
+    desc: 'Top MTEB BERT-large, Matryoshka dimensions (~400MB). 512 ctx.',
+    quantized: false,
+    pooling: 'cls',
+  },
+  'bge-m3': {
+    name: 'Xenova/bge-m3',
+    dim: 1024,
+    contextWindow: 8192,
+    desc: 'Multilingual, multi-task (~600MB). 100+ languages, 8192 context.',
+    quantized: false,
+  },
+  modernbert: {
+    name: 'nomic-ai/modernbert-embed-base',
+    dim: 768,
+    contextWindow: 8192,
+    desc: 'ModernBERT base (~150MB). Newer architecture, 8192 ctx, English.',
+    quantized: false,
+  },
 };
 
 export const EMBEDDING_STRATEGIES: readonly string[] = ['structured', 'source'];
 
-export const DEFAULT_MODEL: string = 'nomic-v1.5';
+export const DEFAULT_MODEL: string = 'nomic';
 const NPM_BIN = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 const BATCH_SIZE_MAP: Record<string, number> = {
   minilm: 32,
@@ -115,6 +147,10 @@ const BATCH_SIZE_MAP: Record<string, number> = {
   nomic: 8,
   'nomic-v1.5': 8,
   'bge-large': 4,
+  'mxbai-xsmall': 32,
+  'mxbai-large': 4,
+  'bge-m3': 4,
+  modernbert: 8,
 };
 const DEFAULT_BATCH_SIZE = 32;
 
@@ -274,7 +310,7 @@ export async function embed(
     const batch = texts.slice(i, i + batchSize);
     const output =
       (await // biome-ignore lint/complexity/noBannedTypes: dynamically loaded extractor is untyped
-      (ext as Function)(batch, { pooling: 'mean', normalize: true })) as {
+      (ext as Function)(batch, { pooling: config.pooling ?? 'mean', normalize: true })) as {
         data: number[];
       };
 

package/src/domain/search/search/hybrid.ts

@@ -105,61 +105,72 @@ async function collectRankedLists(
   return rankedLists;
 }
 
+/** Initialise a fusion entry seeded from the first ranked item we see for a key. */
+function createFusionEntry(item: RankedItem): FusionEntry {
+  return {
+    name: item.name,
+    kind: item.kind,
+    file: item.file,
+    line: item.line,
+    endLine: (item.endLine as number | null) ?? null,
+    role: (item.role as string | null) ?? null,
+    fileHash: (item.fileHash as string | null) ?? null,
+    rrfScore: 0,
+    bm25Score: null,
+    bm25Rank: null,
+    similarity: null,
+    semanticRank: null,
+  };
+}
+
+/** Merge a single ranked item into its fusion entry: update RRF and best per-source rank. */
+function mergeRankedItem(entry: FusionEntry, item: RankedItem, k: number): void {
+  entry.rrfScore += 1 / (k + item.rank);
+  if (item.source === 'bm25') {
+    if (entry.bm25Rank === null || item.rank < entry.bm25Rank) {
+      entry.bm25Score = item.bm25Score ?? null;
+      entry.bm25Rank = item.rank;
+    }
+  } else if (entry.semanticRank === null || item.rank < entry.semanticRank) {
+    entry.similarity = item.similarity ?? null;
+    entry.semanticRank = item.rank;
+  }
+}
+
+/** Flatten a fusion entry into the public-facing hybrid result shape. */
+function toHybridResult(e: FusionEntry): HybridResult {
+  return {
+    name: e.name,
+    kind: e.kind,
+    file: e.file,
+    line: e.line,
+    endLine: e.endLine,
+    role: e.role,
+    fileHash: e.fileHash,
+    rrf: e.rrfScore,
+    bm25Score: e.bm25Score,
+    bm25Rank: e.bm25Rank,
+    similarity: e.similarity,
+    semanticRank: e.semanticRank,
+  };
+}
+
 /** Reciprocal Rank Fusion: merge ranked lists into a single scored result set. */
 function fuseResults(rankedLists: RankedItem[][], k: number, limit: number): HybridResult[] {
   const fusionMap = new Map<string, FusionEntry>();
-
   for (const list of rankedLists) {
     for (const item of list) {
       if (!fusionMap.has(item.key)) {
-        fusionMap.set(item.key, {
-          name: item.name,
-          kind: item.kind,
-          file: item.file,
-          line: item.line,
-          endLine: (item.endLine as number | null) ?? null,
-          role: (item.role as string | null) ?? null,
-          fileHash: (item.fileHash as string | null) ?? null,
-          rrfScore: 0,
-          bm25Score: null,
-          bm25Rank: null,
-          similarity: null,
-          semanticRank: null,
-        });
-      }
-      const entry = fusionMap.get(item.key)!;
-      entry.rrfScore += 1 / (k + item.rank);
-      if (item.source === 'bm25') {
-        if (entry.bm25Rank === null || item.rank < entry.bm25Rank) {
-          entry.bm25Score = (item as RankedItem & { bm25Score?: number }).bm25Score ?? null;
-          entry.bm25Rank = item.rank;
-        }
-      } else {
-        if (entry.semanticRank === null || item.rank < entry.semanticRank) {
-          entry.similarity = (item as RankedItem & { similarity?: number }).similarity ?? null;
-          entry.semanticRank = item.rank;
-        }
+        fusionMap.set(item.key, createFusionEntry(item));
       }
+      mergeRankedItem(fusionMap.get(item.key)!, item, k);
     }
   }
 
   return [...fusionMap.values()]
     .sort((a, b) => b.rrfScore - a.rrfScore)
     .slice(0, limit)
-    .map((e) => ({
-      name: e.name,
-      kind: e.kind,
-      file: e.file,
-      line: e.line,
-      endLine: e.endLine,
-      role: e.role,
-      fileHash: e.fileHash,
-      rrf: e.rrfScore,
-      bm25Score: e.bm25Score,
-      bm25Rank: e.bm25Rank,
-      similarity: e.similarity,
-      semanticRank: e.semanticRank,
-    }));
+    .map(toHybridResult);
 }
 
 export async function hybridSearchData(

package/src/domain/search/search/semantic.ts

@@ -4,7 +4,7 @@ import type { BetterSqlite3Database, CodegraphConfig } from '../../../types.js';
 import { normalizeSymbol } from '../../queries.js';
 import { embed } from '../models.js';
 import { cosineSim } from '../stores/sqlite-blob.js';
-import { prepareSearch } from './prepare.js';
+import { type PreparedSearch, prepareSearch } from './prepare.js';
 
 export interface SemanticSearchOpts {
   config?: CodegraphConfig;
@@ -30,6 +30,25 @@ export interface SearchDataResult {
   results: SemanticResult[];
 }
 
+type StoredRow = PreparedSearch['rows'][number];
+
+/** Reconstitute a stored embedding row's vector blob into a Float32Array. */
+function rowVector(row: StoredRow): Float32Array {
+  return new Float32Array(new Uint8Array(row.vector as unknown as ArrayBuffer).buffer);
+}
+
+/** Warn when stored embeddings and the query model use different dimensions. */
+function checkDimensionMismatch(storedDim: number | null, dim: number): boolean {
+  if (storedDim && dim !== storedDim) {
+    console.log(
+      `Warning: query model dimension (${dim}) doesn't match stored embeddings (${storedDim}).`,
+    );
+    console.log(`  Re-run \`codegraph embed\` with the same model, or use --model to match.`);
+    return true;
+  }
+  return false;
+}
+
 export async function searchData(
   query: string,
   customDbPath: string | undefined,
@@ -50,20 +69,12 @@ export async function searchData(
       dim,
     } = await embed([query], modelKey ?? undefined);
 
-    if (storedDim && dim !== storedDim) {
-      console.log(
-        `Warning: query model dimension (${dim}) doesn't match stored embeddings (${storedDim}).`,
-      );
-      console.log(`  Re-run \`codegraph embed\` with the same model, or use --model to match.`);
-      return null;
-    }
+    if (checkDimensionMismatch(storedDim, dim)) return null;
 
     const hc = new Map<string, string>();
     const results: SemanticResult[] = [];
     for (const row of rows) {
-      const vec = new Float32Array(new Uint8Array(row.vector as unknown as ArrayBuffer).buffer);
-      const sim = cosineSim(queryVec!, vec);
-
+      const sim = cosineSim(queryVec!, rowVector(row));
       if (sim >= minScore) {
         results.push({
           ...normalizeSymbol(row, db as BetterSqlite3Database, hc),
@@ -91,6 +102,82 @@ export interface MultiSearchResult {
   }>;
 }
 
+interface RankedHit {
+  rowIndex: number;
+  similarity: number;
+  rank: number;
+}
+
+interface FusionEntry {
+  rrfScore: number;
+  queryScores: Array<{ query: string; similarity: number; rank: number }>;
+}
+
+/**
+ * Emit a warning for any query pair whose embeddings are nearly identical,
+ * since RRF would over-weight matches shared between them.
+ */
+function warnOnSimilarQueries(
+  queries: string[],
+  queryVecs: Float32Array[],
+  threshold: number,
+): void {
+  for (let i = 0; i < queryVecs.length; i++) {
+    for (let j = i + 1; j < queryVecs.length; j++) {
+      const sim = cosineSim(queryVecs[i]!, queryVecs[j]!);
+      if (sim >= threshold) {
+        warn(
+          `Queries "${queries[i]}" and "${queries[j]}" are very similar ` +
+            `(${(sim * 100).toFixed(0)}% cosine similarity). ` +
+            `This may bias RRF results toward their shared matches. ` +
+            `Consider using more distinct queries.`,
+        );
+      }
+    }
+  }
+}
+
+/** Rank stored rows for a single query, keeping only those above minScore. */
+function rankRowsForQuery(
+  queryVec: Float32Array,
+  rowVecs: Float32Array[],
+  minScore: number,
+): RankedHit[] {
+  const scored: Array<{ rowIndex: number; similarity: number }> = [];
+  for (let ri = 0; ri < rowVecs.length; ri++) {
+    const sim = cosineSim(queryVec, rowVecs[ri]!);
+    if (sim >= minScore) {
+      scored.push({ rowIndex: ri, similarity: sim });
+    }
+  }
+  scored.sort((a, b) => b.similarity - a.similarity);
+  return scored.map((item, rank) => ({ ...item, rank: rank + 1 }));
+}
+
+/** Reciprocal Rank Fusion across each query's ranked hits. */
+function fuseRankedHits(
+  queries: string[],
+  perQueryRanked: RankedHit[][],
+  k: number,
+): Map<number, FusionEntry> {
+  const fusionMap = new Map<number, FusionEntry>();
+  for (let qi = 0; qi < queries.length; qi++) {
+    for (const item of perQueryRanked[qi]!) {
+      if (!fusionMap.has(item.rowIndex)) {
+        fusionMap.set(item.rowIndex, { rrfScore: 0, queryScores: [] });
+      }
+      const entry = fusionMap.get(item.rowIndex)!;
+      entry.rrfScore += 1 / (k + item.rank);
+      entry.queryScores.push({
+        query: queries[qi]!,
+        similarity: item.similarity,
+        rank: item.rank,
+      });
+    }
+  }
+  return fusionMap;
+}
+
 export async function multiSearchData(
   queries: string[],
   customDbPath: string | undefined,
@@ -101,6 +188,7 @@ export async function multiSearchData(
   const limit = opts.limit ?? searchCfg.topK ?? 15;
   const minScore = opts.minScore ?? searchCfg.defaultMinScore ?? 0.2;
   const k = opts.rrfK ?? searchCfg.rrfK ?? 60;
+  const similarityWarnThreshold = searchCfg.similarityWarnThreshold ?? 0.85;
 
   const prepared = prepareSearch(customDbPath, opts);
   if (!prepared) return null;
@@ -109,63 +197,15 @@ export async function multiSearchData(
   try {
     const { vectors: queryVecs, dim } = await embed(queries, modelKey ?? undefined);
 
-    const SIMILARITY_WARN_THRESHOLD = searchCfg.similarityWarnThreshold ?? 0.85;
-    for (let i = 0; i < queryVecs.length; i++) {
-      for (let j = i + 1; j < queryVecs.length; j++) {
-        const sim = cosineSim(queryVecs[i]!, queryVecs[j]!);
-        if (sim >= SIMILARITY_WARN_THRESHOLD) {
-          warn(
-            `Queries "${queries[i]}" and "${queries[j]}" are very similar ` +
-              `(${(sim * 100).toFixed(0)}% cosine similarity). ` +
-              `This may bias RRF results toward their shared matches. ` +
-              `Consider using more distinct queries.`,
-          );
-        }
-      }
-    }
+    warnOnSimilarQueries(queries, queryVecs as Float32Array[], similarityWarnThreshold);
 
-    if (storedDim && dim !== storedDim) {
-      console.log(
-        `Warning: query model dimension (${dim}) doesn't match stored embeddings (${storedDim}).`,
-      );
-      console.log(`  Re-run \`codegraph embed\` with the same model, or use --model to match.`);
-      return null;
-    }
+    if (checkDimensionMismatch(storedDim, dim)) return null;
 
-    const rowVecs = rows.map(
-      (row) => new Float32Array(new Uint8Array(row.vector as unknown as ArrayBuffer).buffer),
+    const rowVecs = rows.map(rowVector);
+    const perQueryRanked = queries.map((_q, qi) =>
+      rankRowsForQuery(queryVecs[qi]!, rowVecs, minScore),
     );
-
-    const perQueryRanked = queries.map((_query, qi) => {
-      const scored: Array<{ rowIndex: number; similarity: number }> = [];
-      for (let ri = 0; ri < rows.length; ri++) {
-        const sim = cosineSim(queryVecs[qi]!, rowVecs[ri]!);
-        if (sim >= minScore) {
-          scored.push({ rowIndex: ri, similarity: sim });
-        }
-      }
-      scored.sort((a, b) => b.similarity - a.similarity);
-      return scored.map((item, rank) => ({ ...item, rank: rank + 1 }));
-    });
-
-    const fusionMap = new Map<
-      number,
-      { rrfScore: number; queryScores: Array<{ query: string; similarity: number; rank: number }> }
-    >();
-    for (let qi = 0; qi < queries.length; qi++) {
-      for (const item of perQueryRanked[qi]!) {
-        if (!fusionMap.has(item.rowIndex)) {
-          fusionMap.set(item.rowIndex, { rrfScore: 0, queryScores: [] });
-        }
-        const entry = fusionMap.get(item.rowIndex)!;
-        entry.rrfScore += 1 / (k + item.rank);
-        entry.queryScores.push({
-          query: queries[qi]!,
-          similarity: item.similarity,
-          rank: item.rank,
-        });
-      }
-    }
+    const fusionMap = fuseRankedHits(queries, perQueryRanked, k);
 
     const hc = new Map<string, string>();
     const results: MultiSearchResult['results'] = [];