perf: skip unselected scan in BnbIter via per-branch cursor

The flamegraph after the delta-aware refactor showed ~32% of run_bnb
time spent walking candidate_order and checking
Bitset::contains(selected) || Bitset::contains(banned) per element,
inlined into insert_new_branches's `cs.unselected().next()`. As BnB
descends and more candidates get selected/banned, each .next() call
scans further before finding the next viable candidate.

But BnB never re-considers a position: each branch's exploration only
moves forward in candidate_order. Inclusion advances by 1; exclusion
advances past every consecutive same-(value, weight) candidate. So we
can store a per-Branch cursor and avoid the scan entirely.

Add `Branch::cursor: usize` (the position the branch will expand on
next). The init branch starts at 0; insert_new_branches advances past
any pre-selected/pre-banned positions on demand, then expands at the
located cursor and hands children their new cursors directly.

One subtlety: the exclusion branch's same-(value, weight) dedup run now
walks raw candidate_order positions, where the old `unselected()` scan
skipped already-decided candidates implicitly. The run must do the same
explicitly -- skip pre-selected/pre-banned positions (advancing the
cursor past them) rather than banning them or letting them end the run.
Otherwise a caller-pre-selected candidate that duplicates an excluded
one ends up simultaneously selected and banned in the selector that
run_bnb hands back, and a pre-decided candidate inside a duplicate run
fragments the equivalence class into redundant branches. Covered by
`bnb_exclusion_dedup_skips_decided_candidates`.

Bench (run_bnb_lowest_fee, n = pool size):

  n=20     166 us -> 147 us  (11%)
  n=50    5.3 ms -> 4.5 ms   (16%)
  n=100   12.6 ms -> 11.5 ms  (9%)
  n=500   200 ms -> 171 ms   (14%)
  n=1000  365 ms -> 248 ms   (32%)

(n >= 200 rows are the exhaust-cap group: fixed 100k rounds of frontier
expansion, so they measure pure per-round cost.)

Largest win at large n where the unselected scan was burning the most
time. Flamegraph confirms the unselected-scan hot spot is gone; new top
is LowestFee::bound itself (the metric's float math + lookahead).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: evanlinjin

Cargo.toml

@@ -29,3 +29,8 @@ criterion = "0.5"
 [[bench]]
 name = "coin_selector"
 harness = false
+
+# Enable debug symbols so profilers (perf, samply, flamegraph) can resolve
+# function names. No runtime cost.
+[profile.bench]
+debug = true

src/bnb.rs

@@ -1,3 +1,17 @@
+//! Branch-and-bound search.
+//!
+//! BnB explores a binary tree where each [`Branch`] expands into two
+//! children: an *inclusion* child that selects the candidate at the
+//! branch's `cursor`, and an *exclusion* child that bans it along with
+//! any same-(value, weight) duplicates that immediately follow.
+//!
+//! Cursors only advance as we descend — inclusion's child has cursor
+//! `parent + 1`; exclusion's jumps past the banned duplicates. That
+//! invariant lets `insert_new_branches` skip directly to the next
+//! undecided candidate without re-scanning `selected` / `banned`. The
+//! only scanning happens to step past pre-selected / pre-banned positions
+//! (rare, lazy).
+
 use core::cmp::Reverse;
 
 use crate::{float::Ordf32, Drain, SelectionCache, SelectionView, Target};
@@ -61,6 +75,7 @@ impl<'a, M: BnbMetric> Iterator for BnbIter<'a, M> {
             selector,
             cache,
             is_exclusion,
+            cursor,
             ..
         } = branch;
 
@@ -79,7 +94,7 @@ impl<'a, M: BnbMetric> Iterator for BnbIter<'a, M> {
             };
         }
 
-        self.insert_new_branches(&selector, &cache);
+        self.insert_new_branches(&selector, &cache, cursor);
         Some(return_val.map(|score| (selector, score)))
     }
 }
@@ -98,7 +113,7 @@ impl<'a, M: BnbMetric> BnbIter<'a, M> {
         }
 
         let cache = SelectionCache::from_selector(&selector);
-        iter.consider_adding_to_queue(&selector, &cache, false);
+        iter.consider_adding_to_queue(&selector, &cache, false, 0);
 
         iter
     }
@@ -108,6 +123,7 @@ impl<'a, M: BnbMetric> BnbIter<'a, M> {
         cs: &CoinSelector<'a>,
         cache: &SelectionCache,
         is_exclusion: bool,
+        cursor: usize,
     ) {
         let bound = self
             .metric
@@ -123,34 +139,63 @@ impl<'a, M: BnbMetric> BnbIter<'a, M> {
                     selector: cs.clone(),
                     cache: cache.clone(),
                     is_exclusion,
+                    cursor,
                 });
             }
         }
     }
 
-    fn insert_new_branches(&mut self, cs: &CoinSelector<'a>, cache: &SelectionCache) {
-        let (next_index, next) = match cs.unselected().next() {
-            Some(c) => c,
-            None => return, // exhausted
+    fn insert_new_branches(&mut self, cs: &CoinSelector<'a>, cache: &SelectionCache, start: usize) {
+        // Find the position to expand on: at or after `start`, whichever is
+        // the first candidate that's neither selected nor banned. Usually
+        // this *is* `start` — the only reason to advance is to skip past
+        // pre-selected/pre-banned candidates (see module-level docs).
+        let mut iter = cs.candidates().skip(start);
+        let mut cursor = start;
+        let (here_idx, here_cand) = loop {
+            match iter.next() {
+                None => return, // no more candidates — this branch is a leaf
+                Some((idx, cand)) => {
+                    if !cs.is_selected(idx) && !cs.banned().contains(idx) {
+                        break (idx, cand);
+                    }
+                    cursor += 1;
+                }
+            }
         };
+        // Past here, `iter` is positioned at `cursor + 1`.
 
-        // Inclusion branch: selecting `next_index` requires updating the cache.
+        // Inclusion: descendants explore "this candidate is selected".
         let mut inclusion_cs = cs.clone();
         let mut inclusion_cache = cache.clone();
-        inclusion_cs.select(next_index);
-        inclusion_cache.add(next);
-        self.consider_adding_to_queue(&inclusion_cs, &inclusion_cache, false);
+        inclusion_cs.select(here_idx);
+        inclusion_cache.add(here_cand);
+        self.consider_adding_to_queue(&inclusion_cs, &inclusion_cache, false, cursor + 1);
 
-        // Exclusion branch: only bans, no selection change → cache unchanged.
+        // Exclusion: descendants explore "this candidate is *not* selected".
+        // Bans this and every consecutive same-(value, weight) candidate —
+        // they're equivalent choices, so we deduplicate by handling the
+        // entire equivalence class in one branch. The cursor jumps past
+        // all of them.
         let mut exclusion_cs = cs.clone();
-        let to_ban = (next.value, next.weight);
-        for (ban_index, ban_cand) in cs.unselected() {
-            if (ban_cand.value, ban_cand.weight) != to_ban {
+        exclusion_cs.ban(here_idx);
+        let equiv = (here_cand.value, here_cand.weight);
+        let mut exclusion_cursor = cursor + 1;
+        for (idx, cand) in iter {
+            // Already-decided candidates (pre-selected or banned) must not be banned and must not
+            // end the equivalence run: the pre-cursor version scanned `unselected()`, which skips
+            // them entirely. The cursor may still advance past them — they're decided.
+            if cs.is_selected(idx) || cs.banned().contains(idx) {
+                exclusion_cursor += 1;
+                continue;
+            }
+            if (cand.value, cand.weight) != equiv {
                 break;
             }
-            exclusion_cs.ban(ban_index);
+            exclusion_cs.ban(idx);
+            exclusion_cursor += 1;
         }
-        self.consider_adding_to_queue(&exclusion_cs, cache, true);
+        self.consider_adding_to_queue(&exclusion_cs, cache, true, exclusion_cursor);
     }
 }
 
@@ -160,6 +205,10 @@ struct Branch<'a> {
     selector: CoinSelector<'a>,
     cache: SelectionCache,
     is_exclusion: bool,
+    /// Position in `candidate_order` of the candidate whose include /
+    /// exclude decision creates this branch's two children. See the
+    /// module-level "Cursor invariant" section.
+    cursor: usize,
 }
 
 impl Ord for Branch<'_> {

tests/bnb.rs

@@ -148,6 +148,51 @@ fn bnb_finds_solution_if_possible_in_n_iter() {
     assert_eq!(excess, 0);
 }
 
+#[test]
+/// The exclusion branch's same-(value, weight) dedup run must skip already-decided candidates
+/// instead of banning them (a pre-selected candidate must never end up banned) or letting them
+/// end the run early.
+///
+/// Regression test: candidate 1 is pre-selected by the caller and shares (value, weight) with
+/// candidate 0. The optimal solution requires excluding candidate 0, and the dedup run following
+/// that exclusion used to also ban the pre-selected candidate 1, contaminating the selector that
+/// `run_bnb` hands back.
+fn bnb_exclusion_dedup_skips_decided_candidates() {
+    let candidates = vec![
+        Candidate::new(500, 100, false), // same (value, weight) as the pre-selected candidate
+        Candidate::new(500, 100, false), // pre-selected
+        Candidate::new(400, 100, false),
+    ];
+
+    let mut cs = CoinSelector::new(&candidates);
+    cs.select(1);
+
+    let target = Target {
+        outputs: TargetOutputs {
+            value_sum: 900,
+            weight_sum: 0,
+            n_outputs: 1,
+        },
+        fee: TargetFee::ZERO,
+    };
+
+    let _ = cs
+        .run_bnb(target, MinExcessThenWeight, 1_000)
+        .expect("must find solution");
+
+    // Optimal selection is {1, 2}: candidate 1 is mandatory and adding candidate 2 hits the
+    // target exactly, while any selection containing candidate 0 overshoots.
+    assert_eq!(cs.selected_indices().iter().collect::<Vec<_>>(), vec![1, 2]);
+    // The returned selector must not have any candidate simultaneously selected and banned.
+    for (idx, _) in cs.selected() {
+        assert!(
+            !cs.banned().contains(idx),
+            "candidate {} is both selected and banned",
+            idx
+        );
+    }
+}
+
 proptest! {
     #[test]
     fn bnb_always_finds_solution_if_possible(num_inputs in 1usize..18, target_value in 0u64..10_000) {