Version semantics
Numbering, drafts, the stable pointer, deprecation, and what publishing does to a running chat.
Numbering
Monotonic integers per agent, starting at 1. No semver, no branches, no tags. v7 means the seventh publish of this agent and nothing more. The number is allocated inside the same transaction that flips the status, so concurrent publishes serialise and nobody gets v5 twice.
Drafts
The draft is the only mutable object in the system. One per agent per user, created from the stable version when you hit Edit.
- Drafts have no version number and do not appear in history.
- Drafts run only in scratch chats, labelled not reproducible and excluded from run history.
- A draft whose body hash matches an existing published version cannot be published — no duplicate versions.
- Discarding a draft is the only destructive action in the product, and it only destroys something that never had a number.
What happens to running chats when a new version publishes
Nothing. That is the product. Open chats keep streaming against their pinned version, batch jobs holding a version id are unaffected, and no banner interrupts anyone. After publishing you are told how many chats are open on the previous version, with a link to fork any of them — an offer, never an action.
The stable pointer
stable_version_id is what a chat resolves when no version is specified. It is set explicitly, not automatically. Publishing proposes it; on team plans a publisher has to promote it.
- Stable can lag: publish v6, keep v4 stable while you evaluate.
- Rollback is a pointer move, not a republish — there is never a v7 that is secretly v4.
- A chat resolves stable once, at creation, and writes the resolved id. It never re-resolves later.
Deprecation
Deprecating a version stops it being selectable for new chats and hides it from the picker. It does not stop anything running.
- Chats already pinned to it keep working, deliberately.
- It stays readable, diffable, exportable and rerunnable forever.
- It cannot be stable — move the pointer first.
- It is reversible.
Model drift
Versions pin exact model ids, never floating aliases, because an alias lets the provider move the model under a frozen version. The id that actually served a run is recorded separately, so if a fallback ever fires you can see it in the run record and in every diff that touches it.