chore: use a custom exception for inconsistent solution

Author: Christopher-Chianelli

core/src/main/java/ai/timefold/solver/core/api/domain/variable/InconsistentSolutionException.java

@@ -0,0 +1,27 @@
+package ai.timefold.solver.core.api.domain.variable;
+
+import java.util.List;
+
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+public class InconsistentSolutionException extends RuntimeException {
+    private final Object solution;
+    private final List<Object> involvedEntityList;
+
+    public InconsistentSolutionException(String feature, Object solution, List<Object> involvedEntityList) {
+        super("The solution (%s) is inconsistent. %s requires a consistent solution.".formatted(solution, feature));
+        this.solution = solution;
+        this.involvedEntityList = involvedEntityList;
+    }
+
+    @SuppressWarnings("unchecked")
+    public <T> T getSolution() {
+        return (T) solution;
+    }
+
+    @SuppressWarnings("unchecked")
+    public <T> List<T> getInvolvedEntityList() {
+        return (List<T>) involvedEntityList;
+    }
+}

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

@@ -343,8 +343,12 @@ protected void afterSetWorkingSolution() {
         // Do nothing
     }
 
+    public List<Object> getInconsistentEntities() {
+        return shadowVariableSupport.getInconsistentEntities();
+    }
+
     public void unassignInconsistentEntities() {
-        var inconsistentEntities = shadowVariableSupport.getInconsistentEntities();
+        var inconsistentEntities = getInconsistentEntities();
         if (listVariableStateSupply != null) {
             var listVariableDescriptor = listVariableStateSupply.getSourceVariableDescriptor();
             var listElementClass = listVariableStateSupply.getSourceVariableDescriptor().getElementType();

core/src/main/java/ai/timefold/solver/core/impl/solver/DefaultSolutionManager.java

@@ -5,6 +5,7 @@
 import java.util.function.Function;
 
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
+import ai.timefold.solver.core.api.domain.variable.InconsistentSolutionException;
 import ai.timefold.solver.core.api.score.Score;
 import ai.timefold.solver.core.api.score.analysis.ScoreAnalysis;
 import ai.timefold.solver.core.api.solver.RecommendedAssignment;
@@ -87,14 +88,12 @@ private <Result_> Result_ callScoreDirector(String feature, Solution_ solution,
             if (solutionUpdatePolicy.isScoreUpdateEnabled()) {
                 var score = scoreDirector.calculateScore();
                 if (score.isInvalid()) {
-                    throw new IllegalArgumentException("""
-                            The solution (%s) is inconsistent. %s requires a consistent solution to be passed.
-                            """.formatted(solution, feature));
+                    var inconsistentEntities = scoreDirector.getInconsistentEntities();
+                    throw new InconsistentSolutionException(feature, nonNullSolution, inconsistentEntities);
                 }
             } else if (!scoreDirector.isLastVariableUpdateWasSuccessful()) {
-                throw new IllegalArgumentException("""
-                        The solution (%s) is inconsistent. %s requires a consistent solution to be passed.
-                        """.formatted(solution, feature));
+                var inconsistentEntities = scoreDirector.getInconsistentEntities();
+                throw new InconsistentSolutionException(feature, nonNullSolution, inconsistentEntities);
             }
             return function.apply(scoreDirector);
         }

core/src/test/java/ai/timefold/solver/core/api/solver/SolutionManagerTest.java

@@ -9,6 +9,7 @@
 import java.util.List;
 import java.util.function.Function;
 
+import ai.timefold.solver.core.api.domain.variable.InconsistentSolutionException;
 import ai.timefold.solver.core.api.score.HardSoftScore;
 import ai.timefold.solver.core.api.score.Score;
 import ai.timefold.solver.core.config.score.director.ScoreDirectorFactoryConfig;
@@ -137,9 +138,11 @@ void updateInconsistent(SolutionManagerSource solutionManagerSource) {
         assertThat(solutionManager).isNotNull();
 
         assertThatCode(() -> solutionManager.update(inconsistentSolution))
-                .isInstanceOf(IllegalArgumentException.class)
+                .isInstanceOf(InconsistentSolutionException.class)
                 .hasMessageContainingAll("The solution (",
-                        "is inconsistent", "Solution update", "requires a consistent solution");
+                        "is inconsistent", "Solution update", "requires a consistent solution")
+                .hasFieldOrPropertyWithValue("solution", inconsistentSolution)
+                .hasFieldOrPropertyWithValue("involvedEntityList", List.of(valueA1, valueA2));
     }
 
     private void assertShadowedListValueAllNull(SoftAssertions softly, TestdataListValueWithShadowHistory current) {
@@ -196,10 +199,12 @@ void updateOnlyShadowVariablesInconsistent(SolutionManagerSource solutionManager
         var solutionManager = solutionManagerSource.createSolutionManager(solverFactory);
         assertThat(solutionManager).isNotNull();
 
-        assertThatCode(() -> solutionManager.update(inconsistentSolution, SolutionUpdatePolicy.UPDATE_SHADOW_VARIABLES_ONLY))
-                .isInstanceOf(IllegalArgumentException.class)
+        assertThatCode(() -> solutionManager.update(inconsistentSolution))
+                .isInstanceOf(InconsistentSolutionException.class)
                 .hasMessageContainingAll("The solution (",
-                        "is inconsistent", "Solution update", "requires a consistent solution");
+                        "is inconsistent", "Solution update", "requires a consistent solution")
+                .hasFieldOrPropertyWithValue("solution", inconsistentSolution)
+                .hasFieldOrPropertyWithValue("involvedEntityList", List.of(valueA1, valueA2));
     }
 
     @ParameterizedTest