jschoubben
5dcb9dfbf6
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).
70 lines
3.6 KiB
Markdown
70 lines
3.6 KiB
Markdown
---
|
|
topic: checking it
|
|
status: accepted
|
|
date: 2026-09-21
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 02-DECISIONS/0016-the-lab.md
|
|
---
|
|
|
|
# 89. A bed reads the catalogue it proves
|
|
|
|
## Context
|
|
|
|
A lab bed installs a catalogue module and asserts what the mesh does with it; "proven in the
|
|
lab" is the standard a module must meet before it ships. The beds built the manifests they
|
|
install inline — a literal copied from the catalogue when each bed was written, and never since.
|
|
Six modules were converted to file-delivered secrets ([ADR 0086](0086-a-secret-reaches-a-process-as-a-file.md))
|
|
and not one bed ran the converted shape; each ran its copy, and the copies still delivered
|
|
secrets the way the catalogue engine now refuses
|
|
([issue 073](../04-ISSUES/073-beds-carry-copies-of-catalogue-manifests/00-report.md)). A run's
|
|
receipt named the commits of the host, the controller and the lab, and said nothing about the
|
|
catalogue, so a catalogue change and a proven catalogue change were indistinguishable.
|
|
|
|
The end-to-end design already has the rule this breaks — *the run rebuilds what it tests; an
|
|
artifact rebuilt from memory is one rebuilt sometimes* — for binaries and images. A manifest is
|
|
an artifact too.
|
|
|
|
## Considered Options
|
|
|
|
1. **Keep the copies and check them against the catalogue** — a test that diffs each literal
|
|
against the module's manifest, ignoring what the lab must rewrite. Rejected: it keeps two
|
|
sources of truth and adds a third thing that can drift, the list of what to ignore.
|
|
2. **Read the catalogue, rewriting only what the lab must.** Adopted.
|
|
|
|
## Decision
|
|
|
|
A bed that installs a catalogue module reads that module's manifest from the catalogue checkout
|
|
the run was pointed at. It may rewrite what the lab must and nothing else: a build artifact
|
|
becomes the image the machine holds, an image is pinned to what the machine holds, a host port
|
|
is remapped where one machine carries colliding modules, and an address may point at a stand-in
|
|
the bed raises in place of an upstream. Everything else is the catalogue's, verbatim.
|
|
|
|
A bed that needs less than the catalogue declares — no upstream server, a secret in the
|
|
environment, a requirement edge removed — is not testing that module. It is a mesh test, and it
|
|
carries a name of its own (see [issue 074](../04-ISSUES/074-a-mesh-test-wears-a-catalogue-modules-name/00-report.md)).
|
|
|
|
The run's receipt names the catalogue's commit alongside the other repositories', so a receipt
|
|
taken before a manifest changed says so.
|
|
|
|
## Consequences
|
|
|
|
A catalogue change is proven by the beds that install the module, or it is not proven, and the
|
|
receipt says which. What got harder: a bed can no longer trim a module to the shape it finds
|
|
convenient; it meets the module's declared requirements or gives its fixture another name.
|
|
The beds that still carry a copy are declared, each with its reason, and the declared list
|
|
only shrinks.
|
|
|
|
## How it is checked
|
|
|
|
A unit test in the lab refuses an inline manifest literal that names a catalogue module unless
|
|
the bed is declared, with its reason, in the test's own list; a declaration for a bed that no
|
|
longer carries the copy is refused too, so the list cannot outlive the debt. The receipt test
|
|
asserts the catalogue is claimed whenever the run is pointed at one.
|
|
|
|
## References
|
|
|
|
- [issue 073](../04-ISSUES/073-beds-carry-copies-of-catalogue-manifests/00-report.md), [issue 074](../04-ISSUES/074-a-mesh-test-wears-a-catalogue-modules-name/00-report.md)
|
|
- [ADR 0016](0016-the-lab.md), [ADR 0086](0086-a-secret-reaches-a-process-as-a-file.md)
|
|
- [`03-DESIGN/01-to-be/01-end-to-end-testing.md`](../03-DESIGN/01-to-be/01-end-to-end-testing.md)
|