Merge pull request 'Two graphs, and a build chain that orders itself' (#36) from feat/two-graphs-and-the-build-chain into main

2026-09-12 23:09:42 +02:00
parent 90f7bcb209 58ad0742d8
commit a4866ca899
2 changed files with 87 additions and 0 deletions
@@ -0,0 +1,86 @@
+---
+topic: the tiers
+status: accepted
+date: 2026-09-12
+deciders: jochen
+reconstructed: false
+extends: 0070-the-catalogue-owns-the-module-graph.md
+---
+
+# 72. Two graphs, and a build chain that orders itself
+
+## Context
+
+[ADR 0070](0070-the-catalogue-owns-the-module-graph.md) gave the catalogue the module graph and
+said the control plane consumes it — that resolving a requirement and composing what a machine
+should be *"both need to know what modules are, so the dependency runs from the control plane to
+the catalogue."*
+
+**That paragraph is wrong, and this record corrects it.** It was written before the two graphs had
+been told apart, and it creates a dependency that does not need to exist: a catalogue that is down
+would leave the control plane unable to compose the declaration that would repair it.
+
+## Decision
+
+**There are two graphs, with different owners, and they meet only when something is installed.**
+
+| Graph | Owner | What it links | Answers |
+|---|---|---|---|
+| the module graph | the **catalogue** | module-versions to each other | what was this built against · what must rebuild now · what does this need |
+| the runtime graph | the **control plane** | module-versions to nodes | what runs where · who consumes this provision · what breaks if this machine goes |
+
+The catalogue does not know nodes exist. The control plane holds module-versions and nodes, along
+with capabilities and claims, because deciding whether a machine qualifies needs every node.
+
+**So the control plane never asks the catalogue anything.** It holds what it needs to compose a
+declaration. A catalogue that is down stops new installs and stops the rebuild fan-out, and does not
+touch anything already running or the ability to repair it.
+
+**Everything between them travels as events over the broker**, like all module-to-module
+communication. The builder finishes and announces that a module was built. The catalogue registers
+it, places it among what it depends on, and announces that a module was upgraded. The control plane
+reacts to *that*, not to build output — a semantic fact rather than an artifact.
+
+**Nothing is lost if a receiver is down.** A consuming module's queue is durable with a dead-letter
+exchange, declared by the mesh rather than by the module, so an event waits for a consumer that is
+not there.
+
+**Build order is not computed. It emerges from the chain.** The builder never consults the graph: it
+builds what it is asked for, one at a time. The catalogue asks for the next build after the previous
+registration, so *"do not start this until that is registered"* holds by construction rather than by
+a schedule somebody maintains.
+
+**The catalogue's rule is a condition, not an order:** ask for a module to be rebuilt once everything
+it was built against is current. That handles a chain and a diamond with one rule, where an
+order-based approach needs to know the shape in advance.
+
+**Two refusals belong to the catalogue.** A cycle, because the chain would never settle. And a
+rebuild whose artifacts are identical to what it replaced, which is not an upgrade and must not be
+announced as one — or a single change ripples outward forever through modules that did not change.
+
+**Genesis does none of this.** The init builder has a fixed, short list — control plane, catalogue,
+builder — in a written order, because there is no catalogue yet to ask.
+
+## Consequences
+
+The builder stays simple, and independent of the catalogue. That is what makes genesis possible at
+all: the thing that builds the catalogue cannot require the catalogue.
+
+The two sides can be briefly out of step — the catalogue may hold a module-version a moment before
+the control plane knows of it. Assigning in that instant fails, and should say why rather than
+report that no such module exists.
+
+A module's declared events stop being documentation and become its permissions: an account is
+scoped from what a module emits and consumes, so a builder that announces what it built is granted
+what it needs by the ordinary mechanism rather than by a special case.
+
+## Open
+
+**Whether an upgrade is applied or merely noticed.** Today the system this replaces deploys
+automatically, and that is a defensible default for core modules on a mesh its operator runs. But
+the design as it stands does the opposite: it records that the source moved ahead, makes it visible,
+and waits to be told. This must become a setting with a chosen default rather than inherited
+behaviour — and the choice matters most on the day a bad commit reaches something that carries mail.
+
+**Whether a module assigned to several machines upgrades on all of them at once.** Doing so makes
+one bad commit simultaneous everywhere. Doing one machine and pausing turns it into one casualty.
@@ -104,6 +104,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0069** — [A module is a repository and a path within it](0069-a-module-is-a-repository-and-a-path.md)
 - **0070** — [The catalogue owns the module graph, and genesis builds rather than carries](0070-the-catalogue-owns-the-module-graph.md)
 - **0071** — [Genesis clones from a mesh, and checks what it got](0071-where-genesis-gets-its-source.md)
+- **0072** — [Two graphs, and a build chain that orders itself](0072-two-graphs-and-the-build-chain.md)

 ### What runs on them, and how it gets there