jschoubben
1111bd84d7
Settles the design repository now that the self-upgrade build is on main: - Records the two decisions that shipped without a record — ADR 0077 (the controller/foundation/node vocabulary) and ADR 0078 (the store and broker are ordinary modules); accepts ADR 0075 and 0076, which shipped work rests on. - Fills issue 051's amended-design and wires ADR 0078 into 07-the-foundation. - Sweeps the repo rename (mesh-control -> mesh-controller) into the mutable docs now that the forge repo is renamed; updates the glossary note and repos.md. - Fixes the six broken links from the design-doc renames, indexes the glossary, regenerates the decisions reading order. Both checks (records.py, index.py) are green. Statuses stay honest: the build is on main and lab-proven but not deployed as the production mesh, so the to-be docs remain in-progress and the as-is layer (the hal mesh) is unchanged — graduation to implemented + as-is belongs to deployment, not merge. https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
6.3 KiB
topic, status, date, deciders, reconstructed, extends
| topic | status | date | deciders | reconstructed | extends |
|---|---|---|---|---|---|
| the tiers | accepted | 2026-09-12 | jochen | false | 0067-genesis-is-a-pivot.md |
70. The catalogue owns the module graph, and genesis builds rather than carries
Context
The module graph has no owner. What modules exist, what each requires and provides, what each claims, what each is made of — all of it lives inside the control plane because that is where it was first written, not because anything decided it belonged there.
The control plane's own test says it does not belong there.
06-the-control-plane defines the tier as
everything that needs to know about more than one node, and states the corollary plainly:
anything a single machine could answer alone is not the control plane's. What a module is, and
what it needs, requires no knowledge of any node whatsoever.
And nothing can query it. The graph is the thing that answers what must be rebuilt when this changes, what would break if this were removed, and what can be installed here — and today it is reachable only as control-plane internals. ADR 0009 already decided that a build edge is derived, that an artifact is stale when anything it was built against moved, and that the rebuild set is therefore computable. None of that has anywhere to live.
Genesis currently carries an image, and cannot produce a builder at all. ADR 0067 has the installer carry the control plane's image. That works, but it leaves the builder with no route onto a fresh mesh — it cannot be fetched from the public internet, because the mesh builds it, and the installer carries one image only. So a raised mesh cannot build anything, including the modules it is made of.
Decision
The catalogue is a core module, beside the control plane and the builder, and it owns the module graph. Modules, what they require and provide, what they claim, their dependencies and their build edges, assignments and configuration — the catalogue holds them and serves tools over them: install a module, query what is available and what it needs, query the graph, query and update settings.
It is one per mesh, expressed the way the control plane already expresses it — a claim scoped to the mesh, not a new mechanism.
The control plane consumes it. Resolving what a module requires into an actual binding, 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, which is the opposite of what the tiers suggest and is therefore written down here rather than left to be inferred.
Genesis builds the core modules rather than carrying them. The installer ships an init builder — the one thing carried — which is started, clones the source, and builds the control plane, the catalogue and the builder. The installer then raises a temporary control plane, which installs the catalogue, registers the permanent control plane and the builder, and assigns all three to the first machine. The temporary control plane stops; the installer verifies that the permanent one answers and can query the graph. The builder then sees a catalogue in its initial state and builds the core modules into it.
So exactly one thing is carried, and it is a builder rather than a result. That is the difference from ADR 0067, which carried the control plane's image: carrying a builder produces every core module on the machine, including the builder itself, so there is no component left without a route.
Consequences
The catalogue joins the small set of things that cannot arrive through the ordinary path, because it cannot be installed by something that needs it in order to install anything. It arrives the same way everything else does under this record — built by the init builder before the mesh can install anything — so the set is answered by one mechanism rather than three special cases.
The rebuild fan-out gains a home. What was this built against and what must rebuild now are questions about the graph, and the graph now has an owner to hold the edges and answer them.
The catalogue holds state, so it owns a store in the substrate's database, the same way the control
plane's contexts do. That is the mesh's own store and not the postgres module, which is a
provider other modules consume.
A mesh without a catalogue cannot resolve anything, where previously it merely lacked an interface. That is the cost of ownership over surfacing, and it is deliberate: one owner beats two copies.
Open, and to be settled before this is built
Where the init builder clones from. ADR 0067 rejected building from source at genesis partly because the source lives in a forge that runs on the mesh, so a total rebuild would need the mesh it is rebuilding. Carrying a builder answers the toolchain half of that objection and not this half. Genesis must therefore name a source that exists before the mesh does.
What the init builder publishes into. Building produces artifacts that must be pinned by a digest a registry assigned, and today the registry is installed after the machine has joined. If the core modules are built first, the registry has to exist first, so the substrate's order needs restating rather than assumed.
Where the line falls between the catalogue and the control plane. Claims and assignments need to know about every node, which by the control plane's own test is its work. Whether the catalogue holds them and asks, or the control plane holds them and the catalogue surfaces them, is not settled here.
How this is checked
| Rule | Checked by |
|---|---|
| The catalogue owns the graph | The control plane answers what does this module require by asking the catalogue, and a mesh whose catalogue is stopped cannot resolve — observed, not assumed. |
| One per mesh | A second catalogue assigned anywhere in the mesh is refused by the claim, and the refusal is exercised. |
| Genesis builds rather than carries | The installer carries exactly one artifact, and after installing, every core module is pinned to a digest the mesh's own registry assigned. |
| The builder has a route | A mesh raised by the installer, with no hand-placed image, can build a module. |