docs: update enterprise documentation

docs/src/modules/ROOT/nav.adoc

@@ -15,7 +15,7 @@
 * Constraints and Score
 ** xref:constraints-and-score/overview.adoc[leveloffset=+1]
 ** xref:constraints-and-score/score-calculation.adoc[leveloffset=+1]
-** xref:constraints-and-score/understanding-the-score.adoc[leveloffset=+1]
+** xref:constraints-and-score/understanding-the-score.adoc[Understanding the score]
 ** xref:constraints-and-score/constraint-configuration.adoc[leveloffset=+1]
 ** xref:constraints-and-score/load-balancing-and-fairness.adoc[leveloffset=+1]
 ** xref:constraints-and-score/performance.adoc[leveloffset=+1]
@@ -38,4 +38,15 @@
 ** Migration Guides
 *** xref:upgrading-timefold-solver/migration-guides/variable-listeners-to-custom-shadow-variables.adoc[leveloffset=+1]
 *** xref:upgrading-timefold-solver/migration-guides/chained-variables-to-planning-list-variable.adoc[leveloffset=+1]
-* xref:enterprise-edition/enterprise-edition.adoc[leveloffset=+1]
+* xref:commercial-editions/commercial-editions.adoc[leveloffset=+1]
+** xref:commercial-editions/installation.adoc[leveloffset=+1]
+** xref:commercial-editions/performance-improvements.adoc[leveloffset=+1]
+** xref:constraints-and-score/understanding-the-score.adoc[Score Analysis]
+** xref:responding-to-change/responding-to-change.adoc#assignmentRecommendationAPI[Recommendation API]
+** xref:optimization-algorithms/move-selector-reference.adoc#nearbySelection[Nearby selection]
+** xref:using-timefold-solver/running-the-solver.adoc#multithreadedIncrementalSolving[Multithreaded solving]
+** xref:using-timefold-solver/running-the-solver.adoc#partitionedSearch[Partitioned search]
+** xref:constraints-and-score/performance.adoc#constraintProfiling[Constraint profiling]
+** xref:constraints-and-score/score-calculation.adoc#incrementalScoreCalculation[Incremental score calculation]
+** xref:commercial-editions/multistage-moves.adoc[leveloffset=+1]
+** xref:using-timefold-solver/running-the-solver.adoc#throttlingBestSolutionEvents[Throttling best solution events]

docs/src/modules/ROOT/pages/.index.adoc

@@ -32,4 +32,4 @@ include::integration/integration.adoc[leveloffset=+1]
 include::design-patterns/design-patterns.adoc[leveloffset=+1]
 include::frequently-asked-questions.adoc[leveloffset=+1]
 include::upgrading-timefold-solver/.upgrading-timefold-solver.adoc[leveloffset=+1]
-include::enterprise-edition/enterprise-edition.adoc[leveloffset=+1]
+include::commercial-editions/commercial-editions.adoc[leveloffset=+1]

docs/src/modules/ROOT/pages/commercial-editions/_only-enterprise.adoc

@@ -0,0 +1 @@
+NOTE: This feature is exclusive to Timefold Solver Enterprise Edition.

docs/src/modules/ROOT/pages/commercial-editions/_only-plus-and-enterprise.adoc

@@ -0,0 +1 @@
+NOTE: This feature is exclusive to Timefold Solver Plus and Enterprise Editions.

docs/src/modules/ROOT/pages/commercial-editions/commercial-editions.adoc

@@ -0,0 +1,56 @@
+= Plus/Enterprise Editions
+:page-aliases: partitioned-search/partitioned-search.adoc, \
+    enterprise-edition/enterprise-edition.adoc
+:doctype: book
+:icons: font
+
+_Timefold Solver Plus_ and _Timefold Solver Enterprise_ are commercial products which offer additional features,
+such as xref:constraints-and-score/understanding-the-score.adoc[score analysis], xref:optimization-algorithms/move-selector-reference.adoc#nearbySelection[nearby selection] and xref:using-timefold-solver/running-the-solver.adoc#multithreadedIncrementalSolving[multithreaded solving].
+These features are essential to scale out to large datasets and build trust with your users.
+
+Unlike _Timefold Solver Community Edition_, these commercial editions are not open-source.
+
+TIP: Looking for quicker time-to-value?
+Timefold offers https://docs.timefold.ai/[pre-built, fully tuned optimization models], no constraint building required.
+Just plug into our API and start optimizing immediately.
+
+We offer free trials to everyone as well as free licenses to non-profit organizations, start-ups and for academic research.
+xref:commercial-editions/installation.adoc#solverObtainLicenseKey[See: How to obtain a license key?]
+
+== Feature Comparison
+
+[cols="4,^1,^1", options="header"]
+|===
+| Feature | Plus | Enterprise
+
+| xref:constraints-and-score/understanding-the-score.adoc[Score Analysis]
+| ✓ | ✓
+
+| xref:responding-to-change/responding-to-change.adoc#assignmentRecommendationAPI[Recommendation API]
+| ✓ | ✓
+
+| xref:commercial-editions/performance-improvements.adoc[Performance improvements]
+| | ✓
+
+| xref:optimization-algorithms/move-selector-reference.adoc#nearbySelection[Nearby selection]
+| | ✓
+
+| xref:using-timefold-solver/running-the-solver.adoc#multithreadedIncrementalSolving[Multithreaded solving]
+| | ✓
+
+| xref:using-timefold-solver/running-the-solver.adoc#partitionedSearch[Partitioned search]
+| | ✓
+
+| xref:constraints-and-score/performance.adoc#constraintProfiling[Constraint profiling]
+| | ✓
+
+| xref:constraints-and-score/score-calculation.adoc#incrementalScoreCalculation[Incremental score calculation]
+| | ✓
+
+| xref:commercial-editions/multistage-moves.adoc[Multistage moves]
+| | ✓
+
+| xref:using-timefold-solver/running-the-solver.adoc#throttlingBestSolutionEvents[Throttling best solution events]
+| | ✓
+
+|===

docs/src/modules/ROOT/pages/commercial-editions/installation.adoc

@@ -0,0 +1,81 @@
+= Installing Timefold Solver Plus & Enterprise
+
+In order to work with the commercial editions of Timefold Solver, 2 actions need to be taken:
+
+- <<solverLicenseKey,Configure a license key>>;
+- <<enterpriseArtifacts,Use the Enterprise artifacts>>;
+
+[#solverLicenseKey]
+== License Key
+
+A correctly configured and active license key is required in order for our commercial versions to function.
+
+[#solverObtainLicenseKey]
+=== Obtaining a license key
+
+Contact us through our https://timefold.ai/talk-to-us[webform].
+
+[NOTE]
+====
+Take care not to leak the license file, for example by committing it to a public repository,
+logging the license file content in logs, or sharing it with unauthorized parties.
+====
+
+[#solverSetupLicenseKey]
+=== Set up your license key
+
+After obtaining your license file (.pem) you can introduce it to your project by one of the following methods:
+
+* Store the license's PEM string in the `TIMEFOLD_ENTERPRISE_LICENSE` environment variable.
+* Store the absolute path to the file in `TIMEFOLD_ENTERPRISE_LICENSE_PATH` environment variable.
+* Place the file in the user's home directory.
+* Place the file in the root of your application classpath.
+
+[#enterpriseArtifacts]
+== Use the enterprise artifacts
+
+The commercial edition uses different artifacts than our open-source version.
+These artifacts are available from Maven Central, so no additional repositories need to be configured.
+
+[NOTE]
+====
+To avoid operational complexity, both Plus and Enterprise editions of Timefold Solver use the `enterprise` artifacts.
+Features for your licensed version are enabled based on the provided license key.
+====
+
+Replace references to open-source artifacts by their `enterprise` counterparts
+as shown in the following table:
+
+|===
+|Open source|Enterprise
+
+|`ai.timefold.solver:timefold-solver-bom`
+|`ai.timefold.solver.enterprise:timefold-solver-enterprise-bom`
+
+|`ai.timefold.solver:timefold-solver-core`
+|`ai.timefold.solver.enterprise:timefold-solver-enterprise-core`
+
+|`ai.timefold.solver:timefold-solver-jackson`
+|`ai.timefold.solver.enterprise:timefold-solver-enterprise-jackson`
+
+|`ai.timefold.solver:timefold-solver-quarkus`
+|`ai.timefold.solver.enterprise:timefold-solver-enterprise-quarkus`
+
+|`ai.timefold.solver:timefold-solver-quarkus-jackson`
+|`ai.timefold.solver.enterprise:timefold-solver-enterprise-quarkus-jackson`
+
+|`ai.timefold.solver:timefold-solver-spring-boot-starter`
+|`ai.timefold.solver.enterprise:timefold-solver-enterprise-spring-boot-starter`
+|===
+
+If you were not using some of these open source artifacts until now,
+you do not need to add the enterprise counterparts to your project either.
+
+== Troubleshooting
+
+After migrating to a commercial edition, most projects work out of the box.
+
+When using the Enterprise version, automatic node sharing is the only feature that places additional restrictions on your code.
+If you run into unexpected behavior, try xref:commercial-editions/performance-improvements.adoc#automaticNodeSharingConfiguration[disabling that feature] or align your code to xref:commercial-editions/performance-improvements.adoc#automaticNodeSharingRestrictions[comply].
+
+If that did not resolve the issue, link:https://timefold.ai/contact[contact Timefold support].

docs/src/modules/ROOT/pages/commercial-editions/multistage-moves.adoc

@@ -0,0 +1,15 @@
+[#multistageMoves]
+= Multistage Moves
+
+include::./_only-enterprise.adoc[]
+
+Multistage moves are moves composed of one or more stages, where each stage selects a single `Move` to execute.
+
+Each stage has access to either a `BasicVariableMoveEvaluator` or a `ListVariableMoveEvaluator`, which allows the stage to evaluate moves without executing them.
+
+Stages are selected from either a `BasicVariableStageProvider` or a `ListVariableStageProvider`, which is initialized from the working solution at phase start.
+
+Multistage moves are configured from either a xref:optimization-algorithms/move-selector-reference.adoc#multistageMoveSelector[MultistageMoveSelectorConfig]
+or a xref:optimization-algorithms/move-selector-reference.adoc#listMultistageMoveSelector[ListMultistageMoveSelectorConfig].
+
+Multistage moves are useful for creating specialized ruin-and-recreate moves where the valid values that won't violate hard constraints can be determined in advance.

docs/src/modules/ROOT/pages/commercial-editions/performance-improvements.adoc

@@ -0,0 +1,91 @@
+= Performance Improvements
+
+Timefold Solver Enterprise brings many performance improvements. These are shortly described here.
+
+[#fasterCustomShadowVariables]
+== Faster shadow variables
+
+include::./_only-enterprise.adoc[]
+
+Updates to shadow variables happen incrementally with Timefold Solver Enterprise.
+For models making intensive use of xref:using-timefold-solver/modeling-planning-problems.adoc#customShadowVariable[shadow variables], this should be visible as a serious performance improvement out-of-the-box.
+
+This is enabled by default and doesn't require any special considerations.
+
+[#automaticNodeSharing]
+== Node sharing
+
+include::./_only-enterprise.adoc[]
+
+When a `ConstraintProvider` does an operation for multiple constraints (such as finding all shifts corresponding to an employee), that work can be shared.
+This can significantly improve move evaluation speed if the repeated operation is computationally expensive:
+
+image::commercial-editions/nodeSharingValueProposition.png[align="center"]
+
+IMPORTANT: Debugging breakpoints put inside your constraints will not be respected, because the `ConstraintProvider` class will be transformed when this feature is enabled.
+
+[#automaticNodeSharingRestrictions]
+=== Restrictions
+
+To use automatic node sharing outside Quarkus, your `ConstraintProvider` class must oblige by several restrictions so a valid subclass can be generated:
+
+- The `ConstraintProvider` class cannot be final.
+- The `ConstraintProvider` class cannot have any final methods.
+- The `ConstraintProvider` class cannot access any protected classes, methods or fields.
+
+[#automaticNodeSharingConfiguration]
+=== Configuration
+
+Node sharing is automatically enabled when running Timefold Solver Enterprise.
+You can disable the feature by changing the following settings.
+
+[tabs]
+====
+XML::
+
+* Add `<constraintStreamAutomaticNodeSharing>false</constraintStreamAutomaticNodeSharing>` in your `solverConfig.xml`:
++
+[source,xml,options="nowrap"]
+----
+<!-- ... -->
+<scoreDirectorFactory>
+  <constraintProviderClass>org.acme.MyConstraintProvider</constraintProviderClass>
+  <constraintStreamAutomaticNodeSharing>false</constraintStreamAutomaticNodeSharing>
+</scoreDirectorFactory>
+<!-- ... -->
+----
+
+Spring Boot::
+
+Set the property `timefold.solver.constraint-stream-automatic-node-sharing` to `false` in `application.properties`:
++
+[source,properties,options="nowrap"]
+----
+timefold.solver.constraint-stream-automatic-node-sharing=false
+----
+
+Quarkus::
+
+Set the property `quarkus.timefold.solver.constraint-stream-automatic-node-sharing` to `false` in `application.properties`:
++
+[source,properties,options="nowrap"]
+----
+quarkus.timefold.solver.constraint-stream-automatic-node-sharing=false
+----
+====
+
+[#nodeSharing]
+=== What is node sharing?
+
+When using xref:constraints-and-score/score-calculation.adoc#constraintStreams[constraint streams], each xref:constraints-and-score/score-calculation.adoc#constraintStreamsBuildingBlocks[building block] forms a node in the score calculation network.
+When two building blocks are functionally equivalent, they can share the same node in the network.
+Sharing nodes allows the operation to be performed only once instead of multiple times, improving the performance of the solver.
+To be functionally equivalent, the following must be true:
+
+* The building blocks must represent the same operation.
+
+* The building blocks must have functionally equivalent parent building blocks.
+
+* The building blocks must have functionally equivalent inputs.
+
+When all of the above is the case, Timefold Solver can rewrite the `ConstraintProvider` code at runtime to benefit from the performance improvements node sharing brings.

docs/src/modules/ROOT/pages/constraints-and-score/overview.adoc

@@ -425,9 +425,6 @@ Implement all constraints together in a single method.
 Does not scale.
 Does not support xref:constraints-and-score/understanding-the-score.adoc[score explanations].
 
-NOTE: Incremental score calculator is exclusive to Timefold Solver Enterprise Edition.
-It is not available in the open source version.
-
 Every score calculation type can work with any Score definition (such as ``HardSoftScore`` or ``HardMediumSoftScore``).
 All score calculation types are object-oriented and can reuse existing Java code.