From 51739c4302ae56eb996956f8960bf08c5adbd6f0 Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 27 Sep 2026 19:04:45 +0200 Subject: [PATCH] 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. --- 03-DESIGN/01-to-be/28-building-the-bus.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/03-DESIGN/01-to-be/28-building-the-bus.md b/03-DESIGN/01-to-be/28-building-the-bus.md index 7f25dce..d86472c 100644 --- a/03-DESIGN/01-to-be/28-building-the-bus.md +++ b/03-DESIGN/01-to-be/28-building-the-bus.md @@ -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