A stream's name ends in a version segment — which kind of change justifies bumping it, and which must not?

## What the version segment actually marks A version segment in a stream's name is not a version number for the messages. It is a statement about the stream as an object: *this is a different stream from the one with the previous segment, and a reader of the old one should not assume the new one is a drop-in continuation*. That is a much bigger claim than the one a payload version makes, and it is why the two must not share a mechanism. A payload version says the records changed shape in a way the contract governance decides is compatible or not. A version segment says the container itself has been replaced, with all the estate cost that implies — a second set of grants, a second quota, a second set of dashboards, a second entry in every inventory. ## Which changes justify a bump | Change | Bump? | Why | |---|---|---| | The keying or grouping rule changes, so related records no longer land together | **Yes** | A reader relying on the old grouping is now silently wrong, which is the definition of a different stream. | | The scope changes — one region becomes all regions, one product becomes the whole catalogue | **Yes** | Volume, meaning and every downstream assumption move at once. | | One stream is split into several, or several are merged | **Yes** | There is no continuation to point an existing reader at. | | The record-lifetime contract readers depend on changes materially | **Yes** | Readers sized their recovery behaviour against the old promise. | | An optional field is added to the payload | **No** | The contract layer governs that; the container has not changed. | | The producing service is rewritten or redeployed | **No** | Nothing about the stream changed; only who fills it. | | Traffic grows and the stream needs more capacity | **No** | A capacity decision, however awkward it is to make later. | | The owning team is reorganised | **No** | Ownership is recorded against the stream, not encoded in it. | ## The two failure modes They are mirror images, and an interviewer is usually probing for whichever one you have not lived through. 1. **Bumping for everything.** Every payload change gets a new segment, and the estate ends up carrying several live versions of one stream at once. Each one is a real object: grants, a quota, retention settings, dashboards, cost, and readers. The organisation has paid a migration's worth of estate for a change that the contract governance would have absorbed invisibly. Worse, nobody owns ending the old ones, so the count only goes up. 2. **Never bumping.** The meaning of a stream is changed in place and the announcement is a message in a chat channel. Readers that were not in the channel keep interpreting records under the old meaning, and the failure surfaces as wrong numbers rather than as an error. This is the more expensive of the two, because the estate looks clean while the data is wrong. ## Where platforms differ - On platforms where **records remain readable after delivery**, a bump leaves a body of history behind under the old name, and the transition question is which readers still need that history. On platforms where **a delivered message is gone**, there is little history to strand, and the question becomes whether anything is still undelivered when the writers move. - Some platforms provide a **first-class named space** that can carry the version instead of the name, which changes where the segment sits but not the decision about when to move it. - Some platforms let a replacement **inherit settings** from the space it is created in, so a bump restates less; others stamp creation-time defaults, so a bump silently resets settings the old stream had been tuned with. ## Running more than one version at once Two live versions is a transition. Three is a smell. Seven is an estate that has substituted naming for governance. Two rules keep it honest: - **decide the bump on reader impact, not on producer convenience** — the question is always whether an existing reader would be wrong, not whether the producing team finds a new stream tidier; - **a bump is a commitment to end the old one** — the mechanics of moving readers across and eventually deleting the old stream are the retirement procedure, but the decision to take that on is made here, at the moment somebody proposes the new segment. The useful interview answer names the boundary explicitly: the version segment versions the *stream*, and the payload has its own versioning that lives somewhere else entirely. A candidate who conflates them will design an estate that grows a stream for every field.