chore: move streams change moves for list variable (#1727)

Introduces `ListChangeMoveProvider` that is capable of generating change
moves, assign moves and unassign moves.

To do that, several new capabilities are introduced to data streams,
which mimic capabilities of constraint streams and use the same
underlying Bavet nodes.

With the new value range work, nodes and data sessions no longer need
initialization, because everything we need, we can now find in the value
range manager.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: triceo

core/src/main/java/ai/timefold/solver/core/impl/bavet/AbstractSession.java

@@ -2,36 +2,24 @@
 
 import java.util.IdentityHashMap;
 import java.util.Map;
-import java.util.stream.Stream;
 
-import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
 import ai.timefold.solver.core.impl.bavet.uni.AbstractForEachUniNode;
 import ai.timefold.solver.core.impl.bavet.uni.AbstractForEachUniNode.LifecycleOperation;
-import ai.timefold.solver.core.impl.score.director.SessionContext;
 
-public abstract class AbstractSession implements AutoCloseable {
+public abstract class AbstractSession {
 
     private final NodeNetwork nodeNetwork;
-    private final Map<Class<?>, AbstractForEachUniNode.InitializableForEachNode<Object>[]> initializeEffectiveClassToNodeArrayMap;
     private final Map<Class<?>, AbstractForEachUniNode<Object>[]> insertEffectiveClassToNodeArrayMap;
     private final Map<Class<?>, AbstractForEachUniNode<Object>[]> updateEffectiveClassToNodeArrayMap;
     private final Map<Class<?>, AbstractForEachUniNode<Object>[]> retractEffectiveClassToNodeArrayMap;
 
     protected AbstractSession(NodeNetwork nodeNetwork) {
         this.nodeNetwork = nodeNetwork;
-        this.initializeEffectiveClassToNodeArrayMap = new IdentityHashMap<>(nodeNetwork.forEachNodeCount());
         this.insertEffectiveClassToNodeArrayMap = new IdentityHashMap<>(nodeNetwork.forEachNodeCount());
         this.updateEffectiveClassToNodeArrayMap = new IdentityHashMap<>(nodeNetwork.forEachNodeCount());
         this.retractEffectiveClassToNodeArrayMap = new IdentityHashMap<>(nodeNetwork.forEachNodeCount());
     }
 
-    @SuppressWarnings({ "unchecked", "rawtypes" })
-    public final void initialize(SessionContext context) {
-        for (var node : findInitializableNodes()) {
-            node.initialize(context);
-        }
-    }
-
     public final void insert(Object fact) {
         var factClass = fact.getClass();
         for (var node : findNodes(factClass, LifecycleOperation.INSERT)) {
@@ -57,29 +45,6 @@ private AbstractForEachUniNode<Object>[] findNodes(Class<?> factClass, Lifecycle
         return nodeArray;
     }
 
-    @SuppressWarnings("unchecked")
-    private AbstractForEachUniNode.InitializableForEachNode<Object>[] findInitializableNodes() {
-        // There will only be one solution class in the problem.
-        // Therefore we do not need to know what it is, and using the annotation class will serve as a unique key.
-        var factClass = PlanningSolution.class;
-        var effectiveClassToNodeArrayMap = initializeEffectiveClassToNodeArrayMap;
-        // Map.computeIfAbsent() would have created lambdas on the hot path, this will not.
-        var nodeArray = effectiveClassToNodeArrayMap.get(factClass);
-        if (nodeArray == null) {
-            nodeArray = nodeNetwork.getForEachNodes(factClass)
-                    .flatMap(node -> {
-                        if (node instanceof AbstractForEachUniNode.InitializableForEachNode<?> initializableForEachNode) {
-                            return Stream.of(initializableForEachNode);
-                        } else {
-                            return Stream.empty();
-                        }
-                    })
-                    .toArray(AbstractForEachUniNode.InitializableForEachNode[]::new);
-            effectiveClassToNodeArrayMap.put(factClass, nodeArray);
-        }
-        return nodeArray;
-    }
-
     public final void update(Object fact) {
         var factClass = fact.getClass();
         for (var node : findNodes(factClass, LifecycleOperation.UPDATE)) {
@@ -98,13 +63,4 @@ public void settle() {
         nodeNetwork.settle();
     }
 
-    @Override
-    public final void close() {
-        for (var node : findInitializableNodes()) {
-            // Initializable nodes get a supply manager, fair to assume they will be demanding supplies.
-            // Give them the opportunity to cancel those demands.
-            node.close();
-        }
-    }
-
 }

core/src/main/java/ai/timefold/solver/core/impl/bavet/uni/AbstractForEachUniNode.java

@@ -9,7 +9,6 @@
 import ai.timefold.solver.core.impl.bavet.common.tuple.TupleLifecycle;
 import ai.timefold.solver.core.impl.bavet.common.tuple.TupleState;
 import ai.timefold.solver.core.impl.bavet.common.tuple.UniTuple;
-import ai.timefold.solver.core.impl.score.director.SessionContext;
 
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -136,13 +135,4 @@ public enum LifecycleOperation {
         RETRACT
     }
 
-    public interface InitializableForEachNode<Solution_> extends AutoCloseable {
-
-        void initialize(SessionContext<Solution_> context);
-
-        @Override
-        void close(); // Drop the checked exception.
-
-    }
-
 }

core/src/main/java/ai/timefold/solver/core/impl/bavet/uni/ForEachFromSolutionUniNode.java

@@ -7,9 +7,8 @@
 import org.jspecify.annotations.Nullable;
 
 @NullMarked
-public sealed class ForEachIncludingUnassignedUniNode<A>
-        extends AbstractForEachUniNode<A>
-        permits ForEachFromSolutionUniNode {
+public final class ForEachIncludingUnassignedUniNode<A>
+        extends AbstractForEachUniNode<A> {
 
     public ForEachIncludingUnassignedUniNode(Class<A> forEachClass, TupleLifecycle<UniTuple<A>> nextNodesTupleLifecycle,
             int outputStoreSize) {

core/src/main/java/ai/timefold/solver/core/impl/bavet/uni/ForEachIncludingUnassignedUniNode.java

@@ -27,14 +27,9 @@ public String name() {
         return variableDescriptor.getVariableName();
     }
 
-    @Override
-    public boolean hasValueRangeOnEntity() {
-        return !variableDescriptor.canExtractValueRangeFromSolution();
-    }
-
     @Override
     public boolean allowsUnassignedValues() {
-        return false;
+        return variableDescriptor.allowsUnassignedValues();
     }
 
     @Override

core/src/main/java/ai/timefold/solver/core/impl/domain/solution/descriptor/DefaultPlanningListVariableMetaModel.java

@@ -27,11 +27,6 @@ public String name() {
         return variableDescriptor.getVariableName();
     }
 
-    @Override
-    public boolean hasValueRangeOnEntity() {
-        return !variableDescriptor.canExtractValueRangeFromSolution();
-    }
-
     @Override
     public boolean allowsUnassigned() {
         return variableDescriptor.allowsUnassigned();

core/src/main/java/ai/timefold/solver/core/impl/domain/solution/descriptor/DefaultPlanningVariableMetaModel.java

@@ -134,7 +134,7 @@ Convert your entities (%s) to use @%s instead."""
                             .formatted(moveProvidersClass, moveProviderList.size()));
         }
         var moveProvider = moveProviderList.get(0);
-        var moveStreamFactory = new DefaultMoveStreamFactory<>(solutionDescriptor);
+        var moveStreamFactory = new DefaultMoveStreamFactory<>(solutionDescriptor, configPolicy.getEnvironmentMode());
         var moveProducer = moveProvider.apply(moveStreamFactory);
         var moveRepository = new MoveStreamsBasedMoveRepository<>(moveStreamFactory, moveProducer,
                 pickSelectionOrder() == SelectionOrder.RANDOM);

core/src/main/java/ai/timefold/solver/core/impl/localsearch/DefaultLocalSearchPhaseFactory.java

@@ -89,7 +89,6 @@ public void stepEnded(AbstractStepScope<Solution_> stepScope) {
     @Override
     public void phaseEnded(AbstractPhaseScope<Solution_> phaseScope) {
         if (moveStreamSession != null) {
-            moveStreamSession.close();
             moveStreamSession = null;
         }
         phaseScope.getScoreDirector().setMoveRepository(null);

core/src/main/java/ai/timefold/solver/core/impl/move/MoveStreamsBasedMoveRepository.java

@@ -185,6 +185,12 @@ public final <Entity_, Value_> Value_ getValue(PlanningVariableMetaModel<Solutio
         return extractVariableDescriptor(variableMetaModel).getValue(entity);
     }
 
+    @Override
+    public <Entity_, Value_> int countValues(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
+            Entity_ entity) {
+        return extractVariableDescriptor(variableMetaModel).getValue(entity).size();
+    }
+
     @SuppressWarnings("unchecked")
     @Override
     public final <Entity_, Value_> Value_ getValueAtIndex(

core/src/main/java/ai/timefold/solver/core/impl/move/director/MoveDirector.java

@@ -2,7 +2,7 @@
 
 import java.util.Objects;
 
-import ai.timefold.solver.core.impl.move.streams.dataset.BiDataset;
+import ai.timefold.solver.core.impl.move.streams.dataset.bi.BiDataset;
 import ai.timefold.solver.core.impl.move.streams.maybeapi.stream.BiMoveConstructor;
 import ai.timefold.solver.core.impl.move.streams.maybeapi.stream.BiMoveStream;
 import ai.timefold.solver.core.impl.move.streams.maybeapi.stream.MoveProducer;