novox/hq
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

The catalogue owns the module graph, and genesis builds rather than carries

Browse Source 
The graph had no owner: what modules are, what they require, what they claim and
what they are built against all sat in the control plane because that is where it
was written first. The control plane's own test says otherwise — anything a single
machine could answer alone is not its work, and what a module needs requires no
knowledge of any node.

So the catalogue becomes a core module beside the control plane and the builder,
owning the graph and serving tools over it. The control plane consumes it, which
is the opposite of what the tiers suggest and is therefore stated rather than
inferred.

That makes the catalogue a fourth thing that cannot arrive through the ordinary
path, so the claim written this morning that the list was closed at three is
corrected. All four are answered by one mechanism instead: the installer carries
an init builder and the core modules are built on the machine, so what is carried
is a builder rather than a result and nothing is left without a route.

Two things are open and named rather than assumed: where the init builder clones
from, given the forge normally runs on the mesh it would be rebuilding, and what
it publishes into, given the registry is installed later in the order today.

Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
This commit is contained in:
jschoubben
2026-09-12 22:03:05 +02:00
parent 837b5df2f7
commit 64ae75a480
4 changed files with 150 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-DESIGN/01-to-be/12-a-module-repository.md
+26 -14
View File
@@ -360,10 +360,12 @@ machine across the private network, because a mesh-scoped provision that only an
not one. A container that is running is not a registry that replies, and this project has paid for
that distinction once already.*
## The three the loop cannot build, and there are only three
## The four the loop cannot build
*2026-09-12. Written down because it keeps being rediscovered as if it were new, once per
component. It is one rule, it has three instances, and the list is closed.*
component. It is one rule; the instances are listed below. Revised the same day, when the catalogue
gained an owner and turned out to be a fourth — which is the argument for stating the rule rather
than the list.*
**Anything the build loop needs in order to run cannot be delivered by the build loop.** It arrives
from outside exactly once, and from then on it is an ordinary module, upgraded like one. What
@@ -374,20 +376,30 @@ have a route and one does not:
|---|---|---|
| The control plane | It is what installs modules. Nothing can install it before it runs. | **Carried inside the installer** and published once there is a registry ([ADR 0067](../../02-DECISIONS/0067-genesis-is-a-pivot.md)) |
| The registry | It *is* where artifacts are delivered from. A store cannot be delivered through itself. | **Pulled from the public internet** — its image is an ordinary public one, never built ([`04-ISSUES/029`](../../04-ISSUES/029-the-artifact-store-cannot-be-delivered-by-the-artifact-store/00-report.md)) |
| The builder | It is what builds. Nothing builds it before it runs. | **Nothing yet.** Not carried, not public. See below. |
| The builder | It is what builds. Nothing builds it before it runs. | Built at genesis by the init builder ([ADR 0070](../../02-DECISIONS/0070-the-catalogue-owns-the-module-graph.md)) |
| The catalogue | It owns the module graph, and nothing can be resolved or installed without it. | Built at genesis by the init builder ([ADR 0070](../../02-DECISIONS/0070-the-catalogue-owns-the-module-graph.md)) |
**The builder has no route, and this is the open one.** It is built from the control plane's
repository, so it cannot be pulled from the public internet like the registry; and the installer
carries one image only, the control plane's. So a mesh raised by the installer today has no builder
and no way to obtain one, which means it cannot build the catalogue, which means every module
waiting on a digest keeps waiting. Whatever answers this — the installer carrying a second image,
the control plane's own build producing both, or the first builder being fetched some other way —
is the last thing between a raised mesh and a self-upgrading one.
**How they arrive is settled and not yet built.** The installer carries an init builder, which
clones the source and builds the control plane, the catalogue and the builder before a mesh exists
to install anything. Two things about that are open and named in
[ADR 0070](../../02-DECISIONS/0070-the-catalogue-owns-the-module-graph.md): where the init builder
clones from, given the forge normally runs on the mesh it would be rebuilding, and what it
publishes into, given the registry is installed later in the order today.
**There is no fourth.** Everything else the mesh runs is either upstream — a third-party image
pulled by digest — or built by the builder from a repository and published to the registry. So the
question "how does *this* one get here first?" has an answer for every module without asking it
again: if it is not one of the three above, it comes through the loop.
**There is a fourth, and the list was closed too early.** The catalogue owns the module graph
([ADR 0070](../../02-DECISIONS/0070-the-catalogue-owns-the-module-graph.md)), so it cannot be
installed by something that needs it in order to install anything — the same shape as the other
three. This section previously said the list was closed at three, which was written before the
catalogue had an owner and is corrected here rather than left to be reasoned from.
**And the answer for all four is now one mechanism, not four special cases.** Genesis carries an
*init builder* and builds the core modules on the machine — control plane, catalogue and builder —
rather than carrying a finished image of any of them. So the question is no longer "how does this
one get here first?" asked once per component; it is answered once, by the thing that is carried
being a builder rather than a result.
Everything outside those four is either upstream — a third-party image pulled by digest — or built
by the builder from a repository and a path, and published to the registry.
**A carried artifact is not a differently-pinned artifact.** Once published it is named by a digest
the mesh's registry assigned, exactly like everything the builder produces. A reader cannot tell
03-DESIGN/01-to-be/17-raising-a-mesh.md
+16 -3
View File
@@ -36,6 +36,19 @@ Confusing the two is what produced a procedure that only ever worked in a fixtur
raises four machines the same way has not tested genesis at all — it has tested joining, four
times, with the first one hand-fed.
## Genesis is decided to change, and has not yet
*2026-09-12.* [ADR 0070](../../02-DECISIONS/0070-the-catalogue-owns-the-module-graph.md) settles
that the installer carries an **init builder** rather than the control plane's image, and that the
core modules — control plane, catalogue, builder — are **built on the machine** before a mesh exists
to install anything. One thing is carried, and it is a builder rather than a result, which is what
gives the builder and the catalogue a route they did not have.
**The section below describes what the installer does today**, which is to carry the control plane's
image and publish it once there is a registry. It is kept as written because it is true of the
program that exists, and replacing it with the intention would leave nothing describing the thing
anybody actually runs. The order changes when the init builder is built; the pivot does not.
## Genesis
The installer is a single program carrying the control plane's image inside it. That is what makes
@@ -136,9 +149,9 @@ needs a toolchain and a working tree, which is most of the burden the installer
**A mesh cannot say how it was raised.** Nothing afterwards can contradict a claim that a machine
was brought up the supported way, so the rule that it must be is, today, unenforced.
**The builder has no way to arrive.** It cannot be pulled from the public internet, because the
mesh builds it; and the installer carries one image only. So the paragraphs above describing the
core modules being built are, today, describing something that cannot start.
**The init builder is not built.** Until it is, the installer carries the control plane's image and
nothing gives a fresh mesh a builder or a catalogue, so the paragraphs above describing the core
modules being built describe something that cannot yet start.
**A machine has no account for a registry that asks for one.** The mesh grants a consumer a
credential for a database; it does not yet do so for the store its own images live in. Genesis