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