jochen
3abb3a3c07
Three wordings disagree, and the confusion is the damage: the glossary defines artifact as an OCI image while the build vocabulary already names four kinds in use, two of which are not images; the image registry's seat is named after its job while ADR 0079 names foundation seats after their servers and ADR 0109 names package seats after their ecosystem; and prose that says 'the module's image' reads as though a module were an image. Records the question the naming hides: ADR 0075 keeps two provisions because packages and images are two protocols, and already allows the forge to provide the artifact store. The second implementation rests on a bootstrap argument, and the forge has the same upstream-server shape the store and broker have, which ADR 0078 raises as plumbing and adopts in place.
4.9 KiB
status, opened, located-in, fixed-by, amended-design
| status | opened | located-in | fixed-by | amended-design | ||||
|---|---|---|---|---|---|---|---|---|
| located | 2026-09-26 |
|
123 — The image registry is named after a role, and artifact is defined as one format
What was observed
Reading the registry work back to the operator on 2026-09-26, three wordings turned out to disagree with each other, and the disagreement was doing real damage: a reader — including whoever writes the next module — cannot tell what the mesh's image registry is for from what it is called.
One: the word for a delivered thing is defined as one format. The glossary says artifact is
"what the mesh delivers to a machine to install and run: an OCI image, by digest", served by the
artifact-store. But a module definition's own build vocabulary already names four kinds of artifact,
all in use in the catalogue today — image (48 of them), upstream (3), bundle (1), archive (1) —
and the controller's manifest code documents the field as "image or archive". So the catalogue builds
artifacts that are not images, while the word for them means image, and the store named after the word
serves images only.
Two: the seat is named after a role, and every other one is not. ADR 0079
names the foundation seats after their servers — the store, the broker. ADR 0109
settled that a package registry seat is one per ecosystem, not one for all of them, which is why
there is now a seat for one language's packages and another for git. The image registry's seat is
the-artifact-store: named after neither its server nor what it serves. It is the last registry named
after the job it happens to be doing.
Three: a module is not an image. An image is one thing a module may install or build; a module may also ship archives, files, directories, databases and a service it did not build at all. Prose that calls a built image "the module's image" reads as though a module were an image, and the manifest's own vocabulary does not: it says artifacts, each with a kind.
Why it matters
The cost is confusion, in the place where the mesh explains itself. Two people reading
artifact-store will reasonably take it for two different things — "where OCI images live" and "where
everything a module delivers lives" — and those stop being the same thing the moment a module delivers
an archive, which one already does.
It also hides a question that ought to be asked plainly. Because the store is named after a role, a
reader assumes the role needs its own implementation. What the records actually say is narrower:
ADR 0075 keeps two provisions because
packages and images are two protocols — a language's client cannot install from an OCI registry — and
it already allows the forge to provide artifact-store too, saying a mesh may choose it. The
reason the OCI registry is a second implementation is a bootstrap argument: something must serve images
before the mesh can build anything.
That bootstrap argument is weaker than it reads. The forge's server is an upstream public image; only its runtime sidecar is built (issue 121, where the opposite was claimed and retracted). The store and the broker have the same shape, and ADR 0078 raises both at genesis as plumbing and adopts them in place as ordinary modules. The forge can be raised that way too, which would leave the question of a second registry implementation resting on the window before it is adopted, rather than on protocols.
Open questions
- Should the seat and the provision be named after what they serve — an OCI registry, images by digest — leaving artifact free to mean what the build vocabulary already means by it: anything a module produces, of any kind?
- Does the mesh need two registry implementations at all, or can the forge hold every registry seat once it is adopted in place? The protocol argument keeps two provisions; it does not by itself require two servers.
- If a window before adoption is the only reason for the second one, is that window a seat, or a step in genesis that ends?
- Renaming touches the glossary, two records, the seat set, the builder's requirement and every image reference in the catalogue. Which of those can be checked mechanically, so the rename is not a prose exercise that leaves the code disagreeing?
- What check would keep the glossary honest — a definition tested against the kinds a definition may actually declare, rather than restated by hand?