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