feat: allow ConstraintVerifier to update all shadow variables

Author: zepfred

core/src/main/java/ai/timefold/solver/core/impl/domain/variable/listener/support/AbstractNotifiable.java

@@ -34,7 +34,7 @@ static <Solution_> EntityNotifiable<Solution_> buildNotifiable(
                     ((ListVariableListener<Solution_, Object, Object>) variableListener),
                     new ArrayDeque<>(), globalOrder);
         } else {
-            VariableListener<Solution_, Object> basicVariableListener = (VariableListener<Solution_, Object>) variableListener;
+            var basicVariableListener = (VariableListener<Solution_, Object>) variableListener;
             return new VariableListenerNotifiable<>(
                     scoreDirector,
                     basicVariableListener,
@@ -80,26 +80,31 @@ public void closeVariableListener() {
         variableListener.close();
     }
 
+    @Override
+    public void clearAllNotifications() {
+        notificationQueue.clear();
+    }
+
     @Override
     public void triggerAllNotifications() {
-        int notifiedCount = 0;
-        for (Notification<Solution_, ? super T> notification : notificationQueue) {
+        var notifiedCount = 0;
+        for (var notification : notificationQueue) {
             notification.triggerAfter(variableListener, scoreDirector);
             notifiedCount++;
         }
         if (notifiedCount != notificationQueue.size()) {
-            throw new IllegalStateException("The variableListener (" + variableListener.getClass()
-                    + ") has been notified with notifiedCount (" + notifiedCount
-                    + ") but after being triggered, its notificationCount (" + notificationQueue.size()
-                    + ") is different.\n"
-                    + "Maybe that variableListener (" + variableListener.getClass()
-                    + ") changed an upstream shadow variable (which is illegal).");
+            throw new IllegalStateException(
+                    """
+                            The variableListener (%s) has been notified with notifiedCount (%d) but after being triggered, its notificationCount (%d) is different.
+                            Maybe that variableListener (%s) changed an upstream shadow variable (which is illegal)."""
+                            .formatted(variableListener.getClass(), notifiedCount, notificationQueue.size(),
+                                    variableListener.getClass()));
         }
         notificationQueue.clear();
     }
 
     @Override
     public String toString() {
-        return "(" + globalOrder + ") " + variableListener;
+        return "(%d) %s".formatted(globalOrder, variableListener);
     }
 }

core/src/main/java/ai/timefold/solver/core/impl/domain/variable/listener/support/Notifiable.java

@@ -18,6 +18,11 @@ public interface Notifiable {
      */
     void resetWorkingSolution();
 
+    /**
+     * Clear all notifications without triggering any related event logic.
+     */
+    void clearAllNotifications();
+
     /**
      * Trigger all queued notifications.
      */

core/src/main/java/ai/timefold/solver/core/impl/domain/variable/listener/support/VariableListenerSupport.java

@@ -368,6 +368,15 @@ public void forceTriggerAllVariableListeners(Solution_ workingSolution) {
         triggerVariableListenersInNotificationQueues();
     }
 
+    /**
+     * Clear all variable listeners without triggering any logic.
+     * The goal is to clear all queues and avoid executing custom listener logic.
+     */
+    public void clearAllVariableListenerEvents() {
+        notifiableRegistry.getAll().forEach(Notifiable::clearAllNotifications);
+        notificationQueuesAreEmpty = true;
+    }
+
     private void simulateGenuineVariableChange(Object entity) {
         var entityDescriptor = scoreDirector.getSolutionDescriptor()
                 .findEntityDescriptorOrFail(entity.getClass());
@@ -389,11 +398,12 @@ private void simulateGenuineVariableChange(Object entity) {
 
     public void assertNotificationQueuesAreEmpty() {
         if (!notificationQueuesAreEmpty) {
-            throw new IllegalStateException("The notificationQueues might not be empty (" + notificationQueuesAreEmpty
-                    + ") so any shadow variables might be stale so score calculation is unreliable.\n"
-                    + "Maybe a " + ScoreDirector.class.getSimpleName() + ".before*() method was called"
-                    + " without calling " + ScoreDirector.class.getSimpleName() + ".triggerVariableListeners(),"
-                    + " before calling " + ScoreDirector.class.getSimpleName() + ".calculateScore().");
+            throw new IllegalStateException(
+                    """
+                            The notificationQueues might not be empty (%s) so any shadow variables might be stale so score calculation is unreliable.
+                            Maybe a %s.before*() method was called without calling %s.triggerVariableListeners(), before calling %s.calculateScore()."""
+                            .formatted(notificationQueuesAreEmpty, ScoreDirector.class.getSimpleName(),
+                                    ScoreDirector.class.getSimpleName(), ScoreDirector.class.getSimpleName()));
         }
     }
 

core/src/main/java/ai/timefold/solver/core/impl/score/director/AbstractScoreDirector.java

@@ -6,7 +6,6 @@
 import java.util.IdentityHashMap;
 import java.util.LinkedHashSet;
 import java.util.List;
-import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
 import java.util.function.Consumer;
@@ -24,7 +23,6 @@
 import ai.timefold.solver.core.config.solver.EnvironmentMode;
 import ai.timefold.solver.core.impl.domain.entity.descriptor.EntityDescriptor;
 import ai.timefold.solver.core.impl.domain.lookup.LookUpManager;
-import ai.timefold.solver.core.impl.domain.solution.ConstraintWeightSupplier;
 import ai.timefold.solver.core.impl.domain.solution.descriptor.SolutionDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.ListVariableStateSupply;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.ListVariableDescriptor;
@@ -312,17 +310,17 @@ protected void setWorkingEntityListDirty() {
     @Override
     public Solution_ cloneSolution(Solution_ originalSolution) {
         SolutionDescriptor<Solution_> solutionDescriptor = getSolutionDescriptor();
-        Score_ originalScore = solutionDescriptor.getScore(originalSolution);
-        Solution_ cloneSolution = solutionDescriptor.getSolutionCloner().cloneSolution(originalSolution);
-        Score_ cloneScore = solutionDescriptor.getScore(cloneSolution);
+        var originalScore = solutionDescriptor.getScore(originalSolution);
+        var cloneSolution = solutionDescriptor.getSolutionCloner().cloneSolution(originalSolution);
+        var cloneScore = solutionDescriptor.getScore(cloneSolution);
         if (scoreDirectorFactory.isAssertClonedSolution()) {
             if (!Objects.equals(originalScore, cloneScore)) {
                 throw new CloningCorruptionException("""
                         Cloning corruption: the original's score (%s) is different from the clone's score (%s).
                         Check the %s."""
                         .formatted(originalScore, cloneScore, SolutionCloner.class.getSimpleName()));
             }
-            Map<Object, Object> originalEntityMap = new IdentityHashMap<>();
+            var originalEntityMap = new IdentityHashMap<>();
             solutionDescriptor.visitAllEntities(originalSolution,
                     originalEntity -> originalEntityMap.put(originalEntity, null));
             solutionDescriptor.visitAllEntities(cloneSolution, cloneEntity -> {
@@ -343,6 +341,16 @@ public void triggerVariableListeners() {
         variableListenerSupport.triggerVariableListenersInNotificationQueues();
     }
 
+    /**
+     * This function clears all listener events that have been generated without triggering any of them.
+     * Using this method requires caution because clearing the event queue can lead to inconsistent states.
+     * This occurs when the shadow variables are not updated,
+     * causing constraints reliant on these variables to be inaccurately evaluated.
+     */
+    protected void clearVariableListenerEvents() {
+        variableListenerSupport.clearAllVariableListenerEvents();
+    }
+
     @Override
     public void forceTriggerVariableListeners() {
         variableListenerSupport.forceTriggerAllVariableListeners(getWorkingSolution());
@@ -560,9 +568,9 @@ public void afterProblemPropertyChanged(Object problemFactOrEntity) {
     @Override
     public void beforeProblemFactRemoved(Object problemFact) {
         if (isConstraintConfiguration(problemFact)) {
-            throw new IllegalStateException("Attempted to remove constraint configuration (" + problemFact +
-                    ") from solution (" + workingSolution + ").\n" +
-                    "Maybe use before/afterProblemPropertyChanged(...) instead.");
+            throw new IllegalStateException("""
+                    Attempted to remove constraint configuration (%s) from solution (%s).
+                    Maybe use before/afterProblemPropertyChanged(...) instead.""".formatted(problemFact, workingSolution));
         }
     }
 
@@ -580,17 +588,19 @@ public void afterProblemFactRemoved(Object problemFact) {
     @Override
     public <E> @Nullable E lookUpWorkingObject(@Nullable E externalObject) {
         if (!lookUpEnabled) {
-            throw new IllegalStateException("When lookUpEnabled (" + lookUpEnabled
-                    + ") is disabled in the constructor, this method should not be called.");
+            throw new IllegalStateException(
+                    "When lookUpEnabled (%s) is disabled in the constructor, this method should not be called."
+                            .formatted(lookUpEnabled));
         }
         return lookUpManager.lookUpWorkingObject(externalObject);
     }
 
     @Override
     public <E> @Nullable E lookUpWorkingObjectOrReturnNull(@Nullable E externalObject) {
         if (!lookUpEnabled) {
-            throw new IllegalStateException("When lookUpEnabled (" + lookUpEnabled
-                    + ") is disabled in the constructor, this method should not be called.");
+            throw new IllegalStateException(
+                    "When lookUpEnabled (%s) is disabled in the constructor, this method should not be called."
+                            .formatted(lookUpEnabled));
         }
         return lookUpManager.lookUpWorkingObjectOrReturnNull(externalObject);
     }
@@ -601,7 +611,7 @@ public void afterProblemFactRemoved(Object problemFact) {
 
     @Override
     public void assertExpectedWorkingScore(Score_ expectedWorkingScore, Object completedAction) {
-        Score_ workingScore = calculateScore();
+        var workingScore = calculateScore();
         if (!expectedWorkingScore.equals(workingScore)) {
             throw new ScoreCorruptionException("""
                     Score corruption (%s): the expectedWorkingScore (%s) is not the workingScore (%s) \
@@ -613,15 +623,15 @@ after completedAction (%s)."""
 
     @Override
     public void assertShadowVariablesAreNotStale(Score_ expectedWorkingScore, Object completedAction) {
-        String violationMessage = variableListenerSupport.createShadowVariablesViolationMessage();
+        var violationMessage = variableListenerSupport.createShadowVariablesViolationMessage();
         if (violationMessage != null) {
             throw new VariableCorruptionException("""
                     %s corruption after completedAction (%s):
                     %s"""
                     .formatted(VariableListener.class.getSimpleName(), completedAction, violationMessage));
         }
 
-        Score_ workingScore = calculateScore();
+        var workingScore = calculateScore();
         if (!expectedWorkingScore.equals(workingScore)) {
             assertWorkingScoreFromScratch(workingScore,
                     "assertShadowVariablesAreNotStale(" + expectedWorkingScore + ", " + completedAction + ")");
@@ -642,8 +652,8 @@ public void assertShadowVariablesAreNotStale(Score_ expectedWorkingScore, Object
      * @return never null
      */
     protected String buildShadowVariableAnalysis(boolean predicted) {
-        String violationMessage = variableListenerSupport.createShadowVariablesViolationMessage();
-        String workingLabel = predicted ? "working" : "corrupted";
+        var violationMessage = variableListenerSupport.createShadowVariablesViolationMessage();
+        var workingLabel = predicted ? "working" : "corrupted";
         if (violationMessage == null) {
             return """
                     Shadow variable corruption in the %s scoreDirector:
@@ -894,8 +904,8 @@ private void iterateAndAddIfFound(List<MatchAnalysis<Score_>> referenceList, Lis
     }
 
     protected boolean isConstraintConfiguration(Object problemFactOrEntity) {
-        SolutionDescriptor<Solution_> solutionDescriptor = scoreDirectorFactory.getSolutionDescriptor();
-        ConstraintWeightSupplier<Solution_, Score_> constraintWeightSupplier = solutionDescriptor.getConstraintWeightSupplier();
+        var solutionDescriptor = scoreDirectorFactory.getSolutionDescriptor();
+        var constraintWeightSupplier = solutionDescriptor.getConstraintWeightSupplier();
         if (constraintWeightSupplier == null) {
             return false;
         }

core/src/main/java/ai/timefold/solver/core/impl/score/director/stream/BavetConstraintStreamScoreDirector.java

@@ -43,6 +43,18 @@ private BavetConstraintStreamScoreDirector(
     // Complex methods
     // ************************************************************************
 
+    /**
+     * The function is exclusively available for the Bavet score director, and its use must be approached with caution.
+     * The primary purpose of this method is
+     * to enable the {@code ConstraintVerifier}
+     * to ignore events related to shadow variables when testing constraints that do not rely on them.
+     *
+     * @see AbstractScoreDirector#clearVariableListenerEvents()
+     */
+    public void clearShadowVariablesListenerQueue() {
+        clearVariableListenerEvents();
+    }
+
     @Override
     public void setWorkingSolution(Solution_ workingSolution) {
         session = scoreDirectorFactory.newSession(workingSolution, constraintMatchPolicy, derived);
@@ -53,7 +65,7 @@ public void setWorkingSolution(Solution_ workingSolution) {
     @Override
     public Score_ calculateScore() {
         variableListenerSupport.assertNotificationQueuesAreEmpty();
-        Score_ score = session.calculateScore(getWorkingInitScore());
+        var score = session.calculateScore(getWorkingInitScore());
         setCalculatedScore(score);
         return score;
     }
@@ -101,11 +113,11 @@ public void close() {
     @Override
     public void afterEntityAdded(EntityDescriptor<Solution_> entityDescriptor, Object entity) {
         if (entity == null) {
-            throw new IllegalArgumentException("The entity (" + entity + ") cannot be added to the ScoreDirector.");
+            throw new IllegalArgumentException("The entity (%s) cannot be added to the ScoreDirector.".formatted(entity));
         }
         if (!getSolutionDescriptor().hasEntityDescriptor(entity.getClass())) {
-            throw new IllegalArgumentException("The entity (" + entity + ") of class (" + entity.getClass()
-                    + ") is not a configured @" + PlanningEntity.class.getSimpleName() + ".");
+            throw new IllegalArgumentException("The entity (%s) of class (%s) is not a configured @%s.".formatted(entity,
+                    entity.getClass(), PlanningEntity.class.getSimpleName()));
         }
         session.insert(entity);
         super.afterEntityAdded(entityDescriptor, entity);
@@ -143,7 +155,8 @@ public void afterEntityRemoved(EntityDescriptor<Solution_> entityDescriptor, Obj
     @Override
     public void afterProblemFactAdded(Object problemFact) {
         if (problemFact == null) {
-            throw new IllegalArgumentException("The problemFact (" + problemFact + ") cannot be added to the ScoreDirector.");
+            throw new IllegalArgumentException(
+                    "The problemFact (%s) cannot be added to the ScoreDirector.".formatted(problemFact));
         }
         session.insert(problemFact);
         super.afterProblemFactAdded(problemFact);