ModelForge-Public/docs/architecture/adr/0058-approved-serving-transitions.md

ADR 0058: Execute stable route replacement through the approved lifecycle engine

Status: implemented for identical embedding spaces; isolated PostgreSQL qualification passed; production deployment pending.

The project comparison establishes evidence. It grants no production authority. Existing lifecycle subjects, plans and rollback snapshots previously recorded state without switching the gateway. The new transaction-only serving adapter connects those existing operations to the actual capability deployments; there is no second promotion engine.

An approval's typed evidence.serving_transition selects current and candidate deployments, the exact production execution approval, expected capability serving_generation, and one selected-comparison ID for every affected stable project binding. The server derives the complete binding set and identity snapshots. Missing projects, reused comparisons, changed bindings, stale comparison pins, incomplete/errorful runs and revoked production evidence block execution. Creating a new comparison supersedes the older binding evidence for this purpose. The existing production validation engine rechecks the probe and supply chain. Unlike a capability-only readiness record, an operational transition requires the approval's declared production_validation=SATISFIED; explicitly deferred, required or not-required validation cannot activate a project-serving route. This requirement is also carried in the immutable serving contract and rechecked at commit.

For each affected binding, the latest ProjectFitEvidence for that exact candidate is included in the approved contract when present. Negative/deferred conclusions, incomplete integration, blockers or critical errors stop the operation. A later record changes the contract and needs fresh review. Evidence for another deployment is not silently applied to this candidate. Absence of a separate project-fit record does not fabricate one: reviewed per-binding selected comparisons and explicit satisfied production validation remain required. This adapter does not impose ExampleVision's OWNER_PHOTO evidence class on RAG projects, or create separate PROJECT_PRODUCTION approvals. Generic capability-only/LAB policy interpretation remains intact.

The reviewed contract is stored in the approval's resolved evidence and copied into the immutable promotion plan. Production scope, exact candidate/rollback targets and an explicit plan approval are required. This first operational adapter supports only transparent or behavioral plans targeting STABLE from a LAB_READY/PROMOTION_ELIGIBLE deployment subject. Manual canary observations do not acquire operational authority.

Execution captures actual deployment/routing identities in the existing immutable rollback snapshot. The separate explicit lifecycle commit locks the capability contract, revalidates all evidence, compares/increments its durable route generation, drains the old route and activates the next route in one transaction with lifecycle state and audit. The capability endpoint and project credentials do not change. Existing admitted calls retain their old deployment; changing the route neither kills workers nor claims memory was reclaimed.

Rollback checks the exact installed route generation, both deployment snapshots and the affected binding set. It restores the actual route and subject in one transaction and increments generation again. A later route/configuration change produces a conflict; the old operation never overwrites it. The previous artifact set, runtime profile and deployment receive explicit retention records. Nonzero route generations block schema downgrade. Rollback rechecks the retained target's actual production approval, supply-chain/probe facts, node availability and runtime readiness. A later revocation or quarantine is an explicit blocker, not permission to reactivate unsafe assets. Same-operation commit retries verify the exact installed state and return the persisted result without another generation increment. Activation timestamps come from the actual commit journal, not the earlier preparation time.

Embedding identity equality means the exact existing embedding-space ID, not matching vector dimensions or apparently identical model files. A changed identity still requires a trusted consumer reindex/cutover adapter and is blocked by this packet. The old bootstrap promotion and newer experiment identity serializers differ; those existing identities are not rewritten or silently treated as equivalent. The same-space path therefore does not make arbitrary new-model replacement available and does not imply that consumer cutover is complete.

The contract generation starts at zero for existing schemas and is authoritative thereafter. All stable-route writers, including initial promotion and explicit drain, share the same contract lock and generation increment. Recovery must preserve this value and exact rollback provenance; an opaque legacy populated fingerprint is not a substitute for a qualified default-zero source projection. Operators obtain expected_route_generation from route_generation on the existing deployment response. They must refresh and review after a conflict rather than guessing a generation.

Validation includes real offline lifecycle commit/rollback, stale authority/binding/identity negative tests, transaction rollback on subject conflict, and an optional disposable PostgreSQL two-committer race with runtime-role writes. No inference, external index operation or production deployment is performed by this implementation qualification.

The project comparison view offers a read-only replacement preview. It shows every affected stable binding, current/candidate identities, route generation, valid production approval choices and actionable blockers. Stale historical production approvals are excluded without invalidating another valid choice. The preview neither declares production validation satisfied nor creates lifecycle authority. Historical lifecycle approvals remain readable after a route change; expected qualification failures mark them STALE with an audited reason, and previously approved stale authority remains explicitly revocable.