02-DECISIONS/0073-the-installer-carries-a-builder.md

@@ -0,0 +1,94 @@
+---
+topic: the tiers
+status: accepted
+date: 2026-09-13
+deciders: jochen
+reconstructed: false
+extends: 0070-the-catalogue-owns-the-module-graph.md
+---
+
+# 73. The installer carries a builder, and the registry stays where it is
+
+## Context
+
+[ADR 0070](0070-the-catalogue-owns-the-module-graph.md) decided that genesis builds rather than
+carries, and [ADR 0071](0071-where-genesis-gets-its-source.md) settled where it clones from. Two
+questions were left open, and the design record names them as the one gap that stops a fresh mesh
+from being able to produce anything at all: **how the builder arrives**, and **what it publishes
+into**.
+
+Today the installer carries the control plane's image inside itself. That works, and it is why
+genesis needs no registry: nothing is ever fetched, because the one image that matters is already
+present. The cost is that the mesh which results holds an artifact it did not make, cannot rebuild,
+and knows nothing about — no version, no source, no edges. That is the same shape as the fault
+[issue 044](../04-ISSUES/044-the-runtime-every-module-builds-on-cannot-be-built-by-the-mesh/00-report.md)
+recorded for the shared runtime, and fixing it there while shipping it here on every new mesh would
+be a strange place to stop.
+
+## Decision
+
+**The installer carries a builder, and nothing else.** One artifact, not a growing set. It clones
+the source at a named commit, checks what it got ([ADR 0071](0071-where-genesis-gets-its-source.md)),
+and produces the control plane from the same repository and path that any later rebuild of it would
+use. What raises the mesh is therefore the same thing that will maintain it, and there is no second
+mechanism kept in step with the first.
+
+**The registry does not move, and the argument for moving it does not survive being made.**
+
+It was put this way: a produced image has to be put somewhere before anything can fetch it, so the
+registry must now precede the control plane, and
+[ADR 0033](0033-the-substrate-is-a-store-and-a-broker.md)'s answer to that question has to flip.
+
+It does not, because the premise is false. **The thing that builds the image and the machine that
+runs it are the same machine.** A built image is already in that machine's container runtime, and
+the temporary control plane names it exactly as it names a carried one — by the digest of its own
+configuration, a local identity that requires nothing to have served it. Building changes where the
+bytes came from. It does not change where they are.
+
+| | is it substrate? | must it precede the control plane? |
+|---|---|---|
+| the store | yes | yes — there is nowhere else to put the control plane's state |
+| the broker | yes | yes — the control plane reaches a machine only over it |
+| the image registry | yes — it cannot grant itself a repository | **still no** — the first machine neither fetches the control plane nor needs to, whether the image was carried in or made here |
+
+So the registry stays where [ADR 0033](0033-the-substrate-is-a-store-and-a-broker.md) put it:
+substrate by role, ordinary by delivery, installed by the temporary control plane as its first act.
+The bundle carries two services and a control plane, as it did. **What publishes into the registry
+is unchanged too** — the existing step that pushes the control plane's image into it, which is the
+moment that image first receives a digest assigned by something other than itself. It now pushes
+something this mesh built rather than something it was handed.
+
+## Consequences
+
+**Genesis gains one step and changes no others.** A build happens before the image is loaded. The
+pivot described in [ADR 0067](0067-genesis-is-a-pivot.md) survives exactly as written, because the
+step it pivots on never cared where the image came from.
+
+**A fresh mesh can produce from the moment it exists.** The builder is present before the control
+plane is, so the core modules, the catalogue and the builder's own module can be built in the
+ordinary way rather than waiting for somebody to carry them in. The paragraphs in
+[`17-raising-a-mesh`](../03-DESIGN/01-to-be/17-raising-a-mesh.md) that describe this were describing
+something that could not start; they can start now.
+
+**Genesis needs more of the outside world.** Carrying an image needed nothing but the installer.
+Building one needs the source, and whatever the build itself reaches for. This is a real cost and
+is not waved away: it makes genesis fail in more ways, all of them at a step that says what it was
+doing. It is accepted because the alternative is a mesh that cannot rebuild its own control plane,
+which fails in exactly one way, silently, later, and for ever.
+
+**A pre-built bundle remains possible and is not this.** Nothing here forbids delivering artifacts
+rather than building them; it fixes where they may come from. A bundle of pre-built core modules is
+an **export of a mesh that built them**, carrying what the catalogue knows about each alongside the
+artifact itself — so that loading one leaves the graph in the state building would have left it. A
+bundle that carries images without that is the thing this decision rejects, whoever ships it.
+
+## What this does not decide
+
+**Whether the builder's own module is carried or built.** It builds everything else; what installs
+*it* as an ordinary module afterwards, so that it too can be upgraded, is the same closed-list
+question [`12-a-module-repository`](../03-DESIGN/01-to-be/12-a-module-repository.md) already holds,
+and is unchanged by this.
+
+**How a machine authenticates to a registry that asks it to.** Genesis raises its own and reaches it
+over the loopback, so this remains a joining problem
+([issue 042](../04-ISSUES/042-nothing-gives-a-node-an-account-for-a-registry/00-report.md)).

02-DECISIONS/README.md

@@ -105,6 +105,7 @@ python3 00-META/checks/index.py            fail if stale
 - **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)
+- **0073** — [The installer carries a builder, and the registry stays where it is](0073-the-installer-carries-a-builder.md)
 
 ### What runs on them, and how it gets there
 

03-DESIGN/01-to-be/17-raising-a-mesh.md

@@ -36,34 +36,44 @@ 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
+## What changed, and what did not
 
-*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.
+*2026-09-13.* The installer carries a builder now, and builds the control plane it raises. Three
+records settle it: [ADR 0070](../../02-DECISIONS/0070-the-catalogue-owns-the-module-graph.md) that
+genesis builds rather than carries, [ADR 0071](../../02-DECISIONS/0071-where-genesis-gets-its-source.md)
+where it clones from, and [ADR 0073](../../02-DECISIONS/0073-the-installer-carries-a-builder.md) how
+the builder arrives — which also records an argument that failed. It was put that a produced image
+must be published before anything can fetch it, so the registry would have to come up before the
+control plane. It does not: the machine that builds the image is the machine that runs it, and a
+local image is named by the digest of its own configuration exactly as a carried one is. **Building
+changes where the bytes came from, not where they are.**
 
-**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.
+So the pivot is unchanged, the registry is where it was, and one step was added before the bundle is
+written. What follows describes the program that exists.
 
 ## Genesis
 
-The installer is a single program carrying the control plane's image inside it. That is what makes
-genesis possible without a network to fetch from and without a registry to name: the image is
-present because the installer is present.
+The installer is a single program carrying **the builder** inside it — not the control plane
+([ADR 0073](../../02-DECISIONS/0073-the-installer-carries-a-builder.md)). What cannot be fetched is
+the thing that does the fetching, so that is what is carried; everything else is made here.
 
 It proceeds in one direction, and every step is safe to run again.
 
 **First it refuses to start if the machine is not ready.** A container runtime, the ability to
-write where it must write, the host binary where it expects it. A machine that is not ready is told
-what is missing rather than half-changed.
+write where it must write, the host binary where it expects it — and a repository and a commit to
+build from, because an installer told nothing would raise a store and a broker and then have
+nothing to raise a control plane from. A machine that is not ready is told what is missing rather
+than half-changed.
 
-**Then it loads the carried image and describes what the machine will become.** The image is named
-by the digest of its own configuration — content-addressed and unforgeable, and requiring nothing
-to have served it. This is legal precisely where nothing could have served one, and nowhere else.
+**Then it loads the carried builder and builds the control plane with it**, from a repository on a
+mesh that already exists and a named commit ([ADR 0071](../../02-DECISIONS/0071-where-genesis-gets-its-source.md)).
+This is the same repository and path every later rebuild of the control plane will use, so what
+raises the mesh is the same thing that will maintain it.
+
+**Then it describes what the machine will become.** The image it just made is named by the digest
+of its own configuration — content-addressed and unforgeable, and requiring nothing to have served
+it. That is legal precisely where nothing could have served one, and it is why building here needs
+no registry: the machine that made the image is the machine that will run it.
 
 **Then it raises the substrate and a temporary control plane, and waits for that control plane to
 answer.** At this point the machine is a mesh of one node with nothing joined to it.
@@ -149,9 +159,16 @@ 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 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.
+**The builder's own module is not installed by genesis.** The installer carries a builder and uses
+it, so a fresh mesh is raised on something it built; but nothing afterwards installs that builder as
+an ordinary module on the machine, so the mesh cannot yet be asked to build anything else. The
+paragraphs above describing the core modules being built can start now — a builder exists and has
+somewhere to publish — and nothing yet starts them.
+
+**A module's declaration still has to be copied onto the machine by hand.** The installer reads the
+registry's and the control plane's manifests from a checkout somebody put there. The control plane's
+now lives in the control plane's own repository, which the installer clones anyway, so this is a
+thing that can be removed rather than a thing that must be designed.
 
 **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
@@ -167,6 +184,7 @@ pulling problem, not a genesis one.
 | Every step may be run again | The installer is re-run against a raised machine and must change nothing and report why. |
 | An image is named exactly | A machine refuses a bundle naming an image by tag. The refusal is exercised, not assumed. |
 | The installer is what installed this | **Nothing.** See above. |
-| The builder can arrive on a fresh mesh | **Nothing.** There is no route for it yet. |
+| The builder can arrive on a fresh mesh | The installer carries it, and the genesis bed raises a machine by running the installer. A bed that raises one any other way fails its own acceptance check. |
+| The control plane a mesh runs is one it built | The genesis bed asserts the running control plane is pinned to a digest this mesh's own registry serves, for an image built from a named repository and commit — not one the installer carried. |
 | A core module is built rather than only carried | The control plane is rebuilt from its own repository and path, and the running mesh is upgraded to the result — the same path any module takes. |
 | Installing produced a mesh that can produce | After installing, a module with source of its own is asked for and comes back pinned to a digest this mesh's registry assigned, not to a placeholder. |

04-ISSUES/044-the-runtime-every-module-builds-on-cannot-be-built-by-the-mesh/00-report.md

@@ -0,0 +1,112 @@
+---
+status: resolved
+opened: 2026-09-13
+located-in: [mesh-tools, mesh-sdk]
+fixed-by: mesh-tools feat/run-once-entry, mesh-sdk feat/adr-ref-resync
+amended-design:
+---
+
+# 044 — The runtime every module builds on cannot be built by the mesh
+
+## Symptom
+
+Every module written in the mesh's own toolchain is compiled on top of one shared base image — the
+tool runtime. The mesh can build the modules. It cannot build the base.
+
+Two things stop it, and each is enough on its own:
+
+- The base's container definition copies a compiled output directory that is not in the repository.
+  A clean clone has the sources and no compiled output, so the definition refers to something that
+  is not there.
+- The base's dependency on the mesh's own software development kit resolves to a **sibling checkout
+  on disk**, not to anything a clone can fetch:
+
+  ```
+  "node_modules/@novox/mesh-sdk" -> { "resolved": "../mesh-sdk", "link": true }
+  ```
+
+Both mean the same thing: the base can only be produced on a workstation that happens to have the
+neighbouring repositories laid out beside it, and has run a compile step by hand first.
+
+Observed while building four modules through the mesh from a repository and a path. All four
+succeeded, and all four recorded that they were built on top of the same base — an image reference
+that no module in the mesh produced, because no module could have.
+
+## Why this matters
+
+**This is the one artifact the whole build chain rests on, and it is the one artifact outside the
+chain.** Three separate consequences, all visible today:
+
+- *The base is pinned by hand.* Every module's container definition names it as a literal digest
+  written by a person. Nothing checks that digest against anything.
+- *Nothing can tell when it moves.* A build records what it was built on top of, so an artifact is
+  stale when anything beneath it moved. That rule cannot fire for the base: the graph has edges
+  pointing at it, and no version on the other end, because no build ever registered one. The mesh
+  is therefore unable to answer "what must be rebuilt" for the change that would reach *every*
+  module at once.
+- *Nobody can check what is in it.* The published base and the definition in the repository have
+  already drifted: the definition names one operating system base, and the image actually serving
+  every module is built on a different one. This was found by running the image, not by reading
+  anything, and it went unnoticed for exactly as long as nobody could rebuild it.
+
+A rule the design states — an artifact is stale when anything it was built against moved — is
+unenforceable for the artifact it matters most for. That is the shape of a wrong rule, not a
+missing feature: everything downstream reports "nothing to rebuild" and is believed.
+
+## How it would be checked
+
+The check is the fix's own test: clone the repository alone, into an empty directory, and build it.
+Nothing else present, no neighbouring checkouts, no compile run first. If that produces the base,
+the mesh can produce it too, because that is all the mesh does.
+
+## Open questions
+
+- Where should the software development kit come from, for a build that has only one repository?
+  The mesh already knows how to run a package registry as a module, and it already publishes
+  container images to one of its own — so this may be the same answer twice rather than a new one.
+- Is the base a module like any other, or is it one of the few things a new mesh must arrive
+  carrying? It behaves like both: everything is built on top of it, and it is built out of the same
+  sources as everything else.
+- If it becomes an ordinary module, is there a circularity? **No** — checked rather than assumed:
+  the builder is a compiled program built from its own sources and a language toolchain, and does
+  not stand on this base at all. Only modules written in the mesh's scripted toolchain do. So the
+  thing that would build the base is not one of the things built on it, and the chain has an end.
+
+## Resolved, 2026-09-13
+
+The base is a module now, built from its own repository and nothing else.
+
+Three things were in the way, and the third was not visible until the first two were gone:
+
+- **The toolkit could not be fetched.** It is named by a pinned commit of its own repository rather
+  than by a folder on somebody's disk. Both repositories turned out to be readable without a
+  credential, so no package registry was needed after all — which is why this was smaller than it
+  looked.
+- **The toolkit shipped no compiled output.** Every one of its entry points pointed into a directory
+  that is not in source control. It declares the hook that is meant to compile it on install, and
+  the package manager in use does not run that hook — so the build compiles it explicitly instead.
+  Relying on a hook firing would have failed the same invisible way this issue is about.
+- **The base is also the compile environment.** Every module's recipe starts from this image and
+  invokes the compiler out of it. A first attempt dropped the build tools to make a smaller image,
+  which broke every module built on it. They stay, and the recipe now says why.
+
+The drift this issue reported is also closed: the recipe claimed one operating system while serving
+another, and now states what is actually in service. Changing that was deliberately *not* folded in
+— a module already builds against it with that system's package manager, and moving the ground
+under every module at the same moment as making it buildable would be two changes wearing one
+commit.
+
+**Checked the way the report said it should be.** The repository was cloned alone, with nothing
+beside it, and built by the mesh. Then every module was moved onto the result, and the base changed
+for real: all three went stale, each naming the base and the commits it moved between, each listed
+once. Changing only a comment in the base — a new commit, a byte-identical image — correctly makes
+nothing stale, which is a second bug this exercise found and fixed: staleness was comparing commits
+when it should compare artifacts, so the mesh would have rebuilt itself entirely to arrive back
+exactly where it started.
+
+## What is still true
+
+A module names its base as a literal fingerprint in its own recipe. So the mesh can now *say* that
+three modules must be rebuilt, and rebuilding them still produces the old base until somebody edits
+that fingerprint. Noticing is solved; acting on it is the build chain driving itself, which is
+separate work.

04-ISSUES/045-a-container-keeps-the-values-it-started-with/00-report.md

@@ -0,0 +1,60 @@
+---
+status: open
+opened: 2026-09-13
+located-in: []
+fixed-by:
+amended-design:
+---
+
+# 045 — A container keeps the values it started with
+
+## Symptom
+
+A module reads its database credentials from a file the mesh composes. The file was written, then
+rewritten with a different value once the mesh had more to say — the provider's address was not
+known the first time and was the second.
+
+The container went on running with the first version, indefinitely, and reported nothing. Its own
+view:
+
+```
+DATABASE_URL=postgresql://…@:20000/…          what the container holds
+DATABASE_URL=postgresql://…@<provider>:20000/…  what the file on disk says
+```
+
+A module may declare that it restarts when one of its files changes, and this one now does. That
+did not help: the restart fires when the file changes *during an apply*, and the change had already
+happened before the declaration naming it arrived. Applying again is a no-op, because nothing
+changed that time either. The only thing that recovered it was removing the module from the machine
+and putting it back.
+
+## Why this matters
+
+**Reconciliation compares intentions, not what is actually running.** Two intentions in a row can
+both be applied successfully and still leave a container holding values from neither, because a
+container captures its environment once, when it is created, and nothing afterwards re-reads it.
+
+The failure is silent in the worst way: the container is up, the machine reports success, the mesh
+reports every module current, and the thing inside is using a credential the mesh no longer
+believes in. Nothing in the system is in a position to notice — the host knows what it wrote, and
+the module knows what it read, and no one compares the two.
+
+It is not specific to credentials. Any composed value delivered through a file a container reads at
+start has the same shape, which is most of what the mesh delivers.
+
+## How it would be checked
+
+A machine reporting a module as running should be able to say *what it is running with* — not what
+was last written for it. The check is then a comparison the mesh can make on every heartbeat rather
+than a property of one apply: for each container, does what it holds match what the files it was
+built from now say. A mismatch is a drift the mesh can act on, and today it is not expressible at
+all.
+
+## Open questions
+
+- Should the host recreate such a container on its own, or report the drift and let the mesh decide?
+  Recreating is the obvious repair and is also an unannounced restart of a running service.
+- Is "the files a container was created from" something the host already knows, or does a
+  declaration have to say it? A restart-on list is close to this, but it is written by the module
+  author and is therefore exactly as complete as they remembered to make it.
+- Does the same gap exist for values the mesh delivers by other means than a file?