perf(graph): top-K out-edges per source cap (default K=64)

Pathological code repos (django, mui) emit 3M+ raw edges before
hub-suppression even with similarity/history skipped. Source of the
blowup is dense semantic edges from utility files importing into
hundreds of modules. PPR push then iterates over all those edges,
making scoring p99 ~187 seconds.

Cap each source node to the top-K outgoing edges by weight after
hub_suppression. K=64 preserves typical 30-50 edges/node while
clamping pathological hubs. On treemapper itself: 3M -> 363k edges
(88% reduction), scoring 8s -> 3.5s.

K is env-tunable via DIFFCTX_MAX_EDGES_PER_NODE. Cap stats
(edges_before_cap, edges_dropped_by_cap, nodes_capped, K applied)
surface through LatencyBreakdown so calibration runs can quantify
how often the cap fires per benchmark.

Order matters: cap runs AFTER apply_hub_suppression so suppression's
IDF damping sees the true in-degree distribution.

Author: nikolay-e

diffctx/src/graph.rs

@@ -64,12 +64,32 @@ pub struct CsrGraph {
     pub idx_to_node: Vec<FragmentId>,
 }
 
+/// Statistics from the per-source out-edge cap that runs in
+/// `build_graph` after `apply_hub_suppression`. Surfaced to Python
+/// via `LatencyBreakdown` so calibration runs can quantify how often
+/// the cap fires and how many edges it discards.
+#[derive(Default, Clone, Copy)]
+pub struct EdgeCapStats {
+    /// Edge count after merge + hub suppression, before cap.
+    pub edges_before_cap: usize,
+    /// Edge count after cap.
+    pub edges_after_cap: usize,
+    /// Edges discarded by the cap (lowest-weight neighbors of overfull nodes).
+    pub edges_dropped_by_cap: usize,
+    /// Number of source nodes that had > `max_per_node` outgoing edges
+    /// and therefore had their neighbor list truncated.
+    pub nodes_capped: usize,
+    /// The `max_per_node` value actually applied (after env-var override).
+    pub max_out_edges_per_node: usize,
+}
+
 pub struct Graph {
     nodes: FxHashSet<FragmentId>,
     fwd: FxHashMap<FragmentId, FxHashMap<FragmentId, f64>>,
     rev: FxHashMap<FragmentId, FxHashMap<FragmentId, f64>>,
     pub edge_categories: FxHashMap<(FragmentId, FragmentId), EdgeCategory>,
     csr_cache: Option<(CsrGraph, CsrGraph)>,
+    pub cap_stats: EdgeCapStats,
 }
 
 impl Graph {
@@ -80,6 +100,7 @@ impl Graph {
             rev: FxHashMap::default(),
             edge_categories: FxHashMap::default(),
             csr_cache: None,
+            cap_stats: EdgeCapStats::default(),
         }
     }
 
@@ -419,6 +440,62 @@ fn apply_hub_suppression(
     }
 }
 
+/// Default top-K out-edges per source node. Calibrated against the
+/// observed edge density distribution: typical Python file emits
+/// 5-20 semantic + 2-5 structural + ≤20 sibling edges (~30-50 normal),
+/// so K=64 preserves all legitimate edges while clamping pathological
+/// dense nodes (e.g. utility hubs in django/material-ui that radiate
+/// into thousands of dependents).
+const DEFAULT_MAX_OUT_EDGES_PER_NODE: usize = 64;
+
+/// Truncate each node's outgoing edge list to the top-K by weight.
+/// Run AFTER `apply_hub_suppression` so the suppression pass sees
+/// the true in-degree distribution; otherwise its IDF damping is
+/// computed against a graph that has already been thinned.
+///
+/// Returns the cap stats for diagnostic surfacing into `LatencyBreakdown`.
+fn cap_out_edges_per_source(
+    edges: &mut FxHashMap<(FragmentId, FragmentId), f64>,
+    max_per_node: usize,
+) -> EdgeCapStats {
+    let edges_before = edges.len();
+
+    let mut by_src: FxHashMap<FragmentId, Vec<(FragmentId, f64)>> = FxHashMap::default();
+    for ((src, dst), w) in edges.drain() {
+        by_src.entry(src).or_default().push((dst, w));
+    }
+
+    let mut nodes_capped = 0;
+    let mut edges_dropped = 0;
+    for (src, mut neighbors) in by_src {
+        if neighbors.len() > max_per_node {
+            nodes_capped += 1;
+            edges_dropped += neighbors.len() - max_per_node;
+            neighbors.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
+            neighbors.truncate(max_per_node);
+        }
+        for (dst, w) in neighbors {
+            edges.insert((src.clone(), dst), w);
+        }
+    }
+
+    EdgeCapStats {
+        edges_before_cap: edges_before,
+        edges_after_cap: edges.len(),
+        edges_dropped_by_cap: edges_dropped,
+        nodes_capped,
+        max_out_edges_per_node: max_per_node,
+    }
+}
+
+fn read_max_out_edges_per_node() -> usize {
+    std::env::var("DIFFCTX_MAX_EDGES_PER_NODE")
+        .ok()
+        .and_then(|v| v.parse::<usize>().ok())
+        .filter(|&v| v > 0)
+        .unwrap_or(DEFAULT_MAX_OUT_EDGES_PER_NODE)
+}
+
 pub fn build_graph(
     fragments: &[Fragment],
     mut edges: FxHashMap<(FragmentId, FragmentId), f64>,
@@ -431,6 +508,17 @@ pub fn build_graph(
 
     apply_hub_suppression(&mut edges, &categories);
 
+    let max_per_node = read_max_out_edges_per_node();
+    let cap_stats = cap_out_edges_per_source(&mut edges, max_per_node);
+    tracing::debug!(
+        "edge cap K={}: {} -> {} (dropped {} from {} nodes)",
+        max_per_node,
+        cap_stats.edges_before_cap,
+        cap_stats.edges_after_cap,
+        cap_stats.edges_dropped_by_cap,
+        cap_stats.nodes_capped,
+    );
+
     for ((src, dst), w) in edges {
         if w > 0.0 {
             graph
@@ -443,6 +531,7 @@ pub fn build_graph(
     }
 
     graph.edge_categories = categories;
+    graph.cap_stats = cap_stats;
     graph.freeze();
     graph
 }

diffctx/src/pipeline.rs

@@ -413,6 +413,7 @@ pub fn select_with_params(
         + state.heavy_latency_ms.scoring
         + select_ms;
 
+    let cap_stats = state.scoring_result.graph.cap_stats;
     let mut output = render::build_diff_context_output(&state.root_dir, &selected, no_content);
     output.latency = Some(render::LatencyBreakdown {
         parse_changed_ms: state.heavy_latency_ms.parse_changed,
@@ -427,6 +428,10 @@ pub fn select_with_params(
         candidate_count: state.scoring_result.filtered_fragments.len(),
         edge_count: state.scoring_result.graph.edge_count(),
         greedy_iters: selection_iters,
+        edges_before_cap: cap_stats.edges_before_cap,
+        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,
     });
     output
 }

diffctx/src/pybridge.rs

@@ -302,6 +302,10 @@ fn build_diff_context<'py>(
         latency.set_item("candidate_count", lb.candidate_count)?;
         latency.set_item("edge_count", lb.edge_count)?;
         latency.set_item("greedy_iters", lb.greedy_iters)?;
+        latency.set_item("edges_before_cap", lb.edges_before_cap)?;
+        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)?;
     } else {
         latency.set_item("total_ms", (total_ms * 10.0).round() / 10.0)?;
     }
@@ -416,6 +420,10 @@ fn diff_context_output_to_dict<'py>(
         latency.set_item("candidate_count", lb.candidate_count)?;
         latency.set_item("edge_count", lb.edge_count)?;
         latency.set_item("greedy_iters", lb.greedy_iters)?;
+        latency.set_item("edges_before_cap", lb.edges_before_cap)?;
+        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)?;
     }
     dict.set_item("latency", latency)?;
     Ok(dict)

diffctx/src/render.rs

@@ -50,6 +50,14 @@ pub struct LatencyBreakdown {
     /// fragments). Bounded by `selected.len() - core.len()`. Pairs with
     /// `selection_ms` to spot lazy-heap blowup vs. genuine large output.
     pub greedy_iters: usize,
+    /// Edge count after merge + hub suppression, before per-source cap.
+    pub edges_before_cap: usize,
+    /// Edges discarded by the per-source top-K cap.
+    pub edges_dropped_by_cap: usize,
+    /// Source nodes whose outgoing edge list was truncated by the cap.
+    pub nodes_capped: usize,
+    /// The K value applied for the per-source cap.
+    pub max_out_edges_per_node: usize,
 }
 
 #[derive(Serialize, Clone)]