chore: address comments

Author: zepfred

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/LocalSearchDecider.java

@@ -6,7 +6,6 @@
 import ai.timefold.solver.core.impl.heuristic.selector.move.MoveSelector;
 import ai.timefold.solver.core.impl.localsearch.decider.acceptor.Acceptor;
 import ai.timefold.solver.core.impl.localsearch.decider.forager.LocalSearchForager;
-import ai.timefold.solver.core.impl.localsearch.decider.reconfiguration.AdaptedSolverScope;
 import ai.timefold.solver.core.impl.localsearch.decider.reconfiguration.RestartStrategy;
 import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchMoveScope;
 import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchPhaseScope;
@@ -78,13 +77,14 @@ public void setAssertExpectedUndoMoveScore(boolean assertExpectedUndoMoveScore)
     // ************************************************************************
 
     public void solvingStarted(SolverScope<Solution_> solverScope) {
-        restartStrategy.solvingStarted(new AdaptedSolverScope<>(solverScope, this));
+        restartStrategy.solvingStarted(solverScope);
         moveSelector.solvingStarted(solverScope);
         acceptor.solvingStarted(solverScope);
         forager.solvingStarted(solverScope);
     }
 
     public void phaseStarted(LocalSearchPhaseScope<Solution_> phaseScope) {
+        phaseScope.setDecider(this);
         restartStrategy.phaseStarted(phaseScope);
         moveSelector.phaseStarted(phaseScope);
         acceptor.phaseStarted(phaseScope);

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/acceptor/RestartableAcceptor.java

@@ -12,52 +12,52 @@
  */
 public abstract class RestartableAcceptor<Solution_> extends AbstractAcceptor<Solution_> {
 
-    private final StuckCriterion<Solution_> stuckCriterionDetection;
+    private final StuckCriterion<Solution_> stuckCriterion;
     protected boolean restartTriggered;
 
-    protected RestartableAcceptor(StuckCriterion<Solution_> stuckCriterionDetection) {
-        this.stuckCriterionDetection = stuckCriterionDetection;
+    protected RestartableAcceptor(StuckCriterion<Solution_> stuckCriterion) {
+        this.stuckCriterion = stuckCriterion;
     }
 
     @Override
     public void solvingStarted(SolverScope<Solution_> solverScope) {
         super.solvingStarted(solverScope);
-        stuckCriterionDetection.solvingStarted(solverScope);
+        stuckCriterion.solvingStarted(solverScope);
     }
 
     @Override
     public void phaseStarted(LocalSearchPhaseScope<Solution_> phaseScope) {
         super.phaseStarted(phaseScope);
-        stuckCriterionDetection.phaseStarted(phaseScope);
+        stuckCriterion.phaseStarted(phaseScope);
     }
 
     @Override
     public void phaseEnded(LocalSearchPhaseScope<Solution_> phaseScope) {
         super.phaseEnded(phaseScope);
-        stuckCriterionDetection.phaseEnded(phaseScope);
+        stuckCriterion.phaseEnded(phaseScope);
     }
 
     @Override
     public void stepStarted(LocalSearchStepScope<Solution_> stepScope) {
         super.stepStarted(stepScope);
-        stuckCriterionDetection.stepStarted(stepScope);
+        stuckCriterion.stepStarted(stepScope);
     }
 
     @Override
     public void stepEnded(LocalSearchStepScope<Solution_> stepScope) {
         super.stepEnded(stepScope);
-        stuckCriterionDetection.stepEnded(stepScope);
+        stuckCriterion.stepEnded(stepScope);
     }
 
     @Override
     public boolean isAccepted(LocalSearchMoveScope<Solution_> moveScope) {
-        if (stuckCriterionDetection.isSolverStuck(moveScope)) {
-            moveScope.getStepScope().getPhaseScope().triggerSolverStuck();
+        if (stuckCriterion.isSolverStuck(moveScope)) {
+            moveScope.getStepScope().getPhaseScope().setSolverStuck(true);
             restartTriggered = true;
             return true;
         }
-        return applyAcceptanceCriteria(moveScope);
+        return accept(moveScope);
     }
 
-    protected abstract boolean applyAcceptanceCriteria(LocalSearchMoveScope<Solution_> moveScope);
+    protected abstract boolean accept(LocalSearchMoveScope<Solution_> moveScope);
 }

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/acceptor/lateacceptance/DiversifiedLateAcceptanceAcceptor.java

@@ -53,7 +53,7 @@ private void validate() {
 
     @Override
     @SuppressWarnings({ "rawtypes", "unchecked" })
-    protected boolean applyAcceptanceCriteria(LocalSearchMoveScope<Solution_> moveScope) {
+    protected boolean accept(LocalSearchMoveScope<Solution_> moveScope) {
         // The acceptance and replacement strategies are based on the work:
         // Diversified Late Acceptance Search by M. Namazi, C. Sanderson, M. A. H. Newton, M. M. A. Polash, and A. Sattar
         var moveScore = moveScope.getScore();

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/acceptor/lateacceptance/LateAcceptanceAcceptor.java

@@ -52,7 +52,7 @@ private void validate() {
 
     @Override
     @SuppressWarnings("unchecked")
-    public boolean applyAcceptanceCriteria(LocalSearchMoveScope<Solution_> moveScope) {
+    public boolean accept(LocalSearchMoveScope<Solution_> moveScope) {
         var moveScore = moveScope.getScore();
         var lateScore = previousScores[lateScoreIndex];
         if (moveScore.compareTo(lateScore) >= 0) {

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/acceptor/restart/AbstractGeometricStuckCriterion.java

@@ -1,6 +1,7 @@
 package ai.timefold.solver.core.impl.localsearch.decider.acceptor.restart;
 
 import java.time.Clock;
+import java.time.Instant;
 
 import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchMoveScope;
 import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchPhaseScope;
@@ -21,12 +22,12 @@
 public abstract class AbstractGeometricStuckCriterion<Solution_> implements StuckCriterion<Solution_> {
     protected static final Logger logger = LoggerFactory.getLogger(AbstractGeometricStuckCriterion.class);
     private static final double GEOMETRIC_FACTOR = 1.4; // Value extracted from the cited paper
-    private static final long GRACE_PERIOD_MILLIS = 30_000; // Same value as DiminishedReturnsTermination
+    private static final long GRACE_PERIOD_MILLIS = 30_000; // 30s by default
 
     private final double scalingFactor;
     private final Clock clock;
     private boolean gracePeriodFinished;
-    private long gracePeriodMillis;
+    private Instant gracePeriodEnd;
     protected long nextRestart;
     private double currentGeometricGrowFactor;
 
@@ -37,9 +38,9 @@ protected AbstractGeometricStuckCriterion(Clock clock, double scalingFactor) {
 
     @Override
     public void phaseStarted(LocalSearchPhaseScope<Solution_> phaseScope) {
-        if (gracePeriodMillis == 0) {
+        if (gracePeriodEnd == null) {
             // 30 seconds of grace period
-            gracePeriodMillis = clock.instant().toEpochMilli() + GRACE_PERIOD_MILLIS;
+            gracePeriodEnd = clock.instant().plusMillis(GRACE_PERIOD_MILLIS);
         }
     }
 
@@ -51,7 +52,7 @@ public void phaseEnded(LocalSearchPhaseScope<Solution_> phaseScope) {
     @Override
     public void solvingStarted(SolverScope<Solution_> solverScope) {
         currentGeometricGrowFactor = 1;
-        gracePeriodMillis = 0;
+        gracePeriodEnd = null;
         gracePeriodFinished = false;
         nextRestart = calculateNextRestart();
     }
@@ -83,7 +84,7 @@ protected boolean isGracePeriodFinished() {
         if (gracePeriodFinished) {
             return true;
         }
-        gracePeriodFinished = clock.instant().toEpochMilli() >= gracePeriodMillis;
+        gracePeriodFinished = clock.millis() >= gracePeriodEnd.toEpochMilli();
         return gracePeriodFinished;
     }
 

core/src/main/java/ai/timefold/solver/core/impl/localsearch/decider/acceptor/restart/StuckCriterion.java

@@ -1,19 +1,18 @@
 package ai.timefold.solver.core.impl.localsearch.decider.acceptor.restart;
 
+import ai.timefold.solver.core.api.solver.Solver;
 import ai.timefold.solver.core.impl.localsearch.event.LocalSearchPhaseLifecycleListener;
 import ai.timefold.solver.core.impl.localsearch.scope.LocalSearchMoveScope;
 
 /**
- * Base contract
- * for defining strategies that identify when the {@link ai.timefold.solver.core.api.solver.Solver solver} is stuck.
+ * Allow defining strategies that identify when the {@link Solver solver} is stuck.
  * 
- * @param <Solution_>
+ * @param <Solution_> the solution type
  */
 public interface StuckCriterion<Solution_> extends LocalSearchPhaseLifecycleListener<Solution_> {
 
     /**
-     * Main logic that applies a specific metric to determine if a solver is stuck and cannot find better solutions
-     * in the current solving flow.
+     * Main logic that applies a specific metric to determine if a solver is stuck in a local optimum.
      * 
      * @param moveScope cannot be null
      * @return