ADR 0089: a bed reads the catalogue it proves; issue 073 diagnosed; issues 074 and 075 opened

The end-to-end design held 'the run rebuilds what it tests' for binaries and images
and not for manifests. The beds' inline copies fell into three kinds; only the first
is a stale copy. The other two are named: a mesh test wearing a catalogue module's
name (074) and a stocked runtime image the run never rebuilds (075).
This commit is contained in:
2026-09-21 14:35:08 +02:00
parent 1c90777124
commit 5dcb9dfbf6
7 changed files with 210 additions and 2 deletions
@@ -3,7 +3,7 @@ status: located
opened: 2026-09-21
located-in: [mesh-lab test/integration]
fixed-by:
amended-design:
amended-design: 03-DESIGN/01-to-be/01-end-to-end-testing.md
---
# Beds carry copies of catalogue manifests, so a catalogue change is proven nowhere
@@ -0,0 +1,33 @@
# Diagnosis — 2026-09-21
1. Every bed was read against the catalogue. Of forty-five, thirteen already read a manifest
from the catalogue checkout, twenty-one built one or more inline, and eleven install no
catalogue module. The thirteen readers used five private copies of one loader, and the copies
had drifted: one never resolved a runtime artifact to the image the lab stocks, so a module
the mesh builds travelled to the machine unresolved; one still asked the catalogue for two
modules by names it no longer uses and recorded the miss as "not assigned".
2. The inline copies fall into three kinds, and only the first is what the report assumed:
- copies that differ from the catalogue only in what the lab must rewrite — an image, a
build section, an optional key dropped. Ten modules across eight beds;
- a second provider raised beside the foundation's. The catalogue's postgres and lavinmq
*claim* the foundation's store and broker and adopt them in place; four beds raise a
second one next to it, renamed and on a private network. Reading the catalogue there
changes what the bed raises, and its assertions with it;
- a module cut down to the shape a mesh mechanism needs — no upstream server, a secret in
the environment, a requirement edge removed so no second provider is wanted — under a
catalogue module's name. Twelve beds. These are mesh tests wearing a module's name, and
the honest fix is a name of their own, not a catalogue read
([issue 074](../074-a-mesh-test-wears-a-catalogue-modules-name/00-report.md)).
3. The receipt claimed the host, the controller and the lab and never the catalogue, so even a
bed that read the catalogue could not be told apart from one that had read it last week.
4. While converting, the images the beds stock for the modules' runtimes were found to date
from two weeks before the manifests they serve — built by hand, by a script the run never
calls. The run rebuilds the host and the controller and not these
([issue 075](../075-a-stocked-runtime-image-is-never-rebuilt-by-the-run/00-report.md)).
**Located in:** mesh-lab, the integration beds and their harness. The fix gives the harness one
loader that reads the catalogue and rewrites only what the lab must, converts the first kind of
copy to it, folds the five private loaders onto it, makes the receipt claim the catalogue, and
adds a unit test that refuses an inline copy naming a catalogue module unless the bed is declared
with its reason. The second and third kinds are declared there; each declaration names the work
that removes it. Decided in [ADR 0089](../../02-DECISIONS/0089-a-bed-reads-the-catalogue-it-proves.md).
@@ -0,0 +1,41 @@
---
status: located
opened: 2026-09-21
located-in: [mesh-lab test/integration]
fixed-by:
amended-design:
---
# A mesh test wears a catalogue module's name
## Symptom, as observed
Twelve lab beds install a module named `redis`, `grafana`, `plex`, `sonarr`, `minio`, `postgres`,
`route-proxy` or `hello-web` that is not the catalogue's module of that name. Each is cut down to
what the bed's mechanism needs: the sidecar runtime without the upstream server it manages; a
token or an API key in the container's environment where the catalogue delivers a file; a
requirement on a route or a certificate authority removed so no second provider is needed; a
vault-granted secret turned into one the module mints itself; a route contribution in the shape a
decision replaced. One bed's header says its manifests are "verbatim from the catalogue" and its
manifest adds three resources the catalogue has not got.
Found while diagnosing [issue 073](../073-beds-carry-copies-of-catalogue-manifests/00-report.md);
the beds are listed, each with what it cuts, in the lab's `beds-read-the-catalogue` unit test.
## Why it matters beyond this instance
- **A green bed named for a module reads as that module proven.** The status view counts a bed
by the module it names; a bed proving a grant mechanism with a `redis` that mints its own
secret proves nothing about the catalogue's redis, which requires the vault's.
- **The cut is invisible.** Nothing distinguishes "this is redis" from "this is a redis-shaped
fixture" except reading the literal against the catalogue, which is what issue 073 found nobody
had done.
- [ADR 0089](../../02-DECISIONS/0089-a-bed-reads-the-catalogue-it-proves.md) now refuses the
copy; until each bed is renamed or made to read the catalogue, it is declared debt.
## What would close it
Each of the twelve beds either reads the catalogue's module and meets its declared requirements
(a route needs the route module beside it; a secret needs the vault), or gives its fixture a name
that is no catalogue module's — `a-cache`, `a-store`, `a-sidecar` — so a green run claims exactly
what it proved. The declared list in the unit test is empty of the `WEARING` reason.
@@ -0,0 +1,36 @@
---
status: open
opened: 2026-09-21
located-in: []
fixed-by:
amended-design:
---
# A stocked runtime image is never rebuilt by the run
## Symptom, as observed
A per-module bed stocks the module's runtime image — the tool runtime carrying that module's
code — from the workstation's image store, by tag. The image is built by hand, by a script in the
lab repository that the suite never calls. On the day issue 073 was worked, the images for six
modules whose beds were about to run dated from two weeks before the manifests they were to be
installed with; the catalogue's code for those modules had changed since, and every bed would have
passed against the old image. The suite's own rule — *the run rebuilds what it tests* — is held
for the host binary and the controller image and not for these.
## Why it matters beyond this instance
- **Silence and success look alike again.** A bed that passes against a stale runtime reports
the module proven; nothing says the image predates the code.
- **It is the same fault [issue 005](../005-pipeline-test-harness-unbuildable/00-report.md)
named**, one layer down: a stale artifact reporting success against code that moved.
- The receipt now names the catalogue's commit ([ADR 0089](../../02-DECISIONS/0089-a-bed-reads-the-catalogue-it-proves.md)),
which makes this sharper, not better: the receipt claims a commit whose runtime code was never
built into what ran.
## What would close it
The suite builds, or refuses to stock, a module runtime whose image is older than the module's
source in the catalogue the run is pointed at — the same treatment the host binary and the
controller image get. Or the scenario says which images it stocks stale, and the receipt says
so too.