hq/04-ISSUES/123-the-image-registry-is-named-after-a-role/00-report.md

status, opened, located-in, fixed-by, amended-design

status	opened	located-in	fixed-by	amended-design
resolved	2026-09-26	hq 00-META/glossary.md hq 02-DECISIONS/0075-two-stores-and-which-provides-what.md mesh-controller internal/catalogue/seats.go mesh-catalog modules/distribution	ADR 0156; mesh-controller migration 0048 (feat/the-artifact-store-seat-is-named-for-its-scope); mesh-catalog modules/distribution	03-DESIGN/01-to-be/26-the-seats.md

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?

Resolved, 2026-09-30

Read from what the store serves rather than from what it was called: both shapes of a kept reference — an image and an archive's blob — go to the same registry by digest, which is exactly the provision ADR 0075 defined. So the word was wrong and the seat's name was odd, and the provision was right. ADR 0156: artifact means what a build produces, of any of the four kinds; the seat is mesh-artifact-store with the old name as its alias (one migration, ADR 0122's mechanism); the provision keeps its name. The two-implementations question stays as 0075 answered it, with the day to retire the second server named. The mechanical check the report asked for is the alias test and the glossary naming the same four kinds as design 18's table.