brainbank 0.7.0 → 0.8.0

package/src/providers/vector/hnsw-loader.ts

@@ -0,0 +1,129 @@
+/**
+ * BrainBank — HNSW Loader
+ *
+ * Utilities for persisting and loading HNSW indexes to/from disk.
+ * Used by BrainBank._runInitialize() and PluginContext.loadVectors().
+ *
+ * Includes cross-process write locking and hot-reload support
+ * for multi-process coordination.
+ */
+
+import type { DatabaseAdapter, CountRow } from '@/db/adapter.ts';
+import type { HNSWIndex } from './hnsw-index.ts';
+
+import { dirname, join } from 'node:path';
+import { withLock } from '@/lib/write-lock.ts';
+
+/** Derive the HNSW index file path from the DB path. */
+export function hnswPath(dbPath: string, name: string): string {
+    return join(dirname(dbPath), `hnsw-${name}.index`);
+}
+
+/** Derive the lock directory from the DB path. */
+export function lockDir(dbPath: string): string {
+    return dirname(dbPath);
+}
+
+/** Count rows in a vector table (fast, no data transfer). */
+export function countRows(db: DatabaseAdapter, table: string): number {
+    const row = db.prepare(`SELECT COUNT(*) as c FROM ${table}`).get() as CountRow;
+    return row?.c ?? 0;
+}
+
+/**
+ * Save all HNSW indexes to disk with cross-process file locking.
+ * Prevents concurrent writes from corrupting `.index` files.
+ */
+export async function saveAllHnsw(
+    dbPath: string,
+    kvHnsw: HNSWIndex,
+    sharedHnsw: Map<string, { hnsw: HNSWIndex; vecCache: Map<number, Float32Array> }>,
+    privateHnsw: Map<string, HNSWIndex>,
+): Promise<boolean> {
+    try {
+        await withLock(lockDir(dbPath), 'hnsw', () => {
+            kvHnsw.save(hnswPath(dbPath, 'kv'));
+            for (const [name, { hnsw }] of sharedHnsw) {
+                hnsw.save(hnswPath(dbPath, name));
+            }
+            for (const [name, hnsw] of privateHnsw) {
+                hnsw.save(hnswPath(dbPath, name));
+            }
+        });
+        return true;
+    } catch {
+        // Non-fatal: next startup rebuilds from SQLite (slower).
+        return false;
+    }
+}
+
+/** Load vectors from SQLite into HNSW + cache. */
+export function loadVectors(
+    db: DatabaseAdapter,
+    table: string,
+    idCol: string,
+    hnsw: HNSWIndex,
+    cache: Map<number, Float32Array>,
+): void {
+    const iter = db.prepare(`SELECT ${idCol}, embedding FROM ${table}`).iterate() as IterableIterator<{ embedding: Buffer; [key: string]: unknown }>;
+    for (const row of iter) {
+        const vec = new Float32Array(
+            row.embedding.buffer.slice(
+                row.embedding.byteOffset,
+                row.embedding.byteOffset + row.embedding.byteLength,
+            ),
+        );
+        hnsw.add(vec, row[idCol] as number);
+        cache.set(row[idCol] as number, vec);
+    }
+}
+
+/** Populate only the vecCache from SQLite (HNSW already loaded from file). */
+export function loadVecCache(
+    db: DatabaseAdapter,
+    table: string,
+    idCol: string,
+    cache: Map<number, Float32Array>,
+): void {
+    const iter = db.prepare(`SELECT ${idCol}, embedding FROM ${table}`).iterate() as IterableIterator<{ embedding: Buffer; [key: string]: unknown }>;
+    for (const row of iter) {
+        const vec = new Float32Array(
+            row.embedding.buffer.slice(
+                row.embedding.byteOffset,
+                row.embedding.byteOffset + row.embedding.byteLength,
+            ),
+        );
+        cache.set(row[idCol] as number, vec);
+    }
+}
+
+/** Deps for reloading a single HNSW index from disk. */
+interface ReloadDeps {
+    dbPath: string;
+    db: DatabaseAdapter;
+    name: string;
+    hnsw: HNSWIndex;
+    vecCache: Map<number, Float32Array>;
+    vectorTable: string;
+    idCol: string;
+}
+
+/**
+ * Reload a single HNSW index from disk after detecting a stale version.
+ * Reinitializes the in-memory HNSW, loads the saved index file, and
+ * refreshes the vector cache from SQLite.
+ */
+export function reloadHnsw(deps: ReloadDeps): void {
+    const { dbPath, db, name, hnsw, vecCache, vectorTable, idCol } = deps;
+    const indexPath = hnswPath(dbPath, name);
+    const rowCount = countRows(db, vectorTable);
+
+    hnsw.reinit();
+    vecCache.clear();
+
+    if (hnsw.tryLoad(indexPath, rowCount)) {
+        loadVecCache(db, vectorTable, idCol, vecCache);
+    } else {
+        loadVectors(db, vectorTable, idCol, hnsw, vecCache);
+    }
+}

package/src/search/bm25-boost.ts

@@ -0,0 +1,61 @@
+/**
+ * BrainBank — BM25 Intersection Boost
+ *
+ * Pure functions for post-processing vector search results with BM25 keyword overlap.
+ * Extracted from ContextBuilder for single-responsibility and testability.
+ */
+
+import type { SearchResult } from '@/types.ts';
+import type { SearchStrategy } from './types.ts';
+
+/** BM25 boost factor applied to vector results that also match keywords. */
+export const BM25_BOOST = 0.15;
+
+/**
+ * Boost vector results that also appear in BM25 keyword results.
+ * Does NOT add new results — only re-scores and re-sorts existing vector hits.
+ * This promotes keyword-relevant files without introducing BM25-only noise.
+ */
+export async function boostWithBM25(
+    vectorResults: SearchResult[],
+    bm25: SearchStrategy,
+    query: string,
+    sources: Record<string, number>,
+): Promise<SearchResult[]> {
+    if (vectorResults.length === 0) return vectorResults;
+
+    const bm25Results = await bm25.search(query, { sources });
+    if (bm25Results.length === 0) return vectorResults;
+
+    // Build a set of BM25 hit keys for fast lookup
+    const bm25Keys = new Set<string>();
+    for (const r of bm25Results) {
+        bm25Keys.add(resultKey(r));
+    }
+
+    // Boost scores of vector results that also appear in BM25
+    const boosted = vectorResults.map(r => {
+        const k = resultKey(r);
+        if (bm25Keys.has(k)) {
+            return { ...r, score: r.score + BM25_BOOST };
+        }
+        return r;
+    });
+
+    // Re-sort by boosted score
+    boosted.sort((a, b) => b.score - a.score);
+    return boosted;
+}
+
+/** Filter results whose filePath starts with `prefix`. */
+export function filterByPath(results: SearchResult[], prefix: string | undefined): SearchResult[] {
+    if (!prefix) return results;
+    return results.filter(r => r.filePath?.startsWith(prefix));
+}
+
+/** Generate a dedup key for a search result (file:startLine:endLine). */
+export function resultKey(r: SearchResult): string {
+    const sl = 'startLine' in r.metadata ? r.metadata.startLine : '';
+    const el = 'endLine' in r.metadata ? r.metadata.endLine : '';
+    return `${r.filePath ?? ''}:${sl}:${el}`;
+}

package/src/search/context-builder.ts

@@ -0,0 +1,298 @@
+/**
+ * BrainBank — Context Builder
+ *
+ * Orchestrates the context-building pipeline:
+ *   1. Vector search (primary)
+ *   2. Path scoping (filter)
+ *   3. LLM noise pruning (optional)
+ *   4. Session dedup (filter)
+ *   5. LLM context expansion (optional — expander field)
+ *   6. Plugin formatters (output)
+ *
+ * All search post-processing lives in `bm25-boost.ts`.
+ * Plugin-agnostic — discovers formatters from ContextFormatterPlugin.
+ */
+
+import type { ContextOptions, EmbeddingProvider, Expander, ExpanderManifestItem, Pruner, SearchResult } from '@/types.ts';
+import type { SearchStrategy } from './types.ts';
+import type { PluginRegistry } from '@/services/plugin-registry.ts';
+
+import { isContextFormatterPlugin, isContextFieldPlugin, isExpandablePlugin, isSearchable } from '@/plugin.ts';
+import { filterByPath } from './bm25-boost.ts';
+import { pruneResults } from '@/lib/prune.ts';
+import { logQuery } from '@/lib/logger.ts';
+import type { QueryLogResult } from '@/lib/logger.ts';
+import { providerKey } from '@/lib/provider-key.ts';
+
+export class ContextBuilder {
+    constructor(
+        private _search: SearchStrategy | undefined,
+        private _registry: PluginRegistry,
+        private _pruner?: Pruner,
+        private _embedding?: EmbeddingProvider,
+        private _rerankerName?: string,
+        private _configFields: Record<string, unknown> = {},
+        private _expander?: Expander,
+    ) {}
+
+    /** Set config-level context field defaults (from config.json "context" section). */
+    set configFields(fields: Record<string, unknown>) {
+        this._configFields = fields;
+    }
+
+    /** Set the expander instance. */
+    set expander(expander: Expander | undefined) {
+        this._expander = expander;
+    }
+
+    /** Build a full context block for a task. Returns markdown for system prompt. */
+    async build(task: string, options: ContextOptions = {}): Promise<string> {
+        const t0 = Date.now();
+        const src = options.sources ?? {};
+        const { minScore = 0.25, useMMR = true, mmrLambda = 0.7 } = options;
+
+        // 1. Primary: vector search (includes per-repo BM25 fusion internally)
+        let results: SearchResult[] = this._search
+            ? await this._search.search(task, {
+                sources: src,
+                minScore, useMMR, mmrLambda,
+            })
+            : [];
+
+        // 2. Path scoping
+        results = filterByPath(results, options.pathPrefix);
+
+        // 3. LLM noise pruning (optional — per-request override or construction-time)
+        const pruner = options.pruner ?? this._pruner;
+        const beforePrune = results;
+        if (pruner && results.length > 1) {
+            results = await pruneResults(task, results, pruner);
+        }
+
+        // 4. Exclude already-returned files (session dedup)
+        if (options.excludeFiles && options.excludeFiles.size > 0) {
+            results = results.filter(r => !r.filePath || !options.excludeFiles!.has(r.filePath));
+        }
+
+        // 5. LLM context expansion (optional — only when expander field is enabled)
+        const resolvedFields = this._resolveFields(options);
+        let expanderNote: string | undefined;
+        if (resolvedFields.expander === true && this._expander && results.length > 0) {
+            const expansion = await this._expand(task, results);
+            if (expansion.results.length > 0) {
+                results = [...results, ...expansion.results];
+            }
+            expanderNote = expansion.note;
+        }
+
+        // 6. Format output
+        const parts: string[] = [`# Context for: "${task}"\n`];
+        this._appendFormatterResults(results, parts, options, resolvedFields);
+        await this._appendSearchableResults(task, src, minScore, parts);
+
+        // 7. Append expander note (last section)
+        if (expanderNote) {
+            parts.push(`\n## Expansion Notes\n\n${expanderNote}\n`);
+        }
+
+        // ── Log ──
+        const prunedResults = pruner
+            ? beforePrune.filter(r => !results.includes(r))
+            : [];
+        logQuery({
+            source: options.source ?? 'api',
+            method: 'getContext',
+            query: task,
+            embedding: this._embedding ? providerKey(this._embedding) : 'unknown',
+            pruner: pruner ? _prunerName(pruner) : null,
+            reranker: this._rerankerName ?? null,
+            options: {
+                sources: src,
+                pathPrefix: options.pathPrefix,
+                minScore,
+                affectedFiles: options.affectedFiles,
+            },
+            results: results.map(_toLogResult),
+            pruned: prunedResults.length > 0 ? prunedResults.map(_toLogResult) : undefined,
+            durationMs: Date.now() - t0,
+        });
+
+        return parts.join('\n');
+    }
+
+    /** Invoke ContextFormatterPlugins. Multi-repo: each plugin formats its own results. */
+    private _appendFormatterResults(
+        results: SearchResult[],
+        parts: string[],
+        options: ContextOptions,
+        resolvedFields?: Record<string, unknown>,
+    ): void {
+        const fields = resolvedFields ?? this._resolveFields(options);
+        const seenFormatters = new Set<string>();
+
+        for (const mod of this._registry.all) {
+            if (!isContextFormatterPlugin(mod)) continue;
+            const baseType = mod.name.split(':')[0];
+
+            // Multi-repo plugin (e.g. 'code:servicehub-frontend'):
+            // scope results to this repo and let each plugin format its own
+            const colonIdx = mod.name.indexOf(':');
+            if (colonIdx > 0) {
+                const repoPrefix = mod.name.slice(colonIdx + 1);
+                const scoped = results.filter(r =>
+                    r.filePath?.startsWith(repoPrefix + '/'),
+                );
+                if (scoped.length > 0) {
+                    mod.formatContext(scoped, parts, fields);
+                }
+                continue;
+            }
+
+            // Single-repo plugin: dedup by base type (old behavior)
+            if (seenFormatters.has(baseType)) continue;
+            seenFormatters.add(baseType);
+            mod.formatContext(results, parts, fields);
+        }
+    }
+
+    /**
+     * Resolve context fields: plugin defaults ← config.json ← per-query.
+     * Returns a flat Record with the final value for each field.
+     */
+    private _resolveFields(options: ContextOptions): Record<string, unknown> {
+        // 1. Collect plugin defaults
+        const defaults: Record<string, unknown> = {};
+        for (const mod of this._registry.all) {
+            if (isContextFieldPlugin(mod)) {
+                for (const field of mod.contextFields()) {
+                    defaults[field.name] = field.default;
+                }
+            }
+        }
+
+        // 2. Merge: defaults ← config ← per-query
+        return { ...defaults, ...this._configFields, ...(options.fields ?? {}) };
+    }
+
+    /**
+     * Run LLM expansion: build manifest of candidate chunks from files
+     * NOT already in search results, call expander, resolve selected IDs.
+     */
+    private async _expand(task: string, results: SearchResult[]): Promise<{ results: SearchResult[]; note?: string }> {
+        if (!this._expander) return { results: [] };
+
+        // Detect multi-repo prefix from results (e.g. 'servicehub-frontend')
+        // Results have prefixed filePaths like 'servicehub-frontend/src/...'
+        // but DB chunks have unprefixed paths like 'src/...'
+        const repoPrefix = this._detectRepoPrefix(results);
+
+        // Collect unique file paths already in results (strip repo prefix for DB match)
+        const excludeFilePaths = [...new Set(
+            results.filter(r => r.filePath).map(r => {
+                const fp = r.filePath as string;
+                return repoPrefix && fp.startsWith(repoPrefix + '/') ? fp.slice(repoPrefix.length + 1) : fp;
+            }),
+        )];
+
+        // Collect current chunk IDs (to exclude from manifest)
+        const excludeIds: number[] = [];
+        for (const r of results) {
+            const meta = r.metadata as Record<string, unknown> | undefined;
+            const id = meta?.id as number | undefined;
+            if (id !== undefined) excludeIds.push(id);
+        }
+
+        // Build manifest + resolve from the MATCHING ExpandablePlugin only
+        // In multi-repo, expand only from the plugin whose name matches the result set's repo
+        const manifest: ExpanderManifestItem[] = [];
+        let resolver: ((ids: number[]) => SearchResult[]) | undefined;
+        for (const mod of this._registry.all) {
+            if (!isExpandablePlugin(mod)) continue;
+
+            // In multi-repo, only expand from the plugin matching the result set's repo
+            // e.g. 'code:servicehub-frontend' matches repoPrefix 'servicehub-frontend'
+            const colonIdx = mod.name.indexOf(':');
+            const pluginRepo = colonIdx > 0 ? mod.name.slice(colonIdx + 1) : undefined;
+            if (repoPrefix && pluginRepo && pluginRepo !== repoPrefix) continue;
+
+            manifest.push(...mod.buildManifest(excludeFilePaths, excludeIds));
+            if (!resolver) {
+                const prefix = pluginRepo;
+                resolver = (ids: number[]) => {
+                    const chunks = mod.resolveChunks(ids);
+                    // Add repo prefix back to resolved chunk filePaths
+                    if (prefix) {
+                        for (const chunk of chunks) {
+                            if (chunk.filePath) chunk.filePath = `${prefix}/${chunk.filePath}`;
+                            const meta = chunk.metadata as Record<string, unknown>;
+                            if (typeof meta.filePath === 'string') {
+                                meta.filePath = `${prefix}/${meta.filePath}`;
+                            }
+                        }
+                    }
+                    return chunks;
+                };
+            }
+        }
+        if (manifest.length === 0 || !resolver) return { results: [] };
+
+        // Call expander
+        try {
+            const expandResult = await this._expander.expand(task, excludeIds, manifest);
+            if (expandResult.ids.length === 0) return { results: [], note: expandResult.note };
+            return { results: resolver(expandResult.ids), note: expandResult.note };
+        } catch {
+            // Fail-open: expansion errors are non-fatal
+            return { results: [] };
+        }
+    }
+
+    /** Detect the multi-repo prefix from existing results (e.g. 'servicehub-frontend'). */
+    private _detectRepoPrefix(results: SearchResult[]): string | undefined {
+        for (const r of results) {
+            if (!r.filePath) continue;
+            // Multi-repo filePaths look like 'servicehub-frontend/src/...'
+            // The repo prefix is the first path segment before 'src/'
+            const srcIdx = r.filePath.indexOf('/src/');
+            if (srcIdx > 0) return r.filePath.slice(0, srcIdx);
+        }
+        return undefined;
+    }
+
+    /** Collect results from SearchablePlugins that don't have their own formatter. */
+    private async _appendSearchableResults(
+        task: string,
+        sources: Record<string, number>,
+        minScore: number,
+        parts: string[],
+    ): Promise<void> {
+        for (const mod of this._registry.all) {
+            if (isContextFormatterPlugin(mod)) continue;
+            if (!isSearchable(mod)) continue;
+            const hits = await mod.search(task, { k: sources[mod.name.split(':')[0]] ?? 6, minScore });
+            if (hits.length > 0) {
+                parts.push(`## ${mod.name}\n`);
+                for (const r of hits) {
+                    parts.push(`- [${Math.round(r.score * 100)}%] ${r.content.slice(0, 200)}`);
+                }
+                parts.push('');
+            }
+        }
+    }
+}
+
+// ── Helpers ──────────────────────────────────────────
+
+function _toLogResult(r: SearchResult): QueryLogResult {
+    const meta = r.metadata as Record<string, unknown> | undefined;
+    return {
+        filePath: r.filePath ?? 'unknown',
+        score: r.score,
+        type: r.type,
+        name: (meta?.name as string | undefined) ?? undefined,
+    };
+}
+
+function _prunerName(pruner: Pruner): string {
+    return pruner.constructor?.name ?? 'custom';
+}

package/src/search/keyword/composite-bm25-search.ts

@@ -0,0 +1,62 @@
+/**
+ * BrainBank — Composite BM25 Search Strategy
+ *
+ * Generic BM25 coordinator that discovers BM25SearchPlugin instances
+ * from the registry and delegates per-source keyword search.
+ */
+
+import type { SearchResult } from '@/types.ts';
+import type { SearchStrategy, SearchOptions } from '@/search/types.ts';
+import type { PluginRegistry } from '@/services/plugin-registry.ts';
+
+import { isBM25SearchPlugin } from '@/plugin.ts';
+
+const DEFAULT_K = 8;
+
+export class CompositeBM25Search implements SearchStrategy {
+    constructor(private _registry: PluginRegistry) {}
+
+    /**
+     * Run BM25 keyword search across all plugins that implement BM25SearchPlugin.
+     * Each plugin searches its own FTS5 tables.
+     */
+    async search(query: string, options: SearchOptions = {}): Promise<SearchResult[]> {
+        const src = options.sources ?? {};
+        const results: SearchResult[] = [];
+
+        for (const plugin of this._registry.all) {
+            if (!isBM25SearchPlugin(plugin)) continue;
+
+            const baseType = plugin.name.split(':')[0];
+            const k = src[baseType] ?? DEFAULT_K;
+            if (k <= 0) continue;
+
+            const hits = plugin.searchBM25(query, k);
+
+            // Multi-repo: prefix filePaths with sub-repo name (same as CompositeVectorSearch)
+            const colonIdx = plugin.name.indexOf(':');
+            if (colonIdx > 0) {
+                const subRepo = plugin.name.slice(colonIdx + 1);
+                for (const hit of hits) {
+                    if (hit.filePath) hit.filePath = `${subRepo}/${hit.filePath}`;
+                    const meta = hit.metadata as Record<string, unknown>;
+                    if (typeof meta.filePath === 'string') {
+                        meta.filePath = `${subRepo}/${meta.filePath}`;
+                    }
+                }
+            }
+
+            results.push(...hits);
+        }
+
+        return results.sort((a, b) => b.score - a.score);
+    }
+
+    /** Rebuild FTS5 indices across all BM25 plugins. */
+    rebuild(): void {
+        for (const plugin of this._registry.all) {
+            if (!isBM25SearchPlugin(plugin)) continue;
+            plugin.rebuildFTS?.();
+        }
+    }
+}

package/src/search/types.ts

@@ -0,0 +1,35 @@
+/**
+ * BrainBank — Search Types
+ * 
+ * Shared interface for all search strategies.
+ * Implement SearchStrategy to add a new search backend.
+ */
+
+import type { SearchResult } from '@/types.ts';
+
+/** Any search implementation follows this shape. */
+export interface SearchStrategy {
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Rebuild internal indices (e.g. FTS5). Optional. */
+    rebuild?(): void;
+}
+
+/** Pre-embedded vector search for a single domain (code, git, etc.). */
+export interface DomainVectorSearch {
+    /** Search using a pre-computed query vector. Optional queryText enables BM25 fusion. */
+    search(queryVec: Float32Array, k: number, minScore: number, useMMR?: boolean, mmrLambda?: number, queryText?: string): SearchResult[];
+}
+
+export interface SearchOptions {
+    /** Per-source result limits. Built-in: 'code', 'git', 'memory'. Any other key = custom plugin or KV collection. */
+    sources?: Record<string, number>;
+    /** Minimum similarity score. Default: 0.25 */
+    minScore?: number;
+    /** Use MMR for diversity. Default: true */
+    useMMR?: boolean;
+    /** MMR lambda. Default: 0.7 */
+    mmrLambda?: number;
+    /** Caller origin for debug logging. */
+    source?: 'cli' | 'mcp' | 'daemon' | 'api';
+}
+

package/src/search/vector/composite-vector-search.ts

@@ -0,0 +1,76 @@
+/**
+ * BrainBank — Composite Vector Search
+ *
+ * Generic orchestrator for domain-specific vector searches.
+ * Embeds the query once, delegates to registered DomainVectorSearch strategies.
+ * Uses round-robin interleaving when multiple strategies exist to ensure
+ * balanced representation across repos/domains.
+ * Plugin-agnostic — strategies are discovered at wiring time.
+ */
+
+import type { EmbeddingProvider, SearchResult } from '@/types.ts';
+import type { SearchStrategy, SearchOptions, DomainVectorSearch } from '@/search/types.ts';
+
+export interface CompositeVectorConfig {
+    strategies: Map<string, DomainVectorSearch>;
+    embedding: EmbeddingProvider;
+    /** Default K values per strategy name. Strategies not listed default to 0. */
+    defaults?: Record<string, number>;
+}
+
+export class CompositeVectorSearch implements SearchStrategy {
+    /** Default K when no source override is provided. */
+    private static readonly DEFAULT_K = 6;
+
+    constructor(private _c: CompositeVectorConfig) {}
+
+    /** Search across all registered domain strategies with score-based merge. */
+    async search(query: string, options: SearchOptions = {}): Promise<SearchResult[]> {
+        const src = options.sources ?? {};
+        const { minScore = 0.25, useMMR = true, mmrLambda = 0.7 } = options;
+
+        const queryVec = await this._c.embedding.embed(query);
+
+        // Each strategy gets full K for ranking quality, cap total after merge
+        const allResults: SearchResult[] = [];
+        let requestedK = 0;
+
+        for (const [name, strategy] of this._c.strategies) {
+            const baseName = name.split(':')[0];
+            const k = src[name] ?? src[baseName] ?? this._c.defaults?.[name] ?? CompositeVectorSearch.DEFAULT_K;
+            if (k <= 0) continue;
+            requestedK = Math.max(requestedK, k);
+            const hits = strategy.search(queryVec, k, minScore, useMMR, mmrLambda, query);
+
+            // Multi-repo: prefix filePaths with sub-repo name so path filtering works
+            // e.g. strategy 'code:servicehub-backend' → filePath 'servicehub-backend/src/app.ts'
+            const colonIdx = name.indexOf(':');
+            if (colonIdx > 0) {
+                const subRepo = name.slice(colonIdx + 1);
+                for (const hit of hits) {
+                    if (hit.filePath) hit.filePath = `${subRepo}/${hit.filePath}`;
+                    const meta = hit.metadata as Record<string, unknown>;
+                    if (typeof meta.filePath === 'string') {
+                        meta.filePath = `${subRepo}/${meta.filePath}`;
+                    }
+                }
+            }
+
+            allResults.push(...hits);
+        }
+
+        if (allResults.length === 0) return [];
+
+        // Sort by raw rrfScore (comparable across repos), cap to requested K
+        allResults.sort((a, b) => b.score - a.score);
+        const capped = allResults.slice(0, requestedK);
+
+        // Normalize scores 0-1 globally
+        const maxScore = capped[0].score;
+        if (maxScore > 0) {
+            for (const r of capped) r.score = r.score / maxScore;
+        }
+
+        return capped;
+    }
+}