From test to retirement
An API runs in test from its first merge, goes live with a deploy, grows by Changes and new versions, and keeps every pinned version serving.
An API runs in test from its first merged Change and goes live when a Version is deployed. After that it grows by Changes, each additive or shipped as a new major.
From merge to retirement
| Where it is | What is true | Call | Emits |
|---|---|---|---|
| In test | Every merged Change is callable in test at once | Change.merge | Change.merged |
| Live | live serves the deployed Version; every Interface and package follows it | Version.deploy | Version.deployed |
| Growing | An additive Change reaches every version as it ships | Change.merge | Change.merged |
| Versioned | A breaking Change merges only as the next major, with a gate | Change.review | Change.reviewed |
| Pinned | Each Tenant answers at its own apiVersion until it moves | Tenant.pin | Tenant.pinned |
| Retired | A version no Tenant pins stops serving, after notice | Interface.sunset | None |
Interface.deprecate and Interface.sunset have status planned. Every version a Tenant pins keeps serving, and API deprecation covers what retiring one takes.
Going live
live serves nothing until the first deploy, and a call with a live key returns 503 not-live. Each later deploy moves live to a new build, and the previous Version stays one revert away.
The deploy is the moment Customers see. Merging to test changes nothing they call, so a Startup merges and tests freely, then deploys when its checks pass.
Undoing a Change
Change.revert undoes a merged Change with a new Change, deleting nothing. A reverted breaking Change leaves its version in place for every Tenant already pinned to it.
What Customers hear
The Changelog publishes every merged Change, with the Verbs it touches and the one-line upgrade. Customers follow it by email, feed or Watch, and an Agent reads the same notes in Markdown.
A view of what a Change would put live, before it merges, is the Preview capability, with status planned.