CI: record per-target build identity (OID) on images

Foundation for skipping rebuilds of unchanged shell versions. Builds are
byte-reproducible and committed build checksums are the authoritative
output identity, so a content-addressed OID can decide when a target
cannot have changed and its prior-push image can be reused.

shvr.sh (inert — no caller behavior change):
- shvr_toolchain_fingerprint: hash of the global pins (musl-cross-make
  commit, RUST_TOOLCHAIN, DEBIAN_SNAPSHOT, TOOLCHAIN_BASE digest, ncurses,
  rustup-init) + an OIDV scheme tag; folded into every OID so a pin bump
  forces a full rebuild.
- shvr_build_identity <target>: sha256(fingerprint + the target's committed
  build checksums); prints MISSING (always rebuild) when none exist.
- shvr_build_identities, shvr_plan_matrix <file>: emit identities and the
  dynamic build-matrix JSON of missing/forced/mismatched targets. Verified
  to reproduce the committed static matrix exactly (250/250, no field drift).

CI (Step 1 — annotate while still building all 250):
- build-push-retry forwards new annotations/labels/provenance inputs.
- build job computes the OID and pushes each image with provenance:false +
  an org.shvr.oid annotation (and config label) so a later plan job can read
  it from the registry without pulling layers. No skipping yet.

Author: alganet

.github/actions/build-push-retry/action.yml

@@ -35,6 +35,18 @@ inputs:
     description: 'Cache export'
     required: false
     default: ''
+  labels:
+    description: 'Image labels (config-level); empty adds none'
+    required: false
+    default: ''
+  annotations:
+    description: 'OCI annotations (manifest-level); empty adds none'
+    required: false
+    default: ''
+  provenance:
+    description: 'Provenance attestation (true|false|mode=...); empty uses the action default'
+    required: false
+    default: ''
 runs:
   using: composite
   steps:
@@ -51,6 +63,9 @@ runs:
         build-args: ${{ inputs.build-args }}
         cache-from: ${{ inputs.cache-from }}
         cache-to: ${{ inputs.cache-to }}
+        labels: ${{ inputs.labels }}
+        annotations: ${{ inputs.annotations }}
+        provenance: ${{ inputs.provenance }}
     - name: Build and push (retry)
       if: steps.attempt1.outcome == 'failure'
       uses: docker/build-push-action@v7
@@ -63,3 +78,6 @@ runs:
         build-args: ${{ inputs.build-args }}
         cache-from: ${{ inputs.cache-from }}
         cache-to: ${{ inputs.cache-to }}
+        labels: ${{ inputs.labels }}
+        annotations: ${{ inputs.annotations }}
+        provenance: ${{ inputs.provenance }}

.github/workflows/docker.yml

@@ -162,6 +162,15 @@ jobs:
         with:
           driver-opts: image=${{ needs.mirror.outputs.buildkit_ref }}
 
+      # Content-addressed build identity for this target. Recorded on the image
+      # as an OCI annotation (+ config label) so a future `plan` job can skip
+      # rebuilding targets whose OID is unchanged. See shvr_build_identity.
+      - name: Compute build identity (OID)
+        id: oid
+        env:
+          TARGET: ${{ matrix.target }}
+        run: echo "oid=$(sh shvr.sh build_identity "$TARGET")" >> "$GITHUB_OUTPUT"
+
       - name: Build and push shell image
         uses: ./.github/actions/build-push-retry
         with:
@@ -182,6 +191,13 @@ jobs:
             ${{ github.event_name == 'push'
               && format('type=registry,ref=ghcr.io/{0}:buildcache-{1},mode=max', github.repository, matrix.target)
               || '' }}
+          # Single-manifest image so the OID annotation sits at the manifest top
+          # level, readable via `imagetools inspect --raw` without pulling layers.
+          provenance: false
+          annotations: |
+            manifest:org.shvr.oid=${{ steps.oid.outputs.oid }}
+          labels: |
+            org.shvr.oid=${{ steps.oid.outputs.oid }}
 
       - name: Verify build checksums
         uses: ./.github/actions/verify-build-checksums

shvr.sh

@@ -724,4 +724,117 @@ shvr_github_regen_all ()
 	(shvr_github_regen_docker_workflow)
 }
 
+# Toolchain fingerprint: a hash of every globally-pinned reproducibility input
+# (musl-cross-make commit, Rust toolchain, Debian snapshot, base image digest,
+# ncurses, rustup-init). It is folded into every target's build identity, so
+# bumping any pin changes all identities and forces a full rebuild. Bump the
+# OIDV scheme tag to force a rebuild without touching a pin.
+shvr_toolchain_fingerprint ()
+{
+	. "${SHVR_DIR_SELF}/common/musl-cross-make.sh"
+	. "${SHVR_DIR_SELF}/common/ncurses.sh"
+
+	dockerfile="${SHVR_DIR_SELF}/Dockerfile"
+	fp_rust="$(grep -m1 'ARG RUST_TOOLCHAIN=' "$dockerfile" | sed 's/.*=//')"
+	fp_snap="$(grep -m1 'ARG DEBIAN_SNAPSHOT=' "$dockerfile" | sed 's/.*=//')"
+	fp_tbase="$(grep -m1 'ARG TOOLCHAIN_BASE=' "$dockerfile" | sed 's/.*=//')"
+	fp_rustup="$(grep -oE 'rustup-init-[0-9][0-9.]*\.sh' "$dockerfile" | head -n1)"
+
+	{
+		printf 'OIDV=1\n'
+		printf 'MCM=%s\n' "$SHVR_MCM_COMMIT"
+		printf 'RUST=%s\n' "$fp_rust"
+		printf 'SNAP=%s\n' "$fp_snap"
+		printf 'TBASE=%s\n' "$fp_tbase"
+		printf 'NCURSES=%s\n' "$SHVR_NCURSES_VERSION"
+		printf 'RUSTUP=%s\n' "$fp_rustup"
+	} | sha256sum | cut -d' ' -f1
+}
+
+# Build identity (OID) for one target: a hash of the toolchain fingerprint plus
+# the target's committed build checksums. Because builds are byte-reproducible
+# and the build-checksum verify gate keeps committed checksums in sync with the
+# intended binary, the OID changes if and only if the binary should change.
+# Prints MISSING (and warns) when no committed checksums exist, so such a target
+# is always (re)built and never wrongly skipped. Pass a precomputed fingerprint
+# as $2 to avoid recomputing it per target.
+shvr_build_identity ()
+{
+	target="$1"
+	fingerprint="${2:-$(shvr_toolchain_fingerprint)}"
+	dir="${SHVR_CHECKSUMS_DIR}/build/${target}"
+
+	if ! test -d "$dir"
+	then
+		echo "shvr_build_identity: no build checksums for ${target} at ${dir}" >&2
+		echo MISSING
+		return 0
+	fi
+
+	{
+		printf '%s\n' "$fingerprint"
+		find "$dir" -name '*.sha256sums' | LC_ALL=C sort | while IFS= read -r f
+		do cat "$f"
+		done
+	} | sha256sum | cut -d' ' -f1
+}
+
+# Emit "<target> <oid>" for every target (or the targets passed as arguments).
+shvr_build_identities ()
+{
+	if test -z "$*"
+	then set -- $(printf '%s ' $(shvr_targets))
+	fi
+	fingerprint="$(shvr_toolchain_fingerprint)"
+	for bi_target in "$@"
+	do
+		printf '%s %s\n' "$bi_target" "$(shvr_build_identity "$bi_target" "$fingerprint")"
+	done
+}
+
+# Print the dynamic GitHub Actions build matrix (JSON) of targets that must be
+# (re)built. Reads "<target> <current-oid>" lines from <registry_oid_file> (the
+# OID currently published for each target, or MISSING/FORCE), compares against
+# the freshly computed desired OID, and includes any target that is missing,
+# forced, or mismatched. Does no network I/O: the registry read happens in the
+# workflow and is passed in as a file.
+shvr_plan_matrix ()
+(
+	registry_file="$1"
+	fingerprint="$(shvr_toolchain_fingerprint)"
+
+	# Slurp to a real file so it is re-readable per target (handles /dev/stdin).
+	reg="${TMPDIR:-/tmp}/shvr_plan.$$"
+	trap 'rm -f "$reg"' EXIT INT TERM
+	cat "$registry_file" > "$reg"
+
+	printf '{"include":['
+	first=1
+	for target in $(shvr_targets)
+	do
+		desired="$(shvr_build_identity "$target" "$fingerprint")"
+		current="$(awk -v t="$target" '$1 == t {print $2; exit}' "$reg")"
+
+		# Skip only when the published OID matches and is a real identity.
+		if test "$desired" != MISSING && test "x$current" = "x$desired"
+		then continue
+		fi
+
+		shvr_clear_versioninfo
+		interpreter="${target%%_*}"
+		version="${target#*_}"
+		. "${SHVR_DIR_SELF}/variants/${interpreter}.sh"
+		"shvr_versioninfo_${interpreter}" "$version"
+		cache_path="${build_srcdir#${SHVR_DIR_SRC}/}"
+
+		if test "$first" = 1
+		then first=0
+		else printf ','
+		fi
+		printf '{"target":"%s","shell":"%s","version":"%s","cache_path":"%s","oid":"%s"}' \
+			"$target" "$interpreter" "$version" "$cache_path" "$desired"
+	done
+	printf ']}\n'
+)
+
 shvr "${@:-}"