Release channels

A suite version or a scorer version is never edited into production. It is frozen, run beside the current version without deciding anything, and then activated by a governed action bound to its digest. The channels are the states of the version; the one that matters is active, and nobody moves a version there by hand.

The lifecycles below are implemented in the scorers and evaluations components today. EV-047, the improvement component's requirement for release channels driven from improvement work, is not started.

Status (25 October 2026). The improvement component is an empty shell in the application today (one model, no routes, no pages); requirements EV-041 to EV-044, EV-046 and EV-047 are not started in the requirements ledger. This page describes the contract the component is being built to, and nothing on it is available yet.

The channels

Suite version	Scorer version	Meaning
draft	draft	edited as a whole; nothing runs it
review	review	frozen: every reference pinned to an exact version and digest, the content digested; it never changes again
shadow	shadow	runnable by naming the version explicitly; recorded and measured; never the gate
canary	—	the same, one step closer to active
active	active	the suite's gate, or the scorer's version in use
retired	retired	history

A suite version moves draft → review → shadow → canary → active → retired; a scorer version draft → review → shadow → active → retired. People move a version among draft, review, shadow and canary, and retire a version that is not active. A version whose rows no longer hash to its digest cannot move forward. See suites and thresholds and the scorer registry.

A peer asking for an evaluation with suite.version: null gets the active version pinned at admission; a named version must be active or shadow. A shadow run is how a candidate is compared with the gate on the same subjects before anyone asks to activate it (see experiments).

Governed activation

active is entered only through an approved governed action: activate_suite_version or change_threshold for suites, activate_scorer_version or activate_judge_configuration for scorers. The request names the kind, the target, the version's digest, a summary for the approver, the authors and the requester. Its states are requested, pending_approval, approved, deferred, denied, activated, expired, cancelled and failed (a suite request can also be superseded). Asking again for the same version refreshes a deferred or pending decision instead of opening a second request.

Who decides follows the architecture's governance decision:

• Linked to a MadeBook workspace: EvalBook asks MadeBook for a decision bound to the action digest and activates only on allow for the same digest before valid_until. require_approval waits for MadeBook's resolution event and re-fetches the decision; an unreachable MadeBook is defer, and nothing activates. An expired allow, a lapsed approval or an ended link reads as deny. See MadeBook and https://madebook.ai/docs/governance/evalbook-evidence.
• Standalone: the author of a protected change cannot activate it; a different member with the release admin role (config.activate) must. Standalone mode can never be selected to weaken a linked project: unlinking governance is itself a governed action, and activations pending a MadeBook decision stay blocked after an unlink until a person re-requests them.

Activation re-checks everything at the moment it happens. The action must be approved, its digest must equal the version's digest as recomputed from the rows, and the kind must match; otherwise nothing activates and the request is failed with DIGEST_MISMATCH or KIND_MISMATCH. In the same transaction the previously active version is retired and the pointer moves. A judge is activated only with a model Bookbag SSO confirms the organization can run, and activating a materially different judge marks every earlier calibration of that scorer stale with the parts that changed (see calibration and LLM judges). Without the integrations component the request fails closed with GOVERNANCE_UNAVAILABLE.

What changing the gate does

Activating a new suite version supersedes, by policy, the still-valid reports issued under the version it replaces. The report bodies and their digests are untouched; supersession is in the envelope (status: superseded, superseded_by). EvalBook announces suite.activated and report.superseded to linked peers, which re-fetch before relying on anything. See release gates and reports.

Rollback

A retired suite version can be made active again by the same governed path; there is no shortcut. A scorer's active version is retired only by activating another, never directly.

Who may do what

The scorer author drafts scorers, rubrics and suite versions and never activates. The release admin holds config.activate and requests activation, subject to MadeBook or to separation of duties. EvalBook never authorizes: it records the decision it was given and acts only on an allow for the exact digest. The same rule covers modify_protected_dataset and change_holdout; see protected data and governance and roles and access.