build(docker): define every container base image in one config file (ADR-1231)

[lusoris]

Summary

Container base images were pinned by hand at every point of use, and the copies
drifted. Dockerfile.controller and Dockerfile.operator still built on
Debian 12 (golang:1.27-bookworm) and shipped on distroless/cc-debian12 /
distroless/static-debian12 long after the rest of the tree moved to Debian 13
— and both quoted a golang digest in their own header comments (ded31c68…)
that did not match the digest in their own FROM line (648f440f…). Two CUDA
pins sat on Ubuntu 24.04 beside a sibling stage already on 26.04.

Four more pins were not FROM lines at all. dev/Containerfile lifted the
Go toolchain out of a golang:1.27-bookworm image with COPY --from=<image>,
and docker/Dockerfile.node pulled the CUDA, ROCm and oneAPI runtime libraries
the same way. Those decide the libc and SDK the shipped artifact carries, but
they are invisible to anyone grepping for FROM — which is exactly why they
were the most out-of-date images in the repository.

build-config.env is now the single source of truth. No Dockerfile names a
base directly: each takes it as an ARG whose default mirrors the config, so a
plain docker build still works with no wrapper and CI can override any base
with --build-arg. COPY --from pins became named stages.
scripts/ci/check-base-image-single-source.sh fails on drift, on a
non-digest-pinned entry, and on a version knob that disagrees with its pin;
make base-images-sync rewrites the mirrors. Same authority-plus-drift-check
shape as check-default-model-single-source.sh.

Net: 25 FROM lines across 10 Dockerfiles collapse to 13 pins in one file.
Four Debian 12 pins and two Ubuntu 24.04 CUDA pins are gone; no live Debian 12
reference remains.

Behaviour change worth a reviewer's eye

vmafx-controller now runs as UID 65532 instead of root. Its old pin was
gcr.io/distroless/cc-debian12 without the :nonroot suffix; the shared
runtime pin is :nonroot. Rather than let the tag decide it silently, the
USER 65532:65532 line is written explicitly in the file. Both listen ports
(8080, 9090) are above 1024, so nothing needs a capability.

Why oneAPI and ROCm are still on 24.04

Both keep an explicit, self-closing exemption in the gate. Neither is a pin
swap:

• ROCm 7.2.4 → 10.0.0 is feat(hip): migrate every ROCm consumer to 10.0.0 from digest-pinned images (ADR-1225) #1386, which carries the matching HIP changes.
  Bumping a major GPU SDK here without them would be reckless. Target is
  rocm/dev-ubuntu-26.04:10.0.0-full.

• oneAPI 2025 → 2026.1 is a restructure. Measured, not assumed:

  • intel/oneapi-basekit is a retired repository (last tag 2025.3.2).
    Intel continued under the plain name intel/oneapi, now at 2026.1.0.
    Auditing the old name makes the toolchain look two years stale.
  • The SYCL soname moved: 2025.3.2 emits DT_NEEDED libsycl.so.8, 2026.x
    ships libsycl.so.9. A major soname bump is the ABI break, so both sides
    must cross together — the usual runtime ≥ compiler rule only holds while the
    soname is stable.
  • Intel's images can't supply a correct 2026 pair: intel/oneapi is at
    2026.1.0 but intel/oneapi-runtime stops at 2026.0.0 (runtime behind
    compiler), and both are Ubuntu-only — Ubuntu 26.04 is glibc 2.43, Debian
    13 is glibc 2.41, so a binary built in Intel's image cannot load on the
    Debian 13 runtime the release track ships.
  • Intel's apt repo on Debian 13 does work and was verified end to end:
    compiler and runtime both at 2026.1.1-325, libsycl.so.9 resolving.
  • But Intel's runtime image also ships the NEO GPU driver
    (libze_intel_gpu.so.1, OpenCL ICDs) which Debian does not package, so a
    naive move would ship a GPU image that can't see the GPU. The fork already
    solves this for dev via dev/scripts/fetch-intel-neo.py (ADR-1145).

  Folding that into this PR would have shipped a broken GPU image. It is the
  immediate follow-up; everything needed is in the digest.

Type

• build / ci — tooling / infra

Checklist

• Commits follow Conventional Commits (the commit-msg hook enforces this).
• make format && make lint is green locally.
• Unit tests pass: meson test -C build. — no C/C++ code touched; this PR changes container definitions, docs and a shell gate only.
• If I touched any SIMD/GPU code path, I ran /cross-backend-diff and the worst ULP is ≤ 2. — no SIMD/GPU code path touched.
• If I touched a feature extractor with SIMD/GPU twins, I either updated every twin or listed the gap under "Known follow-ups" below. — no feature extractor touched.
• If I added a new .c / .cpp / .cu / .h / .hpp, it has the appropriate license header (see CONTRIBUTING.md). — no new C/C++ sources.
• If this is a breaking change, the commit message uses ! or BREAKING CHANGE: and the migration path is documented below. — not a breaking change.
• If this PR adds an ADR, the ADR row lives in docs/adr/_index_fragments/<NNNN-slug>.md and the slug is appended to docs/adr/_index_fragments/_order.txt.

Bug-status hygiene (ADR-0165)

• docs/state.md updated in this PR with a row —
  T-DOCKER-BASE-IMAGE-DRIFT-2026-09-07 under Recently closed.

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.
• If I believe a golden value must change, I have explained why below AND pinged @lusoris for a CODEOWNERS exception. — no golden value changes.

Deep-dive deliverables (ADR-0108)

• Research digest — docs/research/1231-base-image-single-source.md: the drift inventory, the oneAPI soname/glibc/NEO measurements, and reproduction commands.
• Decision matrix — ADR-1231 ## Alternatives considered (config+ARG+gate vs. no-default ARGs vs. buildx bake vs. Renovate-only).
• AGENTS.md invariant note — added to both docker/AGENTS.md and dev/AGENTS.md.
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/changed/base-image-single-source.md (CHANGELOG.md regenerated via scripts/release/concat-changelog-fragments.sh --write).
• Rebase note — docs/rebase-notes.md, section ADR-1231 — container base images come from build-config.env (2026-09-07).

Reproducer

# The gate is clean, and the config round-trips byte-identically.
scripts/ci/check-base-image-single-source.sh          # -> OK (10 Dockerfiles, 13 pinned bases)
make base-images-sync                                 # -> no-op

# Drift is actually caught (not just asserted):
sed -i 's|^ARG RELEASE_GO_BASE=.*|ARG RELEASE_GO_BASE="golang:1.20-bookworm@sha256:dead…"|' docker/Dockerfile.operator
scripts/ci/check-base-image-single-source.sh          # -> fails, naming file + config value
scripts/ci/check-base-image-single-source.sh --write  # -> repairs it
git diff --quiet docker/Dockerfile.operator && echo "byte-identical"

# Every wired Dockerfile still parses and resolves its ARG-driven FROMs:
for f in Dockerfile Dockerfile.go-server dev/Containerfile docker/Dockerfile.*; do
  docker buildx build --check -f "$f" . ; done

# No live Debian 12 reference remains:
git grep -nE 'debian12|bookworm' -- . ':!docs/adr' ':!CHANGELOG.md' ':!changelog.d' \
    ':!docs/research' ':!docs/state.md'

Known follow-ups

1. oneAPI 2025 → 2026.1.1 — Intel apt on Debian 13 + NEO via
   fetch-intel-neo.py; renames the -oneapi2025 stage/tag. Removes the
   oneAPI half of the gate exemption.
2. ROCm 7.2.4 → 10.0.0 — feat(hip): migrate every ROCm consumer to 10.0.0 from digest-pinned images (ADR-1225) #1386. Now a one-line edit in build-config.env
   plus its HIP changes, rather than four Dockerfile edits.

🤖 Generated with Claude Code