ADR 0046 — the installer fetches what it pins

The blocking question was where a container image comes from, and the version
that blocked assumed the machine might have no network. That assumption came
from the LAB: a scenario is a closed address space by design, which is what lets
two scenarios hold the same addresses without meeting. Production is not sealed
— a machine being adopted has a network, and one that does not is a machine
where very little works anyway.

So substrate.lock carries references, not payload: an image name and a digest,
fetched at apply time. A first node pulls from upstream because no mesh registry
exists yet; every node after that pulls from the mesh's own. The lab is the
exception and places images itself, the way it already places the host binary —
a property of a test environment, and letting it dictate the production design
would be the tail wagging the dog.

Pinned by DIGEST rather than tag. Reproducibility comes from pinning the
identity of a thing, not from carrying its bytes, which is what makes fetching
acceptable rather than a compromise.

ADR 0041 survives untouched, which was the point. "Copy it onto a machine and
run it" stays literally true — one binary, a few megabytes, which then fetches
what it was told to. Carrying images would have quietly redefined the property
that decision rests on.

Costs accepted and named: an apply can now fail because something is
unreachable, which a self-contained artifact could not, so it must fail legibly
— naming what it could not fetch and from where. And the lab needs a way to
place images into a machine that also has no container runtime, both of which
are lab-installation concerns and neither solved here.

Research 012's build-time-versus-apply-time reframing narrows accordingly: it
still holds for what a tailored installer contains, and no longer has to hold
for images.
This commit is contained in:
2026-08-26 23:52:46 +02:00
parent 0531d6fc38
commit 5b3d0ebd4f
3 changed files with 87 additions and 6 deletions
+5 -6
View File
@@ -73,13 +73,12 @@ versions are pinned by hand rather than resolved.
**Why pinned:** the bundle is applied when no mesh exists, so nothing can resolve a version, ask
a registry, or check a constraint. What the host carries must already be exact.
**Why self-contained:** a node raising a first mesh may have no route to anything
([research 012](../../01-RESEARCH/012-the-minimum-viable-node/00-overview.md)). Images and
packages the bundle needs travel *with* it, fetched when the bundle was **built** rather than
when it is applied.
**Why references and not payload:** the bundle names images by **digest** and the host fetches
them ([ADR 0046](../../02-DECISIONS/0046-the-installer-fetches-what-it-pins.md)). A first node is
a real machine with a network; the sealed case is the lab, and the lab places images itself.
**What that makes it:** an artifact built on a machine with a network, for a machine that may
have none — which is the reframing research 012 records, arriving here as a requirement.
Reproducibility comes from pinning the identity of a thing rather than carrying its bytes, which
is what keeps the bundle small enough for a person to read and check.
## Raising it