The order the repositories land in is part of the rollout

Derived while merging and visible from no single repository, so it belongs
written down rather than re-derived later: the client library before the
catalogue, because it is where the subject is derived and a converted module
against the old one publishes the local name itself; the catalogue before the
controller, because the controller refuses an old-style name outright and would
make every unconverted module unregisterable.

Two tested properties are what make it safe and not merely ordered. An old-style
name passes through the derivation untouched, so an unconverted module keeps
working at every step. And a converted name derives to exactly the key the old bus
published, so nothing moves on the wire until 5.2 sets the variable.

The failure avoided is 127's own, which is why this is worth a table: a publisher
and a subscriber disagreeing about a subject log nothing anywhere.
This commit is contained in:
2026-09-27 19:04:45 +02:00
parent 5cac268457
commit 51739c4302
+23
View File
@@ -629,6 +629,29 @@ reserves them for after the move, and a flow built ahead of its design would be
**Why here.** It is the only step that moves a node's bus, and it moves every node's at once.
**The order the repositories land in is part of the rollout, not paperwork.** Derived 2026-09-27
while merging, and not obvious from any one repository, which is why it is written here rather than
left to be re-derived under time pressure:
| order | repository | why it cannot be later |
|---|---|---|
| 1 | this one | prose; nothing deploys |
| 2 | the sdk | comments only, and no module rebuilds for it |
| 3 | the client library | it is what a module calls to emit, and it is where the subject is derived. Until it lands, a locally-named event is published under the local name itself |
| 4 | the catalogue | every manifest and every module's code, renamed together. Safe only once the runtime derives |
| 5 | the controller | **it refuses an old-style event name outright**, so landing it before the catalogue makes every unconverted module unregisterable |
| 6 | the hosts | last, because nothing else waits on them |
Two properties make the sequence safe rather than merely ordered, and both are pinned by tests. A
name already in the old form passes through the derivation untouched, so a module nobody has
converted keeps working at every step. And a converted name derives to **exactly** the key the old
bus published, so steps 3 and 4 change nothing on the wire — the move to the new bus is step 5.2 and
one environment variable, not a side effect of deploying.
The failure this ordering avoids is issue 127's own: a publisher and a subscriber that disagree about
a subject produce no error anywhere. Nothing logs, nothing retries, and the mesh reports itself
healthy while reacting to nothing.
- [ ] 5.1 the cutover bed: a mesh on AMQP with a predecessor stand-in on the deprecated broker
moves its bus in one rollout, every node reporting on NATS afterwards, the stand-in's own
client still connected throughout