Issue 040 — the only description of how a mesh is stood up is a test

There is no installer. The complete account of standing up a mesh is an integration test in the lab, and a fixture may invent what it needs — this one raised a registry no production has and rewrote every image reference through it, concealing both 039 and the fact that a first node outside the lab had no bootstrap path at all. The bed being green said nothing about whether a mesh could be installed. Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
2026-09-10 23:34:59 +02:00
parent e228355a52
commit f9e129f734
1 changed files with 58 additions and 0 deletions
@@ -0,0 +1,58 @@
+---
+status: open
+opened: 2026-09-10
+located-in: []
+fixed-by:
+amended-design:
+---
+
+# 040 — The only description of how a mesh is stood up is a test
+
+## Symptom
+
+There is no installer. The one complete, executable account of how a mesh comes into existence is
+an **integration test** in the lab repository: it builds the images, applies the substrate, enrols
+every node, places the overlay, seeds the operator's secrets, registers modules, assigns them,
+pushes, and waits for convergence.
+
+Nothing else does this. `packaging/` installs and supervises the **host agent** on one machine.
+[`04-lab-installation`](../../03-DESIGN/01-to-be/04-lab-installation.md) covers the **lab's own**
+prerequisites — a virtualisation daemon, storage, a pool. Neither installs a mesh, and no design
+section describes doing so.
+
+## Why this matters
+
+**A test fixture is allowed to invent what it needs, and this one did.** It raised an image
+registry that exists in no production, stocked it from a workstation, and rewrote every image
+reference in every manifest to point at it. That single convenience concealed at least two separate
+faults for as long as the lab has existed:
+
+- modules naming a tag where a digest is required, never caught because the harness was assigning
+  the digests ([039](../039-the-lab-registry-was-silently-pinning-unpinned-modules/00-report.md))
+- the bootstrap itself having **no path at all** on a machine that is not the lab: the mesh's own
+  control-plane image exists in no registry, so nothing could name it, and the fixture's registry
+  was the only reason that never surfaced
+
+**So the bed being green said nothing about whether a mesh could be installed.** Both are the same
+fault: the procedure and the reality drift, and the drift is invisible precisely because the thing
+that would notice is the thing doing the inventing.
+
+**And a person cannot run it.** The procedure is expressed as assertions in a test runner, in a
+repository whose purpose is to raise disposable virtual machines. Somebody standing up a real first
+node has no artefact to use — which is why standing one up has been "a person driving the CLI",
+the loop [ADR 0010](../../02-DECISIONS/0010-delivery.md) removed everywhere else and left here.
+
+## Open questions
+
+- Where should the procedure live so that **the lab uses it rather than reimplementing it**? The
+  lab must remain able to raise machines and inject faults; what it should not be able to do is
+  describe installation differently from the thing an operator runs.
+- What is the smallest arrangement that makes drift *impossible* rather than merely discouraged —
+  the bed invoking the installer, or something generating one from the other? A second description
+  that is merely kept in step is the arrangement that just failed.
+- Which parts of what the test does are genuinely lab-only — documentation addresses, names that
+  resolve nowhere, injected faults — and which are the mesh's own and belong in an installer? The
+  distinction has never been drawn, and everything landed on the lab side of it by default.
+- How is *"the installer is what installed this"* checked afterwards, on a mesh that is already
+  running? A mesh cannot say how it was raised, so nothing can currently contradict a claim that it
+  was raised the supported way.