fix: forbid pinning uninitialized entities when unassigned not allowed (#821)

Author: triceo

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

@@ -38,9 +38,6 @@
  * the <em>order</em> in which customers are visited and tasks are being worked on matters. Also, each customer
  * must be visited <em>once</em> and each task must be completed by <em>exactly one</em> employee.
  *
- * <p>
- * <strong>Overconstrained planning is currently not supported for list variables.</strong>
- *
  * @see PlanningPin
  * @see PlanningPinToIndex
  */

core/src/main/java/ai/timefold/solver/core/impl/domain/variable/descriptor/ListVariableDescriptor.java

@@ -101,7 +101,6 @@ public Class<?> getElementType() {
 
     public int countUnassigned(Solution_ solution) {
         var valueCount = new MutableLong(getValueRangeSize(solution, null));
-        var entityDescriptor = getEntityDescriptor();
         var solutionDescriptor = entityDescriptor.getSolutionDescriptor();
         solutionDescriptor.visitEntitiesByEntityClass(solution,
                 entityDescriptor.getEntityClass(), entity -> {
@@ -113,11 +112,12 @@ public int countUnassigned(Solution_ solution) {
     }
 
     public InverseRelationShadowVariableDescriptor<Solution_> getInverseRelationShadowVariableDescriptor() {
-        var entityDescriptor = getEntityDescriptor().getSolutionDescriptor().findEntityDescriptor(getElementType());
-        if (entityDescriptor == null) {
+        var inverseRelationEntityDescriptor =
+                getEntityDescriptor().getSolutionDescriptor().findEntityDescriptor(getElementType());
+        if (inverseRelationEntityDescriptor == null) {
             return null;
         }
-        var applicableShadowDescriptors = entityDescriptor.getShadowVariableDescriptors()
+        var applicableShadowDescriptors = inverseRelationEntityDescriptor.getShadowVariableDescriptors()
                 .stream()
                 .filter(f -> f instanceof InverseRelationShadowVariableDescriptor<Solution_> inverseRelationShadowVariableDescriptor
                         && Objects.equals(inverseRelationShadowVariableDescriptor.getSourceVariableDescriptorList().get(0),
@@ -131,7 +131,7 @@ public InverseRelationShadowVariableDescriptor<Solution_> getInverseRelationShad
                     """
                             Instances of entityClass (%s) may be used in list variable (%s), but the class has more than one @%s-annotated field (%s).
                             Remove the annotations from all but one field."""
-                            .formatted(entityDescriptor.getEntityClass().getCanonicalName(),
+                            .formatted(inverseRelationEntityDescriptor.getEntityClass().getCanonicalName(),
                                     getSimpleEntityAndVariableName(),
                                     InverseRelationShadowVariable.class.getSimpleName(),
                                     applicableShadowDescriptors.stream()
@@ -150,7 +150,8 @@ Instances of entityClass (%s) may be used in list variable (%s), but the class h
     public List<Object> getValue(Object entity) {
         Object value = super.getValue(entity);
         if (value == null) {
-            throw new IllegalStateException("The planning list variable (" + this + ") of entity (" + entity + ") is null.");
+            throw new IllegalStateException("The planning list variable (%s) of entity (%s) is null."
+                    .formatted(this, entity));
         }
         return (List<Object>) value;
     }

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

@@ -223,6 +223,8 @@ public void setWorkingSolution(Solution_ workingSolution) {
             solutionDescriptor.visitAllProblemFacts(workingSolution, visitor);
         }
         // This visits all the entities, applying the visitor if non-null.
+        Consumer<Object> entityValidator = entity -> scoreDirectorFactory.validateEntity(this, entity);
+        visitor = visitor == null ? entityValidator : visitor.andThen(entityValidator);
         var initializationStatistics = solutionDescriptor.computeInitializationStatistics(workingSolution, visitor);
         setWorkingEntityListDirty();
 

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

@@ -2,7 +2,10 @@
 
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
 import ai.timefold.solver.core.api.score.Score;
+import ai.timefold.solver.core.api.score.director.ScoreDirector;
 import ai.timefold.solver.core.impl.domain.solution.descriptor.SolutionDescriptor;
+import ai.timefold.solver.core.impl.domain.variable.descriptor.BasicVariableDescriptor;
+import ai.timefold.solver.core.impl.domain.variable.descriptor.ListVariableDescriptor;
 import ai.timefold.solver.core.impl.score.definition.ScoreDefinition;
 import ai.timefold.solver.core.impl.score.trend.InitializingScoreTrend;
 
@@ -21,7 +24,8 @@ public abstract class AbstractScoreDirectorFactory<Solution_, Score_ extends Sco
 
     protected final transient Logger logger = LoggerFactory.getLogger(getClass());
 
-    protected SolutionDescriptor<Solution_> solutionDescriptor;
+    protected final SolutionDescriptor<Solution_> solutionDescriptor;
+    protected final ListVariableDescriptor<Solution_> listVariableDescriptor;
 
     protected InitializingScoreTrend initializingScoreTrend;
 
@@ -32,6 +36,7 @@ public abstract class AbstractScoreDirectorFactory<Solution_, Score_ extends Sco
 
     public AbstractScoreDirectorFactory(SolutionDescriptor<Solution_> solutionDescriptor) {
         this.solutionDescriptor = solutionDescriptor;
+        this.listVariableDescriptor = solutionDescriptor.getListVariableDescriptor();
     }
 
     @Override
@@ -108,4 +113,25 @@ public void assertScoreFromScratch(Solution_ solution) {
         }
     }
 
+    public void validateEntity(ScoreDirector<Solution_> scoreDirector, Object entity) {
+        if (listVariableDescriptor == null) { // Only basic variables.
+            var entityDescriptor = solutionDescriptor.findEntityDescriptorOrFail(entity.getClass());
+            if (entityDescriptor.isMovable(scoreDirector, entity)) {
+                return;
+            }
+            for (var variableDescriptor : entityDescriptor.getGenuineVariableDescriptorList()) {
+                var basicVariableDescriptor = (BasicVariableDescriptor<Solution_>) variableDescriptor;
+                if (basicVariableDescriptor.allowsUnassigned()) {
+                    continue;
+                }
+                var value = basicVariableDescriptor.getValue(entity);
+                if (value == null) {
+                    throw new IllegalStateException(
+                            "The entity (%s) has a variable (%s) pinned to null, even though unassigned values are not allowed."
+                                    .formatted(entity, basicVariableDescriptor.getVariableName()));
+                }
+            }
+        }
+    }
+
 }