chore: add indictment support to Bavet's Node Network

core/src/build/revapi-differences.json

@@ -158,6 +158,12 @@
           "code": "java.method.addedToInterface",
           "new": "method <Result_> Result_ ai.timefold.solver.core.api.solver.phase.PhaseCommandContext<Solution_>::executeTemporarilyAndCalculateScore(ai.timefold.solver.core.preview.api.move.Move<Solution_>, java.util.function.Function<Solution_, Result_>, java.util.function.Function<Solution_, Result_>)",
           "justification": "PhaseCommandContext is only ever supplied by the solver to PhaseCommand.changeWorkingSolution(context); it is not implemented by user code."
+        },
+        {
+          "ignore": true,
+          "code": "java.method.addedToInterface",
+          "new": "method java.util.SequencedMap<java.lang.String, java.util.List<ai.timefold.solver.core.api.score.analysis.IndictmentAnalysis<Score_>>> ai.timefold.solver.core.api.score.analysis.ScoreAnalysis<Score_ extends ai.timefold.solver.core.api.score.Score<Score_>>::indictmentMap()",
+          "justification": "Add support for Indictments in ScoreAnalysis; it is not implemented by user code."
         }
       ]
     }

core/src/main/java/ai/timefold/solver/core/api/score/analysis/Indictable.java

@@ -0,0 +1,55 @@
+package ai.timefold.solver.core.api.score.analysis;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * An optional interface a class can implement to customize how it appears
+ * when indicted in a {@link ScoreAnalysis}.
+ * <p>
+ * When not implemented, the class' canonical name is used as the key in {@link ScoreAnalysis#indictmentMap()}}
+ * and {@link IndictmentAnalysis#indictee()} is the same instance.
+ * <p>
+ * The primary use case for implementing {@link Indictable} is if you have a separate
+ * solver and rest model, and don't want to expose your solver types in your REST API.
+ * <p>
+ * Note: {@link ScoreAnalysis} in general and indictments in particular
+ * are exclusive to Timefold Solver Enterprise Edition.
+ */
+@NullMarked
+public interface Indictable {
+
+    /**
+     * Returns the indictment class id used by {@link ScoreAnalysis#indictmentMap()}
+     * when a class does not implement {@link Indictable}.
+     *
+     * @param clazz The type of class
+     * @return the key into {@link ScoreAnalysis#indictmentMap()} to get indicted objects of that type
+     */
+    static String getIndictmentClassId(Class<?> clazz) {
+        if (Indictable.class.isAssignableFrom(clazz)) {
+            throw new IllegalArgumentException("""
+                    The class (%s) implements %s so its indictment map key cannot be determined statically.
+                    Maybe check (%s) implementation of getIndictmentClassId()?""".formatted(clazz.getCanonicalName(),
+                    Indictable.class.getSimpleName(), clazz.getCanonicalName()));
+        }
+        return clazz.getCanonicalName();
+    }
+
+    /**
+     * An identifier that uniquely identifies the type returned by
+     * {@link #getIndictedObject()}.
+     * 
+     * @return a string that can be used to identify the class of {@link #getIndictedObject()}
+     */
+    String getIndictmentClassId();
+
+    /**
+     * Optional method. It is used to calculate the {@link IndictmentAnalysis#indictee()}
+     * when this object is indicted. If not implemented, it will return this object.
+     * 
+     * @return the object that {@link IndictmentAnalysis#indictee()} should return
+     */
+    default Object getIndictedObject() {
+        return this;
+    }
+}

core/src/main/java/ai/timefold/solver/core/api/score/analysis/IndictmentAnalysis.java

@@ -0,0 +1,37 @@
+package ai.timefold.solver.core.api.score.analysis;
+
+import java.util.List;
+
+import ai.timefold.solver.core.api.score.Score;
+
+/**
+ * Note: {@link ScoreAnalysis} is exclusive to Timefold Solver Enterprise Edition.
+ *
+ * @param <Score_>
+ * @see ScoreAnalysis Description of score analysis and the purpose of this class.
+ */
+public interface IndictmentAnalysis<Score_ extends Score<Score_>> {
+    /**
+     * The object that was indicted by constraints.
+     * Its type corresponds to the containing entry's key in {@link ScoreAnalysis#indictmentMap()}.
+     * 
+     * @return the indicted object
+     */
+    Object indictee();
+
+    /**
+     * The sum of score impacts of each constraint match the {@link #indictee()}
+     * is involved with.
+     * 
+     * @return the total score impact of the indicted object
+     */
+    Score_ score();
+
+    /**
+     * A list of {@link MatchAnalysis} for each constraint match the
+     * {@link #indictee()} is involved with, sorted by absolute score impact
+     * 
+     * @return a list of matches the indictee is involved with, sorted by absolute score impact
+     */
+    List<MatchAnalysis<Score_>> matches();
+}

core/src/main/java/ai/timefold/solver/core/api/score/analysis/ScoreAnalysis.java

@@ -1,6 +1,7 @@
 package ai.timefold.solver.core.api.score.analysis;
 
 import java.util.Collection;
+import java.util.List;
 import java.util.SequencedMap;
 
 import ai.timefold.solver.core.api.score.Score;
@@ -154,6 +155,17 @@ public interface ScoreAnalysis<Score_ extends Score<Score_>> {
      */
     Collection<ConstraintAnalysis<Score_>> constraintAnalyses();
 
+    /**
+     * Returns a map from indicted classes to a list of {@link IndictmentAnalysis} that contributed to at least one constraint
+     * match in the {@link ScoreAnalysis}. By default, the key is the canonical name of the class, but can be controlled
+     * by implementing {@link Indictable}. The lists are sorted by the absolute value of their total score contribution, in
+     * descending order.
+     *
+     * @return a map from indicted class to a list of {@link IndictmentAnalysis} linking planning entities and problem facts
+     *         to their impact in this {@link ScoreAnalysis}
+     */
+    SequencedMap<String, List<IndictmentAnalysis<Score_>>> indictmentMap();
+
     /**
      * Returns a diagnostic text that explains the solution through the {@link ConstraintAnalysis} API to identify which
      * constraints cause that score quality.

core/src/main/java/ai/timefold/solver/core/api/solver/ScoreAnalysisFetchPolicy.java

@@ -12,23 +12,31 @@ public enum ScoreAnalysisFetchPolicy {
 
     /**
      * {@link ScoreAnalysis} is fully initialized.
-     * All included {@link ConstraintAnalysis} objects include full {@link ConstraintAnalysis#matches() match analysis}.
+     * All included {@link ConstraintAnalysis} objects include full {@link ConstraintAnalysis#matches() match analysis},
+     * and {@link ScoreAnalysis#indictmentMap()} will be populated.
      */
     FETCH_ALL,
     /**
      * {@link ConstraintAnalysis} included in {@link ScoreAnalysis}
      * provides neither {@link ConstraintAnalysis#matches() match analysis}
      * nor {@link ConstraintAnalysis#matchCount() match count}.
+     * Additionally, {@link ScoreAnalysis#indictmentMap()} will be empty.
      * This is useful for performance reasons when the match analysis is not needed.
      */
     FETCH_SHALLOW,
     /**
      * {@link ConstraintAnalysis} included in {@link ScoreAnalysis}
      * does not provide {@link ConstraintAnalysis#matches() match analysis},
      * but does provide {@link ConstraintAnalysis#matchCount() match count}.
+     * Additionally, {@link ScoreAnalysis#indictmentMap()} will be empty.
      * This is useful when there are too many matches to send over the wire
      * or meaningfully present to users.
      */
-    FETCH_MATCH_COUNT
-
+    FETCH_MATCH_COUNT,
+    /**
+     * {@link ScoreAnalysis} is initialized except for indictments.
+     * All included {@link ConstraintAnalysis} objects include full {@link ConstraintAnalysis#matches() match analysis},
+     * {@link ScoreAnalysis#indictmentMap()} will be empty.
+     */
+    FETCH_JUSTIFICATIONS
 }

core/src/main/java/ai/timefold/solver/core/api/solver/SolutionManager.java

@@ -1,6 +1,6 @@
 package ai.timefold.solver.core.api.solver;
 
-import static ai.timefold.solver.core.api.solver.ScoreAnalysisFetchPolicy.FETCH_ALL;
+import static ai.timefold.solver.core.api.solver.ScoreAnalysisFetchPolicy.FETCH_JUSTIFICATIONS;
 import static ai.timefold.solver.core.api.solver.SolutionUpdatePolicy.UPDATE_ALL;
 
 import java.util.List;
@@ -118,10 +118,10 @@ static <Solution_> void updateShadowVariables(Solution_ solution) {
 
     /**
      * As defined by {@link #analyze(Object, ScoreAnalysisFetchPolicy, SolutionUpdatePolicy)},
-     * using {@link SolutionUpdatePolicy#UPDATE_ALL} and {@link ScoreAnalysisFetchPolicy#FETCH_ALL}.
+     * using {@link SolutionUpdatePolicy#UPDATE_ALL} and {@link ScoreAnalysisFetchPolicy#FETCH_JUSTIFICATIONS}.
      */
     default ScoreAnalysis<Score_> analyze(Solution_ solution) {
-        return analyze(solution, FETCH_ALL, UPDATE_ALL);
+        return analyze(solution, FETCH_JUSTIFICATIONS, UPDATE_ALL);
     }
 
     /**
@@ -179,12 +179,12 @@ ScoreAnalysis<Score_> analyze(Solution_ solution, ScoreAnalysisFetchPolicy fetch
 
     /**
      * As defined by {@link #recommendAssignment(Object, Object, Function, ScoreAnalysisFetchPolicy)},
-     * with {@link ScoreAnalysisFetchPolicy#FETCH_ALL}.
+     * with {@link ScoreAnalysisFetchPolicy#FETCH_JUSTIFICATIONS}.
      */
     default <EntityOrElement_, Proposition_> List<RecommendedAssignment<Proposition_, Score_>> recommendAssignment(
             Solution_ solution, EntityOrElement_ evaluatedEntityOrElement,
             Function<EntityOrElement_, @Nullable Proposition_> propositionFunction) {
-        return recommendAssignment(solution, evaluatedEntityOrElement, propositionFunction, FETCH_ALL);
+        return recommendAssignment(solution, evaluatedEntityOrElement, propositionFunction, FETCH_JUSTIFICATIONS);
     }
 
     /**

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/AbstractConcatNode.java

@@ -66,6 +66,7 @@ protected boolean canProduceTuples() {
     @Override
     public final void insertLeft(LeftTuple_ tuple) {
         var outTuple = getOutTupleFromLeft(tuple);
+        outTuple.setIndictmentSource(tuple.getIndictmentSource());
         tuple.setStore(leftSourceTupleCloneStoreIndex, outTuple);
         propagationQueue.insert(outTuple);
     }
@@ -109,6 +110,7 @@ public final void retractLeft(LeftTuple_ tuple) {
     @Override
     public final void insertRight(RightTuple_ tuple) {
         var outTuple = getOutTupleFromRight(tuple);
+        outTuple.setIndictmentSource(tuple.getIndictmentSource());
         tuple.setStore(rightSourceTupleCloneStoreIndex, outTuple);
         propagationQueue.insert(outTuple);
     }

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/AbstractFlattenNode.java

@@ -73,6 +73,7 @@ private void addTuple(InTuple_ originalTuple, FlattenedItem_ item,
         var reuse = bag.reuseOrAdvance();
         if (reuse == null) {
             var created = createTuple(originalTuple, bag.value);
+            created.setIndictmentSource(originalTuple.getIndictmentSource());
             bag.append(created);
             propagationQueue.insert(created);
         } else {

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/AbstractGroupNode.java

@@ -11,6 +11,7 @@
 import ai.timefold.solver.core.impl.bavet.common.tuple.Tuple;
 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.indictment.IndictmentSource;
 
 public abstract class AbstractGroupNode<InTuple_ extends Tuple, OutTuple_ extends Tuple, GroupKey_, ResultContainer_, Result_>
         extends AbstractSingleInputNode<InTuple_> {
@@ -111,6 +112,7 @@ private void createTuple(InTuple_ tuple, GroupKey_ userSuppliedKey) {
         }
         tuple.setStore(groupStoreIndex, group);
         var outTuple = group.getTuple();
+        outTuple.setIndictmentSource(IndictmentSource.aggregating(tuple, outTuple));
         switch (outTuple.getState()) {
             case CREATING, UPDATING -> {
                 // Already in the correct state.
@@ -190,6 +192,8 @@ public final void update(InTuple_ tuple) {
         if (sameKey) {
             updateGroup(tuple, oldGroup);
         } else {
+            var oldOutTuple = oldGroup.getTuple();
+            oldOutTuple.setIndictmentSource(IndictmentSource.removeFromAggregate(tuple, oldOutTuple));
             if (hasCollector) {
                 groupRetract(tuple);
             }
@@ -274,6 +278,8 @@ public final void retract(InTuple_ tuple) {
             // No fail fast if null because we don't track which tuples made it through the filter predicate(s)
             return;
         }
+        var oldOutTuple = group.getTuple();
+        oldOutTuple.setIndictmentSource(IndictmentSource.removeFromAggregate(tuple, oldOutTuple));
         if (hasCollector) {
             groupRetract(tuple);
         }

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/AbstractIfExistsNode.java

@@ -5,6 +5,7 @@
 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.bavet.common.tuple.indictment.IndictmentSource;
 
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -135,6 +136,20 @@ protected void incrementCounterRight(ExistsCounter<LeftTuple_> counter) {
         counter.countRight++;
     }
 
+    protected void incrementCounterRightUpdatingIndictment(ExistsCounter<LeftTuple_> counter, UniTuple<Right_> rightTuple) {
+        IndictmentSource.addCorroborator(getId(), counter.getTuple(), rightTuple);
+        if (counter.countRight == 0) {
+            if (shouldExist) {
+                doInsertCounter(counter);
+            } else {
+                doRetractCounter(counter);
+            }
+        } else if (shouldExist) {
+            doUpdateCounter(counter);
+        }
+        counter.countRight++;
+    }
+
     protected void decrementCounterRight(ExistsCounter<LeftTuple_> counter) {
         counter.countRight--;
         if (counter.countRight == 0) {
@@ -146,6 +161,20 @@ protected void decrementCounterRight(ExistsCounter<LeftTuple_> counter) {
         } // Else do not even propagate an update
     }
 
+    protected void decrementCounterRightUpdatingIndictment(ExistsCounter<LeftTuple_> counter, UniTuple<Right_> rightTuple) {
+        IndictmentSource.removeCorroborator(getId(), counter.getTuple(), rightTuple);
+        counter.countRight--;
+        if (counter.countRight == 0) {
+            if (shouldExist) {
+                doRetractCounter(counter);
+            } else {
+                doInsertCounter(counter);
+            }
+        } else if (shouldExist) {
+            doUpdateCounter(counter);
+        }
+    }
+
     /**
      * Clears the left tracker list rooted at leftTuple's inputStoreIndexLeftTrackerList slot,
      * cross-removing each tracker from its right tuple's hidden list.
@@ -194,11 +223,20 @@ private void removeRight(FilteringTracker<LeftTuple_> tracker) {
      */
     protected void clearRightTrackerList(UniTuple<Right_> rightTuple) {
         FilteringTracker<LeftTuple_> tracker = rightTuple.removeStore(inputStoreIndexRightTrackerList);
-        while (tracker != null) {
-            var next = tracker.rightNext;
-            decrementCounterRight(tracker.counter);
-            removeLeft(tracker);
-            tracker = next;
+        if (rightTuple.getIndictmentSource() == IndictmentSource.DISABLED) {
+            while (tracker != null) {
+                var next = tracker.rightNext;
+                decrementCounterRight(tracker.counter);
+                removeLeft(tracker);
+                tracker = next;
+            }
+        } else {
+            while (tracker != null) {
+                var next = tracker.rightNext;
+                decrementCounterRightUpdatingIndictment(tracker.counter, rightTuple);
+                removeLeft(tracker);
+                tracker = next;
+            }
         }
     }
 
@@ -233,9 +271,12 @@ protected void updateCounterLeft(ExistsCounter<LeftTuple_> counter, UniTuple<Rig
         }
         if (testFiltering(counter.leftTuple, rightTuple)) {
             counter.countRight++;
+            IndictmentSource.addCorroborator(getId(), counter.getTuple(), rightTuple);
             var tracker = new FilteringTracker<>(counter, rightTuple);
             linkLeft(tracker);
             linkRight(tracker);
+        } else {
+            IndictmentSource.removeCorroborator(getId(), counter.getTuple(), rightTuple);
         }
     }
 
@@ -298,9 +339,12 @@ protected void updateCounterRight(ExistsCounter<LeftTuple_> counter, UniTuple<Ri
         }
         if (testFiltering(leftTuple, rightTuple)) {
             incrementCounterRight(counter);
+            IndictmentSource.addCorroborator(getId(), counter.getTuple(), rightTuple);
             var tracker = new FilteringTracker<>(counter, rightTuple);
             linkLeft(tracker);
             linkRight(tracker);
+        } else {
+            IndictmentSource.removeCorroborator(getId(), counter.getTuple(), rightTuple);
         }
     }
 
@@ -325,6 +369,15 @@ private void doRetractCounter(ExistsCounter<LeftTuple_> counter) {
         }
     }
 
+    private void doUpdateCounter(ExistsCounter<LeftTuple_> counter) {
+        switch (counter.state) {
+            case DYING, OK, UPDATING, CREATING -> propagationQueue.update(counter);
+            case DEAD, ABORTING -> propagationQueue.insert(counter);
+            default -> throw new IllegalStateException("Impossible state: the counter (%s) has an impossible insert state (%s)."
+                    .formatted(counter, counter.state));
+        }
+    }
+
     @Override
     protected boolean canProduceTuples() {
         // The left input must produce tuples no matter what,