feat: Joiners.contain() and Joiners.containedIn()

[ge0ffrey]

Before

    Constraint speakerUnavailableTimeslot(ConstraintFactory factory) {
        return factory.forEach(Talk.class)
                .join(Speaker.class,
                        filtering((talk, speaker) -> talk.hasSpeaker(speaker)
                                && speaker.getUnavailableTimeslots().contains(talk.getTimeslot())))
                .penalize(...)
                .asConstraint(...);
    }

After (bigO order of magnitude more scalable)

    Constraint speakerUnavailableTimeslot(ConstraintFactory factory) {
        return factory.forEach(Talk.class)
                .join(Speaker.class,
                        contain(Talk::getSpeakers, speaker -> speaker),
                        containedIn(Talk::getTimeslot, Speaker::getUnavailableTimeslots))
                .penalize(...)
                .asConstraint(...);
    }

Refactorings

• Unify IndexerFactory.buildIndexer() into one switch across the joiner types
  -- Do not create single/composite KeyRetriever in EqualsIndexer and ComparisonIndexer to unify to one constructor.
  -- Extract KeyRetriever creation to IndexerFactory (that class is responsibility for those key tricks)
  -- Implement equal joiner flip() as no-op, so all right bridges indexer can just get a flip.
• Renamed EqualsIndexer to EqualIndexer because its Joiners.equal() and not Joiners.equals()

Open questions (added as todo's)

• For Neighberhood, why track a left index?
• For neighberhoods, why not flip the right bridge?
  I 'd image this code should feel exactly the same as scoring, but not left side
  so always flip basically?

Tasks

• API
• javadocs (API, ...)
• Refactorings to plug it in
• Unit tests
• Indexer implementations
• Use it in Quickstarts (conference scheduling, ...)
• Docs

[ge0ffrey]

Implements part of #8

[triceo]

We do not create left index in Neighborhoods. The comment below says that.

[triceo]

No. The right bridge doesn't flip for Neighborhoods, because it's queried from the left side. <A, B> never becomes <B, A>, and therefore the index doesn't flip either.

[triceo]

(bigO order of magnitude more scalable)

In theory, yes. In practice, I've seen hashing overhead kill promising experiments in the past. Have you actually seen this improvement?

[ge0ffrey]

(bigO order of magnitude more scalable)

In theory, yes. In practice, I've seen hashing overhead kill promising experiments in the past. Have you actually seen this improvement?

No. We'll need to benchmark it. This PR will allow us to do exactly that.

I even suspect that sometimes you'll want to prefer using filtering(a.contains(b)) over joiners.contain(a, b).
But for the cases where it matters - tags for example - I believe it can be a game changer.

[ge0ffrey]

The tests succeed, but the conference scheduling PR doesn't

TimefoldAI/timefold-quickstarts#972

java.lang.IllegalStateException: Impossible state: the tuple (ai.timefold.solver.core.impl.util.CompositeListEntry@614ca71c) with composite key (BiCompositeKey[propertyA=2025-12-27T11:30, propertyB=[]]) doesn't exist in the indexer size = 4.
        at ai.timefold.solver.core.impl.bavet.common.index.ComparisonIndexer.getDownstreamIndexer(ComparisonIndexer.java:73)
        at ai.timefold.solver.core.impl.bavet.common.index.ComparisonIndexer.remove(ComparisonIndexer.java:61)
        at ai.timefold.solver.core.impl.bavet.common.AbstractIndexedJoinNode.updateRight(AbstractIndexedJoinNode.java:148)
        at ai.timefold.solver.core.impl.bavet.common.AbstractIndexedJoinNode.updateRight(AbstractIndexedJoinNode.java:22)
        at ai.timefold.solver.core.impl.bavet.common.tuple.RightTupleLifecycleImpl.update(RightTupleLifecycleImpl.java:20)
        at ai.timefold.solver.core.impl.bavet.common.tuple.AggregatedTupleLifecycle.update(AggregatedTupleLifecycle.java:25)
        at ai.timefold.solver.core.impl.bavet.common.StaticPropagationQueue.processAndClear(StaticPropagationQueue.java:115)
        at ai.timefold.solver.core.impl.bavet.common.StaticPropagationQueue.propagateUpdates(StaticPropagationQueue.java:94)
        at ai.timefold.solver.core.impl.bavet.NodeNetwork.settleLayer(NodeNetwork.java:65)
        at ai.timefold.solver.core.impl.bavet.NodeNetwork.settle(NodeNetwork.java:52)
        at ai.timefold.solver.core.impl.bavet.AbstractSession.settle(AbstractSession.java:63)

[sonarqubecloud]

Quality Gate passed

Issues
15 New issues
0 Accepted issues

Measures
0 Security Hotspots
84.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud