feat: enable entity value range for list variables

core/src/main/java/ai/timefold/solver/core/config/heuristic/selector/move/NearbyUtil.java

@@ -162,7 +162,7 @@ private static ValueSelectorConfig configureSecondaryValueSelector(ValueSelector
                 .withValueSelectorConfig(valueConfig);
     }
 
-    private static String addRandomSuffix(String name, Random random) {
+    public static String addRandomSuffix(String name, Random random) {
         var value = new StringBuilder(name);
         value.append("-");
         random.ints(97, 122) // ['a', 'z']

core/src/main/java/ai/timefold/solver/core/config/util/ConfigUtils.java

@@ -1,6 +1,7 @@
 package ai.timefold.solver.core.config.util;
 
 import static ai.timefold.solver.core.impl.domain.common.accessor.MemberAccessorFactory.MemberAccessorType.FIELD_OR_READ_METHOD;
+import static ai.timefold.solver.core.impl.domain.solution.cloner.DeepCloningUtils.IMMUTABLE_CLASSES;
 
 import java.lang.annotation.Annotation;
 import java.lang.reflect.AnnotatedElement;
@@ -449,6 +450,17 @@ Maybe the member (%s) should return a parameterized %s."""
                                 memberName, type, memberName, type.getSimpleName())));
     }
 
+    /**
+     * @param type the class type
+     * @return true if it is immutable; otherwise false
+     */
+    public static boolean isGenericTypeImmutable(Class<?> type) {
+        if (type == null) {
+            return false;
+        }
+        return type.isRecord() || IMMUTABLE_CLASSES.contains(type);
+    }
+
     public static Optional<Class<?>> extractGenericTypeParameter(@NonNull String parentClassConcept,
             @NonNull Class<?> parentClass, @NonNull Class<?> type, @NonNull Type genericType,
             @Nullable Class<? extends Annotation> annotationClass, @NonNull String memberName) {

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/DefaultConstructionHeuristicPhase.java

@@ -64,7 +64,8 @@ public void solve(SolverScope<Solution_> solverScope) {
             // (When it exhausts all values, it will start over from the beginning.)
             // To prevent that, we need to limit the number of steps to the number of unassigned values.
             var workingSolution = phaseScope.getWorkingSolution();
-            maxStepCount = solutionDescriptor.getListVariableDescriptor().countUnassigned(workingSolution);
+            maxStepCount = solutionDescriptor.getListVariableDescriptor().countUnassigned(workingSolution,
+                    solverScope.getValueRangeManager());
         }
 
         TerminationStatus earlyTerminationStatus = null;

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/placer/AbstractEntityPlacerFactory.java

@@ -28,7 +28,7 @@ protected ChangeMoveSelectorConfig buildChangeMoveSelectorConfig(HeuristicConfig
                 .withVariableName(variableDescriptor.getVariableName());
         if (ValueSelectorConfig.hasSorter(configPolicy.getValueSorterManner(), variableDescriptor)) {
             changeValueSelectorConfig = changeValueSelectorConfig
-                    .withCacheType(variableDescriptor.isValueRangeEntityIndependent() ? PHASE : STEP)
+                    .withCacheType(variableDescriptor.canExtractValueRangeFromSolution() ? PHASE : STEP)
                     .withSelectionOrder(SelectionOrder.SORTED)
                     .withSorterManner(configPolicy.getValueSorterManner());
         }

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/placer/QueuedValuePlacer.java

@@ -9,17 +9,17 @@
 import ai.timefold.solver.core.impl.heuristic.selector.move.MoveSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.move.factory.MoveIteratorFactory;
 import ai.timefold.solver.core.impl.heuristic.selector.move.generic.list.ListChangeMoveSelector;
-import ai.timefold.solver.core.impl.heuristic.selector.value.EntityIndependentValueSelector;
-import ai.timefold.solver.core.impl.heuristic.selector.value.decorator.EntityIndependentFilteringValueSelector;
+import ai.timefold.solver.core.impl.heuristic.selector.value.IterableValueSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.value.decorator.FilteringValueSelector;
+import ai.timefold.solver.core.impl.heuristic.selector.value.decorator.IterableFilteringValueSelector;
 
 public class QueuedValuePlacer<Solution_> extends AbstractEntityPlacer<Solution_> implements EntityPlacer<Solution_> {
 
-    protected final EntityIndependentValueSelector<Solution_> valueSelector;
+    protected final IterableValueSelector<Solution_> valueSelector;
     protected final MoveSelector<Solution_> moveSelector;
 
     public QueuedValuePlacer(EntityPlacerFactory<Solution_> factory, HeuristicConfigPolicy<Solution_> configPolicy,
-            EntityIndependentValueSelector<Solution_> valueSelector, MoveSelector<Solution_> moveSelector) {
+            IterableValueSelector<Solution_> valueSelector, MoveSelector<Solution_> moveSelector) {
         super(factory, configPolicy);
         this.valueSelector = valueSelector;
         this.moveSelector = moveSelector;
@@ -67,7 +67,7 @@ protected Placement<Solution_> createUpcomingSelection() {
     @Override
     public EntityPlacer<Solution_> rebuildWithFilter(SelectionFilter<Solution_, Object> filter) {
         return new QueuedValuePlacer<>(factory, configPolicy,
-                (EntityIndependentFilteringValueSelector<Solution_>) FilteringValueSelector.of(valueSelector, filter),
+                (IterableFilteringValueSelector<Solution_>) FilteringValueSelector.of(valueSelector, filter),
                 moveSelector);
     }
 

core/src/main/java/ai/timefold/solver/core/impl/constructionheuristic/placer/QueuedValuePlacerFactory.java

@@ -15,16 +15,17 @@
 import ai.timefold.solver.core.impl.heuristic.HeuristicConfigPolicy;
 import ai.timefold.solver.core.impl.heuristic.selector.move.MoveSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.move.MoveSelectorFactory;
-import ai.timefold.solver.core.impl.heuristic.selector.value.EntityIndependentValueSelector;
+import ai.timefold.solver.core.impl.heuristic.selector.value.IterableValueSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.value.ValueSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.value.ValueSelectorFactory;
 
 public class QueuedValuePlacerFactory<Solution_>
         extends AbstractEntityPlacerFactory<Solution_, QueuedValuePlacerConfig> {
 
     public static QueuedValuePlacerConfig unfoldNew(MoveSelectorConfig templateMoveSelectorConfig) {
-        throw new UnsupportedOperationException("The <constructionHeuristic> contains a moveSelector ("
-                + templateMoveSelectorConfig + ") and the <queuedValuePlacer> does not support unfolding those yet.");
+        throw new UnsupportedOperationException(
+                "The <constructionHeuristic> contains a moveSelector (%s) and the <queuedValuePlacer> does not support unfolding those yet."
+                        .formatted(templateMoveSelectorConfig));
     }
 
     public QueuedValuePlacerFactory(QueuedValuePlacerConfig placerConfig) {
@@ -48,15 +49,14 @@ public QueuedValuePlacer<Solution_> buildEntityPlacer(HeuristicConfigPolicy<Solu
 
         MoveSelector<Solution_> moveSelector = MoveSelectorFactory.<Solution_> create(moveSelectorConfig_)
                 .buildMoveSelector(configPolicy, SelectionCacheType.JUST_IN_TIME, SelectionOrder.ORIGINAL, false);
-        if (!(valueSelector instanceof EntityIndependentValueSelector)) {
-            throw new IllegalArgumentException("The queuedValuePlacer (" + this
-                    + ") needs to be based on an "
-                    + EntityIndependentValueSelector.class.getSimpleName() + " (" + valueSelector + ")."
-                    + " Check your @" + ValueRangeProvider.class.getSimpleName() + " annotations.");
+        if (!(valueSelector instanceof IterableValueSelector<Solution_> iterableValueSelector)) {
+            throw new IllegalArgumentException(
+                    "The queuedValuePlacer (%s) needs to be based on an %s (%s). Check your @%s annotations.".formatted(this,
+                            IterableValueSelector.class.getSimpleName(), valueSelector,
+                            ValueRangeProvider.class.getSimpleName()));
 
         }
-        return new QueuedValuePlacer<>(this, configPolicy, (EntityIndependentValueSelector<Solution_>) valueSelector,
-                moveSelector);
+        return new QueuedValuePlacer<>(this, configPolicy, iterableValueSelector, moveSelector);
     }
 
     private ValueSelectorConfig buildValueSelectorConfig(HeuristicConfigPolicy<Solution_> configPolicy,

core/src/main/java/ai/timefold/solver/core/impl/domain/entity/descriptor/EntityDescriptor.java

@@ -27,8 +27,6 @@
 import ai.timefold.solver.core.api.domain.entity.PlanningPin;
 import ai.timefold.solver.core.api.domain.entity.PlanningPinToIndex;
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
-import ai.timefold.solver.core.api.domain.valuerange.CountableValueRange;
-import ai.timefold.solver.core.api.domain.valuerange.ValueRange;
 import ai.timefold.solver.core.api.domain.valuerange.ValueRangeProvider;
 import ai.timefold.solver.core.api.domain.variable.AnchorShadowVariable;
 import ai.timefold.solver.core.api.domain.variable.CascadingUpdateShadowVariable;
@@ -67,6 +65,7 @@
 import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.ComparatorSelectionSorter;
 import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.SelectionSorter;
 import ai.timefold.solver.core.impl.heuristic.selector.common.decorator.WeightFactorySelectionSorter;
+import ai.timefold.solver.core.impl.score.director.ValueRangeManager;
 import ai.timefold.solver.core.impl.util.CollectionUtils;
 import ai.timefold.solver.core.impl.util.MutableInt;
 import ai.timefold.solver.core.preview.api.domain.metamodel.PlanningEntityMetaModel;
@@ -859,18 +858,31 @@ public PlanningPinToIndexReader getEffectivePlanningPinToIndexReader() {
         return effectivePlanningPinToIndexReader;
     }
 
-    public long getMaximumValueCount(Solution_ solution, Object entity) {
+    public long getMaximumValueCount(Solution_ solution, Object entity, ValueRangeManager<Solution_> valueRangeManager) {
         var maximumValueCount = 0L;
         for (var variableDescriptor : effectiveGenuineVariableDescriptorList) {
-            maximumValueCount = Math.max(maximumValueCount, variableDescriptor.getValueRangeSize(solution, entity));
+            if (variableDescriptor.canExtractValueRangeFromSolution()) {
+                maximumValueCount = Math.max(maximumValueCount,
+                        valueRangeManager.countOnSolution(variableDescriptor.getValueRangeDescriptor(),
+                                solution));
+            } else {
+                maximumValueCount = Math.max(maximumValueCount,
+                        valueRangeManager.countOnEntity(variableDescriptor.getValueRangeDescriptor(),
+                                entity));
+
+            }
         }
         return maximumValueCount;
 
     }
 
-    public void processProblemScale(Solution_ solution, Object entity, ProblemScaleTracker tracker) {
+    public void processProblemScale(Solution_ solution, Object entity, ProblemScaleTracker tracker,
+            ValueRangeManager<Solution_> valueRangeManager) {
         for (var variableDescriptor : effectiveGenuineVariableDescriptorList) {
-            var valueCount = variableDescriptor.getValueRangeSize(solution, entity);
+            var valueCount = variableDescriptor.canExtractValueRangeFromSolution()
+                    ? valueRangeManager.countOnSolution(variableDescriptor.getValueRangeDescriptor(),
+                            solution)
+                    : valueRangeManager.countOnEntity(variableDescriptor.getValueRangeDescriptor(), entity);
             // TODO: When minimum Java supported is 21, this can be replaced with a sealed interface switch
             if (variableDescriptor instanceof BasicVariableDescriptor<Solution_> basicVariableDescriptor) {
                 if (basicVariableDescriptor.isChained()) {
@@ -880,34 +892,34 @@ public void processProblemScale(Solution_ solution, Object entity, ProblemScaleT
                         tracker.addPinnedListValueCount(1);
                     }
                     // Anchors are entities
-                    var valueRange = variableDescriptor.getValueRangeDescriptor().extractValueRange(solution, entity);
-                    if (valueRange instanceof CountableValueRange<?> countableValueRange) {
-                        var valueIterator = countableValueRange.createOriginalIterator();
-                        while (valueIterator.hasNext()) {
-                            var value = valueIterator.next();
-                            if (variableDescriptor.isValuePotentialAnchor(value)) {
-                                if (tracker.isAnchorVisited(value)) {
-                                    continue;
-                                }
-                                // Assumes anchors are not pinned
-                                tracker.incrementListEntityCount(true);
+                    var valueRange = variableDescriptor.canExtractValueRangeFromSolution()
+                            ? valueRangeManager.getFromSolution(variableDescriptor.getValueRangeDescriptor(),
+                                    solution)
+                            : valueRangeManager.getFromEntity(variableDescriptor.getValueRangeDescriptor(),
+                                    entity);
+                    var valueIterator = valueRange.createOriginalIterator();
+                    while (valueIterator.hasNext()) {
+                        var value = valueIterator.next();
+                        if (variableDescriptor.isValuePotentialAnchor(value)) {
+                            if (tracker.isAnchorVisited(value)) {
+                                continue;
                             }
+                            // Assumes anchors are not pinned
+                            tracker.incrementListEntityCount(true);
                         }
-                    } else {
-                        throw new IllegalStateException("""
-                                The value range (%s) for variable (%s) is not countable.
-                                Verify that a @%s does not return a %s when it can return %s or %s.
-                                """.formatted(valueRange, variableDescriptor.getSimpleEntityAndVariableName(),
-                                ValueRangeProvider.class.getSimpleName(), ValueRange.class.getSimpleName(),
-                                CountableValueRange.class.getSimpleName(), Collection.class.getSimpleName()));
                     }
                 } else {
                     if (isMovable(solution, entity)) {
                         tracker.addBasicProblemScale(valueCount);
                     }
                 }
             } else if (variableDescriptor instanceof ListVariableDescriptor<Solution_> listVariableDescriptor) {
-                tracker.setListTotalValueCount((int) listVariableDescriptor.getValueRangeSize(solution, entity));
+                var size = variableDescriptor.canExtractValueRangeFromSolution()
+                        ? valueRangeManager.countOnSolution(listVariableDescriptor.getValueRangeDescriptor(),
+                                solution)
+                        : valueRangeManager.countOnEntity(listVariableDescriptor.getValueRangeDescriptor(),
+                                entity);
+                tracker.setListTotalValueCount((int) size);
                 if (isMovable(solution, entity)) {
                     tracker.incrementListEntityCount(true);
                     tracker.addPinnedListValueCount(listVariableDescriptor.getFirstUnpinnedIndex(entity));

core/src/main/java/ai/timefold/solver/core/impl/domain/solution/cloner/DeepCloningUtils.java

@@ -39,7 +39,7 @@
 public final class DeepCloningUtils {
 
     // Instances of these JDK classes will never be deep-cloned.
-    private static final Set<Class<?>> IMMUTABLE_CLASSES = Set.of(
+    public static final Set<Class<?>> IMMUTABLE_CLASSES = Set.of(
             // Numbers
             Byte.class, Short.class, Integer.class, Long.class, Float.class, Double.class, BigInteger.class, BigDecimal.class,
             // Optional