opencode-diane 0.0.5

package/dist/search/bm25.js

@@ -0,0 +1,334 @@
+/**
+ * BM25 retrieval over the in-memory inverted index.
+ *
+ * Hierarchical filtering: callers can narrow candidates by category
+ * and/or subject before scoring. If neither filter is provided, all
+ * docs that contain any query term are considered.
+ *
+ * k1=1.2, b=0.75 — standard defaults that work well on short docs.
+ */
+import { personalizedPageRank } from "./ppr.js";
+import { tokenize } from "./tokenize.js";
+const K1 = 1.2;
+const B = 0.75;
+/**
+ * Fraction of a seed hit's BM25 score given to memories pulled in via
+ * the co-change graph. Deliberately small (< 1): a co-change-surfaced
+ * file always ranks below a direct textual match, but above nothing.
+ */
+const COCHANGE_BOOST = 0.25;
+/**
+ * Only the top-N textual hits act as seeds for co-change propagation.
+ * Keeps the boost focused on what the query actually matched and the
+ * extra work bounded.
+ */
+const SEED_LIMIT = 5;
+/**
+ * Per neighbour file, pull in at most this many memories (ranked by
+ * useCount). Stops a hot file with hundreds of commit memories from
+ * flooding the result set.
+ */
+const PROPAGATE_PER_FILE = 3;
+/** ~4 chars per token — the rough heuristic used throughout the plugin. */
+export function estimateTokens(s) {
+    return Math.ceil(s.length / 4);
+}
+/**
+ * Pack ranked hits into a token budget. `format` renders one hit to
+ * the string the agent will actually see, so the estimate matches the
+ * real output. Always returns at least one hit (the top-ranked) even
+ * if it alone exceeds the budget — an empty result would be worse
+ * than a slightly-over one — but in that case the hit's `content` is
+ * truncated so the budget stays a real ceiling rather than a wish.
+ * Returns the (possibly content-truncated) kept hits and how many
+ * were dropped.
+ */
+export function packToTokenBudget(hits, budget, format) {
+    if (hits.length === 0)
+        return { kept: [], omitted: 0 };
+    const kept = [];
+    let used = 0;
+    for (const h of hits) {
+        const cost = estimateTokens(format(h)) + 1; // +1 for the joining newline
+        if (kept.length === 0 && cost > budget) {
+            // Mandatory first hit overflows on its own — keep it, but trim
+            // its content so the result still respects the ceiling. We trim
+            // a shallow clone so the stored Memory object is untouched.
+            const room = Math.max(40, budget) * 4; // budget back in chars
+            const overhead = format(h).length - h.memory.content.length;
+            const contentRoom = Math.max(20, room - overhead);
+            const trimmed = {
+                score: h.score,
+                memory: {
+                    ...h.memory,
+                    content: h.memory.content.length > contentRoom
+                        ? h.memory.content.slice(0, contentRoom - 1) + "…"
+                        : h.memory.content,
+                },
+            };
+            kept.push(trimmed);
+            break;
+        }
+        if (kept.length > 0 && used + cost > budget)
+            break;
+        kept.push(h);
+        used += cost;
+    }
+    return { kept, omitted: hits.length - kept.length };
+}
+export function search(index, byId, opts) {
+    const queryTokens = tokenize(opts.query);
+    if (queryTokens.length === 0)
+        return [];
+    const limit = opts.limit ?? 10;
+    // 1) Compute candidate set: union of postings for query terms,
+    //    further intersected with category/subject filters if any.
+    const candidates = new Set();
+    for (const token of queryTokens) {
+        const ids = index.postings.get(token);
+        if (!ids)
+            continue;
+        for (const id of ids)
+            candidates.add(id);
+    }
+    if (opts.category)
+        intersectInPlace(candidates, index.byCategory.get(opts.category));
+    if (opts.subject)
+        intersectInPlace(candidates, index.bySubject.get(opts.subject));
+    if (candidates.size === 0)
+        return [];
+    // 2) Compute IDF for each unique query term.
+    const N = index.docCount || 1;
+    const idf = new Map();
+    const uniqueQueryTokens = Array.from(new Set(queryTokens));
+    for (const t of uniqueQueryTokens) {
+        const df = index.postings.get(t)?.size ?? 0;
+        // BM25+ style: log((N - df + 0.5) / (df + 0.5) + 1) — always positive.
+        idf.set(t, Math.log((N - df + 0.5) / (df + 0.5) + 1));
+    }
+    // 3) Score each candidate.
+    const avgdl = index.avgDocLength() || 1;
+    const scoreById = new Map();
+    for (const id of candidates) {
+        const doc = index.docs.get(id);
+        const mem = byId.get(id);
+        if (!doc || !mem)
+            continue;
+        let score = 0;
+        for (const t of uniqueQueryTokens) {
+            const tf = doc.tf.get(t) ?? 0;
+            if (tf === 0)
+                continue;
+            const wt = idf.get(t) ?? 0;
+            const num = tf * (K1 + 1);
+            const denom = tf + K1 * (1 - B + (B * doc.length) / avgdl);
+            score += wt * (num / denom);
+        }
+        // Small recency / popularity bias so that all-else-equal we return
+        // recently-touched and frequently-used entries first.
+        score += Math.log1p(mem.useCount) * 0.05;
+        if (score > 0)
+            scoreById.set(id, score);
+    }
+    // 3b) Co-change graph boost — the Aider PageRank idea.
+    //     A well-scoring memory about file X *pulls in* memories about
+    //     files X is historically modified together with, even when
+    //     those files don't textually match the query — surfacing
+    //     structurally-related context the query alone would miss.
+    //
+    //     Two strategies, selected by `opts.personalizedPageRank`:
+    //       - default (off): ONE HOP — boost the direct co-change
+    //         neighbours of the top textual hits. O(seeds × neighbours),
+    //         fully inspectable.
+    //       - on: PERSONALIZED PAGERANK — a restart-biased random walk
+    //         over the whole co-change graph, so relevance reaches
+    //         multi-hop files, graded by graph distance.
+    //
+    //     Either way it is bounded and low-scored so it can't drown
+    //     direct matches: only the top SEED_LIMIT textual hits seed it,
+    //     each file contributes ≤ PROPAGATE_PER_FILE memories (most-used
+    //     first), and a pulled-in hit always ranks below a real textual
+    //     match.
+    if (scoreById.size > 0 && index.coChange.size > 0) {
+        const seeds = Array.from(scoreById.entries())
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, SEED_LIMIT);
+        if (opts.personalizedPageRank) {
+            applyPprBoost(index, byId, scoreById, seeds);
+        }
+        else {
+            applyOneHopBoost(index, byId, scoreById, seeds);
+        }
+    }
+    // 3c) Intent lean — query-dependent and agent-supplied. Applied
+    //     last, as a *mild* multiplier, so it nudges ranking without
+    //     ever filtering: a much stronger match still wins regardless of
+    //     `prefer`. This is why test de-emphasis here is safe — a query
+    //     that genuinely wants tests still gets them.
+    if (opts.prefer && opts.prefer !== "any") {
+        for (const [id, s] of scoreById) {
+            const mem = byId.get(id);
+            if (!mem)
+                continue;
+            const m = preferMultiplier(opts.prefer, mem);
+            if (m !== 1)
+                scoreById.set(id, s * m);
+        }
+    }
+    const hits = [];
+    for (const [id, score] of scoreById) {
+        const mem = byId.get(id);
+        if (mem)
+            hits.push({ memory: mem, score });
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, limit);
+}
+/**
+ * Whether a memory's subject path looks test-related. Deliberately
+ * minimal and language-neutral: it asks only whether the *word*
+ * "test"/"tests" appears as a token of the path. The plugin's own
+ * tokenizer extracts that word equally from a `test/` directory, a
+ * `_test.go` / `.test.ts` filename, or a `test_x.py` one — so this is
+ * one universal signal, not a per-ecosystem catalogue to overfit. It
+ * checks tokens, not substrings, so `latest`, `contest`, `testimony`
+ * are not mistaken for tests.
+ */
+/**
+ * One-hop co-change boost (the default). Lifts memories about the
+ * direct co-change neighbours of the seed files: a neighbour memory's
+ * score is raised to `seedScore × COCHANGE_BOOST`, never above its own
+ * textual score, and at most `PROPAGATE_PER_FILE` memories per file.
+ */
+function applyOneHopBoost(index, byId, scoreById, seeds) {
+    for (const [seedId, seedScore] of seeds) {
+        const seedMem = byId.get(seedId);
+        if (!seedMem)
+            continue;
+        const seedFile = fileOfSubject(seedMem.subject);
+        if (!seedFile)
+            continue;
+        const neighbors = index.coChangeNeighbors(seedFile);
+        if (!neighbors)
+            continue;
+        for (const neighborFile of neighbors) {
+            const memIds = index.bySubject.get(neighborFile);
+            if (!memIds)
+                continue;
+            // Most-used memories about the neighbour file first.
+            const ranked = Array.from(memIds)
+                .map((id) => byId.get(id))
+                .filter((m) => m !== undefined)
+                .sort((a, b) => b.useCount - a.useCount)
+                .slice(0, PROPAGATE_PER_FILE);
+            const propagated = seedScore * COCHANGE_BOOST;
+            for (const m of ranked) {
+                const current = scoreById.get(m.id) ?? 0;
+                // Never lower an existing (textual) score; only lift.
+                if (propagated > current)
+                    scoreById.set(m.id, propagated);
+            }
+        }
+    }
+}
+/**
+ * Personalized PageRank co-change boost (opt-in). Runs a
+ * restart-biased random walk over the whole co-change graph, seeded on
+ * the textual hits, and lifts memories about every file the walk
+ * reaches — graded by the walk's stationary score, so a direct
+ * neighbour is lifted more than a two-hop file. Bounded: the boost is
+ * scaled so the most-central file receives at most
+ * `topSeedScore × COCHANGE_BOOST`, keeping any pulled-in hit below the
+ * strongest textual match.
+ */
+function applyPprBoost(index, byId, scoreById, seeds) {
+    // Personalization vector: each seed's file, weighted by its BM25 score.
+    const personalization = new Map();
+    for (const [id, score] of seeds) {
+        const file = fileOfSubject(byId.get(id)?.subject ?? "");
+        if (file)
+            personalization.set(file, (personalization.get(file) ?? 0) + score);
+    }
+    if (personalization.size === 0)
+        return;
+    const ppr = personalizedPageRank(index.coChange, personalization);
+    let maxScore = 0;
+    for (const v of ppr.values())
+        if (v > maxScore)
+            maxScore = v;
+    if (maxScore <= 0)
+        return;
+    // Scale so the most-central file gets at most topSeedScore × COCHANGE_BOOST.
+    const topSeedScore = seeds[0][1];
+    for (const [file, prob] of ppr) {
+        const boost = (prob / maxScore) * topSeedScore * COCHANGE_BOOST;
+        if (boost <= 1e-9)
+            continue;
+        const memIds = index.bySubject.get(file);
+        if (!memIds)
+            continue;
+        const ranked = Array.from(memIds)
+            .map((id) => byId.get(id))
+            .filter((m) => m !== undefined)
+            .sort((a, b) => b.useCount - a.useCount)
+            .slice(0, PROPAGATE_PER_FILE);
+        for (const m of ranked) {
+            // Additive: the stationary score already aggregates every path
+            // from every seed, so PPR lifts each file once, on top of any
+            // textual score that memory already has.
+            scoreById.set(m.id, (scoreById.get(m.id) ?? 0) + boost);
+        }
+    }
+}
+function subjectLooksLikeTest(subject) {
+    for (const tok of tokenize(subject)) {
+        if (tok === "test" || tok === "tests")
+            return true;
+    }
+    return false;
+}
+/**
+ * The mild, query-dependent ranking lean for `prefer`. Multipliers are
+ * gentle constants by design — a nudge, not a gate — and are not tuned
+ * to any particular repository.
+ */
+function preferMultiplier(prefer, mem) {
+    const isTest = subjectLooksLikeTest(mem.subject);
+    if (prefer === "tests")
+        return isTest ? 1.5 : 1.0;
+    if (prefer === "history")
+        return mem.category === "git-history" ? 1.3 : 1.0;
+    // prefer === "code": lean toward structural code, away from tests.
+    let m = mem.category === "code-map" ? 1.25 : 1.0;
+    if (isTest)
+        m *= 0.6;
+    return m;
+}
+/**
+ * Extract the file path a memory's subject is "about", or null.
+ * Commit memories use the bare path as subject; co-change and churn
+ * memories prefix it (`co-change:foo`, `churn:foo`). Tree-style
+ * placeholders (`tree:abc1234`) and non-file subjects return null.
+ */
+function fileOfSubject(subject) {
+    if (subject.startsWith("co-change:"))
+        return subject.slice("co-change:".length);
+    if (subject.startsWith("churn:"))
+        return subject.slice("churn:".length);
+    if (subject.startsWith("tree:"))
+        return null;
+    if (subject.startsWith("recency:"))
+        return null;
+    if (subject.includes(":"))
+        return null; // other category-prefixed subjects
+    return subject || null;
+}
+function intersectInPlace(target, other) {
+    if (!other) {
+        target.clear();
+        return;
+    }
+    for (const id of target)
+        if (!other.has(id))
+            target.delete(id);
+}

package/dist/search/e5-embedder.d.ts

@@ -0,0 +1,30 @@
+/**
+ * e5-embedder.ts — the real multilingual embedder, backed by the
+ * `intfloat/e5` family via transformers.js (ONNX).
+ *
+ * This file is the ONLY place that touches the model runtime, and it
+ * is imported dynamically — and only when `enableSemanticSearch` is
+ * on. `@huggingface/transformers` is an OPTIONAL peer dependency: it is
+ * not installed by a default `bun install`, so a user who never
+ * enables semantic search never downloads it. The import specifier is
+ * deliberately indirected through a `string`-typed constant so the
+ * TypeScript build does not require the package to be present.
+ *
+ * `createE5Embedder` throws if the runtime or the model cannot be
+ * loaded (package missing, network blocked, etc.); the caller is
+ * expected to catch that, log it, and fall back to lexical-only
+ * search — enabling the flag must never break the plugin.
+ *
+ * e5 is asymmetric: a query and the passage it should match take
+ * different prefixes ("query: " / "passage: "). Getting that wrong
+ * quietly degrades retrieval, so it is baked into the two methods.
+ */
+import { DEFAULT_EMBEDDING_MODEL, type Embedder } from "./embedder.js";
+export { DEFAULT_EMBEDDING_MODEL };
+/**
+ * Build an e5 embedder. Loads the transformers.js runtime and the
+ * model (downloaded and cached on first use). Throws — with an
+ * actionable message — if the optional dependency is missing or the
+ * model cannot be fetched.
+ */
+export declare function createE5Embedder(modelId?: string): Promise<Embedder>;

package/dist/search/e5-embedder.js

@@ -0,0 +1,91 @@
+/**
+ * e5-embedder.ts — the real multilingual embedder, backed by the
+ * `intfloat/e5` family via transformers.js (ONNX).
+ *
+ * This file is the ONLY place that touches the model runtime, and it
+ * is imported dynamically — and only when `enableSemanticSearch` is
+ * on. `@huggingface/transformers` is an OPTIONAL peer dependency: it is
+ * not installed by a default `bun install`, so a user who never
+ * enables semantic search never downloads it. The import specifier is
+ * deliberately indirected through a `string`-typed constant so the
+ * TypeScript build does not require the package to be present.
+ *
+ * `createE5Embedder` throws if the runtime or the model cannot be
+ * loaded (package missing, network blocked, etc.); the caller is
+ * expected to catch that, log it, and fall back to lexical-only
+ * search — enabling the flag must never break the plugin.
+ *
+ * e5 is asymmetric: a query and the passage it should match take
+ * different prefixes ("query: " / "passage: "). Getting that wrong
+ * quietly degrades retrieval, so it is baked into the two methods.
+ */
+import { DEFAULT_EMBEDDING_MODEL } from "./embedder.js";
+export { DEFAULT_EMBEDDING_MODEL };
+/** Passages longer than this are truncated before embedding (e5 caps at 512 tokens anyway). */
+const MAX_CHARS = 2000;
+/** Embed in batches of this many texts to bound peak memory. */
+const BATCH = 32;
+class E5Embedder {
+    id;
+    extract;
+    constructor(id, extract) {
+        this.id = id;
+        this.extract = extract;
+    }
+    async embedQuery(text) {
+        const [v] = await this.run([`query: ${clip(text)}`]);
+        return v;
+    }
+    async embedPassages(texts) {
+        const out = [];
+        for (let i = 0; i < texts.length; i += BATCH) {
+            const batch = texts.slice(i, i + BATCH).map((t) => `passage: ${clip(t)}`);
+            out.push(...(await this.run(batch)));
+            // Yield between batches so a large embedding pass never starves
+            // the event loop.
+            await new Promise((r) => setTimeout(r, 0));
+        }
+        return out;
+    }
+    /** Run the model on a batch and split the flat output into per-text vectors. */
+    async run(texts) {
+        const t = await this.extract(texts, { pooling: "mean", normalize: true });
+        const flat = t.data instanceof Float32Array ? t.data : Float32Array.from(t.data);
+        const dim = t.dims[t.dims.length - 1];
+        const vecs = [];
+        for (let i = 0; i < texts.length; i++) {
+            vecs.push(flat.slice(i * dim, (i + 1) * dim));
+        }
+        return vecs;
+    }
+}
+/**
+ * Build an e5 embedder. Loads the transformers.js runtime and the
+ * model (downloaded and cached on first use). Throws — with an
+ * actionable message — if the optional dependency is missing or the
+ * model cannot be fetched.
+ */
+export async function createE5Embedder(modelId = DEFAULT_EMBEDDING_MODEL) {
+    // Indirected through a `string`-typed constant: the TS build does
+    // not try to resolve the optional dependency at compile time.
+    const spec = "@huggingface/transformers";
+    let mod;
+    try {
+        mod = (await import(spec));
+    }
+    catch {
+        throw new Error("semantic search needs the optional dependency '@huggingface/transformers' — " +
+            "install it with `bun add @huggingface/transformers` (or `npm install @huggingface/transformers`)");
+    }
+    let extract;
+    try {
+        extract = await mod.pipeline("feature-extraction", modelId);
+    }
+    catch (e) {
+        throw new Error(`could not load embedding model '${modelId}': ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return new E5Embedder(modelId, extract);
+}
+function clip(text) {
+    return text.length > MAX_CHARS ? text.slice(0, MAX_CHARS) : text;
+}

package/dist/search/embed-pass.d.ts

@@ -0,0 +1,26 @@
+/**
+ * embed-pass.ts — populate the vector store for memories that don't
+ * yet have an embedding.
+ *
+ * Runs only when semantic search is enabled, in the background, after
+ * prefill. It is incremental and crash-safe: vectors are persisted in
+ * chunks, so a memory embedded once is never re-embedded across
+ * sessions, and an interrupted pass simply resumes. A recall issued
+ * before the pass finishes still works — it just fuses against the
+ * vectors that exist so far (gracefully degrading toward pure lexical
+ * search when few are ready).
+ */
+import type { Embedder } from "./embedder.js";
+import type { MemoryRepository } from "../store/repository.js";
+import type { VectorStore } from "../store/vector-store.js";
+/**
+ * Embed every memory that lacks a vector, and drop vectors for
+ * memories that no longer exist (evicted or replaced). Returns the
+ * counts. Never throws into the caller — an embedding failure is
+ * reported via `log` and ends the pass cleanly, leaving lexical
+ * search fully functional.
+ */
+export declare function embedMissingMemories(repo: MemoryRepository, vectorStore: VectorStore, embedder: Embedder, log?: (msg: string) => void): Promise<{
+    embedded: number;
+    pruned: number;
+}>;

package/dist/search/embed-pass.js

@@ -0,0 +1,43 @@
+/**
+ * embed-pass.ts — populate the vector store for memories that don't
+ * yet have an embedding.
+ *
+ * Runs only when semantic search is enabled, in the background, after
+ * prefill. It is incremental and crash-safe: vectors are persisted in
+ * chunks, so a memory embedded once is never re-embedded across
+ * sessions, and an interrupted pass simply resumes. A recall issued
+ * before the pass finishes still works — it just fuses against the
+ * vectors that exist so far (gracefully degrading toward pure lexical
+ * search when few are ready).
+ */
+/** Memories are embedded (and persisted) this many at a time. */
+const CHUNK = 64;
+/**
+ * Embed every memory that lacks a vector, and drop vectors for
+ * memories that no longer exist (evicted or replaced). Returns the
+ * counts. Never throws into the caller — an embedding failure is
+ * reported via `log` and ends the pass cleanly, leaving lexical
+ * search fully functional.
+ */
+export async function embedMissingMemories(repo, vectorStore, embedder, log) {
+    const memories = repo.allMemories();
+    const validIds = new Set(memories.map((m) => m.id));
+    const pruned = vectorStore.prune(validIds);
+    const todo = memories.filter((m) => !vectorStore.has(m.id));
+    let embedded = 0;
+    try {
+        for (let i = 0; i < todo.length; i += CHUNK) {
+            const chunk = todo.slice(i, i + CHUNK);
+            const texts = chunk.map((m) => `${m.subject}\n${m.content}`);
+            const vecs = await embedder.embedPassages(texts);
+            vectorStore.putMany(chunk.map((m, j) => ({ id: m.id, vec: vecs[j] })));
+            embedded += chunk.length;
+        }
+    }
+    catch (e) {
+        log?.(`semantic: embedding pass stopped after ${embedded}/${todo.length} — ` +
+            `${e instanceof Error ? e.message : String(e)} (lexical search unaffected)`);
+        return { embedded, pruned };
+    }
+    return { embedded, pruned };
+}

package/dist/search/embedder.d.ts

@@ -0,0 +1,58 @@
+/**
+ * embedder.ts — the small, dependency-free core of optional semantic
+ * search: the `Embedder` contract, vector math, and reciprocal-rank
+ * fusion.
+ *
+ * Nothing here imports a model runtime. The real e5 implementation
+ * lives in `e5-embedder.ts` and is only loaded when semantic search is
+ * switched on; tests substitute a deterministic stub. Keeping the
+ * contract and the math here means the fusion/retrieval logic is
+ * unit-testable without downloading a 100 MB model.
+ */
+/**
+ * Turns text into a vector. e5 expects asymmetric prefixes — a query
+ * and the passage it should match are embedded differently — so the
+ * contract has two methods rather than one.
+ */
+export interface Embedder {
+    /** Stable model identifier, e.g. "Xenova/multilingual-e5-small". */
+    readonly id: string;
+    /** Embed a search query. */
+    embedQuery(text: string): Promise<Float32Array>;
+    /** Embed a batch of documents/passages. */
+    embedPassages(texts: string[]): Promise<Float32Array[]>;
+}
+/**
+ * Default embedding model — small (~120 MB quantized), ~384-dim, and
+ * trained on 100+ languages, which is what makes cross-lingual recall
+ * (a query in one language, code/comments in another) work.
+ */
+export declare const DEFAULT_EMBEDDING_MODEL = "Xenova/multilingual-e5-small";
+/** L2-normalise a vector in place and return it. A zero vector is left as-is. */
+export declare function normalize(v: Float32Array): Float32Array;
+/**
+ * Cosine similarity of two equal-length vectors, in [-1, 1]. Returns 0
+ * on a length mismatch or a zero vector rather than NaN — a recall
+ * must never crash on a malformed vector.
+ */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/** Dot product — equals cosine similarity when both vectors are L2-normalised. */
+export declare function dot(a: Float32Array, b: Float32Array): number;
+/** An id with a fused score, highest first. */
+export interface FusedItem {
+    id: string;
+    score: number;
+}
+/**
+ * Reciprocal-rank fusion of several ranked id-lists into one ranking.
+ *
+ *   score(id) = Σ_lists 1 / (k + rank_in_list)      rank is 1-based
+ *
+ * RRF is the standard way to merge a lexical (BM25) ranking with a
+ * semantic (vector) ranking: it needs no score calibration between the
+ * two — only the *positions* — and `k` (60 by convention) damps the
+ * influence of low ranks. An id absent from a list simply contributes
+ * nothing for that list. Deterministic; ties broken by first
+ * appearance so the result is stable.
+ */
+export declare function reciprocalRankFusion(lists: string[][], k?: number): FusedItem[];

package/dist/search/embedder.js

@@ -0,0 +1,85 @@
+/**
+ * embedder.ts — the small, dependency-free core of optional semantic
+ * search: the `Embedder` contract, vector math, and reciprocal-rank
+ * fusion.
+ *
+ * Nothing here imports a model runtime. The real e5 implementation
+ * lives in `e5-embedder.ts` and is only loaded when semantic search is
+ * switched on; tests substitute a deterministic stub. Keeping the
+ * contract and the math here means the fusion/retrieval logic is
+ * unit-testable without downloading a 100 MB model.
+ */
+/**
+ * Default embedding model — small (~120 MB quantized), ~384-dim, and
+ * trained on 100+ languages, which is what makes cross-lingual recall
+ * (a query in one language, code/comments in another) work.
+ */
+export const DEFAULT_EMBEDDING_MODEL = "Xenova/multilingual-e5-small";
+/** L2-normalise a vector in place and return it. A zero vector is left as-is. */
+export function normalize(v) {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++)
+        sum += v[i] * v[i];
+    const norm = Math.sqrt(sum);
+    if (norm > 0) {
+        for (let i = 0; i < v.length; i++)
+            v[i] /= norm;
+    }
+    return v;
+}
+/**
+ * Cosine similarity of two equal-length vectors, in [-1, 1]. Returns 0
+ * on a length mismatch or a zero vector rather than NaN — a recall
+ * must never crash on a malformed vector.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    const denom = Math.sqrt(na) * Math.sqrt(nb);
+    return denom > 0 ? dot / denom : 0;
+}
+/** Dot product — equals cosine similarity when both vectors are L2-normalised. */
+export function dot(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d += a[i] * b[i];
+    return d;
+}
+/**
+ * Reciprocal-rank fusion of several ranked id-lists into one ranking.
+ *
+ *   score(id) = Σ_lists 1 / (k + rank_in_list)      rank is 1-based
+ *
+ * RRF is the standard way to merge a lexical (BM25) ranking with a
+ * semantic (vector) ranking: it needs no score calibration between the
+ * two — only the *positions* — and `k` (60 by convention) damps the
+ * influence of low ranks. An id absent from a list simply contributes
+ * nothing for that list. Deterministic; ties broken by first
+ * appearance so the result is stable.
+ */
+export function reciprocalRankFusion(lists, k = 60) {
+    const score = new Map();
+    const firstSeen = new Map();
+    let order = 0;
+    for (const list of lists) {
+        for (let rank = 0; rank < list.length; rank++) {
+            const id = list[rank];
+            score.set(id, (score.get(id) ?? 0) + 1 / (k + rank + 1));
+            if (!firstSeen.has(id))
+                firstSeen.set(id, order++);
+        }
+    }
+    return [...score.entries()]
+        .map(([id, s]) => ({ id, score: s }))
+        .sort((a, b) => b.score - a.score || (firstSeen.get(a.id) - firstSeen.get(b.id)));
+}