chore: make getIndictedObjects() return null when indictments disabled, add notes about stale ifExists indictments

Author: Christopher-Chianelli

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

@@ -113,6 +113,8 @@ protected void incrementCounterRightWithoutIndictment(ExistsCounter<LeftTuple_>
                 doRetractCounter(counter);
             }
         } // Else do not even propagate an update
+        // NOTE: By not propagating here, the left tuple's indicted objects can be stale
+        //       if an element is removed.
         counter.countRight++;
     }
 
@@ -124,6 +126,8 @@ protected void incrementCounterRightUpdatingIndictment(ExistsCounter<LeftTuple_>
                 doRetractCounter(counter);
             }
         } // Else do not even propagate an update
+        // NOTE: By not propagating here, the left tuple's indicted objects can be stale
+        //       if an element is removed.
         IndictmentSource.addSupport(getId(), counter.leftTuple, rightTuple);
         counter.countRight++;
     }

core/src/main/java/ai/timefold/solver/core/impl/score/constraint/ConstraintMatch.java

@@ -30,7 +30,7 @@ public final class ConstraintMatch<Score_ extends Score<Score_>> implements Comp
 
     private final ConstraintRef constraintRef;
     private final @Nullable ConstraintJustification justification;
-    private final List<Object> indictedObjects;
+    private final @Nullable List<Object> indictedObjects;
     private final Score_ score;
 
     /**
@@ -39,7 +39,7 @@ public final class ConstraintMatch<Score_ extends Score<Score_>> implements Comp
      * @param score penalty or reward associated with the constraint match
      */
     public ConstraintMatch(ConstraintRef constraintRef, @Nullable ConstraintJustification justification,
-            List<Object> indictedObjects, Score_ score) {
+            @Nullable List<Object> indictedObjects, Score_ score) {
         this.constraintRef = requireNonNull(constraintRef);
         this.justification = justification;
         this.indictedObjects = indictedObjects;
@@ -67,7 +67,7 @@ public ConstraintRef getConstraintRef() {
         return (Justification_) justification;
     }
 
-    public List<Object> getIndictedObjects() {
+    public @Nullable List<Object> getIndictedObjects() {
         return indictedObjects;
     }
 

core/src/main/java/ai/timefold/solver/core/impl/score/constraint/ConstraintMatchTotal.java

@@ -2,7 +2,6 @@
 
 import static java.util.Objects.requireNonNull;
 
-import java.util.Collections;
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Set;
@@ -94,7 +93,7 @@ public ConstraintMatch<Score_> addConstraintMatch(ConstraintJustification justif
      * @return never null
      */
     public ConstraintMatch<Score_> addConstraintMatch(ConstraintJustification justification, Score_ score) {
-        var constraintMatch = new ConstraintMatch<>(constraintRef, justification, Collections.emptyList(), score);
+        var constraintMatch = new ConstraintMatch<>(constraintRef, justification, null, score);
         addConstraintMatch(constraintMatch);
         return constraintMatch;
     }

core/src/main/java/ai/timefold/solver/core/impl/score/stream/common/inliner/ConstraintMatchSupplier.java

@@ -25,6 +25,7 @@
 import ai.timefold.solver.core.impl.score.stream.common.AbstractConstraint;
 
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Allows creating {@link ConstraintMatch} instances lazily if and only if they are required by the end user.
@@ -42,9 +43,9 @@
 public interface ConstraintMatchSupplier<Score_ extends Score<Score_>>
         extends BiFunction<Constraint, Score_, ConstraintMatch<Score_>> {
 
-    static List<Object> collectIndictments(Constraint constraint, Tuple tuple) {
+    static @Nullable List<Object> collectIndictments(Constraint constraint, Tuple tuple) {
         if (tuple.getIndictmentSource() == IndictmentSource.DISABLED) {
-            return Collections.emptyList();
+            return null;
         }
         var out = new LinkedHashSet<>();
         var abstractConstraint = (AbstractConstraint<?, ?, ?>) constraint;

core/src/test/java/ai/timefold/solver/core/impl/score/stream/common/uni/AbstractUniConstraintStreamTest.java

@@ -478,13 +478,19 @@ public void ifExists_0Joiner0Filter() {
         scoreDirector.beforeProblemFactRemoved(entityGroup);
         solution.getEntityGroupList().remove(entityGroup);
         scoreDirector.afterProblemFactRemoved(entityGroup);
+
+        // Note: entityGroup is still indicted, despite being removed,
+        // since only the right tuple of the ifExists changed, so no
+        // change was propagated.
         assertScore(scoreDirector,
                 assertMatch(solution.getFirstValueGroup()).withIndictedObjects(
                         solution.getFirstValueGroup(),
-                        solution.getFirstEntityGroup()),
+                        solution.getFirstEntityGroup(),
+                        entityGroup),
                 assertMatch(valueGroup).withIndictedObjects(
                         valueGroup,
-                        solution.getFirstEntityGroup()));
+                        solution.getFirstEntityGroup(),
+                        entityGroup));
     }
 
     @Override