feat: add RRF fusion and position-aware score blending

Implement reciprocal rank fusion (rrf.ts) to merge BM25 and vector
search ranked lists with weighted contributions and rank bonuses.
Add position-aware score blending (blend.ts) that combines RRF scores
with reranker scores using tiered weights (top3/mid/tail).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/pipeline/blend.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect } from "vitest";
+import { blendScores } from "./blend";
+import type { RRFResult } from "../types";
+import { BLEND_TOP3_RRF, BLEND_MID_RRF, BLEND_TAIL_RRF } from "../constants";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeRRFResult(
+  docId: string,
+  score: number,
+  title = `Title ${docId}`,
+): RRFResult {
+  return {
+    docId,
+    filepath: docId,
+    title,
+    bestChunk: `chunk from ${docId}`,
+    score,
+    contributions: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// blendScores
+// ---------------------------------------------------------------------------
+describe("blendScores", () => {
+  it("returns empty array for empty input", () => {
+    expect(blendScores([], new Map())).toEqual([]);
+  });
+
+  it("uses top3 weight for rank 1-3", () => {
+    const rrfResults = [
+      makeRRFResult("doc1", 0.5),
+      makeRRFResult("doc2", 0.4),
+      makeRRFResult("doc3", 0.3),
+    ];
+    const rerankScores = new Map([
+      ["doc1", 0.9],
+      ["doc2", 0.8],
+      ["doc3", 0.7],
+    ]);
+    const results = blendScores(rrfResults, rerankScores);
+    // All three should use BLEND_TOP3_RRF weight
+    // doc1: 0.75*0.5 + 0.25*0.9 = 0.375 + 0.225 = 0.600
+    const doc1 = results.find((r) => r.docId === "doc1")!;
+    const expected1 = BLEND_TOP3_RRF * 0.5 + (1 - BLEND_TOP3_RRF) * 0.9;
+    expect(doc1.score).toBeCloseTo(expected1, 10);
+  });
+
+  it("uses mid weight for rank 4-10", () => {
+    // Create 5 results; rank 4 and 5 should use mid weight
+    const rrfResults = Array.from({ length: 5 }, (_, i) =>
+      makeRRFResult(`doc${i}`, 0.5 - i * 0.05),
+    );
+    const rerankScores = new Map<string, number>([["doc3", 0.9]]);
+
+    const results = blendScores(rrfResults, rerankScores);
+    // doc3 is at rank 4 in RRF ordering -> uses BLEND_MID_RRF
+    const doc3 = results.find((r) => r.docId === "doc3")!;
+    const expected = BLEND_MID_RRF * 0.35 + (1 - BLEND_MID_RRF) * 0.9;
+    expect(doc3.score).toBeCloseTo(expected, 10);
+  });
+
+  it("uses tail weight for rank 11+", () => {
+    const rrfResults = Array.from({ length: 12 }, (_, i) =>
+      makeRRFResult(`doc${i}`, 0.5 - i * 0.03),
+    );
+    const rerankScores = new Map<string, number>([["doc11", 0.95]]);
+
+    const results = blendScores(rrfResults, rerankScores);
+    // doc11 is at rank 12 -> uses BLEND_TAIL_RRF
+    const doc11 = results.find((r) => r.docId === "doc11")!;
+    const rrfScore = 0.5 - 11 * 0.03; // 0.17
+    const expected = BLEND_TAIL_RRF * rrfScore + (1 - BLEND_TAIL_RRF) * 0.95;
+    expect(doc11.score).toBeCloseTo(expected, 10);
+  });
+
+  it("defaults missing rerank scores to 0", () => {
+    const rrfResults = [makeRRFResult("doc1", 0.5)];
+    const rerankScores = new Map<string, number>(); // no rerank score for doc1
+    const results = blendScores(rrfResults, rerankScores);
+    // score = 0.75 * 0.5 + 0.25 * 0 = 0.375
+    expect(results[0].score).toBeCloseTo(BLEND_TOP3_RRF * 0.5, 10);
+  });
+
+  it("sorts by blended score descending", () => {
+    const rrfResults = [
+      makeRRFResult("doc1", 0.5),
+      makeRRFResult("doc2", 0.4),
+      makeRRFResult("doc3", 0.3),
+    ];
+    // High rerank score on doc3 should push it up
+    const rerankScores = new Map([
+      ["doc1", 0.1],
+      ["doc2", 0.2],
+      ["doc3", 0.99],
+    ]);
+    const results = blendScores(rrfResults, rerankScores);
+    for (let i = 1; i < results.length; i++) {
+      expect(results[i].score).toBeLessThanOrEqual(results[i - 1].score);
+    }
+  });
+
+  it("can reorder results when reranker disagrees with RRF", () => {
+    const rrfResults = [
+      makeRRFResult("doc1", 0.5),
+      makeRRFResult("doc2", 0.49),
+    ];
+    // doc2 gets much higher rerank score
+    const rerankScores = new Map([
+      ["doc1", 0.0],
+      ["doc2", 1.0],
+    ]);
+    const results = blendScores(rrfResults, rerankScores);
+    // doc1: 0.75*0.5 + 0.25*0.0 = 0.375
+    // doc2: 0.75*0.49 + 0.25*1.0 = 0.3675 + 0.25 = 0.6175
+    expect(results[0].docId).toBe("doc2");
+  });
+
+  it("preserves filepath, title, bestChunk in final results", () => {
+    const rrfResults = [makeRRFResult("doc1", 0.5, "My Title")];
+    const results = blendScores(rrfResults, new Map());
+    expect(results[0].filepath).toBe("doc1");
+    expect(results[0].title).toBe("My Title");
+    expect(results[0].bestChunk).toBe("chunk from doc1");
+    expect(results[0].docId).toBe("doc1");
+  });
+
+  it("deduplicates by docId, keeping highest blended score", () => {
+    // This shouldn't normally happen since RRF already deduplicates,
+    // but the function handles it defensively
+    const rrfResults = [
+      makeRRFResult("doc1", 0.5),
+      makeRRFResult("doc1", 0.3), // duplicate
+    ];
+    const rerankScores = new Map([["doc1", 0.8]]);
+    const results = blendScores(rrfResults, rerankScores);
+    expect(results).toHaveLength(1);
+    expect(results[0].docId).toBe("doc1");
+  });
+
+  it("handles single result correctly", () => {
+    const rrfResults = [makeRRFResult("doc1", 0.42)];
+    const rerankScores = new Map([["doc1", 0.88]]);
+    const results = blendScores(rrfResults, rerankScores);
+    expect(results).toHaveLength(1);
+    const expected = BLEND_TOP3_RRF * 0.42 + (1 - BLEND_TOP3_RRF) * 0.88;
+    expect(results[0].score).toBeCloseTo(expected, 10);
+  });
+
+  it("weight transitions are correct at boundaries", () => {
+    // Create exactly 11 results, check ranks 3, 4, 10, 11
+    const rrfResults = Array.from({ length: 11 }, (_, i) =>
+      makeRRFResult(`doc${i}`, 1.0), // same RRF score
+    );
+    const rerankScores = new Map<string, number>();
+    // Give all the same rerank score so we can check weight differences
+    for (let i = 0; i < 11; i++) {
+      rerankScores.set(`doc${i}`, 1.0);
+    }
+
+    const results = blendScores(rrfResults, rerankScores);
+    // All should have blended score = weight * 1.0 + (1-weight) * 1.0 = 1.0
+    // regardless of weight, since both inputs are 1.0
+    for (const r of results) {
+      expect(r.score).toBeCloseTo(1.0, 10);
+    }
+  });
+
+  it("correctly applies different weights when scores differ", () => {
+    // 11 results with identical RRF=0.5, rerank=1.0
+    const rrfResults = Array.from({ length: 11 }, (_, i) =>
+      makeRRFResult(`doc${i}`, 0.5),
+    );
+    const rerankScores = new Map<string, number>();
+    for (let i = 0; i < 11; i++) {
+      rerankScores.set(`doc${i}`, 1.0);
+    }
+
+    const results = blendScores(rrfResults, rerankScores);
+    // Rank 1-3: 0.75*0.5 + 0.25*1.0 = 0.625
+    // Rank 4-10: 0.60*0.5 + 0.40*1.0 = 0.700
+    // Rank 11: 0.40*0.5 + 0.60*1.0 = 0.800
+    // So rank 11 should have highest score (tail weight favors reranker more)
+    const topScore = results[0].score;
+    expect(topScore).toBeCloseTo(0.8, 10); // rank 11 doc
+  });
+});

src/pipeline/blend.ts

@@ -0,0 +1,57 @@
+import type { RRFResult, RerankedResult, FinalResult } from "../types";
+import { BLEND_TOP3_RRF, BLEND_MID_RRF, BLEND_TAIL_RRF } from "../constants";
+
+// Blend RRF score with reranker score using position-aware weights
+export function blendScores(
+  rrfResults: RRFResult[],
+  rerankScores: Map<string, number>, // docId -> rerank score
+): FinalResult[] {
+  const blended: RerankedResult[] = rrfResults.map((result, index) => {
+    const rank = index + 1; // 1-indexed position in RRF ordering
+    const rerankScore = rerankScores.get(result.docId) ?? 0;
+
+    // Position-aware RRF weight (from QMD):
+    //   Rank 1-3:  75% RRF + 25% reranker
+    //   Rank 4-10: 60% RRF + 40% reranker
+    //   Rank 11+:  40% RRF + 60% reranker
+    let rrfWeight: number;
+    if (rank <= 3) {
+      rrfWeight = BLEND_TOP3_RRF; // 0.75
+    } else if (rank <= 10) {
+      rrfWeight = BLEND_MID_RRF; // 0.60
+    } else {
+      rrfWeight = BLEND_TAIL_RRF; // 0.40
+    }
+
+    // Normalize RRF score to [0,1] range for blending
+    // (RRF scores vary based on number of lists, so normalize by max)
+    const blendedScore =
+      rrfWeight * result.score + (1 - rrfWeight) * rerankScore;
+
+    return {
+      ...result,
+      rerankScore,
+      blendedScore,
+    };
+  });
+
+  // Sort by blended score descending
+  blended.sort((a, b) => b.blendedScore - a.blendedScore);
+
+  // Dedup by docId (keep highest blended score)
+  const seen = new Set<string>();
+  const final: FinalResult[] = [];
+  for (const result of blended) {
+    if (seen.has(result.docId)) continue;
+    seen.add(result.docId);
+    final.push({
+      filepath: result.filepath,
+      title: result.title,
+      bestChunk: result.bestChunk,
+      score: result.blendedScore,
+      docId: result.docId,
+    });
+  }
+
+  return final;
+}

src/pipeline/rrf.test.ts

@@ -0,0 +1,223 @@
+import { describe, it, expect } from "vitest";
+import { reciprocalRankFusion } from "./rrf";
+import type { ScoredChunk } from "../types";
+import {
+  RRF_K,
+  RRF_PRIMARY_WEIGHT,
+  RRF_SECONDARY_WEIGHT,
+  RRF_RANK1_BONUS,
+  RRF_RANK2_BONUS,
+} from "../constants";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeScoredChunk(
+  docId: string,
+  score: number,
+  source: "bm25" | "vector" = "bm25",
+  text = `chunk from ${docId}`,
+): ScoredChunk {
+  return {
+    chunk: { docId, chunkIndex: 0, text, startChar: 0, title: `Title ${docId}` },
+    score,
+    source,
+  };
+}
+
+function makeList(
+  results: ScoredChunk[],
+  queryType: "original" | "lex" | "vec" | "hyde" = "original",
+  query = "test query",
+) {
+  return { results, queryType, query };
+}
+
+// ---------------------------------------------------------------------------
+// reciprocalRankFusion
+// ---------------------------------------------------------------------------
+describe("reciprocalRankFusion", () => {
+  it("returns empty array for empty input", () => {
+    expect(reciprocalRankFusion([])).toEqual([]);
+  });
+
+  it("returns empty array for lists with no results", () => {
+    const result = reciprocalRankFusion([
+      makeList([]),
+      makeList([]),
+    ]);
+    expect(result).toEqual([]);
+  });
+
+  it("computes correct RRF score for a single list with one result", () => {
+    const results = reciprocalRankFusion([
+      makeList([makeScoredChunk("doc1", 0.9)]),
+    ]);
+    expect(results).toHaveLength(1);
+    // rank=1, weight=PRIMARY(2.0), score = 2/(60+1) + rank1 bonus + rank2 bonus
+    const expected = RRF_PRIMARY_WEIGHT / (RRF_K + 1) + RRF_RANK1_BONUS + RRF_RANK2_BONUS;
+    expect(results[0].score).toBeCloseTo(expected, 10);
+    expect(results[0].docId).toBe("doc1");
+  });
+
+  it("uses primary weight for first two lists and secondary for rest", () => {
+    // doc1 appears at rank 1 in all three lists
+    const results = reciprocalRankFusion([
+      makeList([makeScoredChunk("doc1", 0.9)], "original"),
+      makeList([makeScoredChunk("doc1", 0.8)], "lex"),
+      makeList([makeScoredChunk("doc1", 0.7)], "vec"),
+    ]);
+    expect(results).toHaveLength(1);
+    // Lists 0,1 use PRIMARY weight, list 2 uses SECONDARY weight
+    const rrfBase =
+      RRF_PRIMARY_WEIGHT / (RRF_K + 1) +
+      RRF_PRIMARY_WEIGHT / (RRF_K + 1) +
+      RRF_SECONDARY_WEIGHT / (RRF_K + 1);
+    const expected = rrfBase + RRF_RANK1_BONUS + RRF_RANK2_BONUS;
+    expect(results[0].score).toBeCloseTo(expected, 10);
+  });
+
+  it("merges results from different lists for the same docId", () => {
+    const results = reciprocalRankFusion([
+      makeList([makeScoredChunk("doc1", 0.9)], "original"),
+      makeList([makeScoredChunk("doc1", 0.8, "vector")], "vec"),
+    ]);
+    expect(results).toHaveLength(1);
+    expect(results[0].contributions).toHaveLength(2);
+    expect(results[0].contributions[0].source).toBe("bm25");
+    expect(results[0].contributions[1].source).toBe("vector");
+  });
+
+  it("keeps the best chunk (highest individual score) per doc", () => {
+    const results = reciprocalRankFusion([
+      makeList([makeScoredChunk("doc1", 0.5, "bm25", "low score chunk")], "original"),
+      makeList([makeScoredChunk("doc1", 0.9, "vector", "high score chunk")], "vec"),
+    ]);
+    expect(results[0].bestChunk).toBe("high score chunk");
+  });
+
+  it("ranks documents by total RRF score descending", () => {
+    // doc1 appears in both lists, doc2 only in one
+    const results = reciprocalRankFusion([
+      makeList(
+        [makeScoredChunk("doc1", 0.9), makeScoredChunk("doc2", 0.8)],
+        "original",
+      ),
+      makeList([makeScoredChunk("doc1", 0.7, "vector")], "vec"),
+    ]);
+    expect(results[0].docId).toBe("doc1");
+    expect(results[1].docId).toBe("doc2");
+    expect(results[0].score).toBeGreaterThan(results[1].score);
+  });
+
+  it("applies rank 1 bonus only to docs that are rank 1 in some list", () => {
+    const results = reciprocalRankFusion([
+      makeList(
+        [makeScoredChunk("doc1", 0.9), makeScoredChunk("doc2", 0.8)],
+        "original",
+      ),
+    ]);
+    // doc1 is rank 1 -> gets both bonuses
+    // doc2 is rank 2 -> gets only rank2 bonus
+    const doc1Score = RRF_PRIMARY_WEIGHT / (RRF_K + 1) + RRF_RANK1_BONUS + RRF_RANK2_BONUS;
+    const doc2Score = RRF_PRIMARY_WEIGHT / (RRF_K + 2) + RRF_RANK2_BONUS;
+    expect(results[0].score).toBeCloseTo(doc1Score, 10);
+    expect(results[1].score).toBeCloseTo(doc2Score, 10);
+  });
+
+  it("does not apply rank bonuses to docs ranked 3 or lower", () => {
+    const results = reciprocalRankFusion([
+      makeList(
+        [
+          makeScoredChunk("doc1", 0.9),
+          makeScoredChunk("doc2", 0.8),
+          makeScoredChunk("doc3", 0.7),
+        ],
+        "original",
+      ),
+    ]);
+    const doc3Score = RRF_PRIMARY_WEIGHT / (RRF_K + 3); // no bonuses
+    expect(results[2].score).toBeCloseTo(doc3Score, 10);
+  });
+
+  it("respects candidateLimit", () => {
+    const chunks = Array.from({ length: 10 }, (_, i) =>
+      makeScoredChunk(`doc${i}`, 1 - i * 0.1),
+    );
+    const results = reciprocalRankFusion([makeList(chunks)], 3);
+    expect(results).toHaveLength(3);
+  });
+
+  it("tracks contributions correctly with queryType and query", () => {
+    const results = reciprocalRankFusion([
+      makeList([makeScoredChunk("doc1", 0.9)], "original", "hello world"),
+      makeList([makeScoredChunk("doc1", 0.8, "vector")], "hyde", "hypothetical doc"),
+    ]);
+    const contribs = results[0].contributions;
+    expect(contribs[0].queryType).toBe("original");
+    expect(contribs[0].query).toBe("hello world");
+    expect(contribs[1].queryType).toBe("hyde");
+    expect(contribs[1].query).toBe("hypothetical doc");
+  });
+
+  it("uses correct rank within each list independently", () => {
+    // doc1 is rank 2 in list 0, rank 1 in list 1
+    const results = reciprocalRankFusion([
+      makeList(
+        [makeScoredChunk("doc0", 0.9), makeScoredChunk("doc1", 0.8)],
+        "original",
+      ),
+      makeList([makeScoredChunk("doc1", 0.95, "vector")], "vec"),
+    ]);
+    const doc1 = results.find((r) => r.docId === "doc1")!;
+    // From list 0: rank=2, from list 1: rank=1 -> topRank=1
+    expect(doc1.contributions).toHaveLength(2);
+    expect(doc1.contributions[0].rank).toBe(2);
+    expect(doc1.contributions[1].rank).toBe(1);
+    // Should get rank1 bonus since topRank=1
+    const expectedScore =
+      RRF_PRIMARY_WEIGHT / (RRF_K + 2) +
+      RRF_PRIMARY_WEIGHT / (RRF_K + 1) +
+      RRF_RANK1_BONUS +
+      RRF_RANK2_BONUS;
+    expect(doc1.score).toBeCloseTo(expectedScore, 10);
+  });
+
+  it("sets filepath equal to docId", () => {
+    const results = reciprocalRankFusion([
+      makeList([makeScoredChunk("my-file.md", 0.9)]),
+    ]);
+    expect(results[0].filepath).toBe("my-file.md");
+  });
+
+  it("preserves title from the chunk", () => {
+    const results = reciprocalRankFusion([
+      makeList([makeScoredChunk("doc1", 0.9)]),
+    ]);
+    expect(results[0].title).toBe("Title doc1");
+  });
+
+  it("handles many lists (>2) with correct weight assignment", () => {
+    const results = reciprocalRankFusion([
+      makeList([makeScoredChunk("doc1", 0.9)], "original"),
+      makeList([makeScoredChunk("doc1", 0.8)], "lex"),
+      makeList([makeScoredChunk("doc1", 0.7)], "vec"),
+      makeList([makeScoredChunk("doc1", 0.6)], "hyde"),
+    ]);
+    expect(results[0].contributions).toHaveLength(4);
+    // First two use primary weight
+    expect(results[0].contributions[0].weight).toBe(RRF_PRIMARY_WEIGHT);
+    expect(results[0].contributions[1].weight).toBe(RRF_PRIMARY_WEIGHT);
+    // Rest use secondary weight
+    expect(results[0].contributions[2].weight).toBe(RRF_SECONDARY_WEIGHT);
+    expect(results[0].contributions[3].weight).toBe(RRF_SECONDARY_WEIGHT);
+  });
+
+  it("default candidateLimit is RERANK_CANDIDATE_LIMIT (40)", () => {
+    const chunks = Array.from({ length: 50 }, (_, i) =>
+      makeScoredChunk(`doc${i}`, 1 - i * 0.01),
+    );
+    const results = reciprocalRankFusion([makeList(chunks)]);
+    expect(results).toHaveLength(40);
+  });
+});

src/pipeline/rrf.ts

@@ -0,0 +1,118 @@
+import type { ScoredChunk, RRFResult, RRFContribution } from "../types";
+import {
+  RRF_K,
+  RRF_PRIMARY_WEIGHT,
+  RRF_SECONDARY_WEIGHT,
+  RRF_RANK1_BONUS,
+  RRF_RANK2_BONUS,
+  RERANK_CANDIDATE_LIMIT,
+} from "../constants";
+
+interface RankedList {
+  results: ScoredChunk[];
+  queryType: "original" | "lex" | "vec" | "hyde";
+  query: string;
+}
+
+// Merge multiple ranked lists using Reciprocal Rank Fusion
+export function reciprocalRankFusion(
+  lists: RankedList[],
+  candidateLimit: number = RERANK_CANDIDATE_LIMIT,
+): RRFResult[] {
+  // For each document across all lists, compute RRF score:
+  //   score = Σ (weight / (k + rank))
+  //
+  // Weight rules (from QMD):
+  //   - First 2 lists: weight = RRF_PRIMARY_WEIGHT (2.0)
+  //   - Remaining lists: weight = RRF_SECONDARY_WEIGHT (1.0)
+  //
+  // Rank bonuses:
+  //   - Rank 1 in any list: +RRF_RANK1_BONUS (0.05)
+  //   - Rank 1 or 2 in any list: +RRF_RANK2_BONUS (0.02)
+  //
+  // Group by docId (not chunk), keep the best chunk per doc.
+  // Sort by total score descending, return top candidateLimit.
+
+  const docScores = new Map<
+    string,
+    {
+      docId: string;
+      filepath: string;
+      title: string;
+      bestChunk: string;
+      bestChunkScore: number;
+      totalScore: number;
+      topRank: number;
+      contributions: RRFContribution[];
+    }
+  >();
+
+  lists.forEach((list, listIndex) => {
+    const weight = listIndex < 2 ? RRF_PRIMARY_WEIGHT : RRF_SECONDARY_WEIGHT;
+
+    list.results.forEach((result, rankIndex) => {
+      const rank = rankIndex + 1; // 1-indexed
+      const rrfContribution = weight / (RRF_K + rank);
+
+      const existing = docScores.get(result.chunk.docId);
+      if (existing) {
+        existing.totalScore += rrfContribution;
+        existing.topRank = Math.min(existing.topRank, rank);
+        existing.contributions.push({
+          source: result.source,
+          queryType: list.queryType,
+          query: list.query,
+          rank,
+          weight,
+          rrfContribution,
+        });
+        // Keep the chunk with the highest individual score
+        if (result.score > existing.bestChunkScore) {
+          existing.bestChunk = result.chunk.text;
+          existing.bestChunkScore = result.score;
+        }
+      } else {
+        docScores.set(result.chunk.docId, {
+          docId: result.chunk.docId,
+          filepath: result.chunk.docId, // In browser demo, docId = filepath
+          title: result.chunk.title,
+          bestChunk: result.chunk.text,
+          bestChunkScore: result.score,
+          totalScore: rrfContribution,
+          topRank: rank,
+          contributions: [
+            {
+              source: result.source,
+              queryType: list.queryType,
+              query: list.query,
+              rank,
+              weight,
+              rrfContribution,
+            },
+          ],
+        });
+      }
+    });
+  });
+
+  // Apply rank bonuses
+  for (const doc of docScores.values()) {
+    if (doc.topRank === 1) doc.totalScore += RRF_RANK1_BONUS;
+    if (doc.topRank <= 2) doc.totalScore += RRF_RANK2_BONUS;
+  }
+
+  // Sort and slice
+  const results = Array.from(docScores.values())
+    .sort((a, b) => b.totalScore - a.totalScore)
+    .slice(0, candidateLimit)
+    .map((doc) => ({
+      docId: doc.docId,
+      filepath: doc.filepath,
+      title: doc.title,
+      bestChunk: doc.bestChunk,
+      score: doc.totalScore,
+      contributions: doc.contributions,
+    }));
+
+  return results;
+}