feat(rag): hybrid multi-path search with RRF fusion

Add configurable hybrid mode on KnowledgeSearchPort that fuses dense unfiltered, dense filtered, and lexical ranks via RRF while preserving dense-compatible threshold scores. Archives Delivery 2 OpenSpec change.
2026-07-27 18:33:31 +08:00
parent ac1f831903
commit 376ad0c241
19 changed files with 661 additions and 8 deletions
@@ -0,0 +1,46 @@
+# rag-hybrid-search Specification
+
+## Purpose
+TBD - created by archiving change rag-hybrid-search-rrf. Update Purpose after archive.
+## Requirements
+### Requirement: Knowledge search SHALL support configurable dense and hybrid modes
+
+The knowledge search port SHALL support `retrieval.search.mode` values `dense` and `hybrid`. Default SHALL be `dense` for backward-compatible behavior.
+
+#### Scenario: Dense mode single path
+
+- **WHEN** mode is dense
+- **THEN** the port SHALL perform a single dense vector search with the provided category filter
+
+#### Scenario: Hybrid mode multi-path fusion
+
+- **WHEN** mode is hybrid
+- **THEN** the port SHALL gather multiple retrieval paths and fuse them by RRF before returning hits
+
+### Requirement: Hybrid fusion SHALL use RRF over evidence identities
+
+Hybrid fusion SHALL score candidates by reciprocal rank fusion on evidenceKey identities and SHALL NOT require comparable raw scores across paths.
+
+#### Scenario: Multi-path candidate rises with RRF
+
+- **WHEN** a chunk ranks highly on more than one hybrid path
+- **THEN** its fused rank SHALL improve relative to a chunk that ranks highly on only one path
+
+### Requirement: Hybrid SHALL preserve dense quality scores for thresholds
+
+Fused ordering SHALL NOT replace the dense compatibility score used by post-process quality thresholds.
+
+#### Scenario: Threshold score remains dense-compatible
+
+- **WHEN** hybrid returns a hit that originated from dense search
+- **THEN** hit.score SHALL remain a dense-compatible distance/similarity mapping usable by existing normalizeL2 thresholds
+
+### Requirement: Hybrid SHALL keep chunk identity fields
+
+Hybrid hits SHALL populate docId, chunkIndex, and evidenceKey consistently with Delivery 1 identity rules.
+
+#### Scenario: Fused hit keeps evidenceKey
+
+- **WHEN** hybrid merges the same chunk from two paths
+- **THEN** the returned hit SHALL use one evidenceKey and retain chunk identity metadata
+