Publish curated ITWorx-ModelForge source from 990401737f96c8d46a9f7b0d84994516cadcb6a0

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

@@ -0,0 +1,81 @@
+# 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.