feat(bench): PPR push-cap truncation flag + mean alongside min

Author: nikolay-e

benchmarks/adapters/calibrate.py

@@ -55,6 +55,17 @@ def score(self) -> float:
             return 0.0
         return min(agg.get("file_recall", 0.0) for agg in self.per_benchmark.values())
 
+    @property
+    def score_mean(self) -> float:
+        """Macro-mean recall across benchmarks. Reported alongside
+        `score` (= min) so the paper can show that the selected cell
+        wins by both — defending against a "cherry-picked min" critique
+        when the surface is flat."""
+        if not self.per_benchmark:
+            return 0.0
+        recalls = [agg.get("file_recall", 0.0) for agg in self.per_benchmark.values()]
+        return sum(recalls) / len(recalls) if recalls else 0.0
+
 
 TrialCallback = Callable[[int, int, "TrialResult"], None]
 

benchmarks/calibrate.py

@@ -127,7 +127,7 @@ def _on_trial(idx: int, total: int, trial) -> None:
         print(
             f"[{idx + 1}/{total}] τ={trial.params.tau:.4f} "
             f"cbf={trial.params.core_budget_fraction:.4f} → "
-            f"min(per_benchmark file_recall) = {trial.score:.4f}"
+            f"min={trial.score:.4f}  mean={trial.score_mean:.4f}"
         )
 
     trials = evaluate_grid_cached(
@@ -153,6 +153,7 @@ def _on_trial(idx: int, total: int, trial) -> None:
             {
                 "params": asdict(t.params),
                 "score": t.score,
+                "score_mean": t.score_mean,
                 "per_benchmark": t.per_benchmark,
             }
             for t in trials
@@ -161,11 +162,15 @@ def _on_trial(idx: int, total: int, trial) -> None:
     (args.out / "grid_results.json").write_text(json.dumps(payload, indent=2, default=str))
 
     top = top_k_trials(trials, k=args.top_k)
-    top_payload = {"top_k": args.top_k, "candidates": [asdict(t.params) for t in top]}
+    top_payload = {
+        "top_k": args.top_k,
+        "candidates": [asdict(t.params) for t in top],
+        "candidate_scores": [{"params": asdict(t.params), "score_min": t.score, "score_mean": t.score_mean} for t in top],
+    }
     (args.out / "top_candidates.json").write_text(json.dumps(top_payload, indent=2, default=str))
-    print(f"\nTop {args.top_k} candidates by min(per_benchmark file_recall):")
+    print(f"\nTop {args.top_k} candidates by min(per_benchmark file_recall) [mean shown for cherry-pick check]:")
     for t in top:
-        print(f"  τ={t.params.tau} cbf={t.params.core_budget_fraction} score={t.score:.4f}")
+        print(f"  τ={t.params.tau} cbf={t.params.core_budget_fraction}" f"  min={t.score:.4f}  mean={t.score_mean:.4f}")
     return 0
 
 

diffctx/src/pipeline.rs

@@ -432,6 +432,9 @@ pub fn select_with_params(
         edges_dropped_by_cap: cap_stats.edges_dropped_by_cap,
         nodes_capped: cap_stats.nodes_capped,
         max_out_edges_per_node: cap_stats.max_out_edges_per_node,
+        ppr_truncated: state.scoring_result.ppr_truncated,
+        ppr_forward_pushes: state.scoring_result.ppr_forward_pushes,
+        ppr_backward_pushes: state.scoring_result.ppr_backward_pushes,
     });
     output
 }
@@ -496,6 +499,9 @@ fn empty_scored_state(root_dir: PathBuf) -> ScoredState {
             rel_scores: FxHashMap::default(),
             filtered_fragments: Vec::new(),
             graph: crate::graph::Graph::new(),
+            ppr_truncated: false,
+            ppr_forward_pushes: 0,
+            ppr_backward_pushes: 0,
         },
         needs: Vec::new(),
         changed_files: Vec::new(),

diffctx/src/ppr.rs

@@ -47,16 +47,32 @@ fn init_seed_residuals(
     residual
 }
 
+/// Result of one PPR push pass. `truncated` flags whether the
+/// `max_pushes` budget cut the iteration short — when true, the
+/// returned estimate is biased toward seeds and the absolute scores
+/// are not comparable to a converged run on the same graph. Surfaced
+/// to Python via `LatencyBreakdown.ppr_truncated` so calibration /
+/// final-eval rows can be filtered or flagged for the paper.
+struct PprPushResult {
+    estimate: Vec<f64>,
+    pushes: usize,
+    truncated: bool,
+}
+
 fn ppr_push_csr(
     csr: &CsrGraph,
     seeds: &FxHashSet<FragmentId>,
     alpha: f64,
     tol: f64,
     seed_weights: Option<&FxHashMap<FragmentId, f64>>,
-) -> Vec<f64> {
+) -> PprPushResult {
     let n = csr.n;
     if n == 0 {
-        return Vec::new();
+        return PprPushResult {
+            estimate: Vec::new(),
+            pushes: 0,
+            truncated: false,
+        };
     }
 
     let restart = 1.0 - alpha;
@@ -74,9 +90,11 @@ fn ppr_push_csr(
 
     let max_pushes = (n * PPR.push_scale_factor).min(PPR.max_pushes_cap);
     let mut pushes: usize = 0;
+    let mut truncated = false;
 
     while let Some(u) = queue.pop_front() {
         if pushes >= max_pushes {
+            truncated = true;
             break;
         }
         let ui = u as usize;
@@ -114,7 +132,26 @@ fn ppr_push_csr(
         pushes += 1;
     }
 
-    estimate
+    PprPushResult {
+        estimate,
+        pushes,
+        truncated,
+    }
+}
+
+/// Public PPR result. `truncated` is logical-OR of forward + backward
+/// push truncation flags. When true, downstream renormalization
+/// (sum-to-1 across nodes) hides the fact that the iteration was cut
+/// short by `max_pushes_cap`; the absolute relevance scores are
+/// biased toward seeds and not directly comparable across instances.
+/// We surface this to Python so calibration / final-eval rows can be
+/// filtered in post-analysis (PolyBench / Multi-SWE-bench instances
+/// with >20k fragments are the primary suspects).
+pub struct PprResult {
+    pub scores: FxHashMap<FragmentId, f64>,
+    pub truncated: bool,
+    pub forward_pushes: usize,
+    pub backward_pushes: usize,
 }
 
 pub fn personalized_pagerank(
@@ -124,26 +161,28 @@ pub fn personalized_pagerank(
     tol: f64,
     forward_blend: f64,
     seed_weights: Option<&FxHashMap<FragmentId, f64>>,
-) -> FxHashMap<FragmentId, f64> {
-    if graph.node_count() == 0 {
-        return FxHashMap::default();
-    }
-
-    if seeds.is_empty() {
-        return FxHashMap::default();
+) -> PprResult {
+    if graph.node_count() == 0 || seeds.is_empty() {
+        return PprResult {
+            scores: FxHashMap::default(),
+            truncated: false,
+            forward_pushes: 0,
+            backward_pushes: 0,
+        };
     }
 
     let (fwd_csr, rev_csr) = graph.to_csr();
 
-    let (forward_est, backward_est) = rayon::join(
+    let (forward, backward) = rayon::join(
         || ppr_push_csr(fwd_csr, seeds, alpha, tol, seed_weights),
         || ppr_push_csr(rev_csr, seeds, alpha, tol, seed_weights),
     );
 
     let n = fwd_csr.n;
     let mut combined = vec![0.0f64; n];
     for i in 0..n {
-        combined[i] = forward_blend * forward_est[i] + (1.0 - forward_blend) * backward_est[i];
+        combined[i] =
+            forward_blend * forward.estimate[i] + (1.0 - forward_blend) * backward.estimate[i];
     }
 
     let total: f64 = combined.iter().sum();
@@ -154,14 +193,19 @@ pub fn personalized_pagerank(
     }
 
     let idx_to_node = &fwd_csr.idx_to_node;
-    let mut result: FxHashMap<FragmentId, f64> = FxHashMap::default();
+    let mut scores: FxHashMap<FragmentId, f64> = FxHashMap::default();
     for i in 0..n {
         if combined[i] > 0.0 {
-            result.insert(idx_to_node[i].clone(), combined[i]);
+            scores.insert(idx_to_node[i].clone(), combined[i]);
         }
     }
 
-    result
+    PprResult {
+        scores,
+        truncated: forward.truncated || backward.truncated,
+        forward_pushes: forward.pushes,
+        backward_pushes: backward.pushes,
+    }
 }
 
 #[cfg(test)]
@@ -177,7 +221,7 @@ mod tests {
     fn ppr_empty_graph() {
         let mut g = Graph::new();
         let seeds = FxHashSet::default();
-        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-4, 0.4, None);
+        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-4, 0.4, None).scores;
         assert!(result.is_empty());
     }
 
@@ -189,7 +233,7 @@ mod tests {
 
         let mut seeds = FxHashSet::default();
         seeds.insert(a.clone());
-        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-4, 0.4, None);
+        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-4, 0.4, None).scores;
         assert!((result[&a] - 1.0).abs() < 1e-6);
     }
 
@@ -207,7 +251,7 @@ mod tests {
 
         let mut seeds = FxHashSet::default();
         seeds.insert(a.clone());
-        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-6, 0.4, None);
+        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-6, 0.4, None).scores;
 
         assert!(result[&a] > result[&b]);
         assert!(result[&b] > result[&c]);
@@ -228,7 +272,7 @@ mod tests {
 
         let mut seeds = FxHashSet::default();
         seeds.insert(a.clone());
-        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-6, 0.4, None);
+        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-6, 0.4, None).scores;
 
         let total: f64 = result.values().sum();
         assert!((total - 1.0).abs() < 1e-6);
@@ -251,7 +295,7 @@ mod tests {
         sw.insert(a.clone(), 0.9);
         sw.insert(b.clone(), 0.1);
 
-        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-6, 0.4, Some(&sw));
+        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-6, 0.4, Some(&sw)).scores;
         assert!(result[&a] > result[&b]);
     }
 
@@ -274,8 +318,8 @@ mod tests {
         let (mut g2, _) = build_star_graph();
         let seeds: FxHashSet<FragmentId> = std::iter::once(center).collect();
 
-        let r1 = personalized_pagerank(&mut g1, &seeds, 0.6, 1e-6, 0.4, None);
-        let r2 = personalized_pagerank(&mut g2, &seeds, 0.6, 1e-6, 0.4, None);
+        let r1 = personalized_pagerank(&mut g1, &seeds, 0.6, 1e-6, 0.4, None).scores;
+        let r2 = personalized_pagerank(&mut g2, &seeds, 0.6, 1e-6, 0.4, None).scores;
 
         assert_eq!(r1.len(), r2.len());
         for (id, v1) in &r1 {
@@ -290,8 +334,8 @@ mod tests {
         let (mut g_tight, _) = build_star_graph();
         let seeds: FxHashSet<FragmentId> = std::iter::once(center).collect();
 
-        let loose = personalized_pagerank(&mut g_loose, &seeds, 0.6, 1e-2, 0.4, None);
-        let tight = personalized_pagerank(&mut g_tight, &seeds, 0.6, 1e-6, 0.4, None);
+        let loose = personalized_pagerank(&mut g_loose, &seeds, 0.6, 1e-2, 0.4, None).scores;
+        let tight = personalized_pagerank(&mut g_tight, &seeds, 0.6, 1e-6, 0.4, None).scores;
 
         let max_diff = loose
             .iter()
@@ -307,7 +351,7 @@ mod tests {
     fn ppr_symmetric_star_assigns_equal_mass_to_leaves() {
         let (mut g, center) = build_star_graph();
         let seeds: FxHashSet<FragmentId> = std::iter::once(center.clone()).collect();
-        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-8, 0.5, None);
+        let result = personalized_pagerank(&mut g, &seeds, 0.6, 1e-8, 0.5, None).scores;
 
         let leaf_scores: Vec<f64> = (0..5)
             .map(|i| result[&fid(&format!("leaf_{i}.rs"), 1, 10)])
@@ -384,8 +428,9 @@ mod tests {
         let tol = 1e-8;
         let blend = 1.0;
 
-        let r_naive = personalized_pagerank(&mut naive, &seeds, alpha, tol, blend, None);
-        let r_suppressed = personalized_pagerank(&mut suppressed, &seeds, alpha, tol, blend, None);
+        let r_naive = personalized_pagerank(&mut naive, &seeds, alpha, tol, blend, None).scores;
+        let r_suppressed =
+            personalized_pagerank(&mut suppressed, &seeds, alpha, tol, blend, None).scores;
 
         let hub_naive = r_naive.get(&hub).copied().unwrap_or(0.0);
         let hub_suppressed = r_suppressed.get(&hub).copied().unwrap_or(0.0);
@@ -449,7 +494,7 @@ mod tests {
         }
 
         let seeds: FxHashSet<FragmentId> = nodes.iter().take(2).cloned().collect();
-        let ppr_scores = personalized_pagerank(&mut g, &seeds, 0.6, 1e-8, 0.5, None);
+        let ppr_scores = personalized_pagerank(&mut g, &seeds, 0.6, 1e-8, 0.5, None).scores;
         let ego_scores = g.ego_graph(&seeds, 3);
 
         let common: Vec<FragmentId> = nodes
@@ -535,7 +580,7 @@ mod tests {
                 g.add_edge(leaf.clone(), center.clone(), 1.0);
             }
             let seeds: FxHashSet<FragmentId> = std::iter::once(center.clone()).collect();
-            let result = personalized_pagerank(&mut g, &seeds, alpha, 1e-10, 0.5, None);
+            let result = personalized_pagerank(&mut g, &seeds, alpha, 1e-10, 0.5, None).scores;
 
             let expected_center = 1.0 / (1.0 + alpha);
             let expected_leaf = alpha / (n_leaves as f64 * (1.0 + alpha));

diffctx/src/pybridge.rs

@@ -306,6 +306,9 @@ fn build_diff_context<'py>(
         latency.set_item("edges_dropped_by_cap", lb.edges_dropped_by_cap)?;
         latency.set_item("nodes_capped", lb.nodes_capped)?;
         latency.set_item("max_out_edges_per_node", lb.max_out_edges_per_node)?;
+        latency.set_item("ppr_truncated", lb.ppr_truncated)?;
+        latency.set_item("ppr_forward_pushes", lb.ppr_forward_pushes)?;
+        latency.set_item("ppr_backward_pushes", lb.ppr_backward_pushes)?;
     } else {
         latency.set_item("total_ms", (total_ms * 10.0).round() / 10.0)?;
     }
@@ -424,6 +427,9 @@ fn diff_context_output_to_dict<'py>(
         latency.set_item("edges_dropped_by_cap", lb.edges_dropped_by_cap)?;
         latency.set_item("nodes_capped", lb.nodes_capped)?;
         latency.set_item("max_out_edges_per_node", lb.max_out_edges_per_node)?;
+        latency.set_item("ppr_truncated", lb.ppr_truncated)?;
+        latency.set_item("ppr_forward_pushes", lb.ppr_forward_pushes)?;
+        latency.set_item("ppr_backward_pushes", lb.ppr_backward_pushes)?;
     }
     dict.set_item("latency", latency)?;
     Ok(dict)

diffctx/src/render.rs

@@ -58,6 +58,13 @@ pub struct LatencyBreakdown {
     pub nodes_capped: usize,
     /// The K value applied for the per-source cap.
     pub max_out_edges_per_node: usize,
+    /// PPR push iteration was truncated by `max_pushes_cap` before
+    /// convergence. When true, `rel_scores` are biased toward seeds
+    /// and absolute file_recall on this instance should be flagged
+    /// in post-analysis. Always false for non-PPR scoring modes.
+    pub ppr_truncated: bool,
+    pub ppr_forward_pushes: usize,
+    pub ppr_backward_pushes: usize,
 }
 
 #[derive(Serialize, Clone)]