fix(vnd)!: honour score_tie_break among equally scored best moves

crates/solverforge-config/WIREFRAME.md

@@ -220,7 +220,8 @@ profile. Explicit `acceptor`, `forager`, `move_selector`, and VND
 
 `score_tie_break` defaults to `ScoreTieBreak::Random`, which uses the seeded
 step stream for reservoir tie selection. `ScoreTieBreak::First` keeps the first
-equally scored accepted candidate.
+equally scored accepted candidate. Variable neighborhood descent applies the
+same rule to equally scored best improving moves of a neighborhood.
 
 ### `VariableTargetConfig`
 

crates/solverforge-config/src/phase.rs

@@ -168,7 +168,9 @@ pub struct LocalSearchConfig {
     /// Forager configuration.
     pub forager: Option<ForagerConfig>,
 
-    /// Selection among equally scored accepted candidates.
+    /// Selection among equally scored accepted candidates; under
+    /// `variable_neighborhood_descent`, among equally scored best improving
+    /// moves of a neighborhood.
     #[serde(default)]
     pub score_tie_break: ScoreTieBreak,
 

crates/solverforge-solver/src/phase/hard_delta_phase_tests.rs

@@ -31,6 +31,7 @@ fn vnd_accepts_required_repair_that_improves_later_hard_level() {
         &mut neighborhoods,
         &mut resources,
         None,
+        solverforge_config::ScoreTieBreak::First,
         &mut solver_scope,
     );
 

crates/solverforge-solver/src/phase/localsearch/forager.rs

@@ -138,7 +138,10 @@ where
     }
 }
 
-fn reservoir_pick(step_seed: u64, equal_count: u64) -> bool {
+/// Seeded reservoir selection: whether the `equal_count`-th equally scored
+/// candidate of a step replaces the current one, so every tie is kept with
+/// probability `1 / equal_count`.
+pub(crate) fn reservoir_pick(step_seed: u64, equal_count: u64) -> bool {
     let mixed = splitmix64(
         step_seed ^ equal_count.wrapping_mul(0x9E37_79B9_7F4A_7C15) ^ 0xF04A_63E2_39B7_4D11,
     );

crates/solverforge-solver/src/phase/localsearch/vnd/phase.rs

@@ -2,6 +2,7 @@ use std::fmt::Debug;
 use std::time::Instant;
 
 use rand::RngExt;
+use solverforge_config::ScoreTieBreak;
 use solverforge_core::domain::PlanningSolution;
 use solverforge_scoring::Director;
 use tracing::info;
@@ -17,6 +18,7 @@ use crate::phase::control::{
 use crate::phase::localsearch::evaluation::{
     evaluate_candidate, record_evaluated_move, CandidateEvaluation,
 };
+use crate::phase::localsearch::forager::reservoir_pick;
 use crate::phase::localsearch::vnd::telemetry::{candidate_selector_label, VndProgress};
 use crate::phase::localsearch::{CursorResources, MoveCursorSource};
 use crate::scope::{PhaseScope, ProgressCallback, SolverScope, StepScope};
@@ -28,10 +30,15 @@ use crate::stats::{
 /// Executes the one VND loop while lending the caller-owned resource only at
 /// cursor opening and candidate pull boundaries. The compiled runner passes
 /// its one solve-owned provider resource directly.
+///
+/// `score_tie_break` chooses among equally scored best improving moves of a
+/// neighborhood: `Random` by seeded reservoir selection from the step's seed,
+/// `First` the first one.
 pub(crate) fn solve_vnd_with_resources<S, D, ProgressCb, M, Source>(
     neighborhoods: &mut [Source],
     resources: &mut Source::Resources,
     step_limit: Option<u64>,
+    score_tie_break: ScoreTieBreak,
     solver_scope: &mut SolverScope<'_, S, D, ProgressCb>,
 ) where
     S: PlanningSolution,
@@ -67,15 +74,12 @@ pub(crate) fn solve_vnd_with_resources<S, D, ProgressCb, M, Source>(
         }
 
         let mut step_scope = StepScope::new(&mut phase_scope);
-        let stream_context = MoveStreamContext::new(
-            step_scope.step_index(),
-            step_scope
-                .phase_scope_mut()
-                .solver_scope_mut()
-                .rng()
-                .random::<u64>(),
-            None,
-        );
+        let step_seed = step_scope
+            .phase_scope_mut()
+            .solver_scope_mut()
+            .rng()
+            .random::<u64>();
+        let stream_context = MoveStreamContext::new(step_scope.step_index(), step_seed, None);
         let mut cursor =
             neighborhoods[k].open_cursor(resources, step_scope.score_director(), stream_context);
 
@@ -85,6 +89,7 @@ pub(crate) fn solve_vnd_with_resources<S, D, ProgressCb, M, Source>(
             &mut step_scope,
             &current_score,
             &mut progress,
+            TieBreak::new(score_tie_break, step_seed),
         );
         resources.flush_step_telemetry(step_scope.phase_scope_mut().stats_mut());
         match search {
@@ -186,6 +191,7 @@ fn find_best_improving_move<S, D, ProgressCb, M, C, Resources>(
     step_scope: &mut StepScope<'_, '_, '_, S, D, ProgressCb>,
     current_score: &S::Score,
     progress: &mut VndProgress,
+    mut ties: TieBreak,
 ) -> MoveSearchResult<S::Score>
 where
     S: PlanningSolution,
@@ -345,8 +351,15 @@ where
         progress.maybe_report(step_scope);
 
         if move_score > *current_score {
+            let replaces_best = match &best {
+                Some((_, best_score, _)) => ties.replaces(move_score.cmp(best_score)),
+                None => {
+                    ties.first();
+                    false
+                }
+            };
             match &best {
-                Some((_, best_score, _)) if move_score > *best_score => {
+                Some(_) if replaces_best => {
                     let (previous_best, _, previous_token) = best
                         .take()
                         .expect("VND best candidate must exist before replacement");
@@ -411,6 +424,46 @@ where
     }
 }
 
+/// Tie state of one VND step: how many equally scored best improving moves
+/// were seen, and whether a later one may replace the current best.
+struct TieBreak {
+    random: bool,
+    step_seed: u64,
+    equal_count: u64,
+}
+
+impl TieBreak {
+    fn new(score_tie_break: ScoreTieBreak, step_seed: u64) -> Self {
+        Self {
+            random: matches!(score_tie_break, ScoreTieBreak::Random),
+            step_seed,
+            equal_count: 0,
+        }
+    }
+
+    /// Records the first improving move of the step.
+    fn first(&mut self) {
+        self.equal_count = 1;
+    }
+
+    /// Whether an improving move comparing `ordering` to the current best
+    /// replaces it: a better one always does, an equal one by seeded
+    /// reservoir selection under `Random`.
+    fn replaces(&mut self, ordering: std::cmp::Ordering) -> bool {
+        match ordering {
+            std::cmp::Ordering::Greater => {
+                self.equal_count = 1;
+                true
+            }
+            std::cmp::Ordering::Equal => {
+                self.equal_count += 1;
+                self.random && reservoir_pick(self.step_seed, self.equal_count)
+            }
+            std::cmp::Ordering::Less => false,
+        }
+    }
+}
+
 #[cfg(test)]
 #[path = "tests.rs"]
 mod tests;

crates/solverforge-solver/src/phase/localsearch/vnd/tests.rs

@@ -21,6 +21,9 @@ use crate::scope::SolverScope;
 #[path = "tests/repair.rs"]
 mod repair;
 
+#[path = "tests/ties.rs"]
+mod ties;
+
 #[derive(Clone, Debug)]
 struct InterruptPlan {
     value: i64,
@@ -244,6 +247,7 @@ fn vnd_single_neighborhood_applies_best_improving_move() {
         &mut neighborhoods,
         &mut resources,
         None,
+        solverforge_config::ScoreTieBreak::First,
         &mut solver_scope,
     );
 
@@ -280,6 +284,7 @@ fn vnd_cancel_mid_neighborhood_does_not_commit_partial_best() {
         &mut neighborhoods,
         &mut resources,
         None,
+        solverforge_config::ScoreTieBreak::First,
         &mut solver_scope,
     );
 
@@ -305,6 +310,7 @@ fn vnd_polling_advances_through_non_doable_tail_after_cancel_request() {
         &mut neighborhoods,
         &mut resources,
         None,
+        solverforge_config::ScoreTieBreak::First,
         &mut solver_scope,
     );
 

crates/solverforge-solver/src/phase/localsearch/vnd/tests/repair.rs

@@ -16,6 +16,7 @@ fn vnd_rejects_hard_neutral_repair_move_when_hard_improvement_required() {
         &mut neighborhoods,
         &mut resources,
         None,
+        solverforge_config::ScoreTieBreak::First,
         &mut solver_scope,
     );