chore: make it clear that we rely on entity equality

Author: triceo

core/src/main/java/ai/timefold/solver/core/api/domain/common/PlanningId.java

@@ -6,6 +6,7 @@
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
+import java.util.UUID;
 
 import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
 import ai.timefold.solver.core.api.domain.solution.ProblemFactCollectionProperty;
@@ -23,7 +24,7 @@
  * {@link ValueRangeProvider planning value} class or any {@link ProblemFactCollectionProperty problem fact} class.
  * <p>
  * The return type can be any {@link Comparable} type which overrides {@link Object#equals(Object)} and
- * {@link Object#hashCode()}, and is usually {@link Long} or {@link String}.
+ * {@link Object#hashCode()}, and is usually {@link Long}, {@link UUID} or {@link String}.
  * It must never return a null instance.
  */
 @Target({ METHOD, FIELD })

core/src/main/java/ai/timefold/solver/core/api/domain/entity/PlanningEntity.java

@@ -8,6 +8,7 @@
 import java.util.Comparator;
 
 import ai.timefold.solver.core.api.domain.common.ComparatorFactory;
+import ai.timefold.solver.core.api.domain.common.PlanningId;
 import ai.timefold.solver.core.api.domain.solution.PlanningSolution;
 import ai.timefold.solver.core.api.domain.variable.PlanningVariable;
 
@@ -27,6 +28,22 @@
  * it is not a planning entity and the solver will fail fast.
  *
  * <p>
+ * Planning entities have special requirements on {@link #equals(Object)}:
+ *
+ * <ul>
+ * <li>If two different entities are equal as defined by {@link #equals(Object)},
+ * they must represent the same entity.
+ * The solver will treat them as one entity.</li>
+ * <li>Entity {@link #equals(Object)} and {@link #hashCode()} must not depend on any planning variable.
+ * The return value of these methods must not change when any planning variable changes.
+ * It is recommended for entities to implement a unique {@link PlanningId},
+ * and use that for equality comparisons.</li>
+ * </ul>
+ *
+ * Failing to follow these requirements will cause undefined behavior in the solver,
+ * ranging from explicit fail fasts to silently producing incorrect results.
+ *
+ * <p>
  * The class should have a public no-arg constructor, so it can be cloned
  * (unless the {@link PlanningSolution#solutionCloner()} is specified).
  */

core/src/main/java/ai/timefold/solver/core/api/domain/solution/PlanningEntityCollectionProperty.java

@@ -9,18 +9,21 @@
 import java.util.Collection;
 import java.util.LinkedHashSet;
 import java.util.List;
-import java.util.SortedSet;
+import java.util.SequencedCollection;
 
 import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
 
 /**
  * Specifies that a property (or a field) on a {@link PlanningSolution} class is a {@link Collection} of planning entities.
  * <p>
- * Every element in the planning entity collection should have the {@link PlanningEntity} annotation.
+ * Every element in the planning entity collection must have the {@link PlanningEntity} annotation.
  * Every element in the planning entity collection will be registered with the solver.
  * <p>
  * For solver reproducibility, the collection must have a deterministic, stable iteration order.
- * It is recommended to use a {@link List}, {@link LinkedHashSet} or {@link SortedSet}.
+ * It must not contain duplicates, as defined by {@link #equals(Object)}.
+ * It is recommended to use any {@link SequencedCollection}, such as {@link List} or {@link LinkedHashSet}.
+ *
+ * @see PlanningEntityProperty
  */
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)

core/src/main/java/ai/timefold/solver/core/api/domain/solution/PlanningEntityProperty.java

@@ -12,7 +12,7 @@
 /**
  * Specifies that a property (or a field) on a {@link PlanningSolution} class is a planning entity.
  * <p>
- * The planning entity should have the {@link PlanningEntity} annotation.
+ * The planning entity must have the {@link PlanningEntity} annotation.
  * The planning entity will be registered with the solver.
  */
 @Target({ METHOD, FIELD })

core/src/main/java/ai/timefold/solver/core/api/domain/solution/ProblemFactCollectionProperty.java

@@ -9,7 +9,7 @@
 import java.util.Collection;
 import java.util.LinkedHashSet;
 import java.util.List;
-import java.util.SortedSet;
+import java.util.SequencedCollection;
 
 import ai.timefold.solver.core.api.domain.entity.PlanningEntity;
 import ai.timefold.solver.core.api.score.stream.ConstraintFactory;
@@ -26,7 +26,8 @@
  * they are automatically available as facts for {@link ConstraintFactory#forEach(Class)}.
  * <p>
  * For solver reproducibility, the collection must have a deterministic, stable iteration order.
- * It is recommended to use a {@link List}, {@link LinkedHashSet} or {@link SortedSet}.
+ * It must not contain duplicates (as defined by {@link #equals(Object)}.
+ * It is recommended to use any {@link SequencedCollection}, such as {@link List} or {@link LinkedHashSet}.
  * 
  * @see ProblemFactProperty
  */

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

@@ -1,6 +1,6 @@
 package ai.timefold.solver.core.impl.bavet.uni;
 
-import java.util.IdentityHashMap;
+import java.util.HashMap;
 import java.util.Map;
 
 import ai.timefold.solver.core.impl.bavet.common.AbstractNode;
@@ -32,7 +32,7 @@ public abstract sealed class AbstractForEachUniNode<A>
     private final Class<A> forEachClass;
     private final int outputStoreSize;
     private final StaticPropagationQueue<UniTuple<A>> propagationQueue;
-    protected final Map<A, UniTuple<A>> tupleMap = new IdentityHashMap<>(1000);
+    protected final Map<A, UniTuple<A>> tupleMap = new HashMap<>(1000);
 
     protected AbstractForEachUniNode(Class<A> forEachClass, TupleLifecycle<UniTuple<A>> nextNodesTupleLifecycle,
             int outputStoreSize) {

docs/src/modules/ROOT/pages/using-timefold-solver/modeling-planning-problems.adoc

@@ -224,7 +224,7 @@ Alternatively, you can sometimes also introduce <<cachedProblemFact,_a cached pr
 For some functionality
 (such as xref:using-timefold-solver/running-the-solver.adoc#multithreadedIncrementalSolving[multi-threaded incremental solving]
 and xref:responding-to-change/responding-to-change.adoc#realTimePlanning[real-time planning]),
-Timefold Solver needs to map problem facts and planning entities to an ID.
+Timefold Solver needs to map problem facts and planning entities to a unique ID.
 Timefold Solver uses that ID to _rebase_ a move from one thread's solution state to another's.
 
 To enable such functionality, specify the `@PlanningId` annotation on the identification field or getter method,
@@ -253,8 +253,8 @@ A `@PlanningId` property must be:
 * Unique for that specific class
 ** It does not need to be unique across different problem fact classes
 (unless in that rare case that those classes are mixed in the same value range or planning entity collection).
-* An instance of a type that implements `Object.hashCode()` and `Object.equals()`. See the Javadoc on the https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Object.html[`java.lang.Object` class] for details.
-** It's recommended to use the type `Integer`, `int`, `Long`, `long`, `String` or `UUID`.
+* An instance of a https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Comparable.html[`Comparable` class].
+** It's recommended to use types such as `Long`, `String` or `UUID`.
 * Never `null` by the time `Solver.solve()` is called.
 
 
@@ -358,11 +358,18 @@ Instead, calculate the free time in the score constraints (or as a <<shadowVaria
 
 If historic data needs to be considered too, then create a problem fact to hold the total of the historic assignments up to, but __not including__, the planning window (so that it does not change when a planning entity changes) and let the score constraints take it into account.
 
-==== Keep planning entity `hashCode()` implementations constant
+==== Keep planning entity `equals()` and `hashCode()` implementations constant
 
-Planning entity `hashCode()` implementations must remain constant.
-Therefore, entity `hashCode()` implementations must not depend on any planning variables, as these change during solving.
-Pay special attention when using data structures with auto-generated `hashCode()` as entities,
+Planning entity equality implementations must remain constant:
+
+- If two entities are equal at the start of solving, they must remain equal during solving.
+- If two entities are not equal at the start of solving, they must remain not equal during solving.
+- If two entities are equal, they are considered to be the same entity.
+
+From this, it follows that entity `equals()` and `hashCode()` implementations must not depend on any planning variables, as these change during solving.
+You can use a <<planningId,`@PlanningId`>> to distinguish planning entities from each other.
+
+Pay special attention when using data structures with auto-generated `equals()` and `hashCode()`,
 such as Kotlin data classes or Lombok's `@EqualsAndHashCode`.
 
 ==== Planning entity implementations must be mutable