Separate three decisions
The training guide covers checkpoint selection. This page covers adoption.
Choose a promotion measure
The schema definespromotion.mode as prediction or application, with prediction as the default. Promotion settings also include minimum_cases (default 16), required_improvement (default 0), and maximum_prediction_regression (default 0.05).
In the checked deployment, the prediction gate reported the criterion paired_validation_mse_and_episode_confidence. It can reject a candidate whose validation mean squared error is worse even when that candidate selects better alternatives. Prediction error and decision utility are different measurements.
Use prediction diagnostics when accurate value estimates are the deployment objective. Use paired application utility when deployment success is defined by the consequences of chosen actions. Continue to inspect prediction regressions and comparison diagnostics so the reason for a change remains visible.
Request fields come from archived schema-version-5 build
0136121bd2cf9d4cdbcb114565c7e1ffb74c5a63; the canary behavior below was checked on 6 November 2026, build af6670b. The complete relationship between application-mode automatic promotion, registered cases, and install: true is not yet confirmed. Use install: false for a separate candidate evaluation, then read back the installed identity after promotion.Run a paired application comparison
Choose the evaluation cases and utility definition before comparing models. For each case, evaluate the candidate and incumbent under the same initial conditions, execution rules, and planning budget. Record the model SHA-256 identities that actually produced the two outcomes. Keep these cases separate from model fitting when they are intended to measure generalization. If outcomes depend on randomness, control or record it so paired differences have a clear interpretation. These are application evaluation choices; the canary’s two utility values do not themselves establish that the cases were paired correctly. Do not replace measured application utility with value predictions while describing the result as an execution comparison. The reference and candidate can be assessed through native planning, but preserve which evaluator and model identity each call used.Submit a canary with model guards
Build thePOST /domains/{domain_id}/value/promote body from the actual installed_sha256, candidate_sha256, and complete paired_cases recorded by your evaluation. Each hash is a 64-character model identity. Canary utility values must be between 0 and 1.
Build a paired promotion request
paired_cases follows this row shape. The numbers illustrate an equal-utility case from the recorded integration; use your own measured outcomes.
One paired case
expected_current_model_sha256 binds the incumbent. expected_model_sha256 binds the candidate. These guards prevent promotion against a different model pair if another operation has changed state.
On the checked build, equal utilities on 36 paired cases returned HTTP 409 with:
required_improvement: 0 therefore did not accept a tie. The observed gate required a strictly positive confidence lower bound. The confidence estimator and the full set of application-mode rules must come from the deployment contract; the example does not define them.
After a successful promotion response, read value/state and confirm that the installed model is the candidate you evaluated. After a rejection, preserve the reason and inspect the incumbent identity before continuing.
Registered cases and recorded outcomes
The deployed schema also exposes the following fields:
These fields identify application cases, their contexts, and the model associated with a utility measurement. Their end-to-end registration, matching, and automatic promotion rules have not been established by the recorded integration. Use the explicit paired-canary flow above for the documented example, and obtain the complete deployed request and lifecycle contract before implementing the registered-case flow.