ADR 0096: an upstream image is copied between registries; issue 046 resolved; design 18 amended

03-DESIGN/01-to-be/18-building-a-module.md

@@ -7,6 +7,7 @@ code:
   - mesh-catalog modules/builder
 updated: 2026-09-21
 decisions:
+  - 02-DECISIONS/0096-an-upstream-image-is-copied-between-registries.md
   - 02-DECISIONS/0091-a-mount-is-declared-three-ways.md
   - 02-DECISIONS/0087-a-seeded-file-is-created-once.md
   - 02-DECISIONS/0040-what-a-module-is.md
@@ -202,6 +203,18 @@ remedies, and a test parses every manifest in the catalogue beside the checkout.
 | `image` | built from a Dockerfile — for software that needs a particular base |
 | `upstream` | somebody else's image, mirrored and pinned by a digest this mesh assigned |
 
+**An upstream image is copied between registries, never through a machine's image store**
+([ADR 0096](../../02-DECISIONS/0096-an-upstream-image-is-copied-between-registries.md)). A
+published image is an index over several architectures, and a runtime's store refuses to push
+one platform out of an index it pulled. The builder reads the index and every manifest it names
+over the registry API, moves each blob by digest into the mesh's registry, puts the manifests and
+then the index under the module's repository, and pins the index — the whole image, so what a
+machine fetches is the one for its own architecture. Public images are read with the anonymous
+token a registry hands out on challenge; a private upstream is refused. *How it is checked:* a
+test copies an index over two platforms from a fake registry behind a bearer challenge into a fake
+mesh registry and asserts every blob arrived once, the manifests and index under their digests,
+and nothing uploaded on a second copy.
+
 ### What it puts on a machine
 
 | resource | is | a module may |