fix(knowledge): credit a shared hit to every leg that returned it

Attributing a row found by both legs to a single leg left the round-robin
owing the other leg a slot it had already been served. With a shared rank-1
hit and topK 2, that evicted the lexical-only row — the exact match hybrid was
enabled to recover — in favor of the vector-only one.

A shared row satisfied every leg that returned it, so every one of them is now
charged for it. Tie-breaking prefers the candidate whose least-served leg has
been served least, which also removes the arbitrary best-rank attribution.

Author: waleedlatif1

apps/sim/app/api/knowledge/search/utils.test.ts

@@ -238,9 +238,9 @@ describe('Knowledge Search Utils', () => {
       )
 
       expect(fused[0].id).toBe('shared')
-      // The two single-leg rows tie; `shared` was already credited to leg 0, so
-      // the round-robin owes leg 1 the next slot.
-      expect(fused.map((r) => r.id)).toEqual(['shared', 'keyword-only', 'vector-only'])
+      // `shared` is credited to both legs, so the following tie is even and
+      // resolves to the earliest list.
+      expect(fused.map((r) => r.id)).toEqual(['shared', 'vector-only', 'keyword-only'])
     })
 
     it('dedupes by chunk id, keeping the first occurrence', () => {
@@ -320,9 +320,29 @@ describe('Knowledge Search Utils', () => {
       const legA = [makeResult('a1'), shared]
       const legB = [makeResult('b1'), shared]
 
-      // shared is rank 2 in both legs (2/62) and outscores either rank-1 row (1/61);
-      // it is credited to leg A, so tied `a1`/`b1` resolve in leg B's favor.
-      expect(fuseByReciprocalRank([legA, legB], 3).map((r) => r.id)).toEqual(['shared', 'b1', 'a1'])
+      // shared is rank 2 in both legs (2/62) and outscores either rank-1 row (1/61).
+      expect(fuseByReciprocalRank([legA, legB], 3).map((r) => r.id)).toEqual(['shared', 'a1', 'b1'])
+    })
+
+    it('does not let a shared top hit evict the lexical-only row at topK 2', () => {
+      const shared = makeResult('shared')
+      const lexicalOnly = makeResult('lexical-only')
+      const vectorOnly = makeResult('vector-only')
+
+      /**
+       * `shared` is rank 1 in both legs. Crediting it to only one leg would
+       * leave the round-robin owing the other leg the remaining slot, evicting
+       * the row that only the shared hit's leg could produce.
+       */
+      const fused = fuseByReciprocalRank(
+        [
+          [shared, lexicalOnly],
+          [shared, vectorOnly],
+        ],
+        2
+      )
+
+      expect(fused.map((r) => r.id)).toEqual(['shared', 'lexical-only'])
     })
 
     it('trims the fused list to topK', () => {

apps/sim/app/api/knowledge/search/utils.ts

@@ -608,33 +608,32 @@ export async function executeKeywordSearch(params: KeywordSearchParams): Promise
  * Equal scores are common and must not be broken by list order: rank *n* in one
  * leg always ties rank *n* in every other leg, so sorting alone would let the
  * first list monopolize the head of the output and starve the others entirely
- * at small `topK`. Selection therefore drains the legs round-robin among tied
- * candidates, and a candidate from a leg that has contributed fewer rows so far
- * wins the tie. A total tie goes to the earliest list, so callers put the leg
- * whose hits the other leg cannot produce first.
+ * at small `topK`. Selection therefore drains each tie group round-robin,
+ * preferring the candidate whose least-served leg has been served least.
+ *
+ * A row is credited to *every* leg that returned it, not to one chosen leg: it
+ * satisfied all of them, and charging a shared hit to a single leg would leave
+ * the round-robin owing the other one a slot it has already been served —
+ * which at small `topK` evicts a row only the shared hit's leg could produce.
+ * A total tie goes to the earliest list, so callers put the leg whose hits the
+ * other leg cannot produce first.
  */
 export function fuseByReciprocalRank(rankedLists: SearchResult[][], topK: number): SearchResult[] {
   const scores = new Map<string, number>()
   const rowById = new Map<string, SearchResult>()
+  const legsOfRow = new Map<string, number[]>()
 
-  for (const list of rankedLists) {
+  rankedLists.forEach((list, leg) => {
     list.forEach((row, index) => {
       scores.set(row.id, (scores.get(row.id) ?? 0) + 1 / (RRF_K + index + 1))
       if (!rowById.has(row.id)) {
         rowById.set(row.id, row)
       }
-    })
-  }
-
-  /** Leg each row is attributed to for interleaving: where it ranked best, earliest leg wins. */
-  const legOfRow = new Map<string, number>()
-  const bestRankOfRow = new Map<string, number>()
-  rankedLists.forEach((list, leg) => {
-    list.forEach((row, index) => {
-      const currentBest = bestRankOfRow.get(row.id)
-      if (currentBest === undefined || index < currentBest) {
-        bestRankOfRow.set(row.id, index)
-        legOfRow.set(row.id, leg)
+      const legs = legsOfRow.get(row.id)
+      if (legs) {
+        if (!legs.includes(leg)) legs.push(leg)
+      } else {
+        legsOfRow.set(row.id, [leg])
       }
     })
   })
@@ -645,6 +644,10 @@ export function fuseByReciprocalRank(rankedLists: SearchResult[][], topK: number
   )
 
   const contributed = rankedLists.map(() => 0)
+  /** How starved a candidate's most-neglected leg is; lower wins the tie. */
+  const starvation = (id: string) =>
+    Math.min(...(legsOfRow.get(id) ?? [0]).map((leg) => contributed[leg]))
+
   const fused: SearchResult[] = []
   let groupStart = 0
 
@@ -655,21 +658,19 @@ export function fuseByReciprocalRank(rankedLists: SearchResult[][], topK: number
       groupEnd++
     }
 
-    // Drain this tie group round-robin, always taking from the leg that has contributed least.
     const group = ordered.slice(groupStart, groupEnd)
     while (group.length > 0 && fused.length < topK) {
       let pick = 0
       for (let i = 1; i < group.length; i++) {
-        if (
-          contributed[legOfRow.get(group[i].id) ?? 0] <
-          contributed[legOfRow.get(group[pick].id) ?? 0]
-        ) {
+        if (starvation(group[i].id) < starvation(group[pick].id)) {
           pick = i
         }
       }
       const [row] = group.splice(pick, 1)
       fused.push(row)
-      contributed[legOfRow.get(row.id) ?? 0]++
+      for (const leg of legsOfRow.get(row.id) ?? []) {
+        contributed[leg]++
+      }
     }
 
     groupStart = groupEnd