chore: unassign if solution is inconsistent (#2443)

Christopher-Chianelli · Christopher-Chianelli · commit c6c721106d7a · 2026-07-28T13:55:47.000-04:00
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/ShadowVariableSupport.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/ShadowVariableSupport.java
@@ -419,6 +419,14 @@ public boolean updateShadowVariables() {
         dirty = false;
     }
 
+    public List<Object> getInconsistentEntities() {
+        if (shadowVariableSession == null) {
+            throw new IllegalStateException(
+                    "Impossible state: The shadowVariableSession is null. A solution without shadow variables cannot be inconsistent.");
+        }
+        return shadowVariableSession.getInconsistentEntities();
+    }
+
     /**
      * Triggers all cascading update shadow variable user-logic.
      */
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/DefaultShadowVariableSession.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/DefaultShadowVariableSession.java
@@ -1,5 +1,7 @@
 package ai.timefold.solver.core.impl.domain.variable.declarative;
 
+import java.util.List;
+
 import ai.timefold.solver.core.impl.domain.variable.descriptor.ListVariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.descriptor.VariableDescriptor;
 import ai.timefold.solver.core.impl.domain.variable.supply.Supply;
@@ -50,4 +52,8 @@ public void afterListVariableChanged(ListVariableDescriptor<Solution_> variableD
     public boolean updateVariables() {
         return graph.updateChanged();
     }
+
+    public List<Object> getInconsistentEntities() {
+        return graph.getInconsistentEntities();
+    }
 }
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/DefaultVariableReferenceGraph.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/DefaultVariableReferenceGraph.java
@@ -6,6 +6,8 @@
 import java.util.List;
 import java.util.function.IntFunction;
 
+import ai.timefold.solver.core.impl.util.LinkedIdentityHashSet;
+
 import org.jspecify.annotations.NonNull;
 
 final class DefaultVariableReferenceGraph<Solution_> extends AbstractVariableReferenceGraph<Solution_, BitSet> {
@@ -71,4 +73,20 @@ public void setUnknownInconsistencyValues() {
         graph.commitChanges(changeTracker);
         affectedEntitiesUpdater.setUnknownInconsistencyValues();
     }
+
+    @Override
+    public List<Object> getInconsistentEntities() {
+        var out = new LinkedIdentityHashSet<>();
+        var graphTrackingInconsistentEntities = new DefaultTopologicalOrderGraph(this.nodeTopologicalOrders.length);
+        graph.forEachEdge(graphTrackingInconsistentEntities::addEdge);
+        graphTrackingInconsistentEntities.commitChanges(new BitSet());
+        var loopedComponentList = graphTrackingInconsistentEntities.getLoopedComponentList();
+        for (var loopedComponent : loopedComponentList) {
+            for (var nodeId : loopedComponent) {
+                var node = this.nodeList.get(nodeId);
+                out.add(node.entity());
+            }
+        }
+        return new ArrayList<>(out);
+    }
 }
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/EmptyVariableReferenceGraph.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/EmptyVariableReferenceGraph.java
@@ -1,5 +1,8 @@
 package ai.timefold.solver.core.impl.domain.variable.declarative;
 
+import java.util.Collections;
+import java.util.List;
+
 import ai.timefold.solver.core.preview.api.domain.metamodel.VariableMetaModel;
 
 final class EmptyVariableReferenceGraph implements VariableReferenceGraph {
@@ -22,6 +25,11 @@ public void afterVariableChanged(VariableMetaModel<?, ?, ?> variableReference, O
         // No need to do anything.
     }
 
+    @Override
+    public List<Object> getInconsistentEntities() {
+        return Collections.emptyList();
+    }
+
     @Override
     public String toString() {
         return "{}";
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/FixedVariableReferenceGraph.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/FixedVariableReferenceGraph.java
@@ -1,6 +1,8 @@
 package ai.timefold.solver.core.impl.domain.variable.declarative;
 
 import java.util.BitSet;
+import java.util.Collections;
+import java.util.List;
 import java.util.PriorityQueue;
 import java.util.Spliterators;
 import java.util.function.IntFunction;
@@ -106,4 +108,9 @@ boolean innerUpdateChanged() {
         isChanged.clear();
         return true;
     }
+
+    @Override
+    public List<Object> getInconsistentEntities() {
+        return Collections.emptyList();
+    }
 }
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/SingleDirectionalParentVariableReferenceGraph.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/SingleDirectionalParentVariableReferenceGraph.java
@@ -2,6 +2,7 @@
 
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.Comparator;
 import java.util.HashSet;
 import java.util.IdentityHashMap;
@@ -136,4 +137,9 @@ public void afterVariableChanged(VariableMetaModel<?, ?, ?> variableReference, O
         }
     }
 
+    @Override
+    public List<Object> getInconsistentEntities() {
+        return Collections.emptyList();
+    }
+
 }
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/VariableReferenceGraph.java b/core/src/main/java/ai/timefold/solver/core/impl/domain/variable/declarative/VariableReferenceGraph.java
@@ -70,4 +70,5 @@ default void afterListVariableChanged(VariableMetaModel<?, ?, ?> variableReferen
         // Most graphs do not have edges that depend on a list variable's contents.
     }
 
+    List<Object> getInconsistentEntities();
 }
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/score/director/AbstractScoreDirector.java b/core/src/main/java/ai/timefold/solver/core/impl/score/director/AbstractScoreDirector.java
@@ -343,6 +343,59 @@ protected void afterSetWorkingSolution() {
         // Do nothing
     }
 
+    public void unassignInconsistentEntities() {
+        var inconsistentEntities = variableListenerSupport.getInconsistentEntities();
+        if (listVariableStateSupply != null) {
+            var listVariableDescriptor = listVariableStateSupply.getSourceVariableDescriptor();
+            var listElementClass = listVariableStateSupply.getSourceVariableDescriptor().getElementType();
+            for (var inconsistentEntity : inconsistentEntities) {
+                if (listElementClass.isInstance(inconsistentEntity)) {
+                    var inverse = Objects.requireNonNull(listVariableStateSupply.getInverseSingleton(inconsistentEntity));
+                    int index = Objects.requireNonNull(listVariableStateSupply.getIndex(inconsistentEntity));
+
+                    if (listVariableDescriptor.isElementPinned(Objects.requireNonNull(workingSolution), inverse, index)) {
+                        throw new IllegalStateException("""
+                                Entity (%s) is pinned while involved in a dependency loop.
+                                This creates an unresolvable inconsistency.""".formatted(inconsistentEntity));
+                    }
+
+                    beforeListVariableElementUnassigned(listVariableDescriptor, inconsistentEntity);
+                    beforeListVariableChanged(listVariableDescriptor, inverse, index, index + 1);
+                    listVariableDescriptor.removeElement(inverse, index);
+                    afterListVariableChanged(listVariableDescriptor, inverse, index, index);
+                    afterListVariableElementUnassigned(listVariableDescriptor, inconsistentEntity);
+                    triggerVariableListeners();
+                }
+                // Unassign any normal @PlanningVariable on the entity too
+                unassignPlainEntity(inconsistentEntity);
+            }
+        } else {
+            for (var inconsistentEntity : inconsistentEntities) {
+                unassignPlainEntity(inconsistentEntity);
+            }
+        }
+    }
+
+    private void unassignPlainEntity(Object inconsistentEntity) {
+        var entityDescriptor = getSolutionDescriptor().findEntityDescriptor(inconsistentEntity.getClass());
+        if (entityDescriptor == null) {
+            throw new IllegalStateException(
+                    "Impossible state: Object (%s) is not an entity but is inconsistent".formatted(inconsistentEntity));
+        }
+        if (entityDescriptor.isGenuine()
+                && !entityDescriptor.isMovable(Objects.requireNonNull(workingSolution), inconsistentEntity)) {
+            throw new IllegalStateException("""
+                    Entity (%s) is pinned while involved in a dependency loop.
+                    This creates an unresolvable inconsistency.""".formatted(inconsistentEntity));
+        }
+        for (var genuineVariableDescriptor : entityDescriptor.getGenuineVariableDescriptorList()) {
+            beforeVariableChanged(genuineVariableDescriptor, inconsistentEntity);
+            genuineVariableDescriptor.setValue(inconsistentEntity, null);
+            afterVariableChanged(genuineVariableDescriptor, inconsistentEntity);
+        }
+        triggerVariableListeners();
+    }
+
     @Override
     public void setMoveRepository(@Nullable MoveRepository<Solution_> moveRepository) {
         if (this.moveRepository == moveRepository) { // Prevent double initialization
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/score/director/InnerScoreDirector.java b/core/src/main/java/ai/timefold/solver/core/impl/score/director/InnerScoreDirector.java
@@ -169,6 +169,8 @@ default InnerScore<Score_> executeTemporaryMove(Move<Solution_> move, boolean as
 
     boolean ignoreInconsistentSolutions();
 
+    void unassignInconsistentEntities();
+
     /**
      * @return never null
      */
@@ -372,5 +374,4 @@ default void afterEntityRemoved(Object entity) {
     void beforeProblemFactRemoved(Object problemFact);
 
     void afterProblemFactRemoved(Object problemFact);
-
 }
diff --git a/core/src/main/java/ai/timefold/solver/core/impl/solver/recaller/BestSolutionRecaller.java b/core/src/main/java/ai/timefold/solver/core/impl/solver/recaller/BestSolutionRecaller.java
@@ -11,13 +11,17 @@
 import ai.timefold.solver.core.impl.solver.event.SolverEventSupport;
 import ai.timefold.solver.core.impl.solver.scope.SolverScope;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 /**
  * Remembers the {@link PlanningSolution best solution} that a {@link Solver} encounters.
  *
  * @param <Solution_> the solution type, the class with the {@link PlanningSolution} annotation
  */
 public class BestSolutionRecaller<Solution_> extends PhaseLifecycleListenerAdapter<Solution_> {
 
+    private static final Logger log = LoggerFactory.getLogger(BestSolutionRecaller.class);
     protected boolean assertInitialScoreFromScratch = false;
     protected boolean assertShadowVariablesAreNotStale = false;
     protected boolean assertBestScoreIsUnmodified = false;
@@ -44,16 +48,21 @@ public void setSolverEventSupport(SolverEventSupport<Solution_> solverEventSuppo
     // Worker methods
     // ************************************************************************
 
-    @SuppressWarnings({ "unchecked", "rawtypes" })
     @Override
+    @SuppressWarnings("unchecked")
     public void solvingStarted(SolverScope<Solution_> solverScope) {
         // Starting bestSolution is already set by Solver.solve(Solution)
         var scoreDirector = solverScope.getScoreDirector();
+        @SuppressWarnings("rawtypes")
         InnerScore innerScore = scoreDirector.calculateScore();
         if (innerScore.isInvalid()) {
-            throw new IllegalStateException(
-                    "The initial solution passed to the solver (%s) is invalid because it has dependency loops."
-                            .formatted(solverScope.getWorkingSolution()));
+            log.warn("The initial solution passed to the solver is inconsistent. Unassigning involved entities.");
+            scoreDirector.unassignInconsistentEntities();
+            innerScore = scoreDirector.calculateScore();
+            if (innerScore.isInvalid()) {
+                throw new IllegalStateException(
+                        "The initial solution passed to the solver is inconsistent even after unassigning involved entities.");
+            }
         }
         var score = innerScore.raw();
         solverScope.setBestScore(innerScore);
diff --git a/core/src/test/java/ai/timefold/solver/core/impl/solver/DefaultSolverTest.java b/core/src/test/java/ai/timefold/solver/core/impl/solver/DefaultSolverTest.java
@@ -1460,7 +1460,65 @@ void solveStaleDeclarativeShadows() {
     }
 
     @Test
-    void solveWhenIgnoringInconsistentSolutionsThrowsIfInitialSolutionInconsistent() {
+    void solveWhenIgnoringInconsistentSolutionsUnassignsIfInitialSolutionInconsistent() {
+        // Solver config
+        var solverConfig = PlannerTestUtils.buildSolverConfig(
+                TestdataDependencyNoInconsistentFieldSolution.class, TestdataDependencyNoInconsistentFieldEntity.class,
+                TestdataDependencyNoInconsistentFieldValue.class)
+                .withEasyScoreCalculatorClass(null)
+                .withConstraintProviderClass(TestdataDependencyNoInconsistentFieldConstraintProvider.class)
+                .withPhases(new CustomPhaseConfig()
+                        .withCustomPhaseCommands(command -> {
+                        }));
+
+        var e1 = new TestdataDependencyNoInconsistentFieldEntity("a");
+        var e2 = new TestdataDependencyNoInconsistentFieldEntity("b");
+
+        var a1 = new TestdataDependencyNoInconsistentFieldValue("a1");
+        var a2 = new TestdataDependencyNoInconsistentFieldValue("a2");
+        var b1 = new TestdataDependencyNoInconsistentFieldValue("b1");
+        var b2 = new TestdataDependencyNoInconsistentFieldValue("b2");
+
+        a2.setDependencies(List.of(a1));
+        b2.setDependencies(List.of(b1));
+
+        e1.setValues(List.of(b2, b1));
+        e2.setValues(List.of(a1, a2));
+
+        var entities = List.of(e1, e2);
+        var values = List.of(a1, a2, b1, b2);
+
+        var problem = new TestdataDependencyNoInconsistentFieldSolution();
+
+        problem.setEntities(entities);
+        problem.setValues(values);
+
+        var solution = PlannerTestUtils.solve(solverConfig, problem, false);
+        assertThat(solution.getEntities().getFirst().getValues()).isEmpty();
+        assertThat(solution.getEntities().getLast().getValues()).hasSize(2);
+
+        var sE2 = solution.getEntities().getLast();
+
+        var sA1 = solution.getValues().get(0);
+        var sA2 = solution.getValues().get(1);
+        var sB1 = solution.getValues().get(2);
+        var sB2 = solution.getValues().get(3);
+
+        assertThat(sA1.getEntity()).isEqualTo(sE2);
+        assertThat(sA1.getPreviousValue()).isNull();
+
+        assertThat(sA2.getEntity()).isEqualTo(sE2);
+        assertThat(sA2.getPreviousValue()).isEqualTo(sA1);
+
+        assertThat(sB1.getEntity()).isNull();
+        assertThat(sB1.getPreviousValue()).isNull();
+
+        assertThat(sB2.getEntity()).isNull();
+        assertThat(sB2.getPreviousValue()).isNull();
+    }
+
+    @Test
+    void solveWhenIgnoringInconsistentSolutionsThrowsIfInconsistentEntityPinned() {
         // Solver config
         var solverConfig = PlannerTestUtils.buildSolverConfig(
                 TestdataDependencyNoInconsistentFieldSolution.class, TestdataDependencyNoInconsistentFieldEntity.class,
@@ -1485,15 +1543,16 @@ void solveWhenIgnoringInconsistentSolutionsThrowsIfInitialSolutionInconsistent()
         var entities = List.of(e1, e2);
         var values = List.of(a1, a2, b1, b2);
 
+        e1.setPinnedToIndex(1);
+
         var problem = new TestdataDependencyNoInconsistentFieldSolution();
 
         problem.setEntities(entities);
         problem.setValues(values);
 
-        // TODO: Verify the values were unassigned instead
-        assertThatCode(() -> PlannerTestUtils.solve(solverConfig, problem)).isInstanceOf(IllegalStateException.class)
-                .hasMessageContainingAll("The initial solution passed to the solver",
-                        "is invalid because it has dependency loops");
+        assertThatCode(() -> PlannerTestUtils.solve(solverConfig, problem, false))
+                .isInstanceOf(IllegalStateException.class)
+                .hasMessageContainingAll("Entity", "b2", "while involved in a dependency loop");
     }
 
     @Test
diff --git a/core/src/test/java/ai/timefold/solver/core/testdomain/shadow/no_inconsistent_field/TestdataDependencyNoInconsistentFieldEntity.java b/core/src/test/java/ai/timefold/solver/core/testdomain/shadow/no_inconsistent_field/TestdataDependencyNoInconsistentFieldEntity.java
@@ -7,6 +7,7 @@
 
 import ai.timefold.solver.core.api.domain.common.PlanningId;
 import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
+import ai.timefold.solver.core.api.domain.entity.PlanningPinToIndex;
 import ai.timefold.solver.core.api.domain.variable.PlanningListVariable;
 
 @PlanningEntity
@@ -17,6 +18,9 @@ public class TestdataDependencyNoInconsistentFieldEntity {
     @PlanningListVariable
     List<TestdataDependencyNoInconsistentFieldValue> values;
 
+    @PlanningPinToIndex
+    int pinnedToIndex;
+
     LocalDateTime startTime;
 
     public TestdataDependencyNoInconsistentFieldEntity() {
@@ -57,6 +61,14 @@ public void setStartTime(LocalDateTime startTime) {
         this.startTime = startTime;
     }
 
+    public int getPinnedToIndex() {
+        return pinnedToIndex;
+    }
+
+    public void setPinnedToIndex(int pinnedToIndex) {
+        this.pinnedToIndex = pinnedToIndex;
+    }
+
     @Override
     public String toString() {
         return "TestdataPredecessorEntity{id=%s, values=%s, startTime=%s}".formatted(id, values, startTime);

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@`
`2`	`2`
`3`	`3`	`import java.util.ArrayList;`
`4`	`4`	`import java.util.Arrays;`
	`5`	`+import java.util.Collections;`
`5`	`6`	`import java.util.Comparator;`
`6`	`7`	`import java.util.HashSet;`
`7`	`8`	`import java.util.IdentityHashMap;`
`@@ -136,4 +137,9 @@ public void afterVariableChanged(VariableMetaModel<?, ?, ?> variableReference, O`
`136`	`137`	`}`
`137`	`138`	`}`
`138`	`139`
	`140`	`+ @Override`
	`141`	`+ public List<Object> getInconsistentEntities() {`
	`142`	`+ return Collections.emptyList();`
	`143`	`+ }`
	`144`	`+`
`139`	`145`	`}`
Original file line number	Diff line number	Diff line change
`@@ -70,4 +70,5 @@ default void afterListVariableChanged(VariableMetaModel<?, ?, ?> variableReferen`
`70`	`70`	`// Most graphs do not have edges that depend on a list variable's contents.`
`71`	`71`	`}`
`72`	`72`
	`73`	`+ List<Object> getInconsistentEntities();`
`73`	`74`	`}`