---
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.