{"version":3,"file":"rrf.d.ts","sourceRoot":"","sources":["../../../src/core/search/rrf.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,SAAgB,GAAG,QAAQ,EAAE,CA6C/F","sourcesContent":["/**\n * Reciprocal Rank Fusion — the transparent, rank-only recall layer of hybrid\n * search (docs/hybrid-retrieval-design.md, Decision 2).\n *\n * Rank-only on purpose: BM25 and cosine scores are not comparable across\n * retrievers, so raw scores are carried through as diagnostics but never\n * enter the fused score.\n */\n\nimport type { FusedHit, RankedHit } from \"./types.js\";\n\n/**\n * Default RRF constant, re-swept on the 62-query harness.\n *\n * History matters here, because the answer changed twice. The original\n * 12-query gold set picked k = 2 over k = 60; that measurement ran on an\n * unpinned corpus with a file-level metric and was never reproducible. The\n * 62-query re-sweep then found the two *indistinguishable* — a 3pp R@10 gap\n * carried by two queries (p = 0.50), with MRR worse on more queries than it\n * was better.\n *\n * What made k decidable was fixing the reranker. Once it could tell a\n * declaration from a call site, the deeper, flatter candidate mix that k = 60\n * produces became worth having: MRR 0.403 -> 0.464, 20 queries better against\n * 7 worse (p <= 0.05), with R@10 unchanged. Small k keeps fusion top-heavy\n * toward each retriever's best hits, which only pays when the reranker cannot\n * exploit the tail — and it now can.\n *\n * Re-sweep again (`bun run search-eval:compare`) after any reranker change,\n * since that is what this value trades against.\n */\nexport const DEFAULT_RRF_K = 60;\n\n/**\n * Fuse ranked lists into one deterministic ordering by summed `1/(k + rank)`.\n *\n * Ties break by number of agreeing retrievers, then lexicographic id, so the\n * same inputs always produce the same context.\n *\n * Duplicate `source:id` pairs within one list are counted once (best rank\n * wins). The adapter dedupes upstream, so this guard should never fire in\n * practice — it exists so a misbehaving retriever cannot inflate its vote.\n */\nexport function rrfFuse(lists: readonly (readonly RankedHit[])[], k = DEFAULT_RRF_K): FusedHit[] {\n\tif (!Number.isFinite(k) || k < 0) {\n\t\tthrow new Error(`RRF k must be a finite non-negative number; got ${k}`);\n\t}\n\n\tconst acc = new Map<string, FusedHit>();\n\n\tfor (const list of lists) {\n\t\t// Collapse duplicates to their best rank first, so the single vote a\n\t\t// duplicated id gets is cast at the best rank regardless of emit order.\n\t\tconst collapsed = new Map<string, RankedHit>();\n\t\tfor (const hit of list) {\n\t\t\tif (!Number.isInteger(hit.rank) || hit.rank < 1) {\n\t\t\t\tthrow new Error(`RRF rank must be a positive integer; got ${hit.rank}`);\n\t\t\t}\n\t\t\tconst dedupeKey = `${hit.source}:${hit.id}`;\n\t\t\tconst existing = collapsed.get(dedupeKey);\n\t\t\tif (!existing || hit.rank < existing.rank) collapsed.set(dedupeKey, hit);\n\t\t}\n\n\t\tfor (const hit of collapsed.values()) {\n\t\t\tlet current = acc.get(hit.id);\n\t\t\tif (!current) {\n\t\t\t\tcurrent = { id: hit.id, rrfScore: 0, ranks: {}, rawScores: {} };\n\t\t\t\tacc.set(hit.id, current);\n\t\t\t}\n\n\t\t\tcurrent.rrfScore += 1 / (k + hit.rank);\n\n\t\t\tconst oldRank = current.ranks[hit.source];\n\t\t\tif (oldRank === undefined || hit.rank < oldRank) {\n\t\t\t\tcurrent.ranks[hit.source] = hit.rank;\n\t\t\t\t// rawScores follows the best rank; a best-ranked hit without a\n\t\t\t\t// score leaves any earlier score in place rather than erasing it.\n\t\t\t\tif (hit.score !== undefined) current.rawScores[hit.source] = hit.score;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn [...acc.values()].sort(\n\t\t(a, b) =>\n\t\t\tb.rrfScore - a.rrfScore ||\n\t\t\tObject.keys(b.ranks).length - Object.keys(a.ranks).length ||\n\t\t\ta.id.localeCompare(b.id),\n\t);\n}\n"]}