refactor: remove isIncremental/incrementalAccumulator switch from *ConstraintCollector

*ConstraintCollectorAccumulator now extends the corresponding function type
(BiFunction/TriFunction/QuadFunction/PentaFunction) and throws on apply().
Bavet nodes detect incremental via instanceof in toIncremental() instead of
isIncremental(). fromIncremental() deleted; all built-in impls return the
accumulator type directly as a covariant override of accumulator().

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: triceo

core/src/main/java/ai/timefold/solver/core/api/score/stream/bi/BiConstraintCollector.java

@@ -33,23 +33,11 @@ public interface BiConstraintCollector<A, B, ResultContainer_, Result_> {
 
     /**
      * As defined by {@link UniConstraintCollector#accumulator()}, but for {@link BiConstraintStream}.
+     * 
+     * @see BiConstraintCollectorAccumulator An incremental API to be returned instead of the deprecated plain tri-function.
      */
     TriFunction<ResultContainer_, A, B, Runnable> accumulator();
 
-    /**
-     * As defined by {@link UniConstraintCollector#incrementalAccumulator()}, but for {@link BiConstraintStream}.
-     */
-    default BiConstraintCollectorAccumulator<ResultContainer_, A, B> incrementalAccumulator() {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * As defined by {@link UniConstraintCollector#isIncremental()}, but for {@link BiConstraintStream}.
-     */
-    default boolean isIncremental() {
-        return false;
-    }
-
     /**
      * As defined by {@link UniConstraintCollector#finisher()}, but for {@link BiConstraintStream}.
      */

core/src/main/java/ai/timefold/solver/core/api/score/stream/bi/BiConstraintCollectorAccumulator.java

@@ -1,21 +1,36 @@
 package ai.timefold.solver.core.api.score.stream.bi;
 
+import ai.timefold.solver.core.api.function.TriFunction;
 import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollectorAccumulator;
 
 import org.jspecify.annotations.NullMarked;
 
 /**
  * As defined by {@link UniConstraintCollectorAccumulator},
  * only for {@link BiConstraintCollector}.
+ * <p>
+ * This interface extends {@link TriFunction} for type compatibility, but {@link #apply(Object, Object, Object)}
+ * always throws {@link UnsupportedOperationException}. Use {@link #intoGroup(Object)} instead.
  */
 @NullMarked
 @FunctionalInterface
-public interface BiConstraintCollectorAccumulator<ResultContainer_, A, B> {
+public interface BiConstraintCollectorAccumulator<ResultContainer_, A, B>
+        extends TriFunction<ResultContainer_, A, B, Runnable> {
 
     /**
      * As defined by {@link UniConstraintCollectorAccumulator#intoGroup(Object)},
      * only for {@link BiConstraintCollector}.
      */
     BiConstraintCollectorValueHandle<A, B> intoGroup(ResultContainer_ resultContainer);
 
+    /**
+     * @deprecated Use {@link #intoGroup(Object)} instead.
+     * @throws UnsupportedOperationException always
+     */
+    @Deprecated(since = "2.2.0", forRemoval = true)
+    @Override
+    default Runnable apply(ResultContainer_ resultContainer, A a, B b) {
+        throw new UnsupportedOperationException("Use intoGroup() instead.");
+    }
+
 }

core/src/main/java/ai/timefold/solver/core/api/score/stream/quad/QuadConstraintCollector.java

@@ -35,23 +35,11 @@ public interface QuadConstraintCollector<A, B, C, D, ResultContainer_, Result_>
 
     /**
      * As defined by {@link UniConstraintCollector#accumulator()}, but for {@link QuadConstraintStream}.
+     * 
+     * @see QuadConstraintCollectorAccumulator An incremental API to be returned instead of the deprecated plain penta-function.
      */
     PentaFunction<ResultContainer_, A, B, C, D, Runnable> accumulator();
 
-    /**
-     * As defined by {@link UniConstraintCollector#incrementalAccumulator()}, but for {@link QuadConstraintStream}.
-     */
-    default QuadConstraintCollectorAccumulator<ResultContainer_, A, B, C, D> incrementalAccumulator() {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * As defined by {@link UniConstraintCollector#isIncremental()}, but for {@link QuadConstraintStream}.
-     */
-    default boolean isIncremental() {
-        return false;
-    }
-
     /**
      * As defined by {@link UniConstraintCollector#finisher()}, but for {@link QuadConstraintStream}.
      */

core/src/main/java/ai/timefold/solver/core/api/score/stream/quad/QuadConstraintCollectorAccumulator.java

@@ -1,21 +1,36 @@
 package ai.timefold.solver.core.api.score.stream.quad;
 
+import ai.timefold.solver.core.api.function.PentaFunction;
 import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollectorAccumulator;
 
 import org.jspecify.annotations.NullMarked;
 
 /**
  * As defined by {@link UniConstraintCollectorAccumulator},
  * only for {@link QuadConstraintCollector}.
+ * <p>
+ * Extends {@link PentaFunction} for detection purposes; {@link #apply} always throws.
+ * Use {@link #intoGroup} instead.
  */
 @NullMarked
 @FunctionalInterface
-public interface QuadConstraintCollectorAccumulator<ResultContainer_, A, B, C, D> {
+public interface QuadConstraintCollectorAccumulator<ResultContainer_, A, B, C, D>
+        extends PentaFunction<ResultContainer_, A, B, C, D, Runnable> {
 
     /**
      * As defined by {@link UniConstraintCollectorAccumulator#intoGroup(Object)},
      * only for {@link QuadConstraintCollector}.
      */
     QuadConstraintCollectorValueHandle<A, B, C, D> intoGroup(ResultContainer_ resultContainer);
 
+    /**
+     * @deprecated Use {@link #intoGroup(Object)} instead.
+     * @throws UnsupportedOperationException always
+     */
+    @Deprecated(since = "2.2.0", forRemoval = true)
+    @Override
+    default Runnable apply(ResultContainer_ resultContainer, A a, B b, C c, D d) {
+        throw new UnsupportedOperationException("Use intoGroup() instead.");
+    }
+
 }

core/src/main/java/ai/timefold/solver/core/api/score/stream/tri/TriConstraintCollector.java

@@ -34,23 +34,11 @@ public interface TriConstraintCollector<A, B, C, ResultContainer_, Result_> {
 
     /**
      * As defined by {@link UniConstraintCollector#accumulator()}, but for {@link TriConstraintStream}.
+     * 
+     * @see TriConstraintCollectorAccumulator An incremental API to be returned instead of the deprecated plain quad-function.
      */
     QuadFunction<ResultContainer_, A, B, C, Runnable> accumulator();
 
-    /**
-     * As defined by {@link UniConstraintCollector#incrementalAccumulator()}, but for {@link TriConstraintStream}.
-     */
-    default TriConstraintCollectorAccumulator<ResultContainer_, A, B, C> incrementalAccumulator() {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * As defined by {@link UniConstraintCollector#isIncremental()}, but for {@link TriConstraintStream}.
-     */
-    default boolean isIncremental() {
-        return false;
-    }
-
     /**
      * As defined by {@link UniConstraintCollector#finisher()}, but for {@link TriConstraintStream}.
      */

core/src/main/java/ai/timefold/solver/core/api/score/stream/tri/TriConstraintCollectorAccumulator.java

@@ -1,21 +1,36 @@
 package ai.timefold.solver.core.api.score.stream.tri;
 
+import ai.timefold.solver.core.api.function.QuadFunction;
 import ai.timefold.solver.core.api.score.stream.uni.UniConstraintCollectorAccumulator;
 
 import org.jspecify.annotations.NullMarked;
 
 /**
  * As defined by {@link UniConstraintCollectorAccumulator},
  * only for {@link TriConstraintCollector}.
+ * <p>
+ * This interface extends {@link QuadFunction}, but {@link #apply(Object, Object, Object, Object)} always throws
+ * {@link UnsupportedOperationException}. Use {@link #intoGroup(Object)} instead.
  */
 @NullMarked
 @FunctionalInterface
-public interface TriConstraintCollectorAccumulator<ResultContainer_, A, B, C> {
+public interface TriConstraintCollectorAccumulator<ResultContainer_, A, B, C>
+        extends QuadFunction<ResultContainer_, A, B, C, Runnable> {
 
     /**
      * As defined by {@link UniConstraintCollectorAccumulator#intoGroup(Object)},
      * only for {@link TriConstraintCollector}.
      */
     TriConstraintCollectorValueHandle<A, B, C> intoGroup(ResultContainer_ resultContainer);
 
+    /**
+     * @deprecated Use {@link #intoGroup(Object)} instead.
+     * @throws UnsupportedOperationException always
+     */
+    @Deprecated(since = "2.2.0", forRemoval = true)
+    @Override
+    default Runnable apply(ResultContainer_ resultContainer, A a, B b, C c) {
+        throw new UnsupportedOperationException("Use intoGroup() instead.");
+    }
+
 }

core/src/main/java/ai/timefold/solver/core/api/score/stream/uni/UniConstraintCollector.java

@@ -15,19 +15,8 @@
  * Usually created with {@link ConstraintCollectors}.
  * Used by {@link UniConstraintStream#groupBy(Function, UniConstraintCollector)}, ...
  * <p>
- * Loosely based on JDK's {@link Collector}, but it returns an undo operation for each accumulation
+ * Loosely based on JDK's {@link Collector}, but it supports undoing each accumulation
  * to enable incremental score calculation in {@link UniConstraintStream#groupBy(UniConstraintCollector)}.
- * It has two modes of operation:
- * <dl>
- * <dt>Insert+Retract</dt>
- * <dd>An element cannot be updated - every update is done by full retraction and reinsertion.
- * This is simpler to implement and therefore it is the default.
- * Provided by {@link #accumulator()}.</dd>
- * <dt>Fully incremental</dt>
- * <dd>An element may be inserted, updated and retracted,
- * allowing for increased performance when a smart update operation is available.
- * Enabled by {@link #incrementalAccumulator()}, when {@link #isIncremental()} returns true.</dd>
- * </dl>
  * <p>
  * It is recommended that if two constraint collectors implement the same functionality,
  * they should {@link Object#equals(Object) be equal}.
@@ -55,38 +44,19 @@ public interface UniConstraintCollector<A, ResultContainer_, Result_> {
     Supplier<ResultContainer_> supplier();
 
     /**
-     * A lambda that extracts data from the matched fact,
+     * A type that extracts data from the matched fact,
      * accumulates it in the result container
      * and returns an undo operation for that accumulation.
+     * <p>
+     * Implementations should return a {@link UniConstraintCollectorAccumulator} instead of a plain {@link BiFunction};
+     * the solver detects this via {@code instanceof} and uses incremental insert/update/retract automatically.
+     * The declared return type stays {@link BiFunction} for backward compatibility
+     * and will be removed in a future major version of the solver.
      *
      * @return the accumulator. Called to insert the match and retract it when it no longer belongs in the group.
-     * @see #incrementalAccumulator() High-performance alternative, disabled by default.
      */
     BiFunction<ResultContainer_, A, Runnable> accumulator();
 
-    /**
-     * A high-performance alternative to {@link #accumulator()} that returns an incremental accumulator.
-     * This is more difficult to implement and therefore it is optional.
-     * If implemented, override {@link #isIncremental()} to return true,
-     * which will cause the solver to use this implementation instead of {@link #accumulator()}.
-     *
-     * @return the accumulator. Called to insert the match, reflect changes
-     *         or to revert it when the fact no longer belongs in the group.
-     * @throws UnsupportedOperationException if {@link #isIncremental()} returns false
-     */
-    default UniConstraintCollectorAccumulator<ResultContainer_, A> incrementalAccumulator() {
-        throw new UnsupportedOperationException();
-    }
-
-    /**
-     * Whether the solver should use {@link #incrementalAccumulator()} instead of {@link #accumulator()}.
-     *
-     * @return defaults to false. Only override to true if {@link #incrementalAccumulator()} is implemented.
-     */
-    default boolean isIncremental() {
-        return false;
-    }
-
     /**
      * A lambda that converts the result container into the result.
      * The result may be null, typically when there is nothing accumulated

core/src/main/java/ai/timefold/solver/core/api/score/stream/uni/UniConstraintCollectorAccumulator.java

@@ -1,19 +1,22 @@
 package ai.timefold.solver.core.api.score.stream.uni;
 
+import java.util.function.BiFunction;
+
 import org.jspecify.annotations.NullMarked;
 
 /**
- * Used by {@link UniConstraintCollector#incrementalAccumulator()}.
- * Allows high-performance accumulation by providing an update operation
- * as well as by letting the accumulator decide whether the group was changed as a result of its operations,
- * but it is more difficult to implement.
+ * Used by {@link UniConstraintCollector#accumulator()} for incremental collectors.
+ * Extends {@link BiFunction} for backward compatibility, but {@link #apply(Object, Object)} always throws;
+ * use {@link #intoGroup(Object)} instead.
+ * Allows high-performance accumulation by providing an {@link UniConstraintCollectorValueHandle#replaceWith update} operation.
  *
  * @param <ResultContainer_>
  * @param <A>
  */
 @NullMarked
 @FunctionalInterface
-public interface UniConstraintCollectorAccumulator<ResultContainer_, A> {
+public interface UniConstraintCollectorAccumulator<ResultContainer_, A>
+        extends BiFunction<ResultContainer_, A, Runnable> {
 
     /**
      * Created every time a new value enters the group.
@@ -23,11 +26,22 @@ public interface UniConstraintCollectorAccumulator<ResultContainer_, A> {
      *        {@link UniConstraintCollector#supplier()} will be used to supply a fresh instance of the container;
      *        otherwise a pre-existing container will be used, carrying the accumulated state.
      *        {@link UniConstraintCollector#finisher()} will be used to extract the final accumulated value from the container.
-     *        The accumulator factory itself must not hold mutable cross-slot state;
-     *        any mutable state must live in the container or in the returned accumulated value.
-     * @return the accumulator for the value, which will be used to insert the value to the group,
+     *        The method itself must not maintain any state;
+     *        any container-level state must live in the container,
+     *        and any state required to update or remove the value must live in the handle.
+     * @return the handle for the value, which will be used to insert the value to the group,
      *         to update it while in the group, and to remove it from the group.
      */
     UniConstraintCollectorValueHandle<A> intoGroup(ResultContainer_ resultContainer);
 
+    /**
+     * @deprecated Use {@link #intoGroup(Object)} instead.
+     * @throws UnsupportedOperationException always
+     */
+    @Deprecated(since = "2.2.0", forRemoval = true)
+    @Override
+    default Runnable apply(ResultContainer_ resultContainer, A a) {
+        throw new UnsupportedOperationException("Use intoGroup() instead.");
+    }
+
 }

core/src/main/java/ai/timefold/solver/core/impl/bavet/bi/AbstractGroupBiNode.java

@@ -28,8 +28,7 @@ protected AbstractGroupBiNode(int groupStoreIndex, int groupAccumulatorIndex,
         super(groupStoreIndex, groupKeyFunction, collector.supplier(), collector.finisher(), nextNodesTupleLifecycle,
                 environmentMode);
         this.groupAccumulatorIndex = groupAccumulatorIndex;
-        this.incrementalAccumulator = collector.isIncremental() ? collector.incrementalAccumulator()
-                : BiCollectorUtils.toIncremental(collector.accumulator());
+        this.incrementalAccumulator = BiCollectorUtils.toIncremental(collector.accumulator());
     }
 
     protected AbstractGroupBiNode(int groupStoreIndex, Function<BiTuple<OldA, OldB>, GroupKey_> groupKeyFunction,

core/src/main/java/ai/timefold/solver/core/impl/bavet/quad/AbstractGroupQuadNode.java

@@ -28,8 +28,7 @@ protected AbstractGroupQuadNode(int groupStoreIndex, int groupAccumulatorIndex,
         super(groupStoreIndex, groupKeyFunction, collector.supplier(), collector.finisher(), nextNodesTupleLifecycle,
                 environmentMode);
         this.groupAccumulatorIndex = groupAccumulatorIndex;
-        this.incrementalAccumulator = collector.isIncremental() ? collector.incrementalAccumulator()
-                : QuadCollectorUtils.toIncremental(collector.accumulator());
+        this.incrementalAccumulator = QuadCollectorUtils.toIncremental(collector.accumulator());
     }
 
     protected AbstractGroupQuadNode(int groupStoreIndex,