fix(knowledge): stop rank fusion from starving the lexical leg

Rank n in one leg always ties rank n in the other, so ordering the fused list
by score alone let whichever leg was scored first take every tied slot. At
topK=1 that meant a hybrid search returned exactly the vector-only result and
discarded the exact keyword match the mode exists to recover.

Selection now orders by score and drains each tie group round-robin, taking
from whichever leg has contributed fewest rows so far. The lexical leg is
passed first so it wins a total tie, since a chunk the vector leg ranked below
its distance threshold is the case hybrid was opted into for.

Author: waleedlatif1

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

@@ -237,7 +237,10 @@ describe('Knowledge Search Utils', () => {
         10
       )
 
-      expect(fused.map((r) => r.id)).toEqual(['shared', 'vector-only', 'keyword-only'])
+      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'])
     })
 
     it('dedupes by chunk id, keeping the first occurrence', () => {
@@ -280,6 +283,48 @@ describe('Knowledge Search Utils', () => {
       expect(fused[0].id).toBe('deep-shared')
     })
 
+    it('does not let the first leg starve the second at small topK', () => {
+      const lexicalOnly = makeResult('lexical-only')
+      const vectorOnly = makeResult('vector-only')
+
+      /**
+       * Rank 1 in each leg scores identically. Ordering by score alone would
+       * always emit the first list's row, so a `topK: 1` hybrid search would
+       * return exactly what vector-only search already returned.
+       */
+      expect(fuseByReciprocalRank([[lexicalOnly], [vectorOnly]], 1).map((r) => r.id)).toEqual([
+        'lexical-only',
+      ])
+      expect(fuseByReciprocalRank([[lexicalOnly], [vectorOnly]], 2).map((r) => r.id)).toEqual([
+        'lexical-only',
+        'vector-only',
+      ])
+    })
+
+    it('interleaves tied ranks so neither leg monopolizes the head', () => {
+      const legA = [makeResult('a1'), makeResult('a2'), makeResult('a3')]
+      const legB = [makeResult('b1'), makeResult('b2'), makeResult('b3')]
+
+      expect(fuseByReciprocalRank([legA, legB], 6).map((r) => r.id)).toEqual([
+        'a1',
+        'b1',
+        'a2',
+        'b2',
+        'a3',
+        'b3',
+      ])
+    })
+
+    it('still floats a row found by both legs above every single-leg row', () => {
+      const shared = makeResult('shared')
+      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'])
+    })
+
     it('trims the fused list to topK', () => {
       const rows = Array.from({ length: 8 }, (_, i) => makeResult(`chunk-${i}`))
 

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

@@ -604,6 +604,14 @@ export async function executeKeywordSearch(params: KeywordSearchParams): Promise
  * Rank fusion is used rather than score normalization because cosine distance
  * and `ts_rank_cd` are on incomparable scales with no corpus-independent
  * mapping between them. Rows are deduped by chunk id, first occurrence wins.
+ *
+ * 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.
  */
 export function fuseByReciprocalRank(rankedLists: SearchResult[][], topK: number): SearchResult[] {
   const scores = new Map<string, number>()
@@ -618,9 +626,56 @@ export function fuseByReciprocalRank(rankedLists: SearchResult[][], topK: number
     })
   }
 
-  return [...rowById.values()]
-    .sort((a, b) => (scores.get(b.id) ?? 0) - (scores.get(a.id) ?? 0))
-    .slice(0, topK)
+  /** 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)
+      }
+    })
+  })
+
+  // Stable sort keeps rowById insertion order (earliest leg first) inside each tie group.
+  const ordered = [...rowById.values()].sort(
+    (a, b) => (scores.get(b.id) ?? 0) - (scores.get(a.id) ?? 0)
+  )
+
+  const contributed = rankedLists.map(() => 0)
+  const fused: SearchResult[] = []
+  let groupStart = 0
+
+  while (groupStart < ordered.length && fused.length < topK) {
+    const groupScore = scores.get(ordered[groupStart].id) ?? 0
+    let groupEnd = groupStart
+    while (groupEnd < ordered.length && (scores.get(ordered[groupEnd].id) ?? 0) === groupScore) {
+      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]
+        ) {
+          pick = i
+        }
+      }
+      const [row] = group.splice(pick, 1)
+      fused.push(row)
+      contributed[legOfRow.get(row.id) ?? 0]++
+    }
+
+    groupStart = groupEnd
+  }
+
+  return fused
 }
 
 export async function handleTagAndVectorSearch(params: SearchParams): Promise<SearchResult[]> {
@@ -725,5 +780,11 @@ export async function executeKnowledgeSearch(
 
   const [vectorResults, keywordResults] = await Promise.all([vectorSearch, keywordSearch])
 
-  return fuseByReciprocalRank([vectorResults, keywordResults], topK)
+  /**
+   * Lexical leg first: on a total tie it wins, which is the behavior this mode
+   * exists for — an exact-token chunk the vector leg ranked below its distance
+   * threshold is precisely what a caller opted into hybrid to recover, and at
+   * `topK: 1` something has to win.
+   */
+  return fuseByReciprocalRank([keywordResults, vectorResults], topK)
 }