feat: --scoring rrf, rank fusion of ego and bm25 (#125)

Author: nikolay-e

CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`--scoring rrf`** — reciprocal-rank fusion of the structural (`ego`) and
+  lexical (`bm25`) signals: each ranks the same candidate universe, and a
+  fragment scores `Σ 1/(k + rank_i)` with `k=60` (`DIFFCTX_RRF_K`). Fusion on
+  ranks alone removes the score-scale calibration between the two signals
+  that made the deployed mixture rank below its own lexical component on
+  genuine retrieval, and the candidate set becomes their union rather than
+  either one alone. EGO's structural guards (hub-noise and
+  generic-config-only suppression) and the per-file cap are re-applied to
+  the union against the fused scores, so the wider candidate set does not
+  leak the noise EGO already rejects. `ego` remains the default (#125).
 - **`--mode locate`** emits the ranked selection as compact
   `diffctx.locate.v1` JSON — path, line range, kind, symbol, relevance score
   and machine-readable provenance reasons (`changed`, `edge` with category /

README.md

@@ -73,7 +73,7 @@ the `--budget` token cap is hit.
 
 | Flag        | Default | Description                                                              |
 |-------------|---------|--------------------------------------------------------------------------|
-| `--scoring` | `ego`   | `ego` = bounded expansion around changed nodes (fast, predictable radius); `ppr` = Personalized PageRank (global, smoother decay, slower); `bm25` = lexical retrieval against the diff hunks (baseline for sparse graphs) |
+| `--scoring` | `ego`   | `ego` = bounded expansion around changed nodes (fast, predictable radius); `ppr` = Personalized PageRank (global, smoother decay, slower); `bm25` = lexical retrieval against the diff hunks (baseline for sparse graphs); `rrf` = reciprocal-rank fusion of `ego` and `bm25` (widest recall, no scale calibration between the two signals) |
 | `--budget`  | auto    | Hard cap in o200k_base tokens (see [Token counting](docs/product/token-budget.md)): `N` enforces a fixed cap, `-1` disables it, `0` is a strict-zero floor (empty selection; use `--full` for changed files only) |
 | `--alpha`   | 0.60    | PPR damping; higher = context clusters tighter around changes (`--scoring ppr` only) |
 | `--tau`     | 0.12    | Relevance threshold for full fragment content; lower-scoring fragments are stubbed or dropped (lower = more context) |

action.yml

@@ -32,7 +32,8 @@ inputs:
   scoring:
     description: >-
       Scoring mode (`--scoring`): `ego` = bounded expansion around the changed
-      nodes, `ppr` = Personalized PageRank, `bm25` = lexical retrieval.
+      nodes, `ppr` = Personalized PageRank, `bm25` = lexical retrieval,
+      `rrf` = reciprocal-rank fusion of `ego` and `bm25`.
     required: false
     default: ego
 

crates/diffctx-native/src/config/scoring.rs

@@ -1,6 +1,6 @@
 use once_cell::sync::Lazy;
 
-use super::env_overrides::{read_env_fraction, read_env_open_fraction};
+use super::env_overrides::{read_env_f64, read_env_fraction, read_env_open_fraction};
 
 pub struct EgoScoringConfig {
     pub identifier_overlap_epsilon: f64,
@@ -19,3 +19,22 @@ impl Default for EgoScoringConfig {
 }
 
 pub static EGO: Lazy<EgoScoringConfig> = Lazy::new(EgoScoringConfig::default);
+
+pub struct RrfConfig {
+    pub k: f64,
+}
+
+impl Default for RrfConfig {
+    fn default() -> Self {
+        Self {
+            // k=60 is the Cormack et al. 2009 constant; it damps the top of
+            // each component list so a rank-1 hit in one signal cannot alone
+            // outrank an item both signals agree on at ranks 2-3.
+            k: read_env_f64("DIFFCTX_RRF_K", 60.0).max(1.0),
+        }
+    }
+}
+
+pub fn rrf() -> RrfConfig {
+    RrfConfig::default()
+}

crates/diffctx-native/src/main.rs

@@ -74,7 +74,7 @@ struct Cli {
     full: bool,
 
     /// Relevance scoring mode
-    #[arg(long, default_value = "ego", value_parser = ["ppr", "ego", "bm25"])]
+    #[arg(long, default_value = "ego", value_parser = ["ppr", "ego", "bm25", "rrf"])]
     scoring: String,
 
     /// Output mode: `pack` = context with source bodies; `locate` = ranked

crates/diffctx-native/src/memory_pipeline.rs

@@ -11,10 +11,10 @@ use crate::config::limits::LIMITS;
 use crate::config::tokenization::TOKENIZATION;
 use crate::core::{compute_seed_weights, identify_core_fragments};
 use crate::edges;
-use crate::mode::{PipelineConfig, ScoringKind, ScoringMode};
+use crate::mode::{PipelineConfig, ScoringMode};
 use crate::parsers::fragment_file;
 use crate::render::{DiffContextOutput, build_diff_context_output};
-use crate::scoring::{BM25Scoring, EgoGraphScoring, PPRScoring, ScoringStrategy};
+use crate::scoring::create_scoring_strategy;
 use crate::signatures::generate_signature_variants;
 use crate::tokenizer::count_tokens;
 use crate::types::{DiffHunk, Fragment, FragmentId};
@@ -104,14 +104,7 @@ pub fn build_diff_context_in_memory(
         .map(|s| Arc::from(s.as_str()))
         .collect();
 
-    let strategy: Box<dyn ScoringStrategy> = match config.scoring {
-        ScoringKind::Ego => Box::new(EgoGraphScoring::new(config.ego_depth)),
-        ScoringKind::Ppr => Box::new(PPRScoring::new(
-            config.ppr_alpha,
-            config.low_relevance_filter,
-        )),
-        ScoringKind::Bm25 => Box::new(BM25Scoring),
-    };
+    let strategy = create_scoring_strategy(&config);
 
     let scoring_result = strategy.score_and_filter(
         &all_fragments,

crates/diffctx-native/src/mode.rs

@@ -6,6 +6,7 @@ pub enum ScoringMode {
     Ppr,
     Ego,
     Bm25,
+    Rrf,
 }
 
 impl ScoringMode {
@@ -14,8 +15,9 @@ impl ScoringMode {
             "ppr" => Ok(Self::Ppr),
             "ego" => Ok(Self::Ego),
             "bm25" => Ok(Self::Bm25),
+            "rrf" => Ok(Self::Rrf),
             other => Err(format!(
-                "unknown scoring_mode '{other}': expected one of ppr|ego|bm25"
+                "unknown scoring_mode '{other}': expected one of ppr|ego|bm25|rrf"
             )),
         }
     }
@@ -32,6 +34,7 @@ pub enum ScoringKind {
     Ppr,
     Ego,
     Bm25,
+    Rrf,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -91,6 +94,18 @@ impl PipelineConfig {
                 ppr_alpha: PPR.alpha,
                 objective: ObjectiveMode::Submodular,
             },
+            // Discovery is deliberately identical to EGO's: the fusion gain
+            // must come from ranking the same universe better, not from a
+            // wider universe that would confound it with a discovery change.
+            ScoringMode::Rrf => Self {
+                discovery: DiscoveryKind::Ensemble,
+                scoring: ScoringKind::Rrf,
+                low_relevance_filter: false,
+                bm25_top_k: m.bm25_top_k_primary,
+                ego_depth: m.ego_depth_extended,
+                ppr_alpha: PPR.alpha,
+                objective: ObjectiveMode::Submodular,
+            },
         }
     }
 }

crates/diffctx-native/src/pipeline.rs

@@ -18,10 +18,10 @@ use crate::discovery::{
 };
 use crate::fragmentation::process_files_for_fragments;
 use crate::git::{self, CatFileBatch};
-use crate::mode::{DiscoveryKind, PipelineConfig, ScoringKind, ScoringMode};
+use crate::mode::{DiscoveryKind, PipelineConfig, ScoringMode};
 use crate::postpass;
 use crate::render::{self, DiffContextOutput};
-use crate::scoring::{BM25Scoring, EgoGraphScoring, PPRScoring, ScoringResult, ScoringStrategy};
+use crate::scoring::{ScoringResult, create_scoring_strategy};
 use crate::signatures::generate_signature_variants;
 use crate::tokenizer::count_tokens;
 use crate::types::{Fragment, FragmentId};
@@ -337,14 +337,7 @@ pub fn compute_scored_state(
         .map(|p| Arc::from(p.to_string_lossy().as_ref()))
         .collect();
 
-    let strategy: Box<dyn ScoringStrategy> = match config.scoring {
-        ScoringKind::Ego => Box::new(EgoGraphScoring::new(config.ego_depth)),
-        ScoringKind::Ppr => Box::new(PPRScoring::new(
-            config.ppr_alpha,
-            config.low_relevance_filter,
-        )),
-        ScoringKind::Bm25 => Box::new(BM25Scoring),
-    };
+    let strategy = create_scoring_strategy(&config);
 
     let scoring_result = strategy.score_and_filter(
         &all_fragments,

crates/diffctx-native/src/scoring.rs

@@ -6,11 +6,12 @@ use rustc_hash::{FxHashMap, FxHashSet};
 
 use crate::config::bm25::BM25;
 use crate::config::limits::{LIMITS, PPR};
-use crate::config::scoring::EGO;
+use crate::config::scoring::{EGO, rrf};
 use crate::config::tokenization::TOKENIZATION;
 use crate::edges;
 use crate::filtering;
 use crate::graph::{self, Graph};
+use crate::mode::{PipelineConfig, ScoringKind};
 use crate::ppr::personalized_pagerank;
 use crate::types::{DiffHunk, Fragment, FragmentId, extract_identifier_list};
 
@@ -30,6 +31,18 @@ pub struct ScoringResult {
     pub ppr_backward_pushes: usize,
 }
 
+pub fn create_scoring_strategy(config: &PipelineConfig) -> Box<dyn ScoringStrategy> {
+    match config.scoring {
+        ScoringKind::Ego => Box::new(EgoGraphScoring::new(config.ego_depth)),
+        ScoringKind::Ppr => Box::new(PPRScoring::new(
+            config.ppr_alpha,
+            config.low_relevance_filter,
+        )),
+        ScoringKind::Bm25 => Box::new(BM25Scoring),
+        ScoringKind::Rrf => Box::new(RrfFusionScoring::new(config.ego_depth)),
+    }
+}
+
 pub trait ScoringStrategy: Send + Sync {
     fn score_and_filter(
         &self,
@@ -282,3 +295,136 @@ impl ScoringStrategy for BM25Scoring {
         }
     }
 }
+
+/// Reciprocal-rank fusion of the structural (EGO) and lexical (BM25) signals.
+///
+/// The two are complementary rather than redundant: on genuine
+/// retrieval the lexical component alone outranks the deployed
+/// graph+lexical mixture, and their score-free union raises the reachable
+/// recall well above either — a miscalibrated-mixture signature. RRF
+/// fuses on ranks only, so neither component's score scale can dominate
+/// the other, which is exactly the failure the weighted mixture had.
+pub struct RrfFusionScoring {
+    pub ego_depth: usize,
+    pub k: f64,
+}
+
+impl RrfFusionScoring {
+    pub fn new(ego_depth: usize) -> Self {
+        Self {
+            ego_depth,
+            k: rrf().k,
+        }
+    }
+}
+
+fn rank_positions(
+    rel: &FxHashMap<FragmentId, f64>,
+    core_ids: &FxHashSet<FragmentId>,
+) -> FxHashMap<FragmentId, usize> {
+    let mut ranked: Vec<(&FragmentId, f64)> = rel
+        .iter()
+        .filter(|(fid, score)| **score > 0.0 && !core_ids.contains(*fid))
+        .map(|(fid, score)| (fid, *score))
+        .collect();
+    // Ties broken by id so the rank list — and therefore every fused
+    // score — is independent of hash-map iteration order.
+    ranked.sort_by(|(ida, sa), (idb, sb)| sb.total_cmp(sa).then_with(|| ida.cmp(idb)));
+    ranked
+        .into_iter()
+        .enumerate()
+        .map(|(i, (fid, _))| (fid.clone(), i + 1))
+        .collect()
+}
+
+fn fuse_reciprocal_ranks(
+    components: &[&FxHashMap<FragmentId, f64>],
+    core_ids: &FxHashSet<FragmentId>,
+    k: f64,
+) -> FxHashMap<FragmentId, f64> {
+    let mut fused: FxHashMap<FragmentId, f64> = FxHashMap::default();
+    for rel in components {
+        for (fid, rank) in rank_positions(rel, core_ids) {
+            *fused.entry(fid).or_insert(0.0) += 1.0 / (k + rank as f64);
+        }
+    }
+
+    let max_fused = fused.values().copied().fold(0.0f64, f64::max);
+    if max_fused > 0.0 {
+        for v in fused.values_mut() {
+            *v /= max_fused;
+        }
+    }
+    // Cores anchor the top of the scale, matching every other strategy —
+    // downstream `r_cap` normalisation and the absolute relevance gates
+    // read these values, so the fused range has to stay [0, 1].
+    for fid in core_ids {
+        fused.insert(fid.clone(), 1.0);
+    }
+    fused
+}
+
+impl ScoringStrategy for RrfFusionScoring {
+    fn score_and_filter(
+        &self,
+        all_fragments: &[Fragment],
+        core_ids: &FxHashSet<FragmentId>,
+        hunks: &[DiffHunk],
+        repo_root: Option<&Path>,
+        seed_weights: Option<&FxHashMap<FragmentId, f64>>,
+        discovered_paths: Option<&FxHashSet<Arc<str>>>,
+    ) -> ScoringResult {
+        let ego = EgoGraphScoring::new(self.ego_depth).score_and_filter(
+            all_fragments,
+            core_ids,
+            hunks,
+            repo_root,
+            seed_weights,
+            discovered_paths,
+        );
+        let lexical = BM25Scoring.score_and_filter(
+            all_fragments,
+            core_ids,
+            hunks,
+            repo_root,
+            seed_weights,
+            discovered_paths,
+        );
+
+        let rel_scores =
+            fuse_reciprocal_ranks(&[&ego.rel_scores, &lexical.rel_scores], core_ids, self.k);
+
+        let mut union_ids: FxHashSet<FragmentId> = ego
+            .filtered_fragments
+            .iter()
+            .map(|f| f.id.clone())
+            .collect();
+        union_ids.extend(lexical.filtered_fragments.iter().map(|f| f.id.clone()));
+
+        let union: Vec<Fragment> = all_fragments
+            .iter()
+            .filter(|f| union_ids.contains(&f.id))
+            .cloned()
+            .collect();
+
+        // The union re-admits paths that EGO's structural guards dropped
+        // (hub noise, generic-config-only code), because BM25 has no graph
+        // to judge them by. Re-applying the guards keeps the fusion a
+        // recall gain rather than a precision regression, and the per-file
+        // cap has to be recomputed against the fused scores since each
+        // component capped against its own.
+        let filtered = filtering::filter_unrelated_fragments(&union, core_ids, &ego.graph);
+        let filtered = filtering::filter_positive_relevance(filtered, core_ids, &rel_scores);
+        let filtered = filtering::cap_context_fragments(filtered, core_ids, &rel_scores);
+
+        ScoringResult {
+            rel_scores,
+            filtered_fragments: filtered,
+            graph: ego.graph,
+            graph_build_ms: ego.graph_build_ms,
+            ppr_truncated: false,
+            ppr_forward_pushes: 0,
+            ppr_backward_pushes: 0,
+        }
+    }
+}

crates/diffctx-native/tests/yaml_cases.rs

@@ -475,11 +475,11 @@ fn main() {
         })
         .collect();
 
-    // Every oracle case above runs Ego. `--scoring ppr` and `--scoring bm25` are
+    // Every oracle case above runs Ego. `--scoring ppr`, `bm25` and `rrf` are
     // documented, user-selectable modes whose only other coverage asserts an
-    // exit code, so either could degrade to changed-files-only and ship green.
+    // exit code, so any of them could degrade to changed-files-only and ship green.
     for c in cases.iter().filter(|c| c.name.starts_with("selection/")) {
-        for scoring in [ScoringMode::Ppr, ScoringMode::Bm25] {
+        for scoring in [ScoringMode::Ppr, ScoringMode::Bm25, ScoringMode::Rrf] {
             let (name, path) = (c.name.clone(), c.path.clone());
             let label = format!("scoring/{scoring:?}/{}", c.name).to_lowercase();
             trials.push(