Docs & rules

TimefoldAI/timefold-solverGitHub

This is a public, read-only report. Striff reads this repository's docs, turns each sentence that makes a claim about the code into a rule, and checks the rule against the code on the default branch. How this works

2 stale names in these docs.

main142276eLast read Oct 9

Is this yours? Install to manage it

Once installed, Striff checks every pull request.

Rules summary
Documents
Rules
67
64
64
64
64
64
10
2
8
2
2
41
6
4
24
7
4
1 stale name
4
4
7
1 stale name
2
1
1
5
1 broken3
28 docs
TimefoldAI/timefold-solverOpen repository

Stale names in these docs2

Each sentence below has a stale name: a type the default branch doesn't declare, or declares somewhere else. Edit the doc so it matches the code, or bring the type back.

  • Goneai.timefold.solver.jackson.api.score.analysis.AbstractScoreAnalysisJacksonDeserializer
    import ai.timefold.solver.jackson.api.score.analysis.AbstractScoreAnalysisJacksonDeserializer;

    The repository once had persistence/jackson/src/main/java/ai/timefold/solver/jackson/api/score/analysis/AbstractScoreAnalysisJacksonDeserializer.java. It doesn't now.

    View on GitHub

  • Goneai.timefold.solver.spring.boot.autoconfigure.TimefoldAutoConfiguration
    import ai.timefold.solver.spring.boot.autoconfigure.TimefoldAutoConfiguration;

    The repository once had spring-integration/spring-boot-autoconfigure/src/main/java/ai/timefold/solver/spring/boot/autoconfigure/TimefoldAutoConfiguration.java. It doesn't now. Closest names there: TimefoldBenchmarkAutoConfiguration, TimefoldSolverAutoConfiguration, TimefoldJacksonConfiguration.

    View on GitHub

TimefoldAI/timefold-solver — documented rules

67 of 67 rules, printed November 17, 2026.

The sentence in your docs
✅ interface Solver → class DefaultSolver;
DefaultSolver implements Solver
Holds
✅ abstract class AbstractPhase;
AbstractPhase is declared abstract
Holds
Optional MUST NOT be used;
nothing in this codebase may import java.util.Optional
Broken by
Broken
On UniConstraintStream, the ifExistsOther() building block is also available which is useful in situations where the forEach() constraint match type is the same as the ifExists() type.
UniConstraintStream has an ifExistsOther method
HoldsPR #2431 · Sep 30
Conversely, if the ifNotExists() building block is used (as well as the ifNotExistsOther() building block on UniConstraintStream) you can achieve the opposite effect:
UniConstraintStream has an ifNotExistsOther method
HoldsPR #2431 · Sep 30
Justifications are user-defined objects that implement the ai.timefold.solver.core.api.score.stream.ConstraintJustification interface, which carry meaningful information about a constraint match, such as its name and any metadata that the user chooses to expose.
ConstraintJustification is a contract
Holds
The score analysis of structurally flawed solutions has a structural flaw analysis, which can be used to get inconsistent entities.
ScoreAnalysis depends on StructuralFlawAnalysis
Holds
If you wish to go further and find out which planning entities and problem facts are responsible for breaking the constraint, you can further explore the ConstraintAnalysis instance you received from ScoreAnalysis.constraintMap():
ScoreAnalysis depends on ConstraintAnalysis
Holds
You can customize it by making your domain objects implement Indictable:
Indictable is a contract
Holds
You can also optionally override getIndictedObject() to change the indictee of an IndictmentAnalysis:
Indictable has a getIndictedObject method
Holds
The PlanningSolutionDiff instance contains the following information: A full list of entities whose planning variables (genuine or shadow) changed between the two solutions. Each entity is represented by a PlanningEntityDiff instance, which contains the entity itself, as well as the old and new values of the changed variables.
PlanningSolutionDiff depends on PlanningEntityDiff
Holds
The oldSolution and newSolution planning solutions.
2 rules from this sentence
PlanningSolutionDiff has oldSolution
Holds
PlanningSolutionDiff has newSolution
Holds
The utility method SolutionManager::updateShadowVariables reads the entity and updates its shadow variables.
SolutionManager has an updateShadowVariables method
Holds
If you don't need to control the score type, extend AbstractSimpleModel instead. It implements SolverModel<HardMediumSoftScore> and includes the @PlanningScore field, so you only need to define your problem facts and planning entities:
AbstractSimpleModel implements SolverModel
Holds
Per step, the QueuedEntityPlacer selects one uninitialized entity from the EntitySelector and applies the winning Move (out of all the moves for that entity generated by the MoveSelector).
3 rules from this sentence
QueuedEntityPlacer depends on EntitySelector
Holds
QueuedEntityPlacer depends on MoveSelector
Holds
QueuedEntityPlacer depends on Move
Holds
Per step, the PooledEntityPlacer applies the winning Move (out of all the moves for that entity generated by the MoveSelector).
3 rules from this sentence
PooledEntityPlacer depends on Move
Holds
MoveSelector depends on Move
Holds
PooledEntityPlacer depends on MoveSelector
Holds
Therefore, implement the NearbyDistanceMeter interface:
NearbyDistanceMeter is a contract
Holds
For information on the Move interface, check out the xref:optimization-algorithms/neighborhoods.adoc#neighborhoodsMove[Move Anatomy] section of the Neighborhoods chapter.
Move is a contract
HoldsPR #2431 · Sep 30
The easiest way to generate custom moves is by implementing the interface MoveListFactory:
MoveListFactory is a contract
HoldsPR #2431 · Sep 30
Use this advanced form to generate custom moves Just In Time by implementing the MoveIteratorFactory interface:
MoveIteratorFactory is a contract
HoldsPR #2431 · Sep 30
In technical terms, a move is an implementation of the ai.timefold.solver.core.preview.api.move.Move interface.
Move is a contract
Holds
The Move interface specifies the following methods that must be implemented: void execute(MutableSolutionView solutionView):: This method makes changes to the given solution.
2 rules from this sentence
Move depends on MutableSolutionView
checks “void execute(MutableSolutionView solutionView)”
Holds
Move has an execute method
checks “The Move interface specifies the following methods that must be implemented: void execute(MutableSolutionView solutionView)”
Holds
Finally, the Move interface specifies the following methods that the user can optionally override to gain access to additional solver features: Move rebase(Lookup lookup):: This method creates a copy of the move that is applicable to a different working solution.
2 rules from this sentence
Move depends on Lookup
checks “Move rebase(Lookup lookup)”
Holds
Move has a rebase method
checks “the Move interface specifies the following methods that the user can optionally override”
Holds
solutionView.changeVariable(...) is a method provided by MutableSolutionView that safely changes the value of a planning variable on a planning entity.
MutableSolutionView has a changeVariable method
Holds
other examples include specialized methods such as swapValuesBetweenLists(...).
MutableSolutionView has a swapValuesBetweenLists method
Holds
These moves are available through the ai.timefold.solver.core.preview.api.move.builtin.Moves class.
Moves is a concrete implementation
Holds
You register a built-in move provider exactly like your own, by adding it in your NeighborhoodProvider implementation:
NeighborhoodProvider is a contract
Holds
The entry point for enumeration is the MoveStreamFactory.forEach method, which operates much like the xref:constraints-and-score/score-calculation.adoc#constraintStreamsForEach[forEach() method of Constraint Streams].
MoveStreamFactory has a forEach method
Holds
MoveStreamFactory.pick(), handing the rows to the <<neighborhoodsPicking,picking layer>> below, or asCachedDataset(), handing you the dataset handle to resolve and pick yourself.
MoveStreamFactory has a pick method
Holds
UniEnumeratingStream#asCachedDataset() and BiEnumeratingStream#asCachedDataset() turn a stream into a UniDataset/BiDataset handle, mirroring pick() but without committing to the declarative picking approach.
4 rules from this sentence
UniEnumeratingStream depends on UniDataset
checks “UniEnumeratingStream#asCachedDataset() and BiEnumeratingStream#asCachedDataset() turn a stream into a UniDataset/BiDataset handle, mirroring pick()”
Holds
BiEnumeratingStream depends on BiDataset
checks “UniEnumeratingStream#asCachedDataset() and BiEnumeratingStream#asCachedDataset() turn a stream into a UniDataset/BiDataset handle, mirroring pick()”
Holds
UniEnumeratingStream has an asCachedDataset method
checks “UniEnumeratingStream#asCachedDataset()”
Holds
BiEnumeratingStream has an asCachedDataset method
checks “BiEnumeratingStream#asCachedDataset()”
Holds
Inside buildMoveStream(...), the MoveIteratorSession resolves each dataset handle to a UniDatasetInstance or BiDatasetInstance, which exposes size(), iterator(RandomGenerator) and exhaustiveIterator(RandomGenerator) - the same random-walk picking used throughout Move Streams.
8 rules from this sentence
MoveIteratorSession depends on UniDatasetInstance
checks “the MoveIteratorSession resolves each dataset handle to a UniDatasetInstance or BiDatasetInstance”
Holds
MoveIteratorSession depends on BiDatasetInstance
checks “the MoveIteratorSession resolves each dataset handle to a UniDatasetInstance or BiDatasetInstance”
Holds
UniDatasetInstance has a size method
Holds
UniDatasetInstance has an iterator method
Holds
UniDatasetInstance has an exhaustiveIterator method
Holds
BiDatasetInstance has a size method
Holds
BiDatasetInstance has an iterator method
Holds
BiDatasetInstance has an exhaustiveIterator method
Holds
The defineNeighborhood method receives a NeighborhoodBuilder instance that you can use to include your move provider:
NeighborhoodProvider has a defineNeighborhood method
Holds
Use the isFeasible() method on BestSolutionChangedEvent's new best Score to detect such cases.
Score has an isFeasible method
Holds
Use the event's isNewBestSolutionInitialized() method to only ignore uninitialized solutions, but also accept infeasible solutions.
BestSolutionChangedEvent has an isNewBestSolutionInitialized method
Holds
The PhaseCommand interface appears as follows:
PhaseCommand is a contract
Holds
The PhaseCommandContext interface offers the following methods:
PhaseCommandContext is a contract
Holds
The PhaseCommandContext interface offers the following methods: Object getWorkingSolution():: Returns the working solution of the Solver that is being solved.
PhaseCommandContext has a getWorkingSolution method
Holds
If you want a fresh score computed, these methods have counterparts, executeAndCalculateScore and executeTemporarilyAndCalculateScore.
2 rules from this sentence
PhaseCommandContext has an executeAndCalculateScore method
Holds
PhaseCommandContext has an executeTemporarilyAndCalculateScore method
Holds
The getConstraintWeightOverrides() method is required by the SolverModel interface (implemented by AbstractSimpleModel), and setConstraintWeightOverrides() is optional.
2 rules from this sentence
AbstractSimpleModel implements SolverModel
Holds
SolverModel has a getConstraintWeightOverrides method
Holds
Using the service module, most of the REST Endpoints will be automatically generated thanks to the use of the ModelInput, ModelOutput and SolverModel interfaces. You didn't have to implement those interfaces in this guide, because they were already implemented for you in the AbstractSimpleModel.
2 rules from this sentence
AbstractSimpleModel implements ModelInput
Holds
AbstractSimpleModel implements ModelOutput
Holds
It does that through the SolutionFileIO interface which has a read and write method:
2 rules from this sentence
SolutionFileIO has a read method
Holds
SolutionFileIO has a write method
Holds
The BenchmarkAggregator provides the following public methods: aggregateBenchmarks(PlannerBenchmarkConfig):: Aggregates all benchmark results found in the configured directory.
BenchmarkAggregator has an aggregateBenchmarks method
Holds
aggregateSelectedBenchmarks(PlannerBenchmarkConfig, List<String>):: Aggregates benchmark results from specific subdirectories by name.
BenchmarkAggregator has an aggregateSelectedBenchmarks method
Holds
getAvailableBenchmarkDirectories(PlannerBenchmarkConfig):: Returns list of available benchmark subdirectories with valid results.
BenchmarkAggregator has a getAvailableBenchmarkDirectories method
Holds
ModelConfigOverrides is a marker interface from ai.timefold.solver.service.definition.api.
ModelConfigOverrides is a contract, and ModelConfigOverrides is in ai.timefold.solver.service.definition.api
Holds
Its accessor is named outputMetrics(), not kpis();
ModelResponse has an outputMetrics method
Holds
67 rules from 12 docs

More open-source reports

Every report →

Other public repositories whose docs Striff read and checked against their code.