From 0d14120002091be39c7652da8f1bc4c84e32d030 Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Wed, 3 Jun 2026 12:06:27 -0700
Subject: [PATCH 1/8] Pin each release's rust base image by digest.

---
 .github/workflows/build.yml                   |  12 +-
 .github/workflows/publish.yml                 |   1 +
 README.md                                     |  27 ++-
 RELEASE.md                                    |  38 ++--
 builds.json                                   |  16 +-
 builds.schema.json                            |  29 +--
 scripts/build_image.py                        |  14 +-
 scripts/lib/builds.py                         |  45 +++--
 scripts/publish_aliases.py                    |   4 +-
 scripts/publish_manifests.py                  |  13 +-
 scripts/refresh.py                            | 161 ++++++++++++++++
 scripts/refresh_rust_digests.py               |  71 -------
 scripts/refresh_stellar_cli_digests.py        |  74 --------
 scripts/release_pr_body.py                    |   6 +-
 scripts/release_prepare.py                    | 120 ++----------
 scripts/resolve_matrix.py                     |   8 +-
 scripts/tag_names.py                          |  36 +++-
 scripts/validate_json.py                      |  21 +-
 ...npinned.json => builds_invalid_entry.json} |   6 +-
 tests/fixtures/builds_minimal.json            |   5 +-
 tests/fixtures/builds_multi_cli.json          |  11 +-
 tests/fixtures/builds_orphan_rust.json        |  17 --
 tests/fixtures/builds_unpinned_refs.json      |   9 +-
 tests/fixtures/builds_unsorted_keys.json      |   3 +-
 tests/integration/test_refresh.py             | 179 ++++++++++++++++++
 .../integration/test_refresh_rust_digests.py  |  94 ---------
 .../test_refresh_stellar_cli_digests.py       | 105 ----------
 tests/integration/test_release_prepare.py     | 125 ++++--------
 tests/unit/test_build_image.py                |  18 +-
 tests/unit/test_builds.py                     |  49 ++++-
 tests/unit/test_newest_pair.py                |   4 +-
 tests/unit/test_publish_aliases.py            |   8 +-
 tests/unit/test_publish_manifests.py          |   9 +-
 tests/unit/test_tag_names.py                  |  72 +++++--
 tests/unit/test_validate_json.py              |  47 +++--
 35 files changed, 696 insertions(+), 761 deletions(-)
 create mode 100644 scripts/refresh.py
 delete mode 100755 scripts/refresh_rust_digests.py
 delete mode 100755 scripts/refresh_stellar_cli_digests.py
 rename tests/fixtures/{builds_unpinned.json => builds_invalid_entry.json} (51%)
 delete mode 100644 tests/fixtures/builds_orphan_rust.json
 create mode 100644 tests/integration/test_refresh.py
 delete mode 100644 tests/integration/test_refresh_rust_digests.py
 delete mode 100644 tests/integration/test_refresh_stellar_cli_digests.py

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 2a2dcc5..0fc9927 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -29,19 +29,25 @@ jobs:
         id: pair
         run: |
           cli="$(./scripts/newest_pair.py --stellar-cli-version)"
-          rust="$(./scripts/newest_pair.py --rust-version)"
+          # The newest pair is a fully-qualified pin: <label>@sha256:<digest>.
+          pin="$(./scripts/newest_pair.py --rust-version)"
+          rust="${pin%@*}"
+          digest="${pin#*@}"
           tag="$(./scripts/tag_names.py \
-            --stellar-cli-version "$cli" --rust-version "$rust")"
+            --stellar-cli-version "$cli" --rust-version "$rust" \
+            --rust-image-digest "$digest")"
           {
             echo "cli=$cli"
             echo "rust=$rust"
+            echo "digest=$digest"
             echo "image=stellar-cli:$tag"
           } >> "$GITHUB_OUTPUT"
       - name: build image
         run: |
           ./scripts/build_image.py \
             --stellar-cli-version "${{ steps.pair.outputs.cli }}" \
-            --rust-version "${{ steps.pair.outputs.rust }}"
+            --rust-version "${{ steps.pair.outputs.rust }}" \
+            --rust-image-digest "${{ steps.pair.outputs.digest }}"
       - name: smoke test
         run: |
           ./scripts/smoke_test_image.py \
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index dd860b2..18f978c 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -80,6 +80,7 @@ jobs:
           tag="$(./scripts/tag_names.py \
             --stellar-cli-version ${{ matrix.stellar_cli_version }} \
             --rust-version ${{ matrix.rust_base_key }} \
+            --rust-image-digest ${{ matrix.rust_image_digest }} \
             --platform ${{ matrix.platform }} \
             --stellar-cli-ref ${{ matrix.stellar_cli_ref }})"
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
diff --git a/README.md b/README.md
index 1d2f961..d30ac21 100644
--- a/README.md
+++ b/README.md
@@ -73,7 +73,7 @@ multi-arch manifest list digest:
 ```sh
 # Find the per-arch digest for the architecture you used to build.
 # Pick any of the immutable manifest-list tags from the release notes,
-# e.g. :26.0.0-<ref>-rust1.94.0-slim-trixie, or the :26.0.0 alias:
+# e.g. :26.0.0-<ref15>-rust1.94.0-slim-trixie-<digest15>, or the :26.0.0 alias:
 docker buildx imagetools inspect docker.io/stellar/stellar-cli:26.0.0
 ```
 
@@ -89,9 +89,8 @@ compare the resulting WASM sha256.
 | `builds.json`                            | Source of truth for which (stellar-cli, rust base key) pairs we publish.                                                                                                                          |
 | `builds.schema.json`                     | JSON Schema for `builds.json`.                                                                                                                                                                    |
 | `scripts/build_image.py`                 | Local single-image build.                                                                                                                                                                         |
-| `scripts/validate_json.py`               | Validates every `*.json` for sorted keys and `builds.json` for schema + cross-field constraints.                                                                                                  |
-| `scripts/refresh_rust_digests.py`        | Fills blank `rust_image_digests` entries by inspecting `rust:<key>` upstream (where `<key>` is the composite `<rust>-<suffix>` form). Does not touch already-pinned digests unless asked per-key. |
-| `scripts/refresh_stellar_cli_digests.py` | Fills blank `stellar_cli_versions[].ref` entries by resolving the matching `v<version>` git tag in `stellar/stellar-cli`. Same per-target opt-in shape as the rust refresher.                     |
+| `scripts/validate_json.py`               | Validates every `*.json` for sorted keys and `builds.json` against the schema.                                                                                                                    |
+| `scripts/refresh.py`                     | For one `--stellar-cli-version`: picks the rust base labels, resolves the upstream cli ref and each base's index digest, and appends the fully-qualified pins `<label>@<digest>` (append-only; already-published pins are retained). |
 | `scripts/verify_image.py`                | Consumer-facing verifier. Wraps `gh attestation verify` for both the SLSA build provenance and the SPDX SBOM attestations against a per-arch image digest.                                        |
 | `scripts/lib/`                           | Shared Python helpers imported by the other scripts (builds.json IO, semver/key parsing, subprocess + adapter wrappers).                                                                          |
 
@@ -101,18 +100,18 @@ compare the resulting WASM sha256.
 # Validate builds.json.
 ./scripts/validate_json.py
 
-# Build a local image for a declared (cli, rust base) pair.
-./scripts/build_image.py --stellar-cli-version 26.0.0 --rust-version 1.94.0-slim-trixie
+# Build a local image for a declared (cli, rust base) pair. The rust base is
+# given as the label plus its pinned digest (copy the pin from builds.json).
+./scripts/build_image.py --stellar-cli-version 26.0.0 \
+  --rust-version 1.94.0-slim-trixie \
+  --rust-image-digest sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0
 
-# Smoke-test the built image.
-docker run --rm stellar-cli:26.0.0-rust1.94.0-slim-trixie --version
-docker run --rm stellar-cli:26.0.0-rust1.94.0-slim-trixie contract build --help
+# Smoke-test the built image (the tag carries the short base-digest fragment).
+docker run --rm stellar-cli:26.0.0-rust1.94.0-slim-trixie-f7bf1c266d9e48c --version
+docker run --rm stellar-cli:26.0.0-rust1.94.0-slim-trixie-f7bf1c266d9e48c contract build --help
 
-# Resolve blank rust base image digests (maintainer task).
-./scripts/refresh_rust_digests.py --dry-run
-
-# Resolve blank stellar-cli refs from upstream git tags (maintainer task).
-./scripts/refresh_stellar_cli_digests.py --dry-run
+# Resolve + append rust base pins and the cli ref for a version (maintainer task).
+./scripts/refresh.py --stellar-cli-version 26.1.0 --dry-run
 ```
 
 Requirements: `docker` (with `buildx`) and [`uv`](https://docs.astral.sh/uv/).
diff --git a/RELEASE.md b/RELEASE.md
index 4884ae1..f2ec484 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -6,9 +6,9 @@ This document covers the maintainer side of `stellar/stellar-cli-docker` — how
 
 Each release publishes to `docker.io/stellar/stellar-cli`:
 
-- **Per-architecture images** — `:<cli>-<ref>-rust<rust>-amd64` and `:<cli>-<ref>-rust<rust>-arm64`, where `<ref>` is the upstream `stellar/stellar-cli` git SHA the image was built from. Each one is a single-architecture manifest with its own SHA-256 digest; this is the form a consumer cites in a SEP-58 `bldimg` field.
-- **Multi-arch manifest list** per `(cli, rust)` pair — `:<cli>-<ref>-rust<rust>` resolves to the right per-arch image at pull time.
-- **Moving tags** — `:<cli>` points at the manifest list for that cli paired with the highest `rust_versions[]` key matching the top-level `default_distro`. `:latest` points at the same derivation for the newest declared cli. **Moving tags must never be used in `bldimg`** — they re-point on every publish.
+- **Per-architecture images** — `:<cli>-<ref15>-rust<rust>-<digest15>-amd64` and `…-arm64`, where `<ref15>` is the first 15 hex chars of the upstream `stellar/stellar-cli` git SHA the image was built from, and `<digest15>` is the first 15 hex chars of the rust base image's index digest. Each one is a single-architecture manifest with its own SHA-256 digest; this is the form a consumer cites in a SEP-58 `bldimg` field.
+- **Multi-arch manifest list** per `(cli, rust base, base digest)` pin — `:<cli>-<ref15>-rust<rust>-<digest15>` resolves to the right per-arch image at pull time.
+- **Moving tags** — `:<cli>` points at the manifest list for that cli paired with the default rust base (highest `rust_versions[]` pin whose label matches the top-level `default_distro`, newest digest wins on a tie). `:latest` points at the same derivation for the newest declared cli. **Moving tags must never be used in `bldimg`** — they re-point on every publish.
 - **Two attestation chains** — buildx-native (SLSA build provenance + SPDX SBOM attached in the registry alongside the image) and GitHub-native (the same predicates signed and stored in the repo's attestation store, verifiable via `gh attestation verify`).
 - **A GitHub Release** for every publish run, with per-architecture digests in the body and the SBOM + provenance files attached as downloadable assets. The release is created by a maintainer following the link in the release PR (see [Releasing](#releasing--new-cli-version-or-refreshing-an-existing-one) below); publishing it triggers the workflow that enriches the release with the images' digests and supply-chain artifacts.
 
@@ -58,7 +58,7 @@ Every release gets a unique tag. Tags are never reused or updated in place.
 
 The `release` workflow picks the next available tag automatically by looking at existing releases. Each release page is the snapshot of `builds.json` at that iteration; the historical `v26.0.0` page stays intact when `v26.0.0-1` is later published.
 
-Docker image tags (`:<cli>-<ref>-rust<key>[-<arch>]`) are unaffected by the `-N` suffix — they remain pinned forever based on the cli + ref + rust base key + arch. Moving tags (`:<cli>`, `:latest`) re-point on every publish, regardless of which iteration.
+Docker image tags (`:<cli>-<ref15>-rust<key>-<digest15>[-<arch>]`) are unaffected by the `-N` suffix — they remain pinned forever based on the cli + ref + rust base key + base image digest + arch. Because the base digest is part of the tag, rebuilding the same cli + ref against a freshly-rebuilt base produces a *new* tag rather than mutating an existing one. Moving tags (`:<cli>`, `:latest`) re-point on every publish, regardless of which iteration.
 
 ## Releasing — new cli version, or refreshing an existing one
 
@@ -68,7 +68,7 @@ Same workflow for both. PR review is the gate; a GitHub Release is the publish t
 
    - Detects whether this is a **new release** (cli not yet declared) or a **refresh** (cli exists in `builds.json`).
    - Picks the last two minor stable rust versions, at their latest patch each, from Docker Hub's `library/rust` tag list, filtered by the `slim-<default_distro>` suffix.
-   - Updates `builds.json`: adds a new entry, or **appends** the picker output (deduped, numerically sorted) to the existing entry's `rust_versions[]`. Resolves the upstream cli commit SHA and any missing rust image digests.
+   - Updates `builds.json`: adds a new entry, or **appends** to the existing entry's `rust_versions[]`. For each picked rust base it resolves the upstream cli commit SHA and the base's current index digest, then appends the fully-qualified pin `<label>@sha256:<digest>` — deduped on the full pin (a rebuilt base, i.e. same label with a new digest, is a new pin) and numerically sorted.
    - Validates the result.
    - Picks the next available release tag — `v<version>` for a fresh release, `v<version>-<N>` for a refresh.
    - Pushes a `release/<tag>` branch and opens a PR with a body modeled on stellar-cli's release PRs, including a pre-filled link to create the GitHub Release on merge.
@@ -103,10 +103,13 @@ The script prints the chosen release tag as its final stdout line. Commit and pu
 
 ```sh
 ./scripts/validate_json.py
-./scripts/build_image.py --stellar-cli-version 26.1.0 --rust-version 1.95.0-slim-trixie
-./scripts/smoke_test_image.py --image stellar-cli:26.1.0-rust1.95.0-slim-trixie \
+# Use the label + digest from the pin in builds.json. The built tag carries the
+# short digest fragment, e.g. stellar-cli:26.1.0-rust1.95.0-slim-trixie-e14e87345b4d596.
+./scripts/build_image.py --stellar-cli-version 26.1.0 --rust-version 1.95.0-slim-trixie \
+  --rust-image-digest sha256:e14e87345b4d5964ddcc3491d27ee046a0f23820f340c3c1e24da6880141f7c0
+./scripts/smoke_test_image.py --image stellar-cli:26.1.0-rust1.95.0-slim-trixie-e14e87345b4d596 \
   --stellar-cli-version 26.1.0 --rust-version 1.95.0-slim-trixie
-./scripts/repro_test.py --image stellar-cli:26.1.0-rust1.95.0-slim-trixie
+./scripts/repro_test.py --image stellar-cli:26.1.0-rust1.95.0-slim-trixie-e14e87345b4d596
 ```
 
 The smoke test confirms the binary reports the expected version and the labels are correct. The repro test confirms `stellar contract build --locked` produces byte-identical WASM across two clean builds. CI does the same against the freshly-built image on every PR push.
@@ -119,14 +122,14 @@ Triggered exclusively by the `release: published` event — when a maintainer cl
 | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `matrix`         | Validates `builds.json`, derives the cli version (from the release's tag name or the dispatch input), then runs `scripts/resolve_matrix.py --stellar-cli-version <v>` to produce a matrix of `(rust base key, arch)` rows for that one cli.                                                                                                                                                                                                                                                                              |
 | `build` (matrix) | Native runner per arch (`ubuntu-24.04` for amd64, `ubuntu-24.04-arm` for arm64). Checks if the per-arch tag exists in the registry: **already-published pairs are skipped with a ⚠️ warning**; only their metadata (digest from the registry) is uploaded as an artifact. Fresh pairs build + push via `docker/build-push-action` with `provenance: mode=max` and `sbom: true`, then attest with `actions/attest-build-provenance` and `actions/attest-sbom`. Either way, the workflow artifacts feed the `release` job. |
-| `manifest`       | Assembles the ref-pinned multi-arch manifest list `:<cli>-<ref>-rust<key>` per rust base key. Existing lists are skipped with a ⚠️ warning; new ones are created via `docker buildx imagetools create`.                                                                                                                                                                                                                                                                                                                  |
-| `aliases`        | Re-points `:<cli>` to the manifest list of `(cli, highest rust_versions[] key matching default_distro)`. If this cli is the newest declared, also re-points `:latest`. Both tags are intentionally moving; the job fails loudly if no `rust_versions[]` key matches `default_distro`.                                                                                                                                                                                                                                    |
+| `manifest`       | Assembles the ref-pinned multi-arch manifest list `:<cli>-<ref15>-rust<key>-<digest15>` per rust base pin. Existing lists are skipped with a ⚠️ warning; new ones are created via `docker buildx imagetools create`.                                                                                                                                                                                                                                                                                                     |
+| `aliases`        | Re-points `:<cli>` to the manifest list of `(cli, default rust pin)` — the highest `rust_versions[]` pin whose label matches `default_distro`, newest digest winning a tie. If this cli is the newest declared, also re-points `:latest`. Both tags are intentionally moving; the job fails loudly if no `rust_versions[]` pin matches `default_distro`.                                                                                                                                                                  |
 | `release`        | Downloads every per-arch metadata + (when present) SBOM/provenance artifact, calls `scripts/release_body.py` to compose a structural body section, then **appends** that section to the just-created release body and attaches the SBOM + provenance files for freshly-built pairs as release assets. Any human-written notes already in the release body are preserved.                                                                                                                                                 |
 | `complete`       | Branch-protection aggregator. Fails if any upstream job failed or was cancelled.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 ## Tag immutability and restarts
 
-Per-architecture tags (`:<cli>-<ref>-rust<key>-<arch>`) and per-pair manifest lists (`:<cli>-<ref>-rust<key>`) on Docker Hub are **immutable**. When the publish workflow sees an existing tag, it skips that row with a ⚠️ warning surfaced in the run's Annotations panel and step summary — never overwrites. There is no force flag and no workflow input to override this.
+Per-architecture tags (`:<cli>-<ref15>-rust<key>-<digest15>-<arch>`) and per-pin manifest lists (`:<cli>-<ref15>-rust<key>-<digest15>`) on Docker Hub are **immutable**. Because the base image digest is encoded in the tag (as `<digest15>`), a rebuilt base never collides with an existing tag — it resolves to a new one — so the immutability promise holds without any in-place overwrite. When the publish workflow sees an existing tag, it skips that row with a ⚠️ warning surfaced in the run's Annotations panel and step summary — never overwrites. There is no force flag and no workflow input to override this.
 
 Moving aliases (`:<cli>`, `:latest`) are exempt; they're documented as moving and re-pointed each release.
 
@@ -142,7 +145,7 @@ The Rust base image carries two choices we make deliberately: the **variant** (`
 
 **Debian codename — track the latest Ubuntu LTS upstream.** Each Ubuntu LTS is based on a Debian release. We default to that Debian. The current latest Ubuntu LTS is 26.04, which is based on Debian 13 (`trixie`), so `trixie` is today's value of `default_distro`. We don't move to the newest Debian release the day it ships — we wait for the next Ubuntu LTS to track it, so users on the prevailing LTS host distro aren't running on a Debian newer than what their host's upstream tracks.
 
-**Tag — include variant + Debian.** The composite rust base key (e.g. `1.94.0-slim-trixie`) flows verbatim into the published image tag: `<cli>-<ref>-rust<key>[-arch]`. When we eventually move off `trixie`, the new images get a new tag suffix and the historical tags stay addressable.
+**Tag — include variant + Debian.** The composite rust base key (e.g. `1.94.0-slim-trixie`) flows verbatim into the published image tag: `<cli>-<ref15>-rust<key>-<digest15>[-arch]`. When we eventually move off `trixie`, the new images get a new tag suffix and the historical tags stay addressable.
 
 ### Switching the default
 
@@ -154,16 +157,17 @@ The Rust base image carries two choices we make deliberately: the **variant** (`
 
 The `Dockerfile`'s `FROM` lines reference the image by digest only; the variant + Debian codename show up in `org.opencontainers.image.base.name` (e.g. `docker.io/library/rust:1.95.0-slim-trixie`) via a build-arg passed from the matrix.
 
-## Bumping a pinned base or ref
+## Adopting a rebuilt base image
 
-Pinned values in `builds.json` are intentional. Bumping them changes the bytes of published images and invalidates anything that already referenced the prior digest, so it's a deliberate action.
+Pins in `builds.json` are append-only and never rewritten in place. To adopt a freshly-rebuilt rust base — e.g. upstream republished `rust:1.94.0-slim-trixie` under a new index digest after a CVE patch — run `refresh` against the cli that should pick it up:
 
 ```sh
-./scripts/refresh_rust_digests.py --rust-version 1.94.0-slim-trixie
-./scripts/refresh_stellar_cli_digests.py --stellar-cli-version 26.1.0
+./scripts/refresh.py --stellar-cli-version 26.1.0 --rust-versions 1.94.0-slim-trixie
 ```
 
-Both target-specific commands skip the blank-only check and re-resolve from upstream. Commit the resulting `builds.json` change and run the release flow as if it were a new release — the immutability guard will refuse to overwrite already-published tags, so you also need to delete those tags from Docker Hub first (or bump the cli version, the cleaner option).
+`refresh` resolves the label's *current* upstream digest and **appends** a new pin `1.94.0-slim-trixie@sha256:<new>` alongside the existing one; the old pin — and its already-published, immutable tag — is left untouched. On publish, only the new pin builds, and it gets its own tag because the base digest is encoded in the tag. There is **no** need to delete anything from Docker Hub, and older cli versions sharing the label are unaffected. Already-published pins skip with a warning.
+
+Commit the resulting `builds.json` change and run the release flow as a refresh iteration (`v<cli>-<N>`). The cli ref itself stays immutable per release; to build against a different upstream commit, declare a new cli version.
 
 ## Verifying a freshly published release
 
diff --git a/builds.json b/builds.json
index 7c446a8..b3ff10e 100644
--- a/builds.json
+++ b/builds.json
@@ -1,33 +1,27 @@
 {
-  "$comment": "Source of truth for which (stellar-cli, rust base) pairs we publish. Each stellar-cli release declares its own rust_versions[] at publish time; we do not cross-product. A rust base key joins the rust toolchain version and the upstream rust:<v>-<suffix> tail (e.g. 1.94.0-slim-trixie); see RELEASE.md '## Base image policy' for how default_distro drives the picker. To refresh a rust_image_digest, capture the multi-arch INDEX digest via: docker buildx imagetools inspect rust:<key> --format '{{.Manifest.Digest}}'.",
+  "$comment": "Source of truth for which (stellar-cli, rust base) pairs we publish. Each stellar-cli release declares its own rust_versions[] at publish time; we do not cross-product. Each entry is a fully-qualified rust base pin '<rust_base_key>@<index-digest>' (e.g. 1.94.0-slim-trixie@sha256:...); see RELEASE.md '## Base image policy' for how default_distro drives the picker. To resolve a base pin's digest, capture the multi-arch INDEX digest via: docker buildx imagetools inspect rust:<key> --format '{{.Manifest.Digest}}'.",
   "$schema": "./builds.schema.json",
   "default_distro": "trixie",
-  "rust_image_digests": {
-    "1.90.0-slim-bookworm": "sha256:64232e656c058f4468e8d024e990acff04f0fd5a5c0a88a574dc37773d7325c9",
-    "1.93.0-slim-trixie": "sha256:760ad1d638d70ebbd0c61e06210e1289cbe45ff6425e3ea6e01241de3e14d08e",
-    "1.94.0-slim-trixie": "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0",
-    "1.95.0-slim-trixie": "sha256:e14e87345b4d5964ddcc3491d27ee046a0f23820f340c3c1e24da6880141f7c0"
-  },
   "stellar_cli_versions": [
     {
       "ref": "a048a57a75762458b487052e0021ea704a926bee",
       "rust_versions": [
-        "1.90.0-slim-bookworm"
+        "1.90.0-slim-bookworm@sha256:64232e656c058f4468e8d024e990acff04f0fd5a5c0a88a574dc37773d7325c9"
       ],
       "version": "25.1.0"
     },
     {
       "ref": "60f7458e7ecffddf2f2d91dc6d0d2db4fab03ecc",
       "rust_versions": [
-        "1.93.0-slim-trixie",
-        "1.94.0-slim-trixie"
+        "1.93.0-slim-trixie@sha256:760ad1d638d70ebbd0c61e06210e1289cbe45ff6425e3ea6e01241de3e14d08e",
+        "1.94.0-slim-trixie@sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
       ],
       "version": "26.0.0"
     },
     {
       "ref": "1228cff8022b804659750b94b315932b0e0f3f6a",
       "rust_versions": [
-        "1.95.0-slim-trixie"
+        "1.95.0-slim-trixie@sha256:e14e87345b4d5964ddcc3491d27ee046a0f23820f340c3c1e24da6880141f7c0"
       ],
       "version": "26.1.0"
     }
diff --git a/builds.schema.json b/builds.schema.json
index a868ca6..cbd8475 100644
--- a/builds.schema.json
+++ b/builds.schema.json
@@ -1,5 +1,5 @@
 {
-  "$comment": "JSON Schema for builds.json. Cross-field constraints that JSON Schema cannot express (rust_versions entries must be keys in rust_image_digests) are enforced by scripts/validate-json.sh.",
+  "$comment": "JSON Schema for builds.json. Each rust_versions[] entry is a fully-qualified rust base pin, '<rust_base_key>@<image_digest>', so a release records the exact base it was built against. The same label may appear with two different digests across (or within) releases; the published tag carries a short digest fragment to keep each immutable.",
   "$id": "https://github.com/stellar/stellar-cli-docker/builds.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "additionalProperties": false,
@@ -9,14 +9,9 @@
       "pattern": "^[0-9a-f]{40}$",
       "type": "string"
     },
-    "image_digest": {
-      "description": "OCI image digest, including the algorithm prefix.",
-      "pattern": "^sha256:[0-9a-f]{64}$",
-      "type": "string"
-    },
-    "rust_base_key": {
-      "description": "Composite key identifying a Rust base image: rust toolchain version followed by the upstream rust:<v>-<suffix> tail (Debian codename, optionally prefixed by `slim-`). Example: 1.94.0-slim-trixie.",
-      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+-[a-z][a-z0-9-]*$",
+    "rust_pin": {
+      "description": "A fully-qualified rust base pin: the composite rust base key (rust toolchain version + upstream rust:<v>-<suffix> tail, e.g. 1.94.0-slim-trixie) joined to the pinned multi-arch index digest with '@'. Example: 1.94.0-slim-trixie@sha256:<64 hex>.",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+-[a-z][a-z0-9-]*@sha256:[0-9a-f]{64}$",
       "type": "string"
     },
     "semver": {
@@ -40,17 +35,6 @@
       ],
       "type": "string"
     },
-    "rust_image_digests": {
-      "additionalProperties": {
-        "$ref": "#/definitions/image_digest"
-      },
-      "description": "Map from rust base key (rust version + Debian codename, joined with a dash) to the pinned multi-arch index digest of the corresponding rust:<key> upstream image.",
-      "minProperties": 1,
-      "propertyNames": {
-        "$ref": "#/definitions/rust_base_key"
-      },
-      "type": "object"
-    },
     "stellar_cli_versions": {
       "description": "Each stellar-cli release we publish images for, with its explicit rust base pairings.",
       "items": {
@@ -61,9 +45,9 @@
             "description": "Upstream stellar/stellar-cli git commit SHA for this release. Source of truth; version is metadata."
           },
           "rust_versions": {
-            "description": "Append-only list of rust base keys this stellar-cli release was ever published against. Refreshes union the picker's output into the existing list; previously-published keys are retained so the file stays consistent with the immutable tags in the registry.",
+            "description": "Append-only list of fully-qualified rust base pins (<rust_base_key>@<image_digest>) this stellar-cli release was ever built against. Refreshes append the picker's freshly-resolved pins; previously-published pins are retained so the file stays consistent with the immutable tags in the registry. The same label may appear more than once with distinct digests (e.g. a rebuilt base) — each pin is its own immutable image.",
             "items": {
-              "$ref": "#/definitions/rust_base_key"
+              "$ref": "#/definitions/rust_pin"
             },
             "minItems": 1,
             "type": "array",
@@ -87,7 +71,6 @@
   },
   "required": [
     "default_distro",
-    "rust_image_digests",
     "stellar_cli_versions"
   ],
   "title": "stellar-cli-docker builds.json",
diff --git a/scripts/build_image.py b/scripts/build_image.py
index 87a8140..209b89d 100755
--- a/scripts/build_image.py
+++ b/scripts/build_image.py
@@ -9,6 +9,7 @@
 import datetime
 import sys
 
+import tag_names
 from lib import builds, common, runner, rust_keys
 
 
@@ -16,6 +17,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
     parser.add_argument("--stellar-cli-version", required=True, metavar="V")
     parser.add_argument("--rust-version", required=True, metavar="KEY")
+    parser.add_argument("--rust-image-digest", required=True, metavar="DIGEST")
     parser.add_argument("--platform", default="", metavar="P")
     parser.add_argument("--tag", default="", metavar="REF")
     parser.add_argument("--source-repo", default="stellar/stellar-cli-docker", metavar="SLUG")
@@ -27,15 +29,21 @@ def main(argv: list[str] | None = None) -> int:
     common.preflight_checks(["buildx"])
 
     data = builds.load()
+    rust_digest = args.rust_image_digest
     try:
-        builds.assert_pair_declared(data, args.stellar_cli_version, args.rust_version)
-        rust_digest = builds.rust_image_digest(data, args.rust_version)
+        builds.assert_pair_declared(
+            data, args.stellar_cli_version, f"{args.rust_version}@{rust_digest}"
+        )
         stellar_ref = builds.stellar_cli_ref(data, args.stellar_cli_version)
         parsed = rust_keys.parse(args.rust_version)
     except ValueError as exc:
         common.die(str(exc))
 
-    tag = args.tag or f"stellar-cli:{args.stellar_cli_version}-rust{args.rust_version}"
+    tag = args.tag or "stellar-cli:" + tag_names.compose_tag(
+        stellar_cli_version=args.stellar_cli_version,
+        rust_version=args.rust_version,
+        rust_image_digest=rust_digest,
+    )
     build_date = datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
 
     common.log(f"building {tag}")
diff --git a/scripts/lib/builds.py b/scripts/lib/builds.py
index 79de429..3d169a6 100644
--- a/scripts/lib/builds.py
+++ b/scripts/lib/builds.py
@@ -51,18 +51,33 @@ def stellar_cli_ref(data: dict[str, Any], version: str) -> str:
     return entry["ref"]
 
 
-def rust_image_digest(data: dict[str, Any], rust_key: str) -> str:
-    digest = data.get("rust_image_digests", {}).get(rust_key)
-    if not digest:
-        raise ValueError(f"no rust_image_digests entry for rust base key: {rust_key}")
-    return digest
+def split_entry(pin: str) -> tuple[str, str]:
+    """Split a rust base pin into its (label, digest) parts.
 
+    A pin is `<rust_base_key>@<image_digest>`, e.g.
+    `1.94.0-slim-trixie@sha256:<64 hex>`. The label drives the upstream
+    `rust:<label>` base and the published tag's `rust<label>` segment;
+    the digest pins the exact base bytes.
+    """
+    label, sep, digest = pin.partition("@")
+    if not sep or not digest:
+        raise ValueError(f"invalid rust base pin (expected <label>@<digest>): {pin}")
+    return label, digest
 
-def assert_pair_declared(data: dict[str, Any], cli: str, rust_key: str) -> None:
+
+def label_of(pin: str) -> str:
+    return split_entry(pin)[0]
+
+
+def digest_of(pin: str) -> str:
+    return split_entry(pin)[1]
+
+
+def assert_pair_declared(data: dict[str, Any], cli: str, rust_pin: str) -> None:
     entry = find_cli(data, cli)
-    if entry is None or rust_key not in entry.get("rust_versions", []):
+    if entry is None or rust_pin not in entry.get("rust_versions", []):
         raise ValueError(
-            f"stellar-cli {cli} is not declared with rust base key {rust_key} in builds.json"
+            f"stellar-cli {cli} is not declared with rust base pin {rust_pin} in builds.json"
         )
 
 
@@ -74,11 +89,17 @@ def derive_default_rust(data: dict[str, Any], cli: str) -> str:
     entry = find_cli(data, cli)
     if entry is None:
         raise ValueError(f"unknown stellar-cli version: {cli}")
-    matches = [k for k in entry.get("rust_versions", []) if k.endswith(f"-{suffix}")]
+    matches = [
+        (semver.parse(rust_keys.version_of(label_of(pin))), idx, pin)
+        for idx, pin in enumerate(entry.get("rust_versions", []))
+        if label_of(pin).endswith(f"-{suffix}")
+    ]
     if not matches:
         raise ValueError(
-            f"no rust_versions[] key matches default_distro {distro!r} "
+            f"no rust_versions[] pin matches default_distro {distro!r} "
             f"(suffix {suffix!r}) for stellar-cli {cli}"
         )
-    matches.sort(key=lambda k: semver.parse(rust_keys.version_of(k)))
-    return matches[-1]
+    # Highest rust version wins; among equal versions (a relabelled base), the
+    # last-appended pin — the freshest digest — wins.
+    matches.sort(key=lambda t: (t[0], t[1]))
+    return matches[-1][2]
diff --git a/scripts/publish_aliases.py b/scripts/publish_aliases.py
index c06749c..73590a2 100755
--- a/scripts/publish_aliases.py
+++ b/scripts/publish_aliases.py
@@ -41,7 +41,8 @@ def main(argv: list[str] | None = None) -> int:
 
     data = builds.load()
     try:
-        default_rust = builds.derive_default_rust(data, args.stellar_cli_version)
+        default_pin = builds.derive_default_rust(data, args.stellar_cli_version)
+        default_rust, default_digest = builds.split_entry(default_pin)
         stellar_ref = builds.stellar_cli_ref(data, args.stellar_cli_version)
     except ValueError as exc:
         common.die(str(exc))
@@ -49,6 +50,7 @@ def main(argv: list[str] | None = None) -> int:
     target_tag = tag_names.compose_tag(
         stellar_cli_version=args.stellar_cli_version,
         rust_version=default_rust,
+        rust_image_digest=default_digest,
         stellar_cli_ref=stellar_ref,
     )
     target = f"{args.registry}:{target_tag}"
diff --git a/scripts/publish_manifests.py b/scripts/publish_manifests.py
index e061002..a203848 100755
--- a/scripts/publish_manifests.py
+++ b/scripts/publish_manifests.py
@@ -15,20 +15,25 @@
 
 
 def manifest_for_pair(
-    *, registry: str, cli: str, rust_key: str, stellar_ref: str
+    *, registry: str, cli: str, rust_key: str, rust_image_digest: str, stellar_ref: str
 ) -> tuple[str, str, str]:
     list_tag = tag_names.compose_tag(
-        stellar_cli_version=cli, rust_version=rust_key, stellar_cli_ref=stellar_ref
+        stellar_cli_version=cli,
+        rust_version=rust_key,
+        rust_image_digest=rust_image_digest,
+        stellar_cli_ref=stellar_ref,
     )
     amd64_tag = tag_names.compose_tag(
         stellar_cli_version=cli,
         rust_version=rust_key,
+        rust_image_digest=rust_image_digest,
         stellar_cli_ref=stellar_ref,
         platform="linux/amd64",
     )
     arm64_tag = tag_names.compose_tag(
         stellar_cli_version=cli,
         rust_version=rust_key,
+        rust_image_digest=rust_image_digest,
         stellar_cli_ref=stellar_ref,
         platform="linux/arm64",
     )
@@ -61,11 +66,13 @@ def main(argv: list[str] | None = None) -> int:
         common.die(f"no stellar_cli_versions entry for {args.stellar_cli_version}")
     stellar_ref = entry["ref"]
 
-    for rust_key in entry["rust_versions"]:
+    for pin in entry["rust_versions"]:
+        rust_key, rust_image_digest = builds.split_entry(pin)
         list_ref, amd64_ref, arm64_ref = manifest_for_pair(
             registry=args.registry,
             cli=args.stellar_cli_version,
             rust_key=rust_key,
+            rust_image_digest=rust_image_digest,
             stellar_ref=stellar_ref,
         )
 
diff --git a/scripts/refresh.py b/scripts/refresh.py
new file mode 100644
index 0000000..252c278
--- /dev/null
+++ b/scripts/refresh.py
@@ -0,0 +1,161 @@
+#!/usr/bin/env -S uv run python
+"""Resolve and append rust base pins (and the cli ref) for one stellar-cli version.
+
+For the given `--stellar-cli-version`:
+
+  1. Pick the rust base labels to pair against — either `--rust-versions`
+     (a CSV of labels) or, by default, the last two minor `slim-<distro>`
+     tags published on Docker Hub.
+  2. Resolve the upstream stellar-cli git ref (only when it's blank, or for a
+     brand-new entry) so previously-published refs stay pinned.
+  3. Resolve each label's current upstream multi-arch index digest and append
+     the fully-qualified pin `<label>@<digest>` to the entry — but only when
+     that exact pin isn't already present.
+
+Appending (never rewriting) keeps already-published pins immutable: a rebuilt
+base shows up as the same label with a fresh digest, i.e. a new pin, while the
+old pin — and its immutable image tag — is retained. All log output goes to
+stderr.
+"""
+
+import argparse
+import re
+import sys
+from collections.abc import Iterable
+
+from lib import builds, common, docker_inspect, git_remote, runner, rust_keys, semver
+
+STELLAR_CLI_REPO = "https://github.com/stellar/stellar-cli.git"
+
+_PINNED_REF = re.compile(r"^[0-9a-f]{40}$")
+
+
+def current_rust_base_suffix(data: dict) -> str:
+    distro = data.get("default_distro") or ""
+    if not distro:
+        raise ValueError("builds.json is missing default_distro")
+    return f"slim-{distro}"
+
+
+def pick_default_rust_base_keys(suffix: str) -> list[str]:
+    """Return the last two unique minor rust base keys for the suffix.
+
+    Sourced from Docker Hub library/rust tags so we never pick a key
+    whose image hasn't been published yet. Output: ascending composite keys.
+    """
+    payload = runner.http_get_json(
+        f"https://hub.docker.com/v2/repositories/library/rust/tags?page_size=100&name={suffix}"
+    )
+    full = re.compile(rf"^[0-9]+\.[0-9]+\.[0-9]+-{re.escape(suffix)}$")
+    candidates = [t["name"] for t in payload.get("results", []) if full.match(t["name"])]
+    # Sort newest first (descending by version), keep first occurrence per minor.
+    candidates.sort(key=lambda k: semver.parse(rust_keys.version_of(k)), reverse=True)
+    picked: list[str] = []
+    seen_minors: set[tuple[int, int]] = set()
+    for key in candidates:
+        v = semver.parse(rust_keys.version_of(key))
+        minor = (v.major, v.minor)
+        if minor in seen_minors:
+            continue
+        seen_minors.add(minor)
+        picked.append(key)
+        if len(picked) == 2:
+            break
+    picked.reverse()  # return ascending so callers iterate oldest-to-newest
+    return picked
+
+
+def resolve_ref(version: str) -> str:
+    sha = git_remote.resolve_tag_commit(STELLAR_CLI_REPO, f"v{version}")
+    if not sha:
+        raise ValueError(f"could not resolve tag v{version} in {STELLAR_CLI_REPO}")
+    return sha
+
+
+def append_pins(entry: dict, labels: Iterable[str]) -> bool:
+    """Resolve each label's digest and append `<label>@<digest>` pins.
+
+    Returns True if any new pin was appended. A pin already present (same
+    label and digest) is left untouched.
+    """
+    changed = False
+    for label in labels:
+        common.log(f"resolving rust:{label} ...")
+        digest = docker_inspect.index_digest(f"rust:{label}")
+        if not digest:
+            raise ValueError(f"empty digest returned for rust:{label}")
+        pin = f"{label}@{digest}"
+        if pin in entry["rust_versions"]:
+            common.log(f"  -> {pin} already declared; skipping")
+            continue
+        common.log(f"  -> appending {pin}")
+        entry["rust_versions"].append(pin)
+        changed = True
+    entry["rust_versions"].sort(
+        key=lambda p: semver.parse(rust_keys.version_of(builds.label_of(p)))
+    )
+    return changed
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--stellar-cli-version", required=True, metavar="V")
+    parser.add_argument(
+        "--rust-versions",
+        default="",
+        metavar="CSV",
+        help="Comma-separated rust base labels; defaults to the last two minor "
+        "slim-<distro> tags on Docker Hub.",
+    )
+    parser.add_argument("--dry-run", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    common.preflight_checks(["git", "buildx"])
+
+    cli = args.stellar_cli_version
+    data = builds.load()
+    entry = builds.find_cli(data, cli)
+
+    try:
+        if args.rust_versions:
+            labels = [k.strip() for k in args.rust_versions.split(",") if k.strip()]
+            common.log(f"rust base labels (from --rust-versions): {' '.join(labels)}")
+        else:
+            suffix = current_rust_base_suffix(data)
+            common.log(f"picking last 2 minor rust base labels '{suffix}' from Docker Hub ...")
+            labels = pick_default_rust_base_keys(suffix)
+            common.log(f"rust base labels (auto): {' '.join(labels)}")
+        if not labels:
+            common.die("no rust base labels selected")
+
+        if entry is None:
+            common.log(f"new stellar-cli {cli}; resolving upstream ref ...")
+            entry = {"ref": resolve_ref(cli), "rust_versions": [], "version": cli}
+            data.setdefault("stellar_cli_versions", []).append(entry)
+        elif not _PINNED_REF.match(entry.get("ref") or ""):
+            common.log(f"stellar-cli {cli} has no pinned ref; resolving ...")
+            entry["ref"] = resolve_ref(cli)
+
+        append_pins(entry, labels)
+        data["stellar_cli_versions"].sort(key=lambda e: semver.parse(e["version"]))
+    except ValueError as exc:
+        common.die(str(exc))
+    except OSError as exc:
+        # Network failure from the Docker Hub tag lookup (urllib raises
+        # URLError, an OSError) or a filesystem error.
+        common.die(f"failed to refresh builds.json: {exc}")
+
+    if args.dry_run:
+        common.log("(dry-run; not writing builds.json)")
+        return 0
+
+    builds.dump(data)
+    common.log(f"wrote {builds.DEFAULT_PATH}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/refresh_rust_digests.py b/scripts/refresh_rust_digests.py
deleted file mode 100755
index 60a9cc7..0000000
--- a/scripts/refresh_rust_digests.py
+++ /dev/null
@@ -1,71 +0,0 @@
-#!/usr/bin/env -S uv run python
-"""Re-resolve each rust_image_digests entry's upstream multi-arch index digest.
-
-Only fills entries whose digest is blank/unpinned; bumping a pinned digest
-must be requested per key via --rust-version.
-"""
-
-import argparse
-import re
-import sys
-
-from lib import builds, common, docker_inspect
-
-_PINNED = re.compile(r"^sha256:[0-9a-f]{64}$")
-
-
-def unpinned_keys(data: dict) -> list[str]:
-    return [
-        key
-        for key, value in data.get("rust_image_digests", {}).items()
-        if not _PINNED.match(value or "")
-    ]
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    parser.add_argument("--rust-version", default="", metavar="KEY")
-    parser.add_argument("--dry-run", action="store_true")
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = build_parser().parse_args(argv)
-    common.preflight_checks(["buildx"])
-    data = builds.load()
-    digests = data.setdefault("rust_image_digests", {})
-
-    if args.rust_version:
-        if args.rust_version not in digests:
-            common.die(
-                f"rust base key {args.rust_version} is not a key in builds.json rust_image_digests"
-            )
-        keys = [args.rust_version]
-    else:
-        keys = unpinned_keys(data)
-        if not keys:
-            common.log("all rust_image_digests entries are already pinned; nothing to do.")
-            common.log("to re-resolve a specific one, pass --rust-version <key>.")
-            return 0
-
-    updates: dict[str, str] = {}
-    for key in keys:
-        common.log(f"resolving rust:{key} ...")
-        digest = docker_inspect.index_digest(f"rust:{key}")
-        if not digest:
-            common.die(f"empty digest returned for rust:{key}")
-        common.log(f"  -> {digest}")
-        updates[key] = digest
-
-    if args.dry_run:
-        common.log("(dry-run; not writing builds.json)")
-        return 0
-
-    digests.update(updates)
-    builds.dump(data)
-    common.log(f"wrote {' '.join(updates.keys())} to {builds.DEFAULT_PATH}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
diff --git a/scripts/refresh_stellar_cli_digests.py b/scripts/refresh_stellar_cli_digests.py
deleted file mode 100755
index c64e041..0000000
--- a/scripts/refresh_stellar_cli_digests.py
+++ /dev/null
@@ -1,74 +0,0 @@
-#!/usr/bin/env -S uv run python
-"""Re-resolve each stellar_cli_versions[].ref by asking upstream git for the tag.
-
-Only fills entries whose ref is blank or not a valid 40-hex SHA; bumping a
-pinned ref must be requested per version via --stellar-cli-version.
-"""
-
-import argparse
-import re
-import sys
-
-from lib import builds, common, git_remote
-
-STELLAR_CLI_REPO = "https://github.com/stellar/stellar-cli.git"
-
-_PINNED = re.compile(r"^[0-9a-f]{40}$")
-
-
-def unpinned_versions(data: dict) -> list[str]:
-    return [
-        entry["version"]
-        for entry in data.get("stellar_cli_versions", [])
-        if not _PINNED.match(entry.get("ref") or "")
-    ]
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    parser.add_argument("--stellar-cli-version", default="", metavar="V")
-    parser.add_argument("--dry-run", action="store_true")
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = build_parser().parse_args(argv)
-    common.preflight_checks(["git"])
-    data = builds.load()
-
-    if args.stellar_cli_version:
-        if builds.find_cli(data, args.stellar_cli_version) is None:
-            common.die(
-                f"stellar-cli version {args.stellar_cli_version} is not declared in builds.json"
-            )
-        versions = [args.stellar_cli_version]
-    else:
-        versions = unpinned_versions(data)
-        if not versions:
-            common.log("all stellar_cli_versions entries are already pinned; nothing to do.")
-            common.log("to re-resolve a specific one, pass --stellar-cli-version <v>.")
-            return 0
-
-    resolved: dict[str, str] = {}
-    for version in versions:
-        common.log(f"resolving stellar-cli v{version} -> commit SHA ...")
-        sha = git_remote.resolve_tag_commit(STELLAR_CLI_REPO, f"v{version}")
-        if not sha:
-            common.die(f"could not resolve tag v{version} in {STELLAR_CLI_REPO}")
-        common.log(f"  -> {sha}")
-        resolved[version] = sha
-
-    if args.dry_run:
-        common.log("(dry-run; not writing builds.json)")
-        return 0
-
-    for entry in data["stellar_cli_versions"]:
-        if entry["version"] in resolved:
-            entry["ref"] = resolved[entry["version"]]
-    builds.dump(data)
-    common.log(f"wrote {' '.join(resolved.keys())} to {builds.DEFAULT_PATH}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
diff --git a/scripts/release_pr_body.py b/scripts/release_pr_body.py
index 1aeef4b..766f35b 100755
--- a/scripts/release_pr_body.py
+++ b/scripts/release_pr_body.py
@@ -30,9 +30,9 @@ def compose(
     body = (
         "### What\n\n"
         f"Stage a {kind} for stellar-cli {version}. `builds.json` is updated with "
-        "the rust pairings auto-picked from the current last two minor stable "
-        "releases on `rust-lang/rust`, and any new `rust_image_digests` entries "
-        "are resolved.\n\n"
+        "the rust base pins auto-picked from the current last two minor stable "
+        "releases on `rust-lang/rust`; each pin resolves the upstream base image "
+        "digest at append time (`<label>@sha256:<digest>`).\n\n"
         "### Why\n\n"
         f"Triggered by @{actor} in {run_url}.\n\n"
         "### What is next\n\n"
diff --git a/scripts/release_prepare.py b/scripts/release_prepare.py
index 4226a2c..9b3e54c 100755
--- a/scripts/release_prepare.py
+++ b/scripts/release_prepare.py
@@ -1,10 +1,10 @@
 #!/usr/bin/env -S uv run python
 """Stage a new stellar-cli release into builds.json.
 
-Adds (new cli) or refreshes (existing cli) the entry, picks rust base
-pairings, resolves the upstream cli ref + any missing rust image digests,
-validates the result, and prints the chosen GitHub Release tag as the
-final stdout line.
+Delegates the builds.json mutation to refresh.py (pick rust bases, resolve the
+upstream cli ref + each base's image digest, append the pins), validates the
+result, fails if nothing changed, and prints the chosen GitHub Release tag as
+the final stdout line.
 
 All log output goes to stderr; stdout is just the tag.
 """
@@ -12,73 +12,14 @@
 import argparse
 import re
 import sys
-from collections.abc import Iterable
 
-import refresh_rust_digests
-import refresh_stellar_cli_digests
+import refresh
 import validate_json
-from lib import builds, common, gh_cli, runner, rust_keys, semver
+from lib import builds, common, gh_cli
 
 ITERATION_RE = re.compile(r"^v(?P<cli>[0-9]+\.[0-9]+\.[0-9]+)(?:-(?P<n>[0-9]+))?$")
 
 
-def current_rust_base_suffix(data: dict) -> str:
-    distro = data.get("default_distro") or ""
-    if not distro:
-        raise ValueError("builds.json is missing default_distro")
-    return f"slim-{distro}"
-
-
-def pick_default_rust_base_keys(suffix: str) -> list[str]:
-    """Return the last two unique minor rust base keys for the suffix.
-
-    Sourced from Docker Hub library/rust tags so we never pick a key
-    whose image hasn't been published yet. Output: ascending composite keys.
-    """
-    payload = runner.http_get_json(
-        f"https://hub.docker.com/v2/repositories/library/rust/tags?page_size=100&name={suffix}"
-    )
-    full = re.compile(rf"^[0-9]+\.[0-9]+\.[0-9]+-{re.escape(suffix)}$")
-    candidates = [t["name"] for t in payload.get("results", []) if full.match(t["name"])]
-    # Sort newest first (descending by version), keep first occurrence per minor.
-    candidates.sort(key=lambda k: semver.parse(rust_keys.version_of(k)), reverse=True)
-    picked: list[str] = []
-    seen_minors: set[tuple[int, int]] = set()
-    for key in candidates:
-        v = semver.parse(rust_keys.version_of(key))
-        minor = (v.major, v.minor)
-        if minor in seen_minors:
-            continue
-        seen_minors.add(minor)
-        picked.append(key)
-        if len(picked) == 2:
-            break
-    picked.reverse()  # return ascending so callers iterate oldest-to-newest
-    return picked
-
-
-def add_cli_entry(data: dict, cli: str, rust_versions: Iterable[str]) -> None:
-    rust_list = sorted(rust_versions, key=lambda k: semver.parse(rust_keys.version_of(k)))
-    entry = {"ref": "", "rust_versions": rust_list, "version": cli}
-    data.setdefault("stellar_cli_versions", []).append(entry)
-    data["stellar_cli_versions"].sort(key=lambda e: semver.parse(e["version"]))
-    digests = data.setdefault("rust_image_digests", {})
-    for key in rust_list:
-        digests.setdefault(key, "")
-
-
-def extend_cli_entry(data: dict, cli: str, rust_versions: Iterable[str]) -> None:
-    entry = builds.find_cli(data, cli)
-    if entry is None:
-        raise ValueError(f"unknown stellar-cli version: {cli}")
-    merged = set(entry["rust_versions"]) | set(rust_versions)
-    entry["rust_versions"] = sorted(merged, key=lambda k: semver.parse(rust_keys.version_of(k)))
-    data["stellar_cli_versions"].sort(key=lambda e: semver.parse(e["version"]))
-    digests = data.setdefault("rust_image_digests", {})
-    for key in entry["rust_versions"]:
-        digests.setdefault(key, "")
-
-
 def pick_release_tag(cli: str, repo: str) -> str:
     """Next available GitHub Release tag: v<cli>, or v<cli>-N for refreshes."""
     existing = gh_cli.list_release_tags(repo)
@@ -112,44 +53,13 @@ def main(argv: list[str] | None = None) -> int:
 
     cli = args.stellar_cli_version
     before = builds.DEFAULT_PATH.read_bytes()
-    data = builds.load()
-
-    mode = "refresh" if builds.find_cli(data, cli) is not None else "new"
-    common.log(f"mode: {mode}")
-
-    try:
-        if args.rust_versions:
-            rusts = [k.strip() for k in args.rust_versions.split(",") if k.strip()]
-            common.log(f"rust base keys (from --rust-versions): {' '.join(rusts)}")
-        else:
-            suffix = current_rust_base_suffix(data)
-            common.log(
-                f"picking the last 2 minor rust base keys with suffix "
-                f"'{suffix}' from Docker Hub ..."
-            )
-            rusts = pick_default_rust_base_keys(suffix)
-            common.log(f"rust base keys (auto): {' '.join(rusts)}")
-        if not rusts:
-            common.die("no rust base keys selected")
-
-        common.log(f"applying changes to {builds.DEFAULT_PATH} ...")
-        if mode == "new":
-            add_cli_entry(data, cli, rusts)
-        else:
-            extend_cli_entry(data, cli, rusts)
-        builds.dump(data)
-    except ValueError as exc:
-        common.die(str(exc))
-    except OSError as exc:
-        # Network failure from the Docker Hub tag lookup (urllib raises
-        # URLError, an OSError) or a filesystem error writing builds.json.
-        common.die(f"failed to stage builds.json: {exc}")
-
-    common.log("resolving upstream stellar-cli ref ...")
-    refresh_stellar_cli_digests.main([])
-
-    common.log("resolving rust image digests ...")
-    refresh_rust_digests.main([])
+
+    common.log(f"refreshing builds.json for stellar-cli {cli} ...")
+    refresh_argv = ["--stellar-cli-version", cli]
+    if args.rust_versions:
+        refresh_argv += ["--rust-versions", args.rust_versions]
+    if refresh.main(refresh_argv) != 0:
+        common.die("refresh failed; see above")
 
     common.log("validating builds.json ...")
     if validate_json.main([]) != 0:
@@ -165,9 +75,7 @@ def main(argv: list[str] | None = None) -> int:
     release_tag = pick_release_tag(cli, args.repo)
     common.log(f"release tag: {release_tag}")
     common.log("")
-    common.log(
-        f"release-prepare: builds.json staged for stellar-cli {cli} with rust {' '.join(rusts)}"
-    )
+    common.log(f"release-prepare: builds.json staged for stellar-cli {cli}")
 
     print(release_tag)
     return 0
diff --git a/scripts/resolve_matrix.py b/scripts/resolve_matrix.py
index 0fb0a4f..d2998b8 100755
--- a/scripts/resolve_matrix.py
+++ b/scripts/resolve_matrix.py
@@ -25,15 +25,15 @@ def build_matrix(data: dict, only_cli: str = "") -> dict:
         if only_cli and cli != only_cli:
             continue
         ref = entry["ref"]
-        for key in entry["rust_versions"]:
-            parsed = rust_keys.parse(key)
-            digest = builds.rust_image_digest(data, key)
+        for pin in entry["rust_versions"]:
+            label, digest = builds.split_entry(pin)
+            parsed = rust_keys.parse(label)
             for arch in ARCHES:
                 rows.append(
                     {
                         "arch": arch,
                         "platform": f"linux/{arch}",
-                        "rust_base_key": key,
+                        "rust_base_key": label,
                         "rust_base_suffix": parsed.suffix,
                         "rust_image_digest": digest,
                         "rust_version": parsed.version,
diff --git a/scripts/tag_names.py b/scripts/tag_names.py
index 0ad99a9..75f1700 100755
--- a/scripts/tag_names.py
+++ b/scripts/tag_names.py
@@ -1,10 +1,16 @@
 #!/usr/bin/env -S uv run python
-"""Compose canonical image tags from cli version, rust base key, optional
-platform, and optional stellar-cli git ref.
+"""Compose canonical image tags from cli version, rust base key, base image
+digest, optional platform, and optional stellar-cli git ref.
 
 Tag scheme:
-    multi-arch list:   <cli>[-<ref>]-rust<key>
-    per-arch:          <cli>[-<ref>]-rust<key>-<arch>
+    multi-arch list:   <cli>[-<ref15>]-rust<key>-<digest15>
+    per-arch:          <cli>[-<ref15>]-rust<key>-<digest15>-<arch>
+
+`ref15`/`digest15` are the first 15 hex chars of the stellar-cli git ref
+and of the rust base image digest (the `sha256:` algorithm prefix stripped).
+Both full values stay authoritative in builds.json; the tag carries short
+fragments so each (cli, ref, base label, base digest) resolves to a distinct,
+immutable tag without blowing the 128-char tag limit.
 
 Output: exactly one tag on stdout, with no registry/repo prefix.
 """
@@ -19,14 +25,30 @@
     "linux/arm64": "arm64",
 }
 
+_SHORT = 15
+
+
+def _short_ref(ref: str) -> str:
+    return ref[:_SHORT]
+
+
+def _short_digest(digest: str) -> str:
+    return digest.removeprefix("sha256:")[:_SHORT]
+
 
 def compose_tag(
-    *, stellar_cli_version: str, rust_version: str, platform: str = "", stellar_cli_ref: str = ""
+    *,
+    stellar_cli_version: str,
+    rust_version: str,
+    rust_image_digest: str,
+    platform: str = "",
+    stellar_cli_ref: str = "",
 ) -> str:
     tag = stellar_cli_version
     if stellar_cli_ref:
-        tag = f"{tag}-{stellar_cli_ref}"
+        tag = f"{tag}-{_short_ref(stellar_cli_ref)}"
     tag = f"{tag}-rust{rust_version}"
+    tag = f"{tag}-{_short_digest(rust_image_digest)}"
     if platform:
         arch = _ARCH_FOR_PLATFORM.get(platform)
         if arch is None:
@@ -39,6 +61,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
     parser.add_argument("--stellar-cli-version", required=True, metavar="V")
     parser.add_argument("--rust-version", required=True, metavar="KEY")
+    parser.add_argument("--rust-image-digest", required=True, metavar="DIGEST")
     parser.add_argument("--platform", default="", metavar="P")
     parser.add_argument("--stellar-cli-ref", default="", metavar="SHA")
     return parser
@@ -50,6 +73,7 @@ def main(argv: list[str] | None = None) -> int:
         tag = compose_tag(
             stellar_cli_version=args.stellar_cli_version,
             rust_version=args.rust_version,
+            rust_image_digest=args.rust_image_digest,
             platform=args.platform,
             stellar_cli_ref=args.stellar_cli_ref,
         )
diff --git a/scripts/validate_json.py b/scripts/validate_json.py
index 210851d..c5338e4 100755
--- a/scripts/validate_json.py
+++ b/scripts/validate_json.py
@@ -1,5 +1,5 @@
 #!/usr/bin/env -S uv run python
-"""Validate every *.json in the repo: sorted keys, schema, cross-field constraints.
+"""Validate every *.json in the repo: sorted keys and schema.
 
 Exits 0 if every check passes, 1 otherwise. Logs go to stderr so callers
 (release_prepare.py et al.) can chain us without polluting stdout.
@@ -78,24 +78,6 @@ def check_schema(builds_data: dict, schema: dict) -> bool:
     return True
 
 
-def check_cross_field_constraints(builds_data: dict) -> bool:
-    digests = set(builds_data.get("rust_image_digests", {}).keys())
-    referenced = {
-        key
-        for entry in builds_data.get("stellar_cli_versions", [])
-        for key in entry.get("rust_versions", [])
-    }
-    missing = referenced - digests
-    if missing:
-        for r in sorted(missing):
-            common.err(
-                f"rust version '{r}' is referenced by a cli entry but "
-                f"missing from rust_image_digests"
-            )
-        return False
-    return True
-
-
 def build_parser() -> argparse.ArgumentParser:
     return argparse.ArgumentParser(description=__doc__.splitlines()[0])
 
@@ -112,7 +94,6 @@ def main(argv: list[str] | None = None) -> int:
     schema = json.loads(schema_path.read_text())
 
     ok &= check_schema(builds_data, schema)
-    ok &= check_cross_field_constraints(builds_data)
 
     if ok:
         common.log("validate-json: all checks passed")
diff --git a/tests/fixtures/builds_unpinned.json b/tests/fixtures/builds_invalid_entry.json
similarity index 51%
rename from tests/fixtures/builds_unpinned.json
rename to tests/fixtures/builds_invalid_entry.json
index 313c7fd..5724e4e 100644
--- a/tests/fixtures/builds_unpinned.json
+++ b/tests/fixtures/builds_invalid_entry.json
@@ -1,11 +1,7 @@
 {
-  "$comment": "Fixture with blank/partial digests so refresh-rust-digests has work to do.",
+  "$comment": "Schema violation: a rust_versions[] entry is a bare label, not label@sha256:<digest>.",
   "$schema": "../../builds.schema.json",
   "default_distro": "trixie",
-  "rust_image_digests": {
-    "1.94.0-slim-trixie": "",
-    "1.95.0-slim-trixie": "sha256:e14e87345b4d5964ddcc3491d27ee046a0f23820f340c3c1e24da6880141f7c0"
-  },
   "stellar_cli_versions": [
     {
       "ref": "60f7458e7ecffddf2f2d91dc6d0d2db4fab03ecc",
diff --git a/tests/fixtures/builds_minimal.json b/tests/fixtures/builds_minimal.json
index 6933b70..149f13d 100644
--- a/tests/fixtures/builds_minimal.json
+++ b/tests/fixtures/builds_minimal.json
@@ -2,14 +2,11 @@
   "$comment": "Minimal fixture: one cli, one rust pairing.",
   "$schema": "../../builds.schema.json",
   "default_distro": "trixie",
-  "rust_image_digests": {
-    "1.94.0-slim-trixie": "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
-  },
   "stellar_cli_versions": [
     {
       "ref": "60f7458e7ecffddf2f2d91dc6d0d2db4fab03ecc",
       "rust_versions": [
-        "1.94.0-slim-trixie"
+        "1.94.0-slim-trixie@sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
       ],
       "version": "26.0.0"
     }
diff --git a/tests/fixtures/builds_multi_cli.json b/tests/fixtures/builds_multi_cli.json
index 00891a4..e558d35 100644
--- a/tests/fixtures/builds_multi_cli.json
+++ b/tests/fixtures/builds_multi_cli.json
@@ -2,24 +2,19 @@
   "$comment": "Two clis, two rust bases (trixie+bookworm), used to exercise the picker.",
   "$schema": "../../builds.schema.json",
   "default_distro": "trixie",
-  "rust_image_digests": {
-    "1.90.0-slim-bookworm": "sha256:64232e656c058f4468e8d024e990acff04f0fd5a5c0a88a574dc37773d7325c9",
-    "1.93.0-slim-trixie": "sha256:760ad1d638d70ebbd0c61e06210e1289cbe45ff6425e3ea6e01241de3e14d08e",
-    "1.94.0-slim-trixie": "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
-  },
   "stellar_cli_versions": [
     {
       "ref": "a048a57a75762458b487052e0021ea704a926bee",
       "rust_versions": [
-        "1.90.0-slim-bookworm"
+        "1.90.0-slim-bookworm@sha256:64232e656c058f4468e8d024e990acff04f0fd5a5c0a88a574dc37773d7325c9"
       ],
       "version": "25.1.0"
     },
     {
       "ref": "60f7458e7ecffddf2f2d91dc6d0d2db4fab03ecc",
       "rust_versions": [
-        "1.93.0-slim-trixie",
-        "1.94.0-slim-trixie"
+        "1.93.0-slim-trixie@sha256:760ad1d638d70ebbd0c61e06210e1289cbe45ff6425e3ea6e01241de3e14d08e",
+        "1.94.0-slim-trixie@sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
       ],
       "version": "26.0.0"
     }
diff --git a/tests/fixtures/builds_orphan_rust.json b/tests/fixtures/builds_orphan_rust.json
deleted file mode 100644
index a363287..0000000
--- a/tests/fixtures/builds_orphan_rust.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
-  "$comment": "Cross-field violation: rust_versions[] references a key absent from rust_image_digests.",
-  "$schema": "../../builds.schema.json",
-  "default_distro": "trixie",
-  "rust_image_digests": {
-    "1.94.0-slim-trixie": "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
-  },
-  "stellar_cli_versions": [
-    {
-      "ref": "60f7458e7ecffddf2f2d91dc6d0d2db4fab03ecc",
-      "rust_versions": [
-        "1.99.0-slim-trixie"
-      ],
-      "version": "26.0.0"
-    }
-  ]
-}
diff --git a/tests/fixtures/builds_unpinned_refs.json b/tests/fixtures/builds_unpinned_refs.json
index 6dbc55c..12f2183 100644
--- a/tests/fixtures/builds_unpinned_refs.json
+++ b/tests/fixtures/builds_unpinned_refs.json
@@ -1,22 +1,19 @@
 {
-  "$comment": "Fixture with one blank ref so refresh-stellar-cli-digests has work to do.",
+  "$comment": "Fixture with one blank ref so refresh has a ref to resolve.",
   "$schema": "../../builds.schema.json",
   "default_distro": "trixie",
-  "rust_image_digests": {
-    "1.94.0-slim-trixie": "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
-  },
   "stellar_cli_versions": [
     {
       "ref": "",
       "rust_versions": [
-        "1.94.0-slim-trixie"
+        "1.94.0-slim-trixie@sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
       ],
       "version": "26.0.0"
     },
     {
       "ref": "1228cff8022b804659750b94b315932b0e0f3f6a",
       "rust_versions": [
-        "1.94.0-slim-trixie"
+        "1.94.0-slim-trixie@sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
       ],
       "version": "26.1.0"
     }
diff --git a/tests/fixtures/builds_unsorted_keys.json b/tests/fixtures/builds_unsorted_keys.json
index 61b8aa9..e907800 100644
--- a/tests/fixtures/builds_unsorted_keys.json
+++ b/tests/fixtures/builds_unsorted_keys.json
@@ -1,6 +1,5 @@
 {
   "stellar_cli_versions": [],
   "$schema": "../../builds.schema.json",
-  "default_distro": "trixie",
-  "rust_image_digests": {}
+  "default_distro": "trixie"
 }
diff --git a/tests/integration/test_refresh.py b/tests/integration/test_refresh.py
new file mode 100644
index 0000000..3abe4ab
--- /dev/null
+++ b/tests/integration/test_refresh.py
@@ -0,0 +1,179 @@
+import json
+from pathlib import Path
+
+import pytest
+
+import refresh
+from lib import builds
+
+DIGEST_94 = "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
+OLD_94 = f"1.94.0-slim-trixie@{DIGEST_94}"
+
+
+@pytest.fixture
+def staged_minimal(tmp_path: Path, fixtures_dir: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    target = tmp_path / "builds.json"
+    target.write_text((fixtures_dir / "builds_minimal.json").read_text())
+    monkeypatch.setattr(builds, "DEFAULT_PATH", target)
+    return target
+
+
+@pytest.fixture
+def staged_unpinned_refs(
+    tmp_path: Path, fixtures_dir: Path, monkeypatch: pytest.MonkeyPatch
+) -> Path:
+    target = tmp_path / "builds.json"
+    target.write_text((fixtures_dir / "builds_unpinned_refs.json").read_text())
+    monkeypatch.setattr(builds, "DEFAULT_PATH", target)
+    return target
+
+
+def _no_git(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(refresh.common, "preflight_checks", lambda _: None)
+    monkeypatch.setattr(
+        refresh.git_remote,
+        "resolve_tag_commit",
+        lambda *_: pytest.fail("should not query git when ref is already pinned"),
+    )
+
+
+def test_current_rust_base_suffix_uses_default_distro(multi_cli_builds: dict) -> None:
+    assert refresh.current_rust_base_suffix(multi_cli_builds) == "slim-trixie"
+
+
+def test_current_rust_base_suffix_dies_without_default(multi_cli_builds: dict) -> None:
+    data = {**multi_cli_builds}
+    del data["default_distro"]
+    with pytest.raises(ValueError, match="missing default_distro"):
+        refresh.current_rust_base_suffix(data)
+
+
+def test_pick_default_rust_base_keys_keeps_two_minors(
+    monkeypatch: pytest.MonkeyPatch, fixtures_dir: Path
+) -> None:
+    payload = json.loads((fixtures_dir / "rust_hub_tags.json").read_text())
+    monkeypatch.setattr(refresh.runner, "http_get_json", lambda _: payload)
+    keys = refresh.pick_default_rust_base_keys("slim-trixie")
+    assert keys == ["1.94.1-slim-trixie", "1.95.0-slim-trixie"]
+
+
+def test_pick_default_rust_base_keys_rejects_wrong_suffix(
+    monkeypatch: pytest.MonkeyPatch, fixtures_dir: Path
+) -> None:
+    payload = json.loads((fixtures_dir / "rust_hub_tags.json").read_text())
+    monkeypatch.setattr(refresh.runner, "http_get_json", lambda _: payload)
+    keys = refresh.pick_default_rust_base_keys("slim-bookworm")
+    assert keys == ["1.94.0-slim-bookworm"]
+
+
+def test_appends_new_label_pin(monkeypatch: pytest.MonkeyPatch, staged_minimal: Path) -> None:
+    _no_git(monkeypatch)
+    new_digest = "sha256:" + "e" * 64
+    monkeypatch.setattr(refresh.docker_inspect, "index_digest", lambda ref: new_digest)
+
+    rc = refresh.main(["--stellar-cli-version", "26.0.0", "--rust-versions", "1.95.0-slim-trixie"])
+    assert rc == 0
+    entry = builds.find_cli(json.loads(staged_minimal.read_text()), "26.0.0")
+    assert entry["rust_versions"] == [OLD_94, f"1.95.0-slim-trixie@{new_digest}"]
+
+
+def test_appends_new_digest_for_same_label(
+    monkeypatch: pytest.MonkeyPatch, staged_minimal: Path
+) -> None:
+    # A rebuilt base: same label, fresh digest → a new pin, old pin retained.
+    _no_git(monkeypatch)
+    new_digest = "sha256:" + "9" * 64
+    monkeypatch.setattr(refresh.docker_inspect, "index_digest", lambda ref: new_digest)
+
+    rc = refresh.main(["--stellar-cli-version", "26.0.0", "--rust-versions", "1.94.0-slim-trixie"])
+    assert rc == 0
+    entry = builds.find_cli(json.loads(staged_minimal.read_text()), "26.0.0")
+    assert entry["rust_versions"] == [OLD_94, f"1.94.0-slim-trixie@{new_digest}"]
+
+
+def test_existing_pin_is_noop(monkeypatch: pytest.MonkeyPatch, staged_minimal: Path) -> None:
+    _no_git(monkeypatch)
+    # Upstream still serves the same digest already on file.
+    monkeypatch.setattr(refresh.docker_inspect, "index_digest", lambda ref: DIGEST_94)
+    before = staged_minimal.read_text()
+    assert (
+        refresh.main(["--stellar-cli-version", "26.0.0", "--rust-versions", "1.94.0-slim-trixie"])
+        == 0
+    )
+    assert staged_minimal.read_text() == before
+
+
+def test_dry_run_does_not_write(monkeypatch: pytest.MonkeyPatch, staged_minimal: Path) -> None:
+    _no_git(monkeypatch)
+    monkeypatch.setattr(refresh.docker_inspect, "index_digest", lambda ref: "sha256:" + "a" * 64)
+    before = staged_minimal.read_text()
+    assert (
+        refresh.main(
+            [
+                "--stellar-cli-version",
+                "26.0.0",
+                "--rust-versions",
+                "1.95.0-slim-trixie",
+                "--dry-run",
+            ]
+        )
+        == 0
+    )
+    assert staged_minimal.read_text() == before
+
+
+def test_resolves_blank_ref(monkeypatch: pytest.MonkeyPatch, staged_unpinned_refs: Path) -> None:
+    monkeypatch.setattr(refresh.common, "preflight_checks", lambda _: None)
+    monkeypatch.setattr(refresh.git_remote, "resolve_tag_commit", lambda repo, tag: "a" * 40)
+    monkeypatch.setattr(
+        refresh.docker_inspect,
+        "index_digest",
+        lambda ref: DIGEST_94,
+    )
+    assert (
+        refresh.main(["--stellar-cli-version", "26.0.0", "--rust-versions", "1.94.0-slim-trixie"])
+        == 0
+    )
+    entry = builds.find_cli(json.loads(staged_unpinned_refs.read_text()), "26.0.0")
+    assert entry["ref"] == "a" * 40
+
+
+def test_creates_new_cli_entry(monkeypatch: pytest.MonkeyPatch, staged_minimal: Path) -> None:
+    monkeypatch.setattr(refresh.common, "preflight_checks", lambda _: None)
+    monkeypatch.setattr(refresh.git_remote, "resolve_tag_commit", lambda repo, tag: "c" * 40)
+    new_digest = "sha256:" + "d" * 64
+    monkeypatch.setattr(refresh.docker_inspect, "index_digest", lambda ref: new_digest)
+
+    assert (
+        refresh.main(["--stellar-cli-version", "27.0.0", "--rust-versions", "1.95.0-slim-trixie"])
+        == 0
+    )
+    data = json.loads(staged_minimal.read_text())
+    entry = builds.find_cli(data, "27.0.0")
+    assert entry["ref"] == "c" * 40
+    assert entry["rust_versions"] == [f"1.95.0-slim-trixie@{new_digest}"]
+    # Versions stay sorted.
+    assert [e["version"] for e in data["stellar_cli_versions"]] == ["26.0.0", "27.0.0"]
+
+
+def test_unresolvable_tag_dies(monkeypatch: pytest.MonkeyPatch, staged_minimal: Path) -> None:
+    monkeypatch.setattr(refresh.common, "preflight_checks", lambda _: None)
+    monkeypatch.setattr(refresh.git_remote, "resolve_tag_commit", lambda repo, tag: None)
+    monkeypatch.setattr(refresh.docker_inspect, "index_digest", lambda ref: "sha256:" + "a" * 64)
+    with pytest.raises(SystemExit):
+        refresh.main(["--stellar-cli-version", "27.0.0", "--rust-versions", "1.95.0-slim-trixie"])
+
+
+def test_auto_picks_when_no_rust_versions(
+    monkeypatch: pytest.MonkeyPatch, staged_minimal: Path, fixtures_dir: Path
+) -> None:
+    _no_git(monkeypatch)
+    payload = json.loads((fixtures_dir / "rust_hub_tags.json").read_text())
+    monkeypatch.setattr(refresh.runner, "http_get_json", lambda _: payload)
+    monkeypatch.setattr(refresh.docker_inspect, "index_digest", lambda ref: "sha256:" + "a" * 64)
+
+    assert refresh.main(["--stellar-cli-version", "26.0.0"]) == 0
+    entry = builds.find_cli(json.loads(staged_minimal.read_text()), "26.0.0")
+    labels = [builds.label_of(p) for p in entry["rust_versions"]]
+    assert "1.94.1-slim-trixie" in labels
+    assert "1.95.0-slim-trixie" in labels
diff --git a/tests/integration/test_refresh_rust_digests.py b/tests/integration/test_refresh_rust_digests.py
deleted file mode 100644
index 3e2c0dd..0000000
--- a/tests/integration/test_refresh_rust_digests.py
+++ /dev/null
@@ -1,94 +0,0 @@
-import json
-from pathlib import Path
-
-import pytest
-
-import refresh_rust_digests
-from lib import builds
-
-
-@pytest.fixture
-def staged_builds(tmp_path: Path, fixtures_dir: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
-    target = tmp_path / "builds.json"
-    target.write_text((fixtures_dir / "builds_unpinned.json").read_text())
-    monkeypatch.setattr(builds, "DEFAULT_PATH", target)
-    return target
-
-
-def test_unpinned_keys_finds_blank_value() -> None:
-    data = {
-        "rust_image_digests": {
-            "ok": "sha256:" + "a" * 64,
-            "blank": "",
-            "partial": "sha256:",
-            "bogus": "not-a-digest",
-        }
-    }
-    assert set(refresh_rust_digests.unpinned_keys(data)) == {"blank", "partial", "bogus"}
-
-
-def test_main_dry_run_does_not_write(monkeypatch: pytest.MonkeyPatch, staged_builds: Path) -> None:
-    monkeypatch.setattr(refresh_rust_digests.common, "preflight_checks", lambda _: None)
-    monkeypatch.setattr(
-        refresh_rust_digests.docker_inspect,
-        "index_digest",
-        lambda ref: "sha256:" + "f" * 64,
-    )
-    before = staged_builds.read_text()
-    assert refresh_rust_digests.main(["--dry-run"]) == 0
-    assert staged_builds.read_text() == before
-
-
-def test_main_fills_blanks_only(monkeypatch: pytest.MonkeyPatch, staged_builds: Path) -> None:
-    monkeypatch.setattr(refresh_rust_digests.common, "preflight_checks", lambda _: None)
-    expected = "sha256:" + "f" * 64
-    monkeypatch.setattr(
-        refresh_rust_digests.docker_inspect,
-        "index_digest",
-        lambda ref: expected,
-    )
-    assert refresh_rust_digests.main([]) == 0
-    data = json.loads(staged_builds.read_text())
-    assert data["rust_image_digests"]["1.94.0-slim-trixie"] == expected
-    # Already-pinned entry is untouched.
-    assert data["rust_image_digests"]["1.95.0-slim-trixie"].endswith("f340c3c1e24da6880141f7c0")
-
-
-def test_main_explicit_key_refreshes_pinned(
-    monkeypatch: pytest.MonkeyPatch, staged_builds: Path
-) -> None:
-    monkeypatch.setattr(refresh_rust_digests.common, "preflight_checks", lambda _: None)
-    new_digest = "sha256:" + "9" * 64
-    monkeypatch.setattr(
-        refresh_rust_digests.docker_inspect,
-        "index_digest",
-        lambda ref: new_digest,
-    )
-    assert refresh_rust_digests.main(["--rust-version", "1.95.0-slim-trixie"]) == 0
-    data = json.loads(staged_builds.read_text())
-    assert data["rust_image_digests"]["1.95.0-slim-trixie"] == new_digest
-    # Blank entry was not touched (we only refreshed the explicit key).
-    assert data["rust_image_digests"]["1.94.0-slim-trixie"] == ""
-
-
-def test_main_unknown_key_dies(monkeypatch: pytest.MonkeyPatch, staged_builds: Path) -> None:
-    monkeypatch.setattr(refresh_rust_digests.common, "preflight_checks", lambda _: None)
-    with pytest.raises(SystemExit):
-        refresh_rust_digests.main(["--rust-version", "1.99.0-slim-bookworm"])
-
-
-def test_main_all_pinned_is_noop(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, fixtures_dir: Path
-) -> None:
-    target = tmp_path / "builds.json"
-    target.write_text((fixtures_dir / "builds_minimal.json").read_text())
-    monkeypatch.setattr(builds, "DEFAULT_PATH", target)
-    monkeypatch.setattr(refresh_rust_digests.common, "preflight_checks", lambda _: None)
-    monkeypatch.setattr(
-        refresh_rust_digests.docker_inspect,
-        "index_digest",
-        lambda ref: pytest.fail("should not query docker when nothing needs refresh"),
-    )
-    before = target.read_text()
-    assert refresh_rust_digests.main([]) == 0
-    assert target.read_text() == before
diff --git a/tests/integration/test_refresh_stellar_cli_digests.py b/tests/integration/test_refresh_stellar_cli_digests.py
deleted file mode 100644
index 352a059..0000000
--- a/tests/integration/test_refresh_stellar_cli_digests.py
+++ /dev/null
@@ -1,105 +0,0 @@
-import json
-from pathlib import Path
-
-import pytest
-
-import refresh_stellar_cli_digests
-from lib import builds
-
-
-@pytest.fixture
-def staged_builds(tmp_path: Path, fixtures_dir: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
-    target = tmp_path / "builds.json"
-    target.write_text((fixtures_dir / "builds_unpinned_refs.json").read_text())
-    monkeypatch.setattr(builds, "DEFAULT_PATH", target)
-    return target
-
-
-def test_unpinned_versions_finds_blank() -> None:
-    data = {
-        "stellar_cli_versions": [
-            {"version": "1.0.0", "ref": "a" * 40, "rust_versions": []},
-            {"version": "1.1.0", "ref": "", "rust_versions": []},
-            {"version": "1.2.0", "ref": "not-a-sha", "rust_versions": []},
-        ]
-    }
-    assert refresh_stellar_cli_digests.unpinned_versions(data) == ["1.1.0", "1.2.0"]
-
-
-def test_main_dry_run_does_not_write(monkeypatch: pytest.MonkeyPatch, staged_builds: Path) -> None:
-    monkeypatch.setattr(refresh_stellar_cli_digests.common, "preflight_checks", lambda _: None)
-    monkeypatch.setattr(
-        refresh_stellar_cli_digests.git_remote,
-        "resolve_tag_commit",
-        lambda repo, tag: "f" * 40,
-    )
-    before = staged_builds.read_text()
-    assert refresh_stellar_cli_digests.main(["--dry-run"]) == 0
-    assert staged_builds.read_text() == before
-
-
-def test_main_fills_blanks_only(monkeypatch: pytest.MonkeyPatch, staged_builds: Path) -> None:
-    monkeypatch.setattr(refresh_stellar_cli_digests.common, "preflight_checks", lambda _: None)
-    expected = "f" * 40
-    monkeypatch.setattr(
-        refresh_stellar_cli_digests.git_remote,
-        "resolve_tag_commit",
-        lambda repo, tag: expected,
-    )
-    assert refresh_stellar_cli_digests.main([]) == 0
-    data = json.loads(staged_builds.read_text())
-    entries = {entry["version"]: entry["ref"] for entry in data["stellar_cli_versions"]}
-    assert entries["26.0.0"] == expected
-    assert entries["26.1.0"] == "1228cff8022b804659750b94b315932b0e0f3f6a"
-
-
-def test_main_explicit_version_refreshes_pinned(
-    monkeypatch: pytest.MonkeyPatch, staged_builds: Path
-) -> None:
-    monkeypatch.setattr(refresh_stellar_cli_digests.common, "preflight_checks", lambda _: None)
-    new_sha = "9" * 40
-    monkeypatch.setattr(
-        refresh_stellar_cli_digests.git_remote,
-        "resolve_tag_commit",
-        lambda repo, tag: new_sha,
-    )
-    assert refresh_stellar_cli_digests.main(["--stellar-cli-version", "26.1.0"]) == 0
-    data = json.loads(staged_builds.read_text())
-    entries = {entry["version"]: entry["ref"] for entry in data["stellar_cli_versions"]}
-    assert entries["26.1.0"] == new_sha
-    # 26.0.0 was blank but we didn't ask for it; leave it.
-    assert entries["26.0.0"] == ""
-
-
-def test_main_unknown_version_dies(monkeypatch: pytest.MonkeyPatch, staged_builds: Path) -> None:
-    monkeypatch.setattr(refresh_stellar_cli_digests.common, "preflight_checks", lambda _: None)
-    with pytest.raises(SystemExit):
-        refresh_stellar_cli_digests.main(["--stellar-cli-version", "99.0.0"])
-
-
-def test_main_unresolvable_tag_dies(monkeypatch: pytest.MonkeyPatch, staged_builds: Path) -> None:
-    monkeypatch.setattr(refresh_stellar_cli_digests.common, "preflight_checks", lambda _: None)
-    monkeypatch.setattr(
-        refresh_stellar_cli_digests.git_remote,
-        "resolve_tag_commit",
-        lambda repo, tag: None,
-    )
-    with pytest.raises(SystemExit):
-        refresh_stellar_cli_digests.main([])
-
-
-def test_main_all_pinned_is_noop(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, fixtures_dir: Path
-) -> None:
-    target = tmp_path / "builds.json"
-    target.write_text((fixtures_dir / "builds_minimal.json").read_text())
-    monkeypatch.setattr(builds, "DEFAULT_PATH", target)
-    monkeypatch.setattr(refresh_stellar_cli_digests.common, "preflight_checks", lambda _: None)
-    monkeypatch.setattr(
-        refresh_stellar_cli_digests.git_remote,
-        "resolve_tag_commit",
-        lambda *_: pytest.fail("should not query git when nothing needs refresh"),
-    )
-    before = target.read_text()
-    assert refresh_stellar_cli_digests.main([]) == 0
-    assert target.read_text() == before
diff --git a/tests/integration/test_release_prepare.py b/tests/integration/test_release_prepare.py
index 111c776..bc74f11 100644
--- a/tests/integration/test_release_prepare.py
+++ b/tests/integration/test_release_prepare.py
@@ -1,5 +1,4 @@
 import json
-import urllib.error
 from pathlib import Path
 
 import pytest
@@ -16,59 +15,6 @@ def staged_minimal(tmp_path: Path, fixtures_dir: Path, monkeypatch: pytest.Monke
     return target
 
 
-def test_current_rust_base_suffix_uses_default_distro(multi_cli_builds: dict) -> None:
-    assert release_prepare.current_rust_base_suffix(multi_cli_builds) == "slim-trixie"
-
-
-def test_current_rust_base_suffix_dies_without_default(multi_cli_builds: dict) -> None:
-    data = {**multi_cli_builds}
-    del data["default_distro"]
-    with pytest.raises(ValueError, match="missing default_distro"):
-        release_prepare.current_rust_base_suffix(data)
-
-
-def test_pick_default_rust_base_keys_keeps_two_minors(
-    monkeypatch: pytest.MonkeyPatch, fixtures_dir: Path
-) -> None:
-    payload = json.loads((fixtures_dir / "rust_hub_tags.json").read_text())
-    monkeypatch.setattr(release_prepare.runner, "http_get_json", lambda _: payload)
-    keys = release_prepare.pick_default_rust_base_keys("slim-trixie")
-    # 1.94.1 wins over 1.94.0 for the 1.94 minor; 1.95.0 wins for 1.95.
-    assert keys == ["1.94.1-slim-trixie", "1.95.0-slim-trixie"]
-
-
-def test_pick_default_rust_base_keys_rejects_wrong_suffix(
-    monkeypatch: pytest.MonkeyPatch, fixtures_dir: Path
-) -> None:
-    payload = json.loads((fixtures_dir / "rust_hub_tags.json").read_text())
-    monkeypatch.setattr(release_prepare.runner, "http_get_json", lambda _: payload)
-    keys = release_prepare.pick_default_rust_base_keys("slim-bookworm")
-    assert keys == ["1.94.0-slim-bookworm"]
-
-
-def test_add_cli_entry_appends_and_stubs_digests(minimal_builds: dict) -> None:
-    release_prepare.add_cli_entry(minimal_builds, "27.0.0", ["1.95.0-slim-trixie"])
-    versions = [e["version"] for e in minimal_builds["stellar_cli_versions"]]
-    assert "27.0.0" in versions
-    assert versions == sorted(versions)
-    # Stub digest was added (so refresh has something to fill).
-    assert "1.95.0-slim-trixie" in minimal_builds["rust_image_digests"]
-
-
-def test_extend_cli_entry_unions_and_sorts(minimal_builds: dict) -> None:
-    release_prepare.extend_cli_entry(
-        minimal_builds, "26.0.0", ["1.94.0-slim-trixie", "1.95.0-slim-trixie"]
-    )
-    entry = builds.find_cli(minimal_builds, "26.0.0")
-    assert entry is not None
-    assert entry["rust_versions"] == ["1.94.0-slim-trixie", "1.95.0-slim-trixie"]
-
-
-def test_extend_cli_entry_rejects_unknown_cli(minimal_builds: dict) -> None:
-    with pytest.raises(ValueError, match="unknown"):
-        release_prepare.extend_cli_entry(minimal_builds, "99.0.0", ["1.95.0-slim-trixie"])
-
-
 def test_pick_release_tag_no_prior_releases(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(release_prepare.gh_cli, "list_release_tags", lambda _: [])
     assert release_prepare.pick_release_tag("26.0.0", "foo/bar") == "v26.0.0"
@@ -99,75 +45,68 @@ def test_pick_release_tag_ignores_other_clis(monkeypatch: pytest.MonkeyPatch) ->
     assert release_prepare.pick_release_tag("26.0.0", "foo/bar") == "v26.0.0"
 
 
-def test_main_new_release_writes_entry_and_emits_tag(
+def test_main_delegates_to_refresh_and_emits_tag(
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
     staged_minimal: Path,
 ) -> None:
     monkeypatch.setattr(release_prepare.common, "preflight_checks", lambda _: None)
     monkeypatch.setattr(release_prepare.gh_cli, "list_release_tags", lambda _: [])
-    # Stub the downstream subscripts so we don't hit the network.
-    monkeypatch.setattr(release_prepare.refresh_stellar_cli_digests, "main", lambda _: 0)
+    monkeypatch.setattr(release_prepare.validate_json, "main", lambda _: 0)
+
+    captured_argv: list[list[str]] = []
 
-    def fake_rust_refresh(_argv):
+    def fake_refresh(argv):
+        captured_argv.append(argv)
         data = builds.load()
-        for key in data["rust_image_digests"]:
-            if not data["rust_image_digests"][key]:
-                data["rust_image_digests"][key] = "sha256:" + "f" * 64
-        # Backfill a ref so validate_json passes.
-        for entry in data["stellar_cli_versions"]:
-            if not entry["ref"]:
-                entry["ref"] = "a" * 40
+        data["stellar_cli_versions"].append(
+            {
+                "ref": "a" * 40,
+                "rust_versions": ["1.95.0-slim-trixie@sha256:" + "f" * 64],
+                "version": "27.0.0",
+            }
+        )
         builds.dump(data)
         return 0
 
-    monkeypatch.setattr(release_prepare.refresh_rust_digests, "main", fake_rust_refresh)
-    monkeypatch.setattr(release_prepare.validate_json, "main", lambda _: 0)
+    monkeypatch.setattr(release_prepare.refresh, "main", fake_refresh)
 
     rc = release_prepare.main(
-        [
-            "--stellar-cli-version",
-            "27.0.0",
-            "--rust-versions",
-            "1.95.0-slim-trixie",
-        ]
+        ["--stellar-cli-version", "27.0.0", "--rust-versions", "1.95.0-slim-trixie"]
     )
     assert rc == 0
     assert capsys.readouterr().out == "v27.0.0\n"
+    # The cli version and the rust-versions override are forwarded to refresh.
+    assert captured_argv[0][:2] == ["--stellar-cli-version", "27.0.0"]
+    assert "--rust-versions" in captured_argv[0]
     data = json.loads(staged_minimal.read_text())
     versions = [e["version"] for e in data["stellar_cli_versions"]]
     assert "27.0.0" in versions
 
 
-def test_main_dies_cleanly_on_network_failure(
+def test_main_dies_when_nothing_changes(
     monkeypatch: pytest.MonkeyPatch, staged_minimal: Path
 ) -> None:
     monkeypatch.setattr(release_prepare.common, "preflight_checks", lambda _: None)
+    monkeypatch.setattr(release_prepare.gh_cli, "list_release_tags", lambda _: [])
+    monkeypatch.setattr(release_prepare.validate_json, "main", lambda _: 0)
+    # refresh resolves to exactly what's already declared → no write.
+    monkeypatch.setattr(release_prepare.refresh, "main", lambda _: 0)
 
-    def boom(_url):
-        raise urllib.error.URLError("name resolution failed")
-
-    # No --rust-versions, so the auto-pick hits Docker Hub and raises.
-    monkeypatch.setattr(release_prepare.runner, "http_get_json", boom)
     with pytest.raises(SystemExit):
-        release_prepare.main(["--stellar-cli-version", "27.0.0"])
+        release_prepare.main(
+            ["--stellar-cli-version", "26.0.0", "--rust-versions", "1.94.0-slim-trixie"]
+        )
 
 
-def test_main_dies_when_nothing_changes(
+def test_main_dies_when_refresh_fails(
     monkeypatch: pytest.MonkeyPatch, staged_minimal: Path
 ) -> None:
     monkeypatch.setattr(release_prepare.common, "preflight_checks", lambda _: None)
-    monkeypatch.setattr(release_prepare.gh_cli, "list_release_tags", lambda _: [])
-    monkeypatch.setattr(release_prepare.refresh_stellar_cli_digests, "main", lambda _: 0)
-    monkeypatch.setattr(release_prepare.refresh_rust_digests, "main", lambda _: 0)
-    monkeypatch.setattr(release_prepare.validate_json, "main", lambda _: 0)
 
+    def boom(_argv):
+        raise SystemExit(1)
+
+    monkeypatch.setattr(release_prepare.refresh, "main", boom)
     with pytest.raises(SystemExit):
-        release_prepare.main(
-            [
-                "--stellar-cli-version",
-                "26.0.0",
-                "--rust-versions",
-                "1.94.0-slim-trixie",
-            ]
-        )
+        release_prepare.main(["--stellar-cli-version", "27.0.0"])
diff --git a/tests/unit/test_build_image.py b/tests/unit/test_build_image.py
index dc00aa4..447279e 100644
--- a/tests/unit/test_build_image.py
+++ b/tests/unit/test_build_image.py
@@ -5,6 +5,8 @@
 
 import build_image
 
+DIGEST = "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
+
 
 def _completed() -> subprocess.CompletedProcess[str]:
     return subprocess.CompletedProcess(args=[], returncode=0, stdout="")
@@ -24,6 +26,8 @@ def test_main_invokes_docker_with_build_args(
             "26.0.0",
             "--rust-version",
             "1.94.0-slim-trixie",
+            "--rust-image-digest",
+            DIGEST,
         ]
     )
 
@@ -32,14 +36,12 @@ def test_main_invokes_docker_with_build_args(
     assert args[0:3] == ["docker", "buildx", "build"]
     assert "--load" in args
     assert "--tag" in args
-    assert "stellar-cli:26.0.0-rust1.94.0-slim-trixie" in args
+    # Default local tag carries the short base-digest fragment.
+    assert "stellar-cli:26.0.0-rust1.94.0-slim-trixie-f7bf1c266d9e48c" in args
     assert "RUST_VERSION=1.94.0" in args
     assert "RUST_BASE_SUFFIX=slim-trixie" in args
     assert "STELLAR_CLI_VERSION=26.0.0" in args
-    assert any(
-        a.startswith("RUST_IMAGE_DIGEST=sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743")
-        for a in args
-    )
+    assert f"RUST_IMAGE_DIGEST={DIGEST}" in args
 
 
 def test_main_respects_platform_flag(monkeypatch: pytest.MonkeyPatch, minimal_builds: dict) -> None:
@@ -54,6 +56,8 @@ def test_main_respects_platform_flag(monkeypatch: pytest.MonkeyPatch, minimal_bu
             "26.0.0",
             "--rust-version",
             "1.94.0-slim-trixie",
+            "--rust-image-digest",
+            DIGEST,
             "--platform",
             "linux/arm64",
         ]
@@ -76,6 +80,8 @@ def test_main_respects_custom_tag(monkeypatch: pytest.MonkeyPatch, minimal_build
             "26.0.0",
             "--rust-version",
             "1.94.0-slim-trixie",
+            "--rust-image-digest",
+            DIGEST,
             "--tag",
             "my-local:test",
         ]
@@ -99,5 +105,7 @@ def test_main_dies_for_undeclared_pair(
                 "26.0.0",
                 "--rust-version",
                 "1.99.0-slim-trixie",
+                "--rust-image-digest",
+                DIGEST,
             ]
         )
diff --git a/tests/unit/test_builds.py b/tests/unit/test_builds.py
index 29313d7..eff3654 100644
--- a/tests/unit/test_builds.py
+++ b/tests/unit/test_builds.py
@@ -69,32 +69,61 @@ def test_stellar_cli_ref_unknown(multi_cli_builds: dict) -> None:
         builds.stellar_cli_ref(multi_cli_builds, "99.0.0")
 
 
-def test_rust_image_digest_known(multi_cli_builds: dict) -> None:
-    digest = builds.rust_image_digest(multi_cli_builds, "1.94.0-slim-trixie")
-    assert digest.startswith("sha256:")
+_DIGEST_94 = "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
+_PIN_94 = f"1.94.0-slim-trixie@{_DIGEST_94}"
 
 
-def test_rust_image_digest_unknown(multi_cli_builds: dict) -> None:
-    with pytest.raises(ValueError, match="no rust_image_digests entry"):
-        builds.rust_image_digest(multi_cli_builds, "1.0.0-nope")
+def test_split_entry_returns_label_and_digest() -> None:
+    label, digest = builds.split_entry(_PIN_94)
+    assert label == "1.94.0-slim-trixie"
+    assert digest == "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
+
+
+def test_label_of_and_digest_of() -> None:
+    assert builds.label_of(_PIN_94) == "1.94.0-slim-trixie"
+    assert builds.digest_of(_PIN_94).startswith("sha256:")
+
+
+def test_split_entry_rejects_bare_label() -> None:
+    with pytest.raises(ValueError, match="invalid rust base pin"):
+        builds.split_entry("1.94.0-slim-trixie")
 
 
 def test_assert_pair_declared_passes(multi_cli_builds: dict) -> None:
-    builds.assert_pair_declared(multi_cli_builds, "26.0.0", "1.94.0-slim-trixie")
+    builds.assert_pair_declared(multi_cli_builds, "26.0.0", _PIN_94)
 
 
 def test_assert_pair_declared_rejects_unknown_cli(multi_cli_builds: dict) -> None:
     with pytest.raises(ValueError, match="not declared"):
-        builds.assert_pair_declared(multi_cli_builds, "99.0.0", "1.94.0-slim-trixie")
+        builds.assert_pair_declared(multi_cli_builds, "99.0.0", _PIN_94)
 
 
 def test_assert_pair_declared_rejects_undeclared_pair(multi_cli_builds: dict) -> None:
     with pytest.raises(ValueError, match="not declared"):
-        builds.assert_pair_declared(multi_cli_builds, "25.1.0", "1.94.0-slim-trixie")
+        builds.assert_pair_declared(multi_cli_builds, "25.1.0", _PIN_94)
 
 
 def test_derive_default_rust_picks_highest_matching_suffix(multi_cli_builds: dict) -> None:
-    assert builds.derive_default_rust(multi_cli_builds, "26.0.0") == "1.94.0-slim-trixie"
+    assert builds.derive_default_rust(multi_cli_builds, "26.0.0") == _PIN_94
+
+
+def test_derive_default_rust_newest_digest_for_repeated_label() -> None:
+    # When a label carries two digests, the newest (last appended) wins.
+    newest = "1.94.0-slim-trixie@sha256:" + "b" * 64
+    data = {
+        "default_distro": "trixie",
+        "stellar_cli_versions": [
+            {
+                "ref": "a" * 40,
+                "version": "26.0.0",
+                "rust_versions": [
+                    "1.94.0-slim-trixie@sha256:" + "a" * 64,
+                    newest,
+                ],
+            }
+        ],
+    }
+    assert builds.derive_default_rust(data, "26.0.0") == newest
 
 
 def test_derive_default_rust_skips_non_matching_suffix(multi_cli_builds: dict) -> None:
diff --git a/tests/unit/test_newest_pair.py b/tests/unit/test_newest_pair.py
index 9c92e05..aa218a3 100644
--- a/tests/unit/test_newest_pair.py
+++ b/tests/unit/test_newest_pair.py
@@ -46,7 +46,9 @@ def test_main_rust_mode(
 ) -> None:
     monkeypatch.setattr(newest_pair.builds, "load", lambda: multi_cli_builds)
     assert newest_pair.main(["--rust-version"]) == 0
-    assert capsys.readouterr().out == "1.94.0-slim-trixie\n"
+    assert capsys.readouterr().out == (
+        "1.94.0-slim-trixie@sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0\n"
+    )
 
 
 def test_main_requires_one_mode() -> None:
diff --git a/tests/unit/test_publish_aliases.py b/tests/unit/test_publish_aliases.py
index d0c783c..5ef382d 100644
--- a/tests/unit/test_publish_aliases.py
+++ b/tests/unit/test_publish_aliases.py
@@ -24,14 +24,12 @@ def test_main_publishes_cli_alias_and_latest_for_newest(
 
 def test_main_skips_latest_for_non_newest(monkeypatch: pytest.MonkeyPatch) -> None:
     # Both clis carry a trixie key so derive_default_rust succeeds; 26.0.0 is newest.
+    pin = "1.94.0-slim-trixie@sha256:" + "a" * 64
     data = {
         "default_distro": "trixie",
-        "rust_image_digests": {
-            "1.94.0-slim-trixie": "sha256:" + "a" * 64,
-        },
         "stellar_cli_versions": [
-            {"ref": "a" * 40, "rust_versions": ["1.94.0-slim-trixie"], "version": "26.0.0"},
-            {"ref": "b" * 40, "rust_versions": ["1.94.0-slim-trixie"], "version": "26.1.0"},
+            {"ref": "a" * 40, "rust_versions": [pin], "version": "26.0.0"},
+            {"ref": "b" * 40, "rust_versions": [pin], "version": "26.1.0"},
         ],
     }
     monkeypatch.setattr(publish_aliases.common, "preflight_checks", lambda _: None)
diff --git a/tests/unit/test_publish_manifests.py b/tests/unit/test_publish_manifests.py
index 2c93031..aab9308 100644
--- a/tests/unit/test_publish_manifests.py
+++ b/tests/unit/test_publish_manifests.py
@@ -6,15 +6,18 @@
 
 
 def test_manifest_for_pair_composes_three_refs() -> None:
+    digest = "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
     list_ref, amd64_ref, arm64_ref = publish_manifests.manifest_for_pair(
         registry="docker.io/stellar/stellar-cli",
         cli="26.0.0",
         rust_key="1.94.0-slim-trixie",
+        rust_image_digest=digest,
         stellar_ref="abc123",
     )
-    assert list_ref == "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie"
-    assert amd64_ref == "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie-amd64"
-    assert arm64_ref == "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie-arm64"
+    base = "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c"
+    assert list_ref == base
+    assert amd64_ref == f"{base}-amd64"
+    assert arm64_ref == f"{base}-arm64"
 
 
 def test_main_creates_manifest_for_each_rust_version(
diff --git a/tests/unit/test_tag_names.py b/tests/unit/test_tag_names.py
index 791f59b..5714092 100644
--- a/tests/unit/test_tag_names.py
+++ b/tests/unit/test_tag_names.py
@@ -2,29 +2,45 @@
 
 import tag_names
 
+# Full 64-hex digest; the tag carries only its first 15 hex chars.
+DIGEST = "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
+DIGEST15 = "f7bf1c266d9e48c"
+REF = "ee3115b93b9c11b7a4d090f676f35736d3d86172"
+REF15 = "ee3115b93b9c11b"
+
 
 def test_compose_no_platform_no_ref() -> None:
     assert (
-        tag_names.compose_tag(stellar_cli_version="26.0.0", rust_version="1.94.0-slim-trixie")
-        == "26.0.0-rust1.94.0-slim-trixie"
+        tag_names.compose_tag(
+            stellar_cli_version="26.0.0",
+            rust_version="1.94.0-slim-trixie",
+            rust_image_digest=DIGEST,
+        )
+        == f"26.0.0-rust1.94.0-slim-trixie-{DIGEST15}"
     )
 
 
 def test_compose_with_amd64() -> None:
     assert (
         tag_names.compose_tag(
-            stellar_cli_version="26.0.0", rust_version="1.94.0-slim-trixie", platform="linux/amd64"
+            stellar_cli_version="26.0.0",
+            rust_version="1.94.0-slim-trixie",
+            rust_image_digest=DIGEST,
+            platform="linux/amd64",
         )
-        == "26.0.0-rust1.94.0-slim-trixie-amd64"
+        == f"26.0.0-rust1.94.0-slim-trixie-{DIGEST15}-amd64"
     )
 
 
 def test_compose_with_arm64() -> None:
     assert (
         tag_names.compose_tag(
-            stellar_cli_version="26.0.0", rust_version="1.94.0-slim-trixie", platform="linux/arm64"
+            stellar_cli_version="26.0.0",
+            rust_version="1.94.0-slim-trixie",
+            rust_image_digest=DIGEST,
+            platform="linux/arm64",
         )
-        == "26.0.0-rust1.94.0-slim-trixie-arm64"
+        == f"26.0.0-rust1.94.0-slim-trixie-{DIGEST15}-arm64"
     )
 
 
@@ -33,9 +49,10 @@ def test_compose_with_ref_only() -> None:
         tag_names.compose_tag(
             stellar_cli_version="26.0.0",
             rust_version="1.94.0-slim-trixie",
-            stellar_cli_ref="ee3115b93b9c11b7a4d090f676f35736d3d86172",
+            rust_image_digest=DIGEST,
+            stellar_cli_ref=REF,
         )
-        == "26.0.0-ee3115b93b9c11b7a4d090f676f35736d3d86172-rust1.94.0-slim-trixie"
+        == f"26.0.0-{REF15}-rust1.94.0-slim-trixie-{DIGEST15}"
     )
 
 
@@ -44,17 +61,23 @@ def test_compose_with_ref_and_platform() -> None:
         tag_names.compose_tag(
             stellar_cli_version="26.0.0",
             rust_version="1.94.0-slim-trixie",
+            rust_image_digest=DIGEST,
             platform="linux/amd64",
-            stellar_cli_ref="ee3115b93b9c11b7a4d090f676f35736d3d86172",
+            stellar_cli_ref=REF,
         )
-        == "26.0.0-ee3115b93b9c11b7a4d090f676f35736d3d86172-rust1.94.0-slim-trixie-amd64"
+        == f"26.0.0-{REF15}-rust1.94.0-slim-trixie-{DIGEST15}-amd64"
     )
 
 
-def test_compose_plain_suffix() -> None:
+def test_compose_accepts_bare_hex_digest() -> None:
+    # The sha256: prefix is optional; truncation is on the hex.
     assert (
-        tag_names.compose_tag(stellar_cli_version="26.1.0", rust_version="1.94.0-trixie")
-        == "26.1.0-rust1.94.0-trixie"
+        tag_names.compose_tag(
+            stellar_cli_version="26.0.0",
+            rust_version="1.94.0-slim-trixie",
+            rust_image_digest="f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0",
+        )
+        == f"26.0.0-rust1.94.0-slim-trixie-{DIGEST15}"
     )
 
 
@@ -63,21 +86,36 @@ def test_compose_rejects_unsupported_platform() -> None:
         tag_names.compose_tag(
             stellar_cli_version="26.0.0",
             rust_version="1.94.0-slim-trixie",
+            rust_image_digest=DIGEST,
             platform="linux/riscv64",
         )
 
 
 def test_main_prints_tag(capsys: pytest.CaptureFixture[str]) -> None:
-    rc = tag_names.main(["--stellar-cli-version", "26.0.0", "--rust-version", "1.94.0-slim-trixie"])
+    rc = tag_names.main(
+        [
+            "--stellar-cli-version",
+            "26.0.0",
+            "--rust-version",
+            "1.94.0-slim-trixie",
+            "--rust-image-digest",
+            DIGEST,
+        ]
+    )
     assert rc == 0
-    assert capsys.readouterr().out == "26.0.0-rust1.94.0-slim-trixie\n"
+    assert capsys.readouterr().out == f"26.0.0-rust1.94.0-slim-trixie-{DIGEST15}\n"
 
 
 def test_main_requires_stellar_cli_version() -> None:
     with pytest.raises(SystemExit):
-        tag_names.main(["--rust-version", "1.94.0-slim-trixie"])
+        tag_names.main(["--rust-version", "1.94.0-slim-trixie", "--rust-image-digest", DIGEST])
 
 
 def test_main_requires_rust_version() -> None:
     with pytest.raises(SystemExit):
-        tag_names.main(["--stellar-cli-version", "26.0.0"])
+        tag_names.main(["--stellar-cli-version", "26.0.0", "--rust-image-digest", DIGEST])
+
+
+def test_main_requires_rust_image_digest() -> None:
+    with pytest.raises(SystemExit):
+        tag_names.main(["--stellar-cli-version", "26.0.0", "--rust-version", "1.94.0-slim-trixie"])
diff --git a/tests/unit/test_validate_json.py b/tests/unit/test_validate_json.py
index 06ec75a..d6e6dbc 100644
--- a/tests/unit/test_validate_json.py
+++ b/tests/unit/test_validate_json.py
@@ -28,24 +28,41 @@ def test_has_sorted_keys_handles_primitives() -> None:
     assert validate_json.has_sorted_keys(None)
 
 
-def test_check_cross_field_constraints_passes(multi_cli_builds: dict) -> None:
-    assert validate_json.check_cross_field_constraints(multi_cli_builds)
-
-
-def test_check_cross_field_constraints_detects_orphan(fixtures_dir: Path) -> None:
-    data = json.loads((fixtures_dir / "builds_orphan_rust.json").read_text())
-    assert not validate_json.check_cross_field_constraints(data)
+def _schema(fixtures_dir: Path) -> dict:
+    return json.loads((fixtures_dir.parent.parent / "builds.schema.json").read_text())
 
 
 def test_check_schema_passes_for_valid(minimal_builds: dict, fixtures_dir: Path) -> None:
-    schema = json.loads((fixtures_dir.parent.parent / "builds.schema.json").read_text())
-    assert validate_json.check_schema(minimal_builds, schema)
+    assert validate_json.check_schema(minimal_builds, _schema(fixtures_dir))
 
 
 def test_check_schema_rejects_missing_required(fixtures_dir: Path) -> None:
-    schema = json.loads((fixtures_dir.parent.parent / "builds.schema.json").read_text())
-    broken = {"default_distro": "trixie"}  # missing rust_image_digests, stellar_cli_versions
-    assert not validate_json.check_schema(broken, schema)
+    broken = {"default_distro": "trixie"}  # missing stellar_cli_versions
+    assert not validate_json.check_schema(broken, _schema(fixtures_dir))
+
+
+def test_check_schema_rejects_bare_label_entry(minimal_builds: dict, fixtures_dir: Path) -> None:
+    # rust_versions entries must be fully-qualified label@sha256:<digest>.
+    minimal_builds["stellar_cli_versions"][0]["rust_versions"] = ["1.94.0-slim-trixie"]
+    assert not validate_json.check_schema(minimal_builds, _schema(fixtures_dir))
+
+
+def test_check_schema_rejects_duplicate_entry(minimal_builds: dict, fixtures_dir: Path) -> None:
+    digest = "sha256:" + "f" * 64
+    minimal_builds["stellar_cli_versions"][0]["rust_versions"] = [
+        f"1.94.0-slim-trixie@{digest}",
+        f"1.94.0-slim-trixie@{digest}",
+    ]
+    assert not validate_json.check_schema(minimal_builds, _schema(fixtures_dir))
+
+
+def test_check_schema_allows_two_digests(minimal_builds: dict, fixtures_dir: Path) -> None:
+    # The whole point of inlining: one label may carry two distinct digests.
+    minimal_builds["stellar_cli_versions"][0]["rust_versions"] = [
+        "1.94.0-slim-trixie@sha256:" + "a" * 64,
+        "1.94.0-slim-trixie@sha256:" + "b" * 64,
+    ]
+    assert validate_json.check_schema(minimal_builds, _schema(fixtures_dir))
 
 
 def test_iter_json_files_excludes_well_known_dirs(tmp_path: Path) -> None:
@@ -64,11 +81,11 @@ def test_main_passes_on_real_repo(monkeypatch: pytest.MonkeyPatch) -> None:
     assert validate_json.main([]) == 0
 
 
-def test_main_fails_when_cross_field_violated(
+def test_main_fails_on_invalid_entry(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch, fixtures_dir: Path
 ) -> None:
-    # Stage a fake repo root with an orphan rust_versions entry.
-    (tmp_path / "builds.json").write_text((fixtures_dir / "builds_orphan_rust.json").read_text())
+    # Stage a fake repo root whose builds.json has a bare (un-pinned) entry.
+    (tmp_path / "builds.json").write_text((fixtures_dir / "builds_invalid_entry.json").read_text())
     (tmp_path / "builds.schema.json").write_text(
         (fixtures_dir.parent.parent / "builds.schema.json").read_text()
     )

From 3f59d79a23fdfd70c96136f4d56cdf1ab4af068c Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Wed, 3 Jun 2026 12:35:41 -0700
Subject: [PATCH 2/8] Disambiguate release artifacts and tags by base digest.

---
 .github/workflows/publish.yml     | 12 +++---
 scripts/release_body.py           | 40 +++++++++++--------
 scripts/resolve_matrix.py         |  3 ++
 scripts/tag_names.py              |  5 ++-
 tests/fixtures/meta_amd64.json    |  4 +-
 tests/fixtures/meta_arm64.json    |  4 +-
 tests/unit/test_release_body.py   | 64 ++++++++++++++++++++-----------
 tests/unit/test_resolve_matrix.py | 30 +++++++++++++++
 8 files changed, 112 insertions(+), 50 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 18f978c..2eb71f7 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -141,7 +141,7 @@ jobs:
         with:
           image: ${{ steps.tag.outputs.image }}@${{ steps.build.outputs.digest }}
           format: spdx-json
-          output-file: sbom-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_key }}-${{ matrix.arch }}.spdx.json
+          output-file: sbom-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_id }}-${{ matrix.arch }}.spdx.json
           upload-release-assets: false
           upload-artifact: false
 
@@ -164,14 +164,14 @@ jobs:
         with:
           subject-name: ${{ env.REGISTRY }}
           subject-digest: ${{ steps.build.outputs.digest }}
-          sbom-path: sbom-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_key }}-${{ matrix.arch }}.spdx.json
+          sbom-path: sbom-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_id }}-${{ matrix.arch }}.spdx.json
           push-to-registry: true
 
       - name: write per-arch metadata
         if: steps.skip.outputs.skipped != 'true'
         run: |
           ./scripts/write_metadata.py \
-            --output "meta-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_key }}-${{ matrix.arch }}.json" \
+            --output "meta-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_id }}-${{ matrix.arch }}.json" \
             --arch "${{ matrix.arch }}" \
             --stellar-cli-version "${{ matrix.stellar_cli_version }}" \
             --digest "${{ steps.build.outputs.digest }}" \
@@ -184,7 +184,7 @@ jobs:
         if: steps.skip.outputs.skipped != 'true'
         run: |
           cp "${{ steps.attest-prov.outputs.bundle-path }}" \
-            "prov-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_key }}-${{ matrix.arch }}.intoto.jsonl"
+            "prov-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_id }}-${{ matrix.arch }}.intoto.jsonl"
 
       # Skipped pairs still need metadata so the release-body composer can
       # show the full state of every declared pair, not just the freshly
@@ -196,7 +196,7 @@ jobs:
         if: steps.skip.outputs.skipped == 'true'
         run: |
           ./scripts/write_metadata.py \
-            --output "meta-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_key }}-${{ matrix.arch }}.json" \
+            --output "meta-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_id }}-${{ matrix.arch }}.json" \
             --arch "${{ matrix.arch }}" \
             --stellar-cli-version "${{ matrix.stellar_cli_version }}" \
             --image "${{ steps.tag.outputs.image }}" \
@@ -207,7 +207,7 @@ jobs:
       - name: upload release artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: release-artifacts-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_key }}-${{ matrix.arch }}
+          name: release-artifacts-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_id }}-${{ matrix.arch }}
           path: |
             sbom-*.spdx.json
             prov-*.intoto.jsonl
diff --git a/scripts/release_body.py b/scripts/release_body.py
index 14a8bee..52cac89 100755
--- a/scripts/release_body.py
+++ b/scripts/release_body.py
@@ -35,13 +35,19 @@ def load_metadata(metadata_dir: Path, expected_cli: str) -> list[dict]:
     return rows
 
 
-def rust_keys_newest_first(rows: list[dict]) -> list[str]:
-    """Unique rust base keys, ordered by toolchain version descending."""
+def list_tag(row: dict) -> str:
+    """The multi-arch manifest-list tag for a row: its per-arch tag minus the arch."""
+    return row["tag"].removesuffix(f"-{row['arch']}")
+
+
+def pins_newest_first(rows: list[dict]) -> list[str]:
+    """Unique multi-arch list tags (one per base pin), ordered by version descending."""
     seen: dict[str, tuple] = {}
     for row in rows:
-        if row["rust_base_key"] not in seen:
-            seen[row["rust_base_key"]] = semver.parse(row["rust_version"])
-    return sorted(seen.keys(), key=lambda k: (seen[k], k), reverse=True)
+        tag = list_tag(row)
+        if tag not in seen:
+            seen[tag] = semver.parse(row["rust_version"])
+    return sorted(seen.keys(), key=lambda t: (seen[t], t), reverse=True)
 
 
 def emit_body(*, cli: str, rows: list[dict], registry: str, repo: str, stellar_ref: str) -> str:
@@ -57,10 +63,10 @@ def emit_body(*, cli: str, rows: list[dict], registry: str, repo: str, stellar_r
     p(f"- `{registry}:{cli}` — this cli, default Rust")
     p()
     p(f"Immutable, pinned to stellar-cli `{stellar_ref}`:\n")
-    for key in rust_keys_newest_first(rows):
-        p(f"- `{registry}:{cli}-{stellar_ref}-rust{key}` — multi-arch")
-        p(f"- `{registry}:{cli}-{stellar_ref}-rust{key}-amd64`")
-        p(f"- `{registry}:{cli}-{stellar_ref}-rust{key}-arm64`")
+    for tag in pins_newest_first(rows):
+        p(f"- `{registry}:{tag}` — multi-arch")
+        for row in [r for r in rows if list_tag(r) == tag]:
+            p(f"- `{registry}:{row['tag']}`")
 
     p("\n## Per-architecture digests (for SEP-58 `bldimg`)\n")
     p(
@@ -68,17 +74,19 @@ def emit_body(*, cli: str, rows: list[dict], registry: str, repo: str, stellar_r
         f"metadata. Never use a moving tag like `:latest` or `:{cli}`.\n"
     )
 
-    for key in rust_keys_newest_first(rows):
-        p(f"### Rust {key}\n")
-        key_rows = [r for r in rows if r["rust_base_key"] == key]
-        for row in key_rows:
+    for tag in pins_newest_first(rows):
+        pin_rows = [r for r in rows if list_tag(r) == tag]
+        key = pin_rows[0]["rust_base_key"]
+        base_digest = tag.rsplit("-", 1)[1]
+        p(f"### Rust {key} (base {base_digest})\n")
+        for row in pin_rows:
             p(f"- `linux/{row['arch']}`: `{registry}@{row['digest']}`")
         p("\nVerify:\n")
         p("```sh")
-        for row in key_rows:
+        for row in pin_rows:
             p(f"gh attestation verify oci://{registry}@{row['digest']} --repo {repo}")
         p()
-        for row in key_rows:
+        for row in pin_rows:
             p("cosign verify-attestation \\")
             p("  --type slsaprovenance1 \\")
             identity_re = f"https://github.com/{repo}/\\.github/workflows/.*"
@@ -86,7 +94,7 @@ def emit_body(*, cli: str, rows: list[dict], registry: str, repo: str, stellar_r
             p("  --certificate-oidc-issuer https://token.actions.githubusercontent.com \\")
             p(f"  {registry}@{row['digest']}")
         p()
-        for row in key_rows:
+        for row in pin_rows:
             p(f"docker buildx imagetools inspect {registry}@{row['digest']}")
         p("```\n")
 
diff --git a/scripts/resolve_matrix.py b/scripts/resolve_matrix.py
index d2998b8..031d69e 100755
--- a/scripts/resolve_matrix.py
+++ b/scripts/resolve_matrix.py
@@ -10,6 +10,7 @@
 import json
 import sys
 
+import tag_names
 from lib import builds, common, rust_keys
 
 ARCHES = ("amd64", "arm64")
@@ -28,11 +29,13 @@ def build_matrix(data: dict, only_cli: str = "") -> dict:
         for pin in entry["rust_versions"]:
             label, digest = builds.split_entry(pin)
             parsed = rust_keys.parse(label)
+            rust_base_id = f"{label}-{tag_names.short_digest(digest)}"
             for arch in ARCHES:
                 rows.append(
                     {
                         "arch": arch,
                         "platform": f"linux/{arch}",
+                        "rust_base_id": rust_base_id,
                         "rust_base_key": label,
                         "rust_base_suffix": parsed.suffix,
                         "rust_image_digest": digest,
diff --git a/scripts/tag_names.py b/scripts/tag_names.py
index 75f1700..fed42d5 100755
--- a/scripts/tag_names.py
+++ b/scripts/tag_names.py
@@ -32,7 +32,8 @@ def _short_ref(ref: str) -> str:
     return ref[:_SHORT]
 
 
-def _short_digest(digest: str) -> str:
+def short_digest(digest: str) -> str:
+    """First 15 hex chars of an image digest, with any `sha256:` prefix stripped."""
     return digest.removeprefix("sha256:")[:_SHORT]
 
 
@@ -48,7 +49,7 @@ def compose_tag(
     if stellar_cli_ref:
         tag = f"{tag}-{_short_ref(stellar_cli_ref)}"
     tag = f"{tag}-rust{rust_version}"
-    tag = f"{tag}-{_short_digest(rust_image_digest)}"
+    tag = f"{tag}-{short_digest(rust_image_digest)}"
     if platform:
         arch = _ARCH_FOR_PLATFORM.get(platform)
         if arch is None:
diff --git a/tests/fixtures/meta_amd64.json b/tests/fixtures/meta_amd64.json
index e555242..a0de21b 100644
--- a/tests/fixtures/meta_amd64.json
+++ b/tests/fixtures/meta_amd64.json
@@ -1,9 +1,9 @@
 {
   "arch": "amd64",
   "digest": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
-  "image": "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie-amd64",
+  "image": "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c-amd64",
   "rust_base_key": "1.94.0-slim-trixie",
   "rust_version": "1.94.0",
   "stellar_cli_version": "26.0.0",
-  "tag": "26.0.0-abc123-rust1.94.0-slim-trixie-amd64"
+  "tag": "26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c-amd64"
 }
diff --git a/tests/fixtures/meta_arm64.json b/tests/fixtures/meta_arm64.json
index b8f7194..1acb27c 100644
--- a/tests/fixtures/meta_arm64.json
+++ b/tests/fixtures/meta_arm64.json
@@ -1,9 +1,9 @@
 {
   "arch": "arm64",
   "digest": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
-  "image": "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie-arm64",
+  "image": "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c-arm64",
   "rust_base_key": "1.94.0-slim-trixie",
   "rust_version": "1.94.0",
   "stellar_cli_version": "26.0.0",
-  "tag": "26.0.0-abc123-rust1.94.0-slim-trixie-arm64"
+  "tag": "26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c-arm64"
 }
diff --git a/tests/unit/test_release_body.py b/tests/unit/test_release_body.py
index 09807a0..7a8743a 100644
--- a/tests/unit/test_release_body.py
+++ b/tests/unit/test_release_body.py
@@ -68,33 +68,33 @@ def test_load_metadata_sorts_by_rust_version_then_key_then_arch(tmp_path: Path)
     ]
 
 
-def test_rust_keys_newest_first_orders_by_version_desc() -> None:
+def _pin_rows(label: str, version: str, digest15: str) -> list[dict]:
+    base = f"26.0.0-abc123-rust{label}-{digest15}"
+    return [
+        {
+            "arch": arch,
+            "digest": "sha256:" + char * 64,
+            "rust_base_key": label,
+            "rust_version": version,
+            "tag": f"{base}-{arch}",
+        }
+        for arch, char in (("amd64", "1"), ("arm64", "2"))
+    ]
+
+
+def test_pins_newest_first_orders_by_version_desc() -> None:
     rows = [
-        {"rust_base_key": "1.94.0-slim-trixie", "rust_version": "1.94.0"},
-        {"rust_base_key": "1.100.0-slim-trixie", "rust_version": "1.100.0"},
-        {"rust_base_key": "1.94.0-slim-trixie", "rust_version": "1.94.0"},  # dup
+        *_pin_rows("1.94.0-slim-trixie", "1.94.0", "a" * 15),
+        *_pin_rows("1.100.0-slim-trixie", "1.100.0", "b" * 15),
     ]
-    assert release_body.rust_keys_newest_first(rows) == [
-        "1.100.0-slim-trixie",
-        "1.94.0-slim-trixie",
+    assert release_body.pins_newest_first(rows) == [
+        "26.0.0-abc123-rust1.100.0-slim-trixie-" + "b" * 15,
+        "26.0.0-abc123-rust1.94.0-slim-trixie-" + "a" * 15,
     ]
 
 
 def test_emit_body_includes_expected_sections() -> None:
-    rows = [
-        {
-            "arch": "amd64",
-            "digest": "sha256:" + "1" * 64,
-            "rust_base_key": "1.94.0-slim-trixie",
-            "rust_version": "1.94.0",
-        },
-        {
-            "arch": "arm64",
-            "digest": "sha256:" + "2" * 64,
-            "rust_base_key": "1.94.0-slim-trixie",
-            "rust_version": "1.94.0",
-        },
-    ]
+    rows = _pin_rows("1.94.0-slim-trixie", "1.94.0", "f7bf1c266d9e48c")
     body = release_body.emit_body(
         cli="26.0.0",
         rows=rows,
@@ -102,10 +102,12 @@ def test_emit_body_includes_expected_sections() -> None:
         repo="stellar/stellar-cli-docker",
         stellar_ref="abc123",
     )
+    list_tag = "26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c"
     assert "# stellar-cli 26.0.0" in body
     assert "## Tags" in body
     assert "docker.io/stellar/stellar-cli:latest" in body
-    assert "26.0.0-abc123-rust1.94.0-slim-trixie" in body
+    assert f"docker.io/stellar/stellar-cli:{list_tag}" in body
+    assert f"{list_tag}-amd64" in body
     assert "## Per-architecture digests" in body
     assert "### Rust 1.94.0-slim-trixie" in body
     assert "linux/amd64" in body
@@ -115,6 +117,24 @@ def test_emit_body_includes_expected_sections() -> None:
     assert "docker buildx imagetools inspect" in body
     assert "## Verification" in body
     assert "## Assets" in body
+
+
+def test_emit_body_two_digests_same_label_render_distinctly() -> None:
+    rows = [
+        *_pin_rows("1.94.0-slim-trixie", "1.94.0", "a" * 15),
+        *_pin_rows("1.94.0-slim-trixie", "1.94.0", "c" * 15),
+    ]
+    body = release_body.emit_body(
+        cli="26.0.0",
+        rows=rows,
+        registry="docker.io/stellar/stellar-cli",
+        repo="stellar/stellar-cli-docker",
+        stellar_ref="abc123",
+    )
+    # Both pins surface as their own multi-arch tag and their own section.
+    assert "26.0.0-abc123-rust1.94.0-slim-trixie-" + "a" * 15 in body
+    assert "26.0.0-abc123-rust1.94.0-slim-trixie-" + "c" * 15 in body
+    assert body.count("### Rust 1.94.0-slim-trixie") == 2
     # Each shell-continuation line in the cosign block must end with a single
     # backslash, not two — `\\` in the rendered markdown would land as a
     # literal `\\` in the user's terminal instead of a line continuation.
diff --git a/tests/unit/test_resolve_matrix.py b/tests/unit/test_resolve_matrix.py
index 3c75337..3696d78 100644
--- a/tests/unit/test_resolve_matrix.py
+++ b/tests/unit/test_resolve_matrix.py
@@ -29,6 +29,7 @@ def test_build_matrix_row_carries_expected_keys(minimal_builds: dict) -> None:
     assert set(row.keys()) == {
         "arch",
         "platform",
+        "rust_base_id",
         "rust_base_key",
         "rust_base_suffix",
         "rust_image_digest",
@@ -38,6 +39,35 @@ def test_build_matrix_row_carries_expected_keys(minimal_builds: dict) -> None:
     }
 
 
+def test_build_matrix_row_id_carries_digest_fragment(minimal_builds: dict) -> None:
+    matrix = resolve_matrix.build_matrix(minimal_builds)
+    row = matrix["include"][0]
+    # rust_base_id disambiguates two pins that share a label but differ by digest,
+    # so downstream artifact/file names never collide.
+    assert row["rust_base_id"] == "1.94.0-slim-trixie-f7bf1c266d9e48c"
+
+
+def test_build_matrix_same_label_two_digests_distinct_ids() -> None:
+    data = {
+        "default_distro": "trixie",
+        "stellar_cli_versions": [
+            {
+                "ref": "a" * 40,
+                "version": "26.0.0",
+                "rust_versions": [
+                    "1.94.0-slim-trixie@sha256:" + "a" * 64,
+                    "1.94.0-slim-trixie@sha256:" + "b" * 64,
+                ],
+            }
+        ],
+    }
+    ids = {row["rust_base_id"] for row in resolve_matrix.build_matrix(data)["include"]}
+    assert ids == {
+        "1.94.0-slim-trixie-" + "a" * 15,
+        "1.94.0-slim-trixie-" + "b" * 15,
+    }
+
+
 def test_build_matrix_parses_rust_key(minimal_builds: dict) -> None:
     matrix = resolve_matrix.build_matrix(minimal_builds)
     row = matrix["include"][0]

From 8d018b803b457d752e09509b29f2c8a896c0b12b Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Wed, 3 Jun 2026 13:22:11 -0700
Subject: [PATCH 3/8] Fix smoke test to take the pinned base image digest.

---
 .github/workflows/build.yml         |  3 ++-
 scripts/smoke_test_image.py         |  4 ++--
 tests/unit/test_smoke_test_image.py | 30 +++++++++++++++++++++++++++++
 3 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 0fc9927..9f52bc2 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -53,7 +53,8 @@ jobs:
           ./scripts/smoke_test_image.py \
             --image "${{ steps.pair.outputs.image }}" \
             --stellar-cli-version "${{ steps.pair.outputs.cli }}" \
-            --rust-version "${{ steps.pair.outputs.rust }}"
+            --rust-version "${{ steps.pair.outputs.rust }}" \
+            --rust-image-digest "${{ steps.pair.outputs.digest }}"
       - name: wasm reproducibility
         run: |
           ./scripts/repro_test.py \
diff --git a/scripts/smoke_test_image.py b/scripts/smoke_test_image.py
index 82aa4b0..7f08bc7 100755
--- a/scripts/smoke_test_image.py
+++ b/scripts/smoke_test_image.py
@@ -74,6 +74,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--image", required=True, metavar="REF")
     parser.add_argument("--stellar-cli-version", required=True, metavar="V")
     parser.add_argument("--rust-version", required=True, metavar="KEY")
+    parser.add_argument("--rust-image-digest", required=True, metavar="DIGEST")
     return parser
 
 
@@ -84,7 +85,6 @@ def main(argv: list[str] | None = None) -> int:
     data = builds.load()
     try:
         parsed = rust_keys.parse(args.rust_version)
-        rust_image_digest = builds.rust_image_digest(data, args.rust_version)
         stellar_ref = builds.stellar_cli_ref(data, args.stellar_cli_version)
     except ValueError as exc:
         common.die(str(exc))
@@ -98,7 +98,7 @@ def main(argv: list[str] | None = None) -> int:
         stellar_ref=stellar_ref,
         rust_version=parsed.version,
         rust_base_suffix=parsed.suffix,
-        rust_image_digest=rust_image_digest,
+        rust_image_digest=args.rust_image_digest,
     )
 
     if ok:
diff --git a/tests/unit/test_smoke_test_image.py b/tests/unit/test_smoke_test_image.py
index fabf3c3..8cb42f5 100644
--- a/tests/unit/test_smoke_test_image.py
+++ b/tests/unit/test_smoke_test_image.py
@@ -78,6 +78,36 @@ def test_check_labels_detects_missing(
     assert "revision" in capsys.readouterr().err
 
 
+def test_main_threads_pinned_digest(monkeypatch: pytest.MonkeyPatch, minimal_builds: dict) -> None:
+    monkeypatch.setattr(smoke_test_image.common, "preflight_checks", lambda _: None)
+    monkeypatch.setattr(smoke_test_image.builds, "load", lambda: minimal_builds)
+    monkeypatch.setattr(smoke_test_image, "check_version_output", lambda *a, **k: True)
+    monkeypatch.setattr(smoke_test_image, "check_contract_build_help", lambda *a, **k: True)
+    seen = {}
+    monkeypatch.setattr(
+        smoke_test_image,
+        "check_labels",
+        lambda image, **kwargs: seen.update(kwargs) or True,
+    )
+
+    rc = smoke_test_image.main(
+        [
+            "--image",
+            "img",
+            "--stellar-cli-version",
+            "26.0.0",
+            "--rust-version",
+            "1.94.0-slim-trixie",
+            "--rust-image-digest",
+            "sha256:" + "a" * 64,
+        ]
+    )
+    assert rc == 0
+    assert seen["rust_image_digest"] == "sha256:" + "a" * 64
+    assert seen["rust_version"] == "1.94.0"
+    assert seen["rust_base_suffix"] == "slim-trixie"
+
+
 def test_check_labels_detects_drifted_digest(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:

From b790370c3919ee3401b656b0425b0bf508d67a48 Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Wed, 3 Jun 2026 19:00:53 -0700
Subject: [PATCH 4/8] Simplify published image tags and allow overwriting.

---
 .github/workflows/build.yml          |  3 +-
 .github/workflows/publish.yml        | 50 +----------------
 README.md                            | 14 ++---
 RELEASE.md                           | 46 ++++++++--------
 scripts/build_image.py               |  1 -
 scripts/publish_aliases.py           |  5 +-
 scripts/publish_manifests.py         | 42 +++------------
 scripts/release_body.py              |  5 +-
 scripts/tag_names.py                 | 39 ++++----------
 tests/fixtures/meta_amd64.json       |  4 +-
 tests/fixtures/meta_arm64.json       |  4 +-
 tests/unit/test_build_image.py       |  3 +-
 tests/unit/test_publish_manifests.py | 17 ++----
 tests/unit/test_release_body.py      | 30 +++++------
 tests/unit/test_tag_names.py         | 81 +++++-----------------------
 15 files changed, 87 insertions(+), 257 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 9f52bc2..bb673da 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -34,8 +34,7 @@ jobs:
           rust="${pin%@*}"
           digest="${pin#*@}"
           tag="$(./scripts/tag_names.py \
-            --stellar-cli-version "$cli" --rust-version "$rust" \
-            --rust-image-digest "$digest")"
+            --stellar-cli-version "$cli" --rust-version "$rust")"
           {
             echo "cli=$cli"
             echo "rust=$rust"
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 2eb71f7..46cb2b3 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -80,9 +80,7 @@ jobs:
           tag="$(./scripts/tag_names.py \
             --stellar-cli-version ${{ matrix.stellar_cli_version }} \
             --rust-version ${{ matrix.rust_base_key }} \
-            --rust-image-digest ${{ matrix.rust_image_digest }} \
-            --platform ${{ matrix.platform }} \
-            --stellar-cli-ref ${{ matrix.stellar_cli_ref }})"
+            --platform ${{ matrix.platform }})"
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
           echo "image=$REGISTRY:$tag" >> "$GITHUB_OUTPUT"
 
@@ -92,32 +90,13 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: check whether already published
-        id: skip
-        run: |
-          if docker buildx imagetools inspect "${{ steps.tag.outputs.image }}" >/dev/null 2>&1; then
-            echo "::warning::${{ steps.tag.outputs.image }} already exists in the registry; skipping build (per-arch tags are immutable)"
-            {
-              echo "## ⚠️ Skipped — already published"
-              echo ""
-              echo "\`${{ steps.tag.outputs.image }}\` was already in the registry."
-              echo ""
-              echo "Per-arch tags are immutable, so no build or push happened for this row. If this is a corrupt-push recovery, delete the tag in Docker Hub by hand and re-run the workflow."
-            } >> "$GITHUB_STEP_SUMMARY"
-            echo "skipped=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "skipped=false" >> "$GITHUB_OUTPUT"
-          fi
-
       - name: build metadata
         id: meta
-        if: steps.skip.outputs.skipped != 'true'
         run: |
           echo "build_date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$GITHUB_OUTPUT"
 
       - name: build and push
         id: build
-        if: steps.skip.outputs.skipped != 'true'
         uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
@@ -136,7 +115,6 @@ jobs:
             SOURCE_REPO=${{ github.repository }}
 
       - name: generate SBOM file
-        if: steps.skip.outputs.skipped != 'true'
         uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
         with:
           image: ${{ steps.tag.outputs.image }}@${{ steps.build.outputs.digest }}
@@ -147,7 +125,6 @@ jobs:
 
       - name: attest build provenance
         id: attest-prov
-        if: steps.skip.outputs.skipped != 'true'
         uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
         with:
           subject-name: ${{ env.REGISTRY }}
@@ -159,7 +136,6 @@ jobs:
 
       - name: attest SBOM
         id: attest-sbom
-        if: steps.skip.outputs.skipped != 'true'
         uses: actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 # v4.1.0
         with:
           subject-name: ${{ env.REGISTRY }}
@@ -168,7 +144,6 @@ jobs:
           push-to-registry: true
 
       - name: write per-arch metadata
-        if: steps.skip.outputs.skipped != 'true'
         run: |
           ./scripts/write_metadata.py \
             --output "meta-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_id }}-${{ matrix.arch }}.json" \
@@ -181,29 +156,10 @@ jobs:
             --tag "${{ steps.tag.outputs.tag }}"
 
       - name: rename provenance bundle
-        if: steps.skip.outputs.skipped != 'true'
         run: |
           cp "${{ steps.attest-prov.outputs.bundle-path }}" \
             "prov-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_id }}-${{ matrix.arch }}.intoto.jsonl"
 
-      # Skipped pairs still need metadata so the release-body composer can
-      # show the full state of every declared pair, not just the freshly
-      # built ones. Omitting --digest tells write_metadata to resolve it
-      # from the existing tag in the registry; the SBOM/provenance files
-      # are not regenerated (they stay attached to the previously-
-      # published image's attestation store).
-      - name: write per-arch metadata (skipped pair)
-        if: steps.skip.outputs.skipped == 'true'
-        run: |
-          ./scripts/write_metadata.py \
-            --output "meta-${{ matrix.stellar_cli_version }}-rust${{ matrix.rust_base_id }}-${{ matrix.arch }}.json" \
-            --arch "${{ matrix.arch }}" \
-            --stellar-cli-version "${{ matrix.stellar_cli_version }}" \
-            --image "${{ steps.tag.outputs.image }}" \
-            --rust-base-key "${{ matrix.rust_base_key }}" \
-            --rust-version "${{ matrix.rust_version }}" \
-            --tag "${{ steps.tag.outputs.tag }}"
-
       - name: upload release artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
@@ -213,9 +169,7 @@ jobs:
             prov-*.intoto.jsonl
             meta-*.json
           retention-days: 7
-          # warn (not error) because the skipped path only produces meta-*.json;
-          # the sbom-*/prov-* globs find nothing in that case.
-          if-no-files-found: warn
+          if-no-files-found: error
 
   manifest:
     name: assemble manifest lists
diff --git a/README.md b/README.md
index d30ac21..d506942 100644
--- a/README.md
+++ b/README.md
@@ -72,8 +72,8 @@ multi-arch manifest list digest:
 
 ```sh
 # Find the per-arch digest for the architecture you used to build.
-# Pick any of the immutable manifest-list tags from the release notes,
-# e.g. :26.0.0-<ref15>-rust1.94.0-slim-trixie-<digest15>, or the :26.0.0 alias:
+# Pick any of the manifest-list tags from the release notes,
+# e.g. :26.0.0-rust1.94.0-slim-trixie, or the :26.0.0 alias:
 docker buildx imagetools inspect docker.io/stellar/stellar-cli:26.0.0
 ```
 
@@ -106,9 +106,9 @@ compare the resulting WASM sha256.
   --rust-version 1.94.0-slim-trixie \
   --rust-image-digest sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0
 
-# Smoke-test the built image (the tag carries the short base-digest fragment).
-docker run --rm stellar-cli:26.0.0-rust1.94.0-slim-trixie-f7bf1c266d9e48c --version
-docker run --rm stellar-cli:26.0.0-rust1.94.0-slim-trixie-f7bf1c266d9e48c contract build --help
+# Smoke-test the built image.
+docker run --rm stellar-cli:26.0.0-rust1.94.0-slim-trixie --version
+docker run --rm stellar-cli:26.0.0-rust1.94.0-slim-trixie contract build --help
 
 # Resolve + append rust base pins and the cli ref for a version (maintainer task).
 ./scripts/refresh.py --stellar-cli-version 26.1.0 --dry-run
@@ -120,8 +120,8 @@ Requirements: `docker` (with `buildx`) and [`uv`](https://docs.astral.sh/uv/).
 
 Maintainers: see [`RELEASE.md`](./RELEASE.md) for the end-to-end release
 process — how `builds.json` works, the PR-driven release flow that fires
-the publish workflow when a GitHub Release is published, the tag-
-immutability guard, and how to verify a freshly published image.
+the publish workflow when a GitHub Release is published, the published tag
+scheme, and how to verify a freshly published image.
 
 ## License
 
diff --git a/RELEASE.md b/RELEASE.md
index f2ec484..3e57dd7 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -6,8 +6,8 @@ This document covers the maintainer side of `stellar/stellar-cli-docker` — how
 
 Each release publishes to `docker.io/stellar/stellar-cli`:
 
-- **Per-architecture images** — `:<cli>-<ref15>-rust<rust>-<digest15>-amd64` and `…-arm64`, where `<ref15>` is the first 15 hex chars of the upstream `stellar/stellar-cli` git SHA the image was built from, and `<digest15>` is the first 15 hex chars of the rust base image's index digest. Each one is a single-architecture manifest with its own SHA-256 digest; this is the form a consumer cites in a SEP-58 `bldimg` field.
-- **Multi-arch manifest list** per `(cli, rust base, base digest)` pin — `:<cli>-<ref15>-rust<rust>-<digest15>` resolves to the right per-arch image at pull time.
+- **Per-architecture images** — `:<cli>-rust<rust>-amd64` and `:<cli>-rust<rust>-arm64`. Each one is a single-architecture manifest with its own SHA-256 digest; this per-arch digest is the form a consumer cites in a SEP-58 `bldimg` field.
+- **Multi-arch manifest list** per `(cli, rust base, base digest)` pin — `:<cli>-rust<rust>` resolves to the right per-arch image at pull time.
 - **Moving tags** — `:<cli>` points at the manifest list for that cli paired with the default rust base (highest `rust_versions[]` pin whose label matches the top-level `default_distro`, newest digest wins on a tie). `:latest` points at the same derivation for the newest declared cli. **Moving tags must never be used in `bldimg`** — they re-point on every publish.
 - **Two attestation chains** — buildx-native (SLSA build provenance + SPDX SBOM attached in the registry alongside the image) and GitHub-native (the same predicates signed and stored in the repo's attestation store, verifiable via `gh attestation verify`).
 - **A GitHub Release** for every publish run, with per-architecture digests in the body and the SBOM + provenance files attached as downloadable assets. The release is created by a maintainer following the link in the release PR (see [Releasing](#releasing--new-cli-version-or-refreshing-an-existing-one) below); publishing it triggers the workflow that enriches the release with the images' digests and supply-chain artifacts.
@@ -58,7 +58,7 @@ Every release gets a unique tag. Tags are never reused or updated in place.
 
 The `release` workflow picks the next available tag automatically by looking at existing releases. Each release page is the snapshot of `builds.json` at that iteration; the historical `v26.0.0` page stays intact when `v26.0.0-1` is later published.
 
-Docker image tags (`:<cli>-<ref15>-rust<key>-<digest15>[-<arch>]`) are unaffected by the `-N` suffix — they remain pinned forever based on the cli + ref + rust base key + base image digest + arch. Because the base digest is part of the tag, rebuilding the same cli + ref against a freshly-rebuilt base produces a *new* tag rather than mutating an existing one. Moving tags (`:<cli>`, `:latest`) re-point on every publish, regardless of which iteration.
+Docker image tags (`:<cli>-rust<key>[-<arch>]`) are unaffected by the `-N` suffix — they're keyed by the cli version + rust base label + arch. They are **mutable**: re-publishing a `(cli, rust base)` pair (e.g. after a refreshed base) overwrites the tag in place. Moving tags (`:<cli>`, `:latest`) re-point on every publish.
 
 ## Releasing — new cli version, or refreshing an existing one
 
@@ -81,7 +81,7 @@ Same workflow for both. PR review is the gate; a GitHub Release is the publish t
 
    The `publish` workflow fires on the `release: published` event and:
 
-   - Builds and pushes per-arch images for any **new** (cli, rust) pairs. Existing pairs (already in the registry) are **skipped with a ⚠️ warning** in the run summary — per-arch tags are immutable.
+   - Builds and pushes per-arch images for every declared (cli, rust) pair; tags are mutable, so an existing tag is overwritten in place.
    - Generates SLSA build provenance + SPDX SBOM attestations on each freshly-built image (buildx-native + GitHub-native chains).
    - Re-points the `:<cli>` and (if newest) `:latest` aliases.
    - Updates the new GitHub Release: appends per-architecture digests for every declared pair (whether built fresh or previously published) and verification commands to the body, attaches the SBOM and provenance files for the freshly-built pairs as downloadable assets.
@@ -103,13 +103,15 @@ The script prints the chosen release tag as its final stdout line. Commit and pu
 
 ```sh
 ./scripts/validate_json.py
-# Use the label + digest from the pin in builds.json. The built tag carries the
-# short digest fragment, e.g. stellar-cli:26.1.0-rust1.95.0-slim-trixie-e14e87345b4d596.
+# --rust-version is the label; --rust-image-digest is the pin's digest from
+# builds.json (it pins the FROM and is cross-checked against the image's
+# org.opencontainers.image.base.digest label). The built tag is label-only.
 ./scripts/build_image.py --stellar-cli-version 26.1.0 --rust-version 1.95.0-slim-trixie \
   --rust-image-digest sha256:e14e87345b4d5964ddcc3491d27ee046a0f23820f340c3c1e24da6880141f7c0
-./scripts/smoke_test_image.py --image stellar-cli:26.1.0-rust1.95.0-slim-trixie-e14e87345b4d596 \
-  --stellar-cli-version 26.1.0 --rust-version 1.95.0-slim-trixie
-./scripts/repro_test.py --image stellar-cli:26.1.0-rust1.95.0-slim-trixie-e14e87345b4d596
+./scripts/smoke_test_image.py --image stellar-cli:26.1.0-rust1.95.0-slim-trixie \
+  --stellar-cli-version 26.1.0 --rust-version 1.95.0-slim-trixie \
+  --rust-image-digest sha256:e14e87345b4d5964ddcc3491d27ee046a0f23820f340c3c1e24da6880141f7c0
+./scripts/repro_test.py --image stellar-cli:26.1.0-rust1.95.0-slim-trixie
 ```
 
 The smoke test confirms the binary reports the expected version and the labels are correct. The repro test confirms `stellar contract build --locked` produces byte-identical WASM across two clean builds. CI does the same against the freshly-built image on every PR push.
@@ -121,21 +123,19 @@ Triggered exclusively by the `release: published` event — when a maintainer cl
 | Job              | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `matrix`         | Validates `builds.json`, derives the cli version (from the release's tag name or the dispatch input), then runs `scripts/resolve_matrix.py --stellar-cli-version <v>` to produce a matrix of `(rust base key, arch)` rows for that one cli.                                                                                                                                                                                                                                                                              |
-| `build` (matrix) | Native runner per arch (`ubuntu-24.04` for amd64, `ubuntu-24.04-arm` for arm64). Checks if the per-arch tag exists in the registry: **already-published pairs are skipped with a ⚠️ warning**; only their metadata (digest from the registry) is uploaded as an artifact. Fresh pairs build + push via `docker/build-push-action` with `provenance: mode=max` and `sbom: true`, then attest with `actions/attest-build-provenance` and `actions/attest-sbom`. Either way, the workflow artifacts feed the `release` job. |
-| `manifest`       | Assembles the ref-pinned multi-arch manifest list `:<cli>-<ref15>-rust<key>-<digest15>` per rust base pin. Existing lists are skipped with a ⚠️ warning; new ones are created via `docker buildx imagetools create`.                                                                                                                                                                                                                                                                                                     |
+| `build` (matrix) | Native runner per arch (`ubuntu-24.04` for amd64, `ubuntu-24.04-arm` for arm64). Builds + pushes every pair via `docker/build-push-action` with `provenance: mode=max` and `sbom: true`, then attests with `actions/attest-build-provenance` and `actions/attest-sbom`. Tags are mutable, so an existing tag is overwritten. The per-arch metadata + SBOM/provenance artifacts feed the `release` job. |
+| `manifest`       | Assembles the multi-arch manifest list `:<cli>-rust<key>` per rust base. Lists are (re)created via `docker buildx imagetools create`, overwriting any existing list.                                                                                                                                                                                                                                                                                                                                                   |
 | `aliases`        | Re-points `:<cli>` to the manifest list of `(cli, default rust pin)` — the highest `rust_versions[]` pin whose label matches `default_distro`, newest digest winning a tie. If this cli is the newest declared, also re-points `:latest`. Both tags are intentionally moving; the job fails loudly if no `rust_versions[]` pin matches `default_distro`.                                                                                                                                                                  |
 | `release`        | Downloads every per-arch metadata + (when present) SBOM/provenance artifact, calls `scripts/release_body.py` to compose a structural body section, then **appends** that section to the just-created release body and attaches the SBOM + provenance files for freshly-built pairs as release assets. Any human-written notes already in the release body are preserved.                                                                                                                                                 |
 | `complete`       | Branch-protection aggregator. Fails if any upstream job failed or was cancelled.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
-## Tag immutability and restarts
-
-Per-architecture tags (`:<cli>-<ref15>-rust<key>-<digest15>-<arch>`) and per-pin manifest lists (`:<cli>-<ref15>-rust<key>-<digest15>`) on Docker Hub are **immutable**. Because the base image digest is encoded in the tag (as `<digest15>`), a rebuilt base never collides with an existing tag — it resolves to a new one — so the immutability promise holds without any in-place overwrite. When the publish workflow sees an existing tag, it skips that row with a ⚠️ warning surfaced in the run's Annotations panel and step summary — never overwrites. There is no force flag and no workflow input to override this.
+## Mutable tags and restarts
 
-Moving aliases (`:<cli>`, `:latest`) are exempt; they're documented as moving and re-pointed each release.
+Per-architecture tags (`:<cli>-rust<key>-<arch>`) and multi-arch manifest lists (`:<cli>-rust<key>`) on Docker Hub are **mutable** — re-publishing a `(cli, rust base)` pair overwrites the tag in place. Reproducibility is anchored by the per-arch image content digest (what SEP-58 `bldimg` cites) and by the `builds.json` pins, not by tag stability.
 
-To recover from a failed run, use **Re-run failed jobs** from the GitHub Actions UI. Already-successful jobs aren't re-run, and re-runs of failed jobs simply re-attempt the build (existing tags still skip, missing tags get built).
+Moving aliases (`:<cli>`, `:latest`) re-point each release.
 
-To genuinely re-publish a content-immutable tag (e.g. recovering from a corrupt push), delete the offending tag in Docker Hub by hand first, then click **Re-run all jobs** on the original publish run. The workflow re-uses the originating release-published event context, so no manual trigger is needed.
+To recover from a failed run, use **Re-run failed jobs** from the GitHub Actions UI; re-runs simply rebuild and overwrite. Recovering from a corrupt push is the same — just re-run, no manual tag deletion needed.
 
 ## Base image policy
 
@@ -145,11 +145,11 @@ The Rust base image carries two choices we make deliberately: the **variant** (`
 
 **Debian codename — track the latest Ubuntu LTS upstream.** Each Ubuntu LTS is based on a Debian release. We default to that Debian. The current latest Ubuntu LTS is 26.04, which is based on Debian 13 (`trixie`), so `trixie` is today's value of `default_distro`. We don't move to the newest Debian release the day it ships — we wait for the next Ubuntu LTS to track it, so users on the prevailing LTS host distro aren't running on a Debian newer than what their host's upstream tracks.
 
-**Tag — include variant + Debian.** The composite rust base key (e.g. `1.94.0-slim-trixie`) flows verbatim into the published image tag: `<cli>-<ref15>-rust<key>-<digest15>[-arch]`. When we eventually move off `trixie`, the new images get a new tag suffix and the historical tags stay addressable.
+**Tag — include variant + Debian.** The composite rust base key (e.g. `1.94.0-slim-trixie`) flows verbatim into the published image tag: `<cli>-rust<key>[-arch]`. When we eventually move off `trixie`, the new images get a new tag suffix and the historical tags stay addressable.
 
 ### Switching the default
 
-`default_distro` is the single switch. The picker queries Docker Hub for tags with the `slim-<default_distro>` suffix; the aliases job derives `:<cli>` and `:latest` targets the same way. Historical entries with the old suffix stay in each cli's `rust_versions[]` so the file remains consistent with the immutable tags already in the registry.
+`default_distro` is the single switch. The picker queries Docker Hub for tags with the `slim-<default_distro>` suffix; the aliases job derives `:<cli>` and `:latest` targets the same way. Historical entries with the old suffix stay in each cli's `rust_versions[]` so the file stays consistent with what's already been published.
 
 1. Edit `builds.json:default_distro` to the new codename (the schema's `enum` lists the supported values).
 2. Run `./scripts/validate_json.py` and the local smoke build (see [Validating locally before pushing](#validating-locally-before-pushing)).
@@ -159,15 +159,15 @@ The `Dockerfile`'s `FROM` lines reference the image by digest only; the variant
 
 ## Adopting a rebuilt base image
 
-Pins in `builds.json` are append-only and never rewritten in place. To adopt a freshly-rebuilt rust base — e.g. upstream republished `rust:1.94.0-slim-trixie` under a new index digest after a CVE patch — run `refresh` against the cli that should pick it up:
+To adopt a freshly-rebuilt rust base for an already-published cli — e.g. upstream republished `rust:1.95.0-slim-trixie` under a new index digest after a CVE patch — run `refresh` against that cli:
 
 ```sh
-./scripts/refresh.py --stellar-cli-version 26.1.0 --rust-versions 1.94.0-slim-trixie
+./scripts/refresh.py --stellar-cli-version 26.1.0 --rust-versions 1.95.0-slim-trixie
 ```
 
-`refresh` resolves the label's *current* upstream digest and **appends** a new pin `1.94.0-slim-trixie@sha256:<new>` alongside the existing one; the old pin — and its already-published, immutable tag — is left untouched. On publish, only the new pin builds, and it gets its own tag because the base digest is encoded in the tag. There is **no** need to delete anything from Docker Hub, and older cli versions sharing the label are unaffected. Already-published pins skip with a warning.
+`refresh` resolves the label's current upstream index digest and **appends** it as a new `label@sha256:<digest>` pin. Appending rather than rewriting keeps `builds.json` an append-only ledger of every base a release was built against — an audit trail of what shipped — while the mutable `:<cli>-rust<label>` tag tracks the most recent publish. Don't hand-edit the pin: `refresh` resolves the digest from the registry and keeps the file sorted and consistent, so it's the single supported way to change a base.
 
-Commit the resulting `builds.json` change and run the release flow as a refresh iteration (`v<cli>-<N>`). The cli ref itself stays immutable per release; to build against a different upstream commit, declare a new cli version.
+Commit the change and run the release flow as a refresh iteration (`v<cli>-<N>`). On publish, the `:26.1.0-rust1.95.0-slim-trixie` tag is rebuilt against the new base and overwritten in place; its per-arch image content digest changes accordingly. Other cli versions are unaffected — their tags carry a different cli prefix. To build against a different upstream stellar-cli commit instead, declare a new cli version.
 
 ## Verifying a freshly published release
 
diff --git a/scripts/build_image.py b/scripts/build_image.py
index 209b89d..5057a46 100755
--- a/scripts/build_image.py
+++ b/scripts/build_image.py
@@ -42,7 +42,6 @@ def main(argv: list[str] | None = None) -> int:
     tag = args.tag or "stellar-cli:" + tag_names.compose_tag(
         stellar_cli_version=args.stellar_cli_version,
         rust_version=args.rust_version,
-        rust_image_digest=rust_digest,
     )
     build_date = datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
 
diff --git a/scripts/publish_aliases.py b/scripts/publish_aliases.py
index 73590a2..2bc357e 100755
--- a/scripts/publish_aliases.py
+++ b/scripts/publish_aliases.py
@@ -42,16 +42,13 @@ def main(argv: list[str] | None = None) -> int:
     data = builds.load()
     try:
         default_pin = builds.derive_default_rust(data, args.stellar_cli_version)
-        default_rust, default_digest = builds.split_entry(default_pin)
-        stellar_ref = builds.stellar_cli_ref(data, args.stellar_cli_version)
+        default_rust = builds.label_of(default_pin)
     except ValueError as exc:
         common.die(str(exc))
 
     target_tag = tag_names.compose_tag(
         stellar_cli_version=args.stellar_cli_version,
         rust_version=default_rust,
-        rust_image_digest=default_digest,
-        stellar_cli_ref=stellar_ref,
     )
     target = f"{args.registry}:{target_tag}"
 
diff --git a/scripts/publish_manifests.py b/scripts/publish_manifests.py
index a203848..f9ad5a2 100755
--- a/scripts/publish_manifests.py
+++ b/scripts/publish_manifests.py
@@ -3,8 +3,7 @@
 
 For one stellar-cli version, walks its rust_versions[] and runs
 `docker buildx imagetools create` to assemble the multi-arch list from
-the per-arch tags. Existing manifest lists are skipped with a warning —
-the per-arch tags are immutable, so re-creating the list is a no-op.
+the per-arch tags. Tags are mutable, so an existing list is overwritten.
 """
 
 import argparse
@@ -14,28 +13,13 @@
 from lib import builds, common, docker_inspect
 
 
-def manifest_for_pair(
-    *, registry: str, cli: str, rust_key: str, rust_image_digest: str, stellar_ref: str
-) -> tuple[str, str, str]:
-    list_tag = tag_names.compose_tag(
-        stellar_cli_version=cli,
-        rust_version=rust_key,
-        rust_image_digest=rust_image_digest,
-        stellar_cli_ref=stellar_ref,
-    )
+def manifest_for_pair(*, registry: str, cli: str, rust_key: str) -> tuple[str, str, str]:
+    list_tag = tag_names.compose_tag(stellar_cli_version=cli, rust_version=rust_key)
     amd64_tag = tag_names.compose_tag(
-        stellar_cli_version=cli,
-        rust_version=rust_key,
-        rust_image_digest=rust_image_digest,
-        stellar_cli_ref=stellar_ref,
-        platform="linux/amd64",
+        stellar_cli_version=cli, rust_version=rust_key, platform="linux/amd64"
     )
     arm64_tag = tag_names.compose_tag(
-        stellar_cli_version=cli,
-        rust_version=rust_key,
-        rust_image_digest=rust_image_digest,
-        stellar_cli_ref=stellar_ref,
-        platform="linux/arm64",
+        stellar_cli_version=cli, rust_version=rust_key, platform="linux/arm64"
     )
     return (
         f"{registry}:{list_tag}",
@@ -64,29 +48,15 @@ def main(argv: list[str] | None = None) -> int:
     entry = builds.find_cli(data, args.stellar_cli_version)
     if entry is None:
         common.die(f"no stellar_cli_versions entry for {args.stellar_cli_version}")
-    stellar_ref = entry["ref"]
 
     for pin in entry["rust_versions"]:
-        rust_key, rust_image_digest = builds.split_entry(pin)
+        rust_key = builds.label_of(pin)
         list_ref, amd64_ref, arm64_ref = manifest_for_pair(
             registry=args.registry,
             cli=args.stellar_cli_version,
             rust_key=rust_key,
-            rust_image_digest=rust_image_digest,
-            stellar_ref=stellar_ref,
         )
 
-        if docker_inspect.exists(list_ref):
-            common.log(
-                f"::warning::manifest list {list_ref} already exists; "
-                "skipping (lists are immutable)"
-            )
-            common.step_summary(
-                "## ⚠️ Manifest list skipped — already published\n\n"
-                f"`{list_ref}` was already in the registry."
-            )
-            continue
-
         common.log(f"::group::manifest {list_ref}")
         if args.dry_run:
             common.log(f"docker buildx imagetools create --tag {list_ref} {amd64_ref} {arm64_ref}")
diff --git a/scripts/release_body.py b/scripts/release_body.py
index 52cac89..1874152 100755
--- a/scripts/release_body.py
+++ b/scripts/release_body.py
@@ -62,7 +62,7 @@ def emit_body(*, cli: str, rows: list[dict], registry: str, repo: str, stellar_r
     p(f"- `{registry}:latest` — newest declared cli, default Rust")
     p(f"- `{registry}:{cli}` — this cli, default Rust")
     p()
-    p(f"Immutable, pinned to stellar-cli `{stellar_ref}`:\n")
+    p(f"Pinned to stellar-cli `{stellar_ref}`:\n")
     for tag in pins_newest_first(rows):
         p(f"- `{registry}:{tag}` — multi-arch")
         for row in [r for r in rows if list_tag(r) == tag]:
@@ -77,8 +77,7 @@ def emit_body(*, cli: str, rows: list[dict], registry: str, repo: str, stellar_r
     for tag in pins_newest_first(rows):
         pin_rows = [r for r in rows if list_tag(r) == tag]
         key = pin_rows[0]["rust_base_key"]
-        base_digest = tag.rsplit("-", 1)[1]
-        p(f"### Rust {key} (base {base_digest})\n")
+        p(f"### Rust {key}\n")
         for row in pin_rows:
             p(f"- `linux/{row['arch']}`: `{registry}@{row['digest']}`")
         p("\nVerify:\n")
diff --git a/scripts/tag_names.py b/scripts/tag_names.py
index fed42d5..c89d862 100755
--- a/scripts/tag_names.py
+++ b/scripts/tag_names.py
@@ -1,16 +1,14 @@
 #!/usr/bin/env -S uv run python
-"""Compose canonical image tags from cli version, rust base key, base image
-digest, optional platform, and optional stellar-cli git ref.
+"""Compose canonical image tags from cli version, rust base key, and platform.
 
 Tag scheme:
-    multi-arch list:   <cli>[-<ref15>]-rust<key>-<digest15>
-    per-arch:          <cli>[-<ref15>]-rust<key>-<digest15>-<arch>
+    multi-arch list:   <cli>-rust<key>
+    per-arch:          <cli>-rust<key>-<arch>
 
-`ref15`/`digest15` are the first 15 hex chars of the stellar-cli git ref
-and of the rust base image digest (the `sha256:` algorithm prefix stripped).
-Both full values stay authoritative in builds.json; the tag carries short
-fragments so each (cli, ref, base label, base digest) resolves to a distinct,
-immutable tag without blowing the 128-char tag limit.
+The base image digest and stellar-cli ref stay authoritative in builds.json
+(and pin the build's FROM), but they are not encoded in the published tag —
+the tag is a plain, human-readable pointer. Reproducibility is anchored by the
+per-arch image content digest, which is what SEP-58 `bldimg` cites.
 
 Output: exactly one tag on stdout, with no registry/repo prefix.
 """
@@ -28,28 +26,13 @@
 _SHORT = 15
 
 
-def _short_ref(ref: str) -> str:
-    return ref[:_SHORT]
-
-
 def short_digest(digest: str) -> str:
     """First 15 hex chars of an image digest, with any `sha256:` prefix stripped."""
     return digest.removeprefix("sha256:")[:_SHORT]
 
 
-def compose_tag(
-    *,
-    stellar_cli_version: str,
-    rust_version: str,
-    rust_image_digest: str,
-    platform: str = "",
-    stellar_cli_ref: str = "",
-) -> str:
-    tag = stellar_cli_version
-    if stellar_cli_ref:
-        tag = f"{tag}-{_short_ref(stellar_cli_ref)}"
-    tag = f"{tag}-rust{rust_version}"
-    tag = f"{tag}-{short_digest(rust_image_digest)}"
+def compose_tag(*, stellar_cli_version: str, rust_version: str, platform: str = "") -> str:
+    tag = f"{stellar_cli_version}-rust{rust_version}"
     if platform:
         arch = _ARCH_FOR_PLATFORM.get(platform)
         if arch is None:
@@ -62,9 +45,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
     parser.add_argument("--stellar-cli-version", required=True, metavar="V")
     parser.add_argument("--rust-version", required=True, metavar="KEY")
-    parser.add_argument("--rust-image-digest", required=True, metavar="DIGEST")
     parser.add_argument("--platform", default="", metavar="P")
-    parser.add_argument("--stellar-cli-ref", default="", metavar="SHA")
     return parser
 
 
@@ -74,9 +55,7 @@ def main(argv: list[str] | None = None) -> int:
         tag = compose_tag(
             stellar_cli_version=args.stellar_cli_version,
             rust_version=args.rust_version,
-            rust_image_digest=args.rust_image_digest,
             platform=args.platform,
-            stellar_cli_ref=args.stellar_cli_ref,
         )
     except ValueError as exc:
         common.die(str(exc))
diff --git a/tests/fixtures/meta_amd64.json b/tests/fixtures/meta_amd64.json
index a0de21b..f805d35 100644
--- a/tests/fixtures/meta_amd64.json
+++ b/tests/fixtures/meta_amd64.json
@@ -1,9 +1,9 @@
 {
   "arch": "amd64",
   "digest": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
-  "image": "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c-amd64",
+  "image": "docker.io/stellar/stellar-cli:26.0.0-rust1.94.0-slim-trixie-amd64",
   "rust_base_key": "1.94.0-slim-trixie",
   "rust_version": "1.94.0",
   "stellar_cli_version": "26.0.0",
-  "tag": "26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c-amd64"
+  "tag": "26.0.0-rust1.94.0-slim-trixie-amd64"
 }
diff --git a/tests/fixtures/meta_arm64.json b/tests/fixtures/meta_arm64.json
index 1acb27c..59b79d9 100644
--- a/tests/fixtures/meta_arm64.json
+++ b/tests/fixtures/meta_arm64.json
@@ -1,9 +1,9 @@
 {
   "arch": "arm64",
   "digest": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
-  "image": "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c-arm64",
+  "image": "docker.io/stellar/stellar-cli:26.0.0-rust1.94.0-slim-trixie-arm64",
   "rust_base_key": "1.94.0-slim-trixie",
   "rust_version": "1.94.0",
   "stellar_cli_version": "26.0.0",
-  "tag": "26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c-arm64"
+  "tag": "26.0.0-rust1.94.0-slim-trixie-arm64"
 }
diff --git a/tests/unit/test_build_image.py b/tests/unit/test_build_image.py
index 447279e..78ffd05 100644
--- a/tests/unit/test_build_image.py
+++ b/tests/unit/test_build_image.py
@@ -36,8 +36,7 @@ def test_main_invokes_docker_with_build_args(
     assert args[0:3] == ["docker", "buildx", "build"]
     assert "--load" in args
     assert "--tag" in args
-    # Default local tag carries the short base-digest fragment.
-    assert "stellar-cli:26.0.0-rust1.94.0-slim-trixie-f7bf1c266d9e48c" in args
+    assert "stellar-cli:26.0.0-rust1.94.0-slim-trixie" in args
     assert "RUST_VERSION=1.94.0" in args
     assert "RUST_BASE_SUFFIX=slim-trixie" in args
     assert "STELLAR_CLI_VERSION=26.0.0" in args
diff --git a/tests/unit/test_publish_manifests.py b/tests/unit/test_publish_manifests.py
index aab9308..5dd3c54 100644
--- a/tests/unit/test_publish_manifests.py
+++ b/tests/unit/test_publish_manifests.py
@@ -6,15 +6,12 @@
 
 
 def test_manifest_for_pair_composes_three_refs() -> None:
-    digest = "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
     list_ref, amd64_ref, arm64_ref = publish_manifests.manifest_for_pair(
         registry="docker.io/stellar/stellar-cli",
         cli="26.0.0",
         rust_key="1.94.0-slim-trixie",
-        rust_image_digest=digest,
-        stellar_ref="abc123",
     )
-    base = "docker.io/stellar/stellar-cli:26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c"
+    base = "docker.io/stellar/stellar-cli:26.0.0-rust1.94.0-slim-trixie"
     assert list_ref == base
     assert amd64_ref == f"{base}-amd64"
     assert arm64_ref == f"{base}-arm64"
@@ -25,7 +22,6 @@ def test_main_creates_manifest_for_each_rust_version(
 ) -> None:
     monkeypatch.setattr(publish_manifests.common, "preflight_checks", lambda _: None)
     monkeypatch.setattr(publish_manifests.builds, "load", lambda: multi_cli_builds)
-    monkeypatch.setattr(publish_manifests.docker_inspect, "exists", lambda _: False)
     captured = MagicMock()
     monkeypatch.setattr(publish_manifests.docker_inspect, "create_manifest", captured)
 
@@ -34,21 +30,17 @@ def test_main_creates_manifest_for_each_rust_version(
     assert captured.call_count == 2
 
 
-def test_main_skips_existing_manifests(
+def test_main_overwrites_existing_manifests(
     monkeypatch: pytest.MonkeyPatch, multi_cli_builds: dict
 ) -> None:
+    # Tags are mutable: there is no skip path, so existing lists are recreated.
     monkeypatch.setattr(publish_manifests.common, "preflight_checks", lambda _: None)
     monkeypatch.setattr(publish_manifests.builds, "load", lambda: multi_cli_builds)
-    monkeypatch.setattr(publish_manifests.docker_inspect, "exists", lambda _: True)
     captured = MagicMock()
     monkeypatch.setattr(publish_manifests.docker_inspect, "create_manifest", captured)
-    summary = MagicMock()
-    monkeypatch.setattr(publish_manifests.common, "step_summary", summary)
 
     assert publish_manifests.main(["--stellar-cli-version", "26.0.0"]) == 0
-    assert captured.call_count == 0
-    # Each skipped list records a step-summary note (26.0.0 has 2 rust_versions).
-    assert summary.call_count == 2
+    assert captured.call_count == 2
 
 
 def test_main_unknown_cli_dies(monkeypatch: pytest.MonkeyPatch, multi_cli_builds: dict) -> None:
@@ -63,7 +55,6 @@ def test_main_dry_run_does_not_create(
 ) -> None:
     monkeypatch.setattr(publish_manifests.common, "preflight_checks", lambda _: None)
     monkeypatch.setattr(publish_manifests.builds, "load", lambda: multi_cli_builds)
-    monkeypatch.setattr(publish_manifests.docker_inspect, "exists", lambda _: False)
     captured = MagicMock()
     monkeypatch.setattr(publish_manifests.docker_inspect, "create_manifest", captured)
 
diff --git a/tests/unit/test_release_body.py b/tests/unit/test_release_body.py
index 7a8743a..dfa0b39 100644
--- a/tests/unit/test_release_body.py
+++ b/tests/unit/test_release_body.py
@@ -68,8 +68,8 @@ def test_load_metadata_sorts_by_rust_version_then_key_then_arch(tmp_path: Path)
     ]
 
 
-def _pin_rows(label: str, version: str, digest15: str) -> list[dict]:
-    base = f"26.0.0-abc123-rust{label}-{digest15}"
+def _pin_rows(label: str, version: str) -> list[dict]:
+    base = f"26.0.0-rust{label}"
     return [
         {
             "arch": arch,
@@ -84,17 +84,17 @@ def _pin_rows(label: str, version: str, digest15: str) -> list[dict]:
 
 def test_pins_newest_first_orders_by_version_desc() -> None:
     rows = [
-        *_pin_rows("1.94.0-slim-trixie", "1.94.0", "a" * 15),
-        *_pin_rows("1.100.0-slim-trixie", "1.100.0", "b" * 15),
+        *_pin_rows("1.94.0-slim-trixie", "1.94.0"),
+        *_pin_rows("1.100.0-slim-trixie", "1.100.0"),
     ]
     assert release_body.pins_newest_first(rows) == [
-        "26.0.0-abc123-rust1.100.0-slim-trixie-" + "b" * 15,
-        "26.0.0-abc123-rust1.94.0-slim-trixie-" + "a" * 15,
+        "26.0.0-rust1.100.0-slim-trixie",
+        "26.0.0-rust1.94.0-slim-trixie",
     ]
 
 
 def test_emit_body_includes_expected_sections() -> None:
-    rows = _pin_rows("1.94.0-slim-trixie", "1.94.0", "f7bf1c266d9e48c")
+    rows = _pin_rows("1.94.0-slim-trixie", "1.94.0")
     body = release_body.emit_body(
         cli="26.0.0",
         rows=rows,
@@ -102,7 +102,7 @@ def test_emit_body_includes_expected_sections() -> None:
         repo="stellar/stellar-cli-docker",
         stellar_ref="abc123",
     )
-    list_tag = "26.0.0-abc123-rust1.94.0-slim-trixie-f7bf1c266d9e48c"
+    list_tag = "26.0.0-rust1.94.0-slim-trixie"
     assert "# stellar-cli 26.0.0" in body
     assert "## Tags" in body
     assert "docker.io/stellar/stellar-cli:latest" in body
@@ -119,10 +119,10 @@ def test_emit_body_includes_expected_sections() -> None:
     assert "## Assets" in body
 
 
-def test_emit_body_two_digests_same_label_render_distinctly() -> None:
+def test_emit_body_two_labels_render_as_two_sections() -> None:
     rows = [
-        *_pin_rows("1.94.0-slim-trixie", "1.94.0", "a" * 15),
-        *_pin_rows("1.94.0-slim-trixie", "1.94.0", "c" * 15),
+        *_pin_rows("1.95.0-slim-trixie", "1.95.0"),
+        *_pin_rows("1.96.0-slim-trixie", "1.96.0"),
     ]
     body = release_body.emit_body(
         cli="26.0.0",
@@ -131,10 +131,10 @@ def test_emit_body_two_digests_same_label_render_distinctly() -> None:
         repo="stellar/stellar-cli-docker",
         stellar_ref="abc123",
     )
-    # Both pins surface as their own multi-arch tag and their own section.
-    assert "26.0.0-abc123-rust1.94.0-slim-trixie-" + "a" * 15 in body
-    assert "26.0.0-abc123-rust1.94.0-slim-trixie-" + "c" * 15 in body
-    assert body.count("### Rust 1.94.0-slim-trixie") == 2
+    assert "26.0.0-rust1.95.0-slim-trixie" in body
+    assert "26.0.0-rust1.96.0-slim-trixie" in body
+    assert "### Rust 1.95.0-slim-trixie" in body
+    assert "### Rust 1.96.0-slim-trixie" in body
     # Each shell-continuation line in the cosign block must end with a single
     # backslash, not two — `\\` in the rendered markdown would land as a
     # literal `\\` in the user's terminal instead of a line continuation.
diff --git a/tests/unit/test_tag_names.py b/tests/unit/test_tag_names.py
index 5714092..40eeab6 100644
--- a/tests/unit/test_tag_names.py
+++ b/tests/unit/test_tag_names.py
@@ -2,21 +2,11 @@
 
 import tag_names
 
-# Full 64-hex digest; the tag carries only its first 15 hex chars.
-DIGEST = "sha256:f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0"
-DIGEST15 = "f7bf1c266d9e48c"
-REF = "ee3115b93b9c11b7a4d090f676f35736d3d86172"
-REF15 = "ee3115b93b9c11b"
 
-
-def test_compose_no_platform_no_ref() -> None:
+def test_compose_no_platform() -> None:
     assert (
-        tag_names.compose_tag(
-            stellar_cli_version="26.0.0",
-            rust_version="1.94.0-slim-trixie",
-            rust_image_digest=DIGEST,
-        )
-        == f"26.0.0-rust1.94.0-slim-trixie-{DIGEST15}"
+        tag_names.compose_tag(stellar_cli_version="26.0.0", rust_version="1.94.0-slim-trixie")
+        == "26.0.0-rust1.94.0-slim-trixie"
     )
 
 
@@ -25,10 +15,9 @@ def test_compose_with_amd64() -> None:
         tag_names.compose_tag(
             stellar_cli_version="26.0.0",
             rust_version="1.94.0-slim-trixie",
-            rust_image_digest=DIGEST,
             platform="linux/amd64",
         )
-        == f"26.0.0-rust1.94.0-slim-trixie-{DIGEST15}-amd64"
+        == "26.0.0-rust1.94.0-slim-trixie-amd64"
     )
 
 
@@ -37,47 +26,16 @@ def test_compose_with_arm64() -> None:
         tag_names.compose_tag(
             stellar_cli_version="26.0.0",
             rust_version="1.94.0-slim-trixie",
-            rust_image_digest=DIGEST,
             platform="linux/arm64",
         )
-        == f"26.0.0-rust1.94.0-slim-trixie-{DIGEST15}-arm64"
-    )
-
-
-def test_compose_with_ref_only() -> None:
-    assert (
-        tag_names.compose_tag(
-            stellar_cli_version="26.0.0",
-            rust_version="1.94.0-slim-trixie",
-            rust_image_digest=DIGEST,
-            stellar_cli_ref=REF,
-        )
-        == f"26.0.0-{REF15}-rust1.94.0-slim-trixie-{DIGEST15}"
-    )
-
-
-def test_compose_with_ref_and_platform() -> None:
-    assert (
-        tag_names.compose_tag(
-            stellar_cli_version="26.0.0",
-            rust_version="1.94.0-slim-trixie",
-            rust_image_digest=DIGEST,
-            platform="linux/amd64",
-            stellar_cli_ref=REF,
-        )
-        == f"26.0.0-{REF15}-rust1.94.0-slim-trixie-{DIGEST15}-amd64"
+        == "26.0.0-rust1.94.0-slim-trixie-arm64"
     )
 
 
-def test_compose_accepts_bare_hex_digest() -> None:
-    # The sha256: prefix is optional; truncation is on the hex.
+def test_compose_plain_suffix() -> None:
     assert (
-        tag_names.compose_tag(
-            stellar_cli_version="26.0.0",
-            rust_version="1.94.0-slim-trixie",
-            rust_image_digest="f7bf1c266d9e48c8d724733fd97ba60464c44b743eb4f46f935577d3242d81d0",
-        )
-        == f"26.0.0-rust1.94.0-slim-trixie-{DIGEST15}"
+        tag_names.compose_tag(stellar_cli_version="26.1.0", rust_version="1.94.0-trixie")
+        == "26.1.0-rust1.94.0-trixie"
     )
 
 
@@ -86,36 +44,21 @@ def test_compose_rejects_unsupported_platform() -> None:
         tag_names.compose_tag(
             stellar_cli_version="26.0.0",
             rust_version="1.94.0-slim-trixie",
-            rust_image_digest=DIGEST,
             platform="linux/riscv64",
         )
 
 
 def test_main_prints_tag(capsys: pytest.CaptureFixture[str]) -> None:
-    rc = tag_names.main(
-        [
-            "--stellar-cli-version",
-            "26.0.0",
-            "--rust-version",
-            "1.94.0-slim-trixie",
-            "--rust-image-digest",
-            DIGEST,
-        ]
-    )
+    rc = tag_names.main(["--stellar-cli-version", "26.0.0", "--rust-version", "1.94.0-slim-trixie"])
     assert rc == 0
-    assert capsys.readouterr().out == f"26.0.0-rust1.94.0-slim-trixie-{DIGEST15}\n"
+    assert capsys.readouterr().out == "26.0.0-rust1.94.0-slim-trixie\n"
 
 
 def test_main_requires_stellar_cli_version() -> None:
     with pytest.raises(SystemExit):
-        tag_names.main(["--rust-version", "1.94.0-slim-trixie", "--rust-image-digest", DIGEST])
+        tag_names.main(["--rust-version", "1.94.0-slim-trixie"])
 
 
 def test_main_requires_rust_version() -> None:
     with pytest.raises(SystemExit):
-        tag_names.main(["--stellar-cli-version", "26.0.0", "--rust-image-digest", DIGEST])
-
-
-def test_main_requires_rust_image_digest() -> None:
-    with pytest.raises(SystemExit):
-        tag_names.main(["--stellar-cli-version", "26.0.0", "--rust-version", "1.94.0-slim-trixie"])
+        tag_names.main(["--stellar-cli-version", "26.0.0"])

From 17b98c2df50fefb77290891a6b0b4e0626c609d5 Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Wed, 3 Jun 2026 19:14:37 -0700
Subject: [PATCH 5/8] Publish only the newest base pin per rust label.

---
 scripts/resolve_matrix.py         |  6 +++++-
 tests/unit/test_resolve_matrix.py | 14 ++++++++------
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/scripts/resolve_matrix.py b/scripts/resolve_matrix.py
index 031d69e..a980d48 100755
--- a/scripts/resolve_matrix.py
+++ b/scripts/resolve_matrix.py
@@ -26,7 +26,11 @@ def build_matrix(data: dict, only_cli: str = "") -> dict:
         if only_cli and cli != only_cli:
             continue
         ref = entry["ref"]
-        for pin in entry["rust_versions"]:
+        # The published tag is label-only, so only the newest pin per label is
+        # built — the last occurrence in rust_versions wins. builds.json keeps
+        # the superseded pins as history; they are not rebuilt or republished.
+        latest_per_label = {builds.label_of(pin): pin for pin in entry["rust_versions"]}
+        for pin in latest_per_label.values():
             label, digest = builds.split_entry(pin)
             parsed = rust_keys.parse(label)
             rust_base_id = f"{label}-{tag_names.short_digest(digest)}"
diff --git a/tests/unit/test_resolve_matrix.py b/tests/unit/test_resolve_matrix.py
index 3696d78..f79055f 100644
--- a/tests/unit/test_resolve_matrix.py
+++ b/tests/unit/test_resolve_matrix.py
@@ -47,7 +47,9 @@ def test_build_matrix_row_id_carries_digest_fragment(minimal_builds: dict) -> No
     assert row["rust_base_id"] == "1.94.0-slim-trixie-f7bf1c266d9e48c"
 
 
-def test_build_matrix_same_label_two_digests_distinct_ids() -> None:
+def test_build_matrix_same_label_builds_only_last_pin() -> None:
+    # builds.json keeps the full history, but only the newest pin per label
+    # (last in the list) is published, so the mutable tag is deterministic.
     data = {
         "default_distro": "trixie",
         "stellar_cli_versions": [
@@ -61,11 +63,11 @@ def test_build_matrix_same_label_two_digests_distinct_ids() -> None:
             }
         ],
     }
-    ids = {row["rust_base_id"] for row in resolve_matrix.build_matrix(data)["include"]}
-    assert ids == {
-        "1.94.0-slim-trixie-" + "a" * 15,
-        "1.94.0-slim-trixie-" + "b" * 15,
-    }
+    rows = resolve_matrix.build_matrix(data)["include"]
+    # Only the last pin builds (one per arch); the superseded pin is not built.
+    assert len(rows) == 2
+    assert {r["rust_base_id"] for r in rows} == {"1.94.0-slim-trixie-" + "b" * 15}
+    assert {r["rust_image_digest"] for r in rows} == {"sha256:" + "b" * 64}
 
 
 def test_build_matrix_parses_rust_key(minimal_builds: dict) -> None:

From 2078d7b1230470dfb625c3e0d835d517528b681c Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Wed, 3 Jun 2026 19:29:53 -0700
Subject: [PATCH 6/8] Fix release PR body and docs for mutable tags.

---
 README.md                          | 24 ++++++++++++------------
 RELEASE.md                         | 22 +++++++++++-----------
 scripts/release_pr_body.py         |  6 +++---
 tests/unit/test_release_pr_body.py |  8 ++++++++
 4 files changed, 34 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index d506942..2203347 100644
--- a/README.md
+++ b/README.md
@@ -67,8 +67,8 @@ docker run --rm \
 ## Verifiable builds ([SEP-58](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0058.md))
 
 For verifiable references, **always pin to a per-arch single-architecture
-digest**, never to a moving tag like `:latest` or `:<cli>`, and never to a
-multi-arch manifest list digest:
+digest (`@sha256:…`)** — it is the only stable reference. Never use a tag or a
+multi-arch manifest list digest in `bldimg`:
 
 ```sh
 # Find the per-arch digest for the architecture you used to build.
@@ -83,16 +83,16 @@ compare the resulting WASM sha256.
 
 ## Repo layout
 
-| Path                                     | What                                                                                                                                                                                              |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Dockerfile`                             | Two-stage builder + runtime, args-driven.                                                                                                                                                         |
-| `builds.json`                            | Source of truth for which (stellar-cli, rust base key) pairs we publish.                                                                                                                          |
-| `builds.schema.json`                     | JSON Schema for `builds.json`.                                                                                                                                                                    |
-| `scripts/build_image.py`                 | Local single-image build.                                                                                                                                                                         |
-| `scripts/validate_json.py`               | Validates every `*.json` for sorted keys and `builds.json` against the schema.                                                                                                                    |
-| `scripts/refresh.py`                     | For one `--stellar-cli-version`: picks the rust base labels, resolves the upstream cli ref and each base's index digest, and appends the fully-qualified pins `<label>@<digest>` (append-only; already-published pins are retained). |
-| `scripts/verify_image.py`                | Consumer-facing verifier. Wraps `gh attestation verify` for both the SLSA build provenance and the SPDX SBOM attestations against a per-arch image digest.                                        |
-| `scripts/lib/`                           | Shared Python helpers imported by the other scripts (builds.json IO, semver/key parsing, subprocess + adapter wrappers).                                                                          |
+| Path                       | What                                                                                                                                                                                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Dockerfile`               | Two-stage builder + runtime, args-driven.                                                                                                                                                                                            |
+| `builds.json`              | Source of truth for which (stellar-cli, rust base key) pairs we publish.                                                                                                                                                             |
+| `builds.schema.json`       | JSON Schema for `builds.json`.                                                                                                                                                                                                       |
+| `scripts/build_image.py`   | Local single-image build.                                                                                                                                                                                                            |
+| `scripts/validate_json.py` | Validates every `*.json` for sorted keys and `builds.json` against the schema.                                                                                                                                                       |
+| `scripts/refresh.py`       | For one `--stellar-cli-version`: picks the rust base labels, resolves the upstream cli ref and each base's index digest, and appends the fully-qualified pins `<label>@<digest>` (append-only; already-published pins are retained). |
+| `scripts/verify_image.py`  | Consumer-facing verifier. Wraps `gh attestation verify` for both the SLSA build provenance and the SPDX SBOM attestations against a per-arch image digest.                                                                           |
+| `scripts/lib/`             | Shared Python helpers imported by the other scripts (builds.json IO, semver/key parsing, subprocess + adapter wrappers).                                                                                                             |
 
 ## Local development
 
diff --git a/RELEASE.md b/RELEASE.md
index 3e57dd7..a6a8529 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -6,9 +6,9 @@ This document covers the maintainer side of `stellar/stellar-cli-docker` — how
 
 Each release publishes to `docker.io/stellar/stellar-cli`:
 
-- **Per-architecture images** — `:<cli>-rust<rust>-amd64` and `:<cli>-rust<rust>-arm64`. Each one is a single-architecture manifest with its own SHA-256 digest; this per-arch digest is the form a consumer cites in a SEP-58 `bldimg` field.
-- **Multi-arch manifest list** per `(cli, rust base, base digest)` pin — `:<cli>-rust<rust>` resolves to the right per-arch image at pull time.
-- **Moving tags** — `:<cli>` points at the manifest list for that cli paired with the default rust base (highest `rust_versions[]` pin whose label matches the top-level `default_distro`, newest digest wins on a tie). `:latest` points at the same derivation for the newest declared cli. **Moving tags must never be used in `bldimg`** — they re-point on every publish.
+- **Per-architecture images** — `:<cli>-rust<rust>-amd64` and `:<cli>-rust<rust>-arm64`. Each one is a single-architecture manifest with its own SHA-256 digest.
+- **Multi-arch manifest list** per `(cli, rust base)` pair — `:<cli>-rust<rust>` resolves to the right per-arch image at pull time.
+- **Moving tags** — `:<cli>` points at the manifest list for that cli paired with the default rust base (highest `rust_versions[]` pin whose label matches the top-level `default_distro`, newest digest wins on a tie). `:latest` points at the same derivation for the newest declared cli. Both re-point on every publish.
 - **Two attestation chains** — buildx-native (SLSA build provenance + SPDX SBOM attached in the registry alongside the image) and GitHub-native (the same predicates signed and stored in the repo's attestation store, verifiable via `gh attestation verify`).
 - **A GitHub Release** for every publish run, with per-architecture digests in the body and the SBOM + provenance files attached as downloadable assets. The release is created by a maintainer following the link in the release PR (see [Releasing](#releasing--new-cli-version-or-refreshing-an-existing-one) below); publishing it triggers the workflow that enriches the release with the images' digests and supply-chain artifacts.
 
@@ -120,18 +120,18 @@ The smoke test confirms the binary reports the expected version and the labels a
 
 Triggered exclusively by the `release: published` event — when a maintainer clicks **Publish release** in the GitHub UI for a `v<version>` tag. There is no manual-dispatch entry point: publishing always goes through a reviewed `builds.json` PR and a GitHub Release page, so accidental ad-hoc publishes are off the table. Each run publishes **exactly one** cli version.
 
-| Job              | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `matrix`         | Validates `builds.json`, derives the cli version (from the release's tag name or the dispatch input), then runs `scripts/resolve_matrix.py --stellar-cli-version <v>` to produce a matrix of `(rust base key, arch)` rows for that one cli.                                                                                                                                                                                                                                                                              |
+| Job              | What it does                                                                                                                                                                                                                                                                                                                                                                                           |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `matrix`         | Validates `builds.json`, derives the cli version (from the release's tag name or the dispatch input), then runs `scripts/resolve_matrix.py --stellar-cli-version <v>` to produce a matrix of `(rust base key, arch)` rows for that one cli.                                                                                                                                                            |
 | `build` (matrix) | Native runner per arch (`ubuntu-24.04` for amd64, `ubuntu-24.04-arm` for arm64). Builds + pushes every pair via `docker/build-push-action` with `provenance: mode=max` and `sbom: true`, then attests with `actions/attest-build-provenance` and `actions/attest-sbom`. Tags are mutable, so an existing tag is overwritten. The per-arch metadata + SBOM/provenance artifacts feed the `release` job. |
-| `manifest`       | Assembles the multi-arch manifest list `:<cli>-rust<key>` per rust base. Lists are (re)created via `docker buildx imagetools create`, overwriting any existing list.                                                                                                                                                                                                                                                                                                                                                   |
-| `aliases`        | Re-points `:<cli>` to the manifest list of `(cli, default rust pin)` — the highest `rust_versions[]` pin whose label matches `default_distro`, newest digest winning a tie. If this cli is the newest declared, also re-points `:latest`. Both tags are intentionally moving; the job fails loudly if no `rust_versions[]` pin matches `default_distro`.                                                                                                                                                                  |
-| `release`        | Downloads every per-arch metadata + (when present) SBOM/provenance artifact, calls `scripts/release_body.py` to compose a structural body section, then **appends** that section to the just-created release body and attaches the SBOM + provenance files for freshly-built pairs as release assets. Any human-written notes already in the release body are preserved.                                                                                                                                                 |
-| `complete`       | Branch-protection aggregator. Fails if any upstream job failed or was cancelled.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `manifest`       | Assembles the multi-arch manifest list `:<cli>-rust<key>` per rust base. Lists are (re)created via `docker buildx imagetools create`, overwriting any existing list.                                                                                                                                                                                                                                   |
+| `aliases`        | Re-points `:<cli>` to the manifest list of `(cli, default rust pin)` — the highest `rust_versions[]` pin whose label matches `default_distro`, newest digest winning a tie. If this cli is the newest declared, also re-points `:latest`. Both tags are intentionally moving; the job fails loudly if no `rust_versions[]` pin matches `default_distro`.                                               |
+| `release`        | Downloads every per-arch metadata + (when present) SBOM/provenance artifact, calls `scripts/release_body.py` to compose a structural body section, then **appends** that section to the just-created release body and attaches the SBOM + provenance files for freshly-built pairs as release assets. Any human-written notes already in the release body are preserved.                               |
+| `complete`       | Branch-protection aggregator. Fails if any upstream job failed or was cancelled.                                                                                                                                                                                                                                                                                                                       |
 
 ## Mutable tags and restarts
 
-Per-architecture tags (`:<cli>-rust<key>-<arch>`) and multi-arch manifest lists (`:<cli>-rust<key>`) on Docker Hub are **mutable** — re-publishing a `(cli, rust base)` pair overwrites the tag in place. Reproducibility is anchored by the per-arch image content digest (what SEP-58 `bldimg` cites) and by the `builds.json` pins, not by tag stability.
+Per-architecture tags (`:<cli>-rust<key>-<arch>`) and multi-arch manifest lists (`:<cli>-rust<key>`) on Docker Hub are **mutable** — re-publishing a `(cli, rust base)` pair overwrites the tag in place. Reproducibility is anchored by the per-arch image content digest and by the `builds.json` pins, not by tag stability.
 
 Moving aliases (`:<cli>`, `:latest`) re-point each release.
 
diff --git a/scripts/release_pr_body.py b/scripts/release_pr_body.py
index 766f35b..60babff 100755
--- a/scripts/release_pr_body.py
+++ b/scripts/release_pr_body.py
@@ -44,10 +44,10 @@ def compose(
         f"https://github.com/{repo}/releases/new?tag={release_tag}"
         f"&title={release_tag.removeprefix('v')}&target={default_branch}\n\n"
         "The publish workflow fires on the release-published event and:\n"
-        "- Builds and pushes per-arch images for any new (cli, rust base) pairs; "
-        "existing pairs are skipped with a warning (per-arch tags are immutable)\n"
+        "- Builds and pushes per-arch images for every declared (cli, rust base) "
+        "pair; tags are mutable, so an existing tag is overwritten in place\n"
         "- Generates SLSA build provenance + SPDX SBOM attestations on each "
-        "newly-built image (buildx-native + GitHub-native chains)\n"
+        "built image (buildx-native + GitHub-native chains)\n"
         f"- Re-points the `:{version}` and (if newest) `:latest` aliases\n"
         "- Attaches the SBOM and provenance files to the new GitHub Release, "
         "with per-arch digests in the body"
diff --git a/tests/unit/test_release_pr_body.py b/tests/unit/test_release_pr_body.py
index ea627bf..378f2db 100644
--- a/tests/unit/test_release_pr_body.py
+++ b/tests/unit/test_release_pr_body.py
@@ -29,6 +29,14 @@ def test_refresh_title_and_body() -> None:
     assert "release/v26.0.0-1" in body
 
 
+def test_body_describes_mutable_publish_behavior() -> None:
+    _, body = _compose()
+    # Tags are mutable now — the body must not claim pairs are skipped/immutable.
+    assert "skipped" not in body
+    assert "immutable" not in body
+    assert "mutable" in body
+
+
 def test_body_carries_release_url_with_correct_target() -> None:
     _, body = _compose()
     assert "https://github.com/stellar/stellar-cli-docker/releases/new" in body

From 44d64953a9910da9dc51bdb0c17adf6c2a7b8746 Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Wed, 3 Jun 2026 19:36:18 -0700
Subject: [PATCH 7/8] Point release notes at the per-arch digest only.

---
 scripts/release_body.py         | 4 ++--
 tests/unit/test_release_body.py | 3 +++
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/scripts/release_body.py b/scripts/release_body.py
index 1874152..bb57c5f 100755
--- a/scripts/release_body.py
+++ b/scripts/release_body.py
@@ -70,8 +70,8 @@ def emit_body(*, cli: str, rows: list[dict], registry: str, repo: str, stellar_r
 
     p("\n## Per-architecture digests (for SEP-58 `bldimg`)\n")
     p(
-        f"Use the per-architecture digest when recording `bldimg` in your contract "
-        f"metadata. Never use a moving tag like `:latest` or `:{cli}`.\n"
+        "Use the per-architecture digest when recording `bldimg` in your contract "
+        "metadata. Never use a tag — only the per-arch digest is a stable reference.\n"
     )
 
     for tag in pins_newest_first(rows):
diff --git a/tests/unit/test_release_body.py b/tests/unit/test_release_body.py
index dfa0b39..543554e 100644
--- a/tests/unit/test_release_body.py
+++ b/tests/unit/test_release_body.py
@@ -117,6 +117,9 @@ def test_emit_body_includes_expected_sections() -> None:
     assert "docker buildx imagetools inspect" in body
     assert "## Verification" in body
     assert "## Assets" in body
+    # Every tag is mutable; only the per-arch digest is a stable bldimg reference.
+    assert "moving tag" not in body
+    assert "only the per-arch digest is a stable" in body
 
 
 def test_emit_body_two_labels_render_as_two_sections() -> None:

From 33bb3ed5baea8bbb93f629381f4711abf6c58a2c Mon Sep 17 00:00:00 2001
From: Nando Vieira <me@fnando.com>
Date: Mon, 8 Jun 2026 13:05:14 -0700
Subject: [PATCH 8/8] Fix release body type hint and stale schema note.

---
 builds.schema.json      | 2 +-
 scripts/release_body.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/builds.schema.json b/builds.schema.json
index cbd8475..05b116c 100644
--- a/builds.schema.json
+++ b/builds.schema.json
@@ -1,5 +1,5 @@
 {
-  "$comment": "JSON Schema for builds.json. Each rust_versions[] entry is a fully-qualified rust base pin, '<rust_base_key>@<image_digest>', so a release records the exact base it was built against. The same label may appear with two different digests across (or within) releases; the published tag carries a short digest fragment to keep each immutable.",
+  "$comment": "JSON Schema for builds.json. Each rust_versions[] entry is a fully-qualified rust base pin, '<rust_base_key>@<image_digest>', so a release records the exact base it was built against. The same label may appear with two different digests across (or within) releases; builds.json keeps the full history, but only the newest pin per label is published, under a label-only tag.",
   "$id": "https://github.com/stellar/stellar-cli-docker/builds.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "additionalProperties": false,
diff --git a/scripts/release_body.py b/scripts/release_body.py
index bb57c5f..fe81113 100755
--- a/scripts/release_body.py
+++ b/scripts/release_body.py
@@ -42,7 +42,7 @@ def list_tag(row: dict) -> str:
 
 def pins_newest_first(rows: list[dict]) -> list[str]:
     """Unique multi-arch list tags (one per base pin), ordered by version descending."""
-    seen: dict[str, tuple] = {}
+    seen: dict[str, semver.Version] = {}
     for row in rows:
         tag = list_tag(row)
         if tag not in seen: