Spec: Durable Stable Baseline Promotion

User Input

why tf do we need to re-deploy the api when we push baseline. cant we just have the api always fetch latest basline?

nine deployment environment values independently match it at baseline-registry.ts (line 447).

why is that wtf is this

GitHub release publication becomes production promotion.

it really was. in my mind

i agree with your proposal. delivery-phase onto this in full parallel

Context

Issue #94 exposed a split publication workflow: a verified stable GitHub release could exist while the control plane still depended on an older deployment-scoped authority record. Operators then had to copy the release identity into nine production environment values and redeploy unchanged API code. Until that completed, the API correctly failed closed but production hi check could not resolve the newly published stable baseline.

Maintainers need one successful stable-publication workflow to be the production promotion event. The control plane must read a durable runtime authority revision rather than deployment-scoped baseline identity. Publication must preserve IP-323's verified identity, newest-stable, exact-version, retrieval, and typed-failure contracts without requiring a separate operator promotion or API deployment.

Non-Goals

• Changing baseline archive or manifest formats.
• Changing exact-version selection or the accepted implicit-stable, explicit stable, exact-version, and explicit bundled fallback matrix.
• Letting clients, caches, bundled content, or an unverified GitHub response substitute another baseline.
• Requiring a second human promotion after a successful stable publication.
• Mutating production baseline identity environment values or redeploying unchanged API code during publication.
• Adding a general release-management UI.
• Reworking unrelated report, telemetry, or operator persistence.

Acceptance Criteria

• A successful verified baseline/stable/* publication makes the next production stable-authority read return that exact release without changing production baseline identity environment values.
• A successful verified stable publication does not deploy unchanged API code.
• For IP-323 ordering, a candidate becomes a published stable baseline only when verified GitHub release evidence exists and its durable promotion revision commits. GitHub visibility before that commit is candidate evidence, not a completed stable publication.
• The durable promotion commit is the production linearization point. Any failure before commit leaves the previous stable revision active.
• After commit, the release is promoted. A failed confirmation read exits nonzero with an indeterminate confirmation outcome; retry reconciles the committed revision without rollback or a second promotion.
• Retrying the same canonical immutable release identity returns the same logical promotion revision without contradictory duplicate records.
• A normal publication promotion commits only when its candidate is newer than the current committed stable under IP-323 ordering. Stale or conflicting publication candidates cannot overwrite newer authority.
• A controlled rollback is an explicit promotion mode targeting a previously committed immutable release. It requires the caller's expected current revision plus an audit reason, appends a new revision, and never mutates or deletes release or promotion history.
• Concurrent publication attempts cannot expose a partially written authority identity or combine metadata from different releases.
• The active authority survives API process restart and unchanged-code redeployment without republishing or repromotion.
• Stable resolution still requires the active authority version, provenance, compatibility range, manifest identity and digest, and archive identity and digest to agree with verified release evidence.
• Missing durable authority or durable-store transport failure is typed availability and cannot silently select another baseline.
• A stale or conflicting promotion is typed authority failure and cannot overwrite current stable.
• Release or digest disagreement is typed integrity failure and cannot activate the candidate.
• A post-commit confirmation transport failure is typed availability with an explicit outcome-reconciliation requirement.
• An HTTP 409 authority disagreement remains visible to hi check --json as an actionable authority defect and is not collapsed into transient baseline-authority-unavailable presentation.
• Existing exact-version requests continue to resolve their matching verified stable release independently of the moving stable revision.
• The promotion ledger identifies canonical release identity, previous and resulting stable identity, publication identity, ordering evidence, promotion revision, and commit outcome.

Constraints

• IP-323 remains authoritative for baseline identity, newest-published stable selection, retrieval verification, fallback eligibility, and fail-closed classification.
• The production control plane is the only online authority returned to CLI consumers; GitHub remains verified release evidence and artifact storage.
• Production authority state must be durable and shared across serverless instances. Process memory is insufficient.
• Promotion persistence must be transactional and concurrency-safe.
• The nine-environment-value cross-check is superseded and must not remain an authority or promotion requirement.
• The promotion mutation uses a dedicated machine credential scoped only to baseline publication. It must not accept or depend on a Backoffice session, role, or endpoint.
• Normal publication and controlled rollback must be distinguishable in the audit ledger; ordinary publication may not bypass newest-stable ordering by naming an older release.

Technical Notes

• The existing Postgres runtime is the accepted durable, append-only promotion ledger. The execution plan owns its exact schema, transaction, migration, API boundary, and cutover mechanics.
• “Publication” means successful completion of the verified baseline publication workflow through the durable promotion commit. GitHub release evidence visible before that commit is a candidate and must be safely retryable.
• Static deployment configuration may continue to hold provider credentials, inventory location, and the public control-plane origin. Mutable baseline identity does not belong there.

Dependency Readiness

• Status: No Stack Required
• Dependency: IP-323 Verified Baseline Authority
• Evidence: apps/wiki/content/docs/project/specs/cli/IP-323-verified-baseline-authority/IMPLEMENTATION-NOTES.md
• Reason: IP-323's identity, resolution, and typed-failure contracts are implemented; this successor replaces only the deployment-scoped moving-authority persistence and publication workflow.

Decision Log