diff --git a/AGENTS.md b/AGENTS.md index 92965df25..6655a3775 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,7 +58,7 @@ checks (`scripts/check-skill-frontmatter.sh`, `scripts/check-skill-index.sh`, before editing it: sources arrive in as few COPYs as origins allow, small RUN steps fold into neighbours, and per-image ARGs are declared late because an ARG is part of the cache key of every layer below it. -- **The kernel cache tag** is a hash of `Containerfile.kernel`'s base image, +- **The kernel cache tag** is a hash of `Containerfile.kernel` (whole file), `scripts/install-ogc-kernel.sh`, `scripts/install-nvidia.sh`, and `packages/hummingbird.repo` (`scripts/kernel-cache-tag.sh`). Any edit to those files — comments included — forces a ~45-minute cache rebuild. That is diff --git a/docs/skills/index.json b/docs/skills/index.json index a94b71151..f11bec450 100644 --- a/docs/skills/index.json +++ b/docs/skills/index.json @@ -1,5 +1,5 @@ { - "generated_at": "2026-09-18", + "generated_at": "2026-09-19", "schema_version": "1.0", "skills": [ { @@ -88,7 +88,7 @@ ], "description": "The kernel cache image, its content-hash tag, and unpack-or-compile behavior. Use when touching install-ogc-kernel.sh, install-nvidia.sh, Containerfile.kernel, or debugging flavored builds.", "version": "1.0", - "last_updated": "2026-09-05", + "last_updated": "2026-09-19", "doc_type": "reference" }, { diff --git a/docs/skills/index.md b/docs/skills/index.md index c62b2f2eb..d3800c2cb 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -3,7 +3,7 @@ This file is a human-readable mirror of `index.json`. Both are generated by `scripts/generate_skill_index.py` — do not hand-edit either file. -Generated: 2026-09-18 · schema 1.0 · 8 skills +Generated: 2026-09-19 · schema 1.0 · 8 skills | id | category | status | one-line purpose | |---|---|---|---| diff --git a/docs/skills/kernel-cache.md b/docs/skills/kernel-cache.md index 2dab3d3c0..b48397b3a 100644 --- a/docs/skills/kernel-cache.md +++ b/docs/skills/kernel-cache.md @@ -1,7 +1,7 @@ --- name: kernel-cache version: "1.0" -last_updated: "2026-09-05" +last_updated: "2026-09-19" id: kernel-cache one_line_purpose: Understand and rebuild the OGC kernel and NVIDIA module cache image. entry_point: docs/skills/kernel-cache.md @@ -48,21 +48,31 @@ The tag must change whenever anything the cache image contains would change, and not otherwise, so it is a hash of exactly those inputs (header comment, `scripts/kernel-cache-tag.sh`): -- The `ARG BASE_IMAGE=` line of `Containerfile.kernel` -- the base image the - cache is built from. +- `Containerfile.kernel`, whole file -- the recipe that builds the cache. Its + `ARG BASE_IMAGE=` line names the base image, but its body is what decides + what the image ends up containing: the repo files copied into the builder, + and the single `RUN` that fills `/cache-out`, and the final stage's + `COPY --from=builder`. Hashing only the `ARG` line would leave an edit to + any of that invisible to the key, and since CI builds the cache image only + when its tag is not already published, the three cached flavors would + silently take an image built from the previous recipe. - `scripts/install-ogc-kernel.sh` and `scripts/install-nvidia.sh`, whole files, comments included -- the two scripts that do the building. - `packages/hummingbird.repo` and `packages/fedora-44.repo` -- the repositories the toolchain comes from (Fedora 44 is builder-only); a different compiler produces a different kernel. -Editing either script changes the hash and forces a rebuild, comment-only +Editing any of them changes the hash and forces a rebuild, comment-only edits included. That is deliberate: the key can only ever rebuild something that did not need rebuilding, never reuse something stale. A cheaper key that hashed just the version pins would miss a change to how the kernel is configured or how the module is linked (header comment, `scripts/kernel-cache-tag.sh`). +`tests/test_kernel_cache_tag.py` holds the key to that contract: it asserts +that mutating a non-`ARG` line of `Containerfile.kernel`, or any of the four +other hashed files, moves the tag. + The `BASE_IMAGE` in `Containerfile.kernel` must match the one in `Containerfile`, or the prebuilt NVIDIA module would be linked against a kernel the image never boots. Two literals, one invariant, so `just check` diff --git a/scripts/kernel-cache-tag.sh b/scripts/kernel-cache-tag.sh index 3983d3378..f236e56d7 100755 --- a/scripts/kernel-cache-tag.sh +++ b/scripts/kernel-cache-tag.sh @@ -2,19 +2,27 @@ # The tag under which the kernel cache image is published. # # It must change whenever anything the cache image contains would change, and -# not otherwise. Those inputs are the base image it is built from, the two -# scripts that do the building, and the repositories the toolchain comes from -- -# a different compiler produces a different kernel -- so the tag is a hash of +# not otherwise. Those inputs are the recipe that builds it, the two scripts +# that do the building, and the repositories the toolchain comes from -- a +# different compiler produces a different kernel -- so the tag is a hash of # exactly those. # -# Hashing the whole scripts, comments included, is deliberate: it can only ever +# Containerfile.kernel is hashed whole, not just its ARG BASE_IMAGE= line: its +# body is the recipe. The single RUN decides what lands in /cache-out and the +# final stage decides what is copied out of the builder, so an edit there +# changes the image's contents while leaving the base pin untouched. Since CI +# builds the cache image only when its tag is not already published, a key that +# missed those edits would silently hand the three cached flavors an image +# built from the previous recipe. +# +# Hashing the whole files, comments included, is deliberate: it can only ever # rebuild something that did not need rebuilding, never reuse something stale. # A cheaper key that hashed just the version pins would miss a change to how # the kernel is configured or how the module is linked. set -euo pipefail cd "$(dirname "$0")/.." { - grep -m1 '^ARG BASE_IMAGE=' Containerfile.kernel + cat Containerfile.kernel cat scripts/install-ogc-kernel.sh scripts/install-nvidia.sh cat packages/hummingbird.repo packages/fedora-44.repo } | sha256sum | cut -c1-16 diff --git a/tests/test_kernel_cache_tag.py b/tests/test_kernel_cache_tag.py new file mode 100644 index 000000000..76392b5ee --- /dev/null +++ b/tests/test_kernel_cache_tag.py @@ -0,0 +1,126 @@ +"""The kernel cache tag must move whenever the cache image's contents would. + +CI builds and pushes the cache image only when `just kernel-cache-tag` names a +tag that is not already published, and the gaming, nvidia and nvidia-gaming +builds take that image as their BASE_IMAGE. So a key that misses an input does +not fail anything -- it hands those three flavors an image built from the +previous recipe, and the only symptom is a kernel build that did not happen. + +These tests copy the repository's hashed inputs into a scratch tree, mutate one +at a time, and assert the tag changes. The mutations are deliberately shallow +(a trailing comment) because the contract is "any edit, comments included", not +"any semantically significant edit". +""" + +from __future__ import annotations + +import shutil +import subprocess +import tempfile +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +SCRIPT = ROOT / "scripts" / "kernel-cache-tag.sh" + +# Every file the tag is required to cover, relative to the repository root. +HASHED_INPUTS = ( + "Containerfile.kernel", + "scripts/install-ogc-kernel.sh", + "scripts/install-nvidia.sh", + "packages/hummingbird.repo", + "packages/fedora-44.repo", +) + + +def tag_of(root: Path) -> str: + """Run the real script against `root` and return the tag it prints.""" + result = subprocess.run( + ["bash", str(root / "scripts" / "kernel-cache-tag.sh")], + capture_output=True, + text=True, + ) + if result.returncode != 0: + raise AssertionError(f"kernel-cache-tag.sh failed:\n{result.stderr}") + return result.stdout.strip() + + +class KernelCacheTagTests(unittest.TestCase): + def setUp(self): + tmp = tempfile.TemporaryDirectory() + self.addCleanup(tmp.cleanup) + self.root = Path(tmp.name) / "utah" + (self.root / "scripts").mkdir(parents=True) + (self.root / "packages").mkdir(parents=True) + shutil.copy2(SCRIPT, self.root / "scripts" / "kernel-cache-tag.sh") + for rel in HASHED_INPUTS: + shutil.copy2(ROOT / rel, self.root / rel) + self.baseline = tag_of(self.root) + + def test_tag_is_a_short_stable_hex_digest(self): + self.assertRegex(self.baseline, r"^[0-9a-f]{16}$") + self.assertEqual(self.baseline, tag_of(self.root), "tag is not deterministic") + + def test_tag_matches_the_real_repository(self): + """The scratch tree reproduces the tag the repository itself produces.""" + self.assertEqual(self.baseline, tag_of(ROOT)) + + def test_every_hashed_input_moves_the_tag(self): + for rel in HASHED_INPUTS: + with self.subTest(input=rel): + path = self.root / rel + original = path.read_text() + path.write_text(original + "\n# cache-key probe\n") + self.addCleanup(path.write_text, original) + self.assertNotEqual( + self.baseline, + tag_of(self.root), + f"editing {rel} left the kernel cache tag unchanged, so CI would " + f"reuse the previously published cache image", + ) + path.write_text(original) + + def test_containerfile_recipe_body_moves_the_tag(self): + """A recipe edit that leaves `ARG BASE_IMAGE=` alone must still rotate. + + Hashing only the `ARG BASE_IMAGE=` line was the original defect: the + single RUN decides what lands in /cache-out and the final stage decides + what is copied out, and neither is on that line. + """ + path = self.root / "Containerfile.kernel" + original = path.read_text() + self.assertIn("/cache-out", original) + mutated = original.replace("/cache-out", "/cache-out-probe") + self.assertNotEqual(original, mutated) + + arg_line = "ARG BASE_IMAGE=" + before = [ln for ln in original.splitlines() if ln.startswith(arg_line)] + after = [ln for ln in mutated.splitlines() if ln.startswith(arg_line)] + self.assertEqual(before, after, "probe must not touch the base image pin") + + path.write_text(mutated) + self.addCleanup(path.write_text, original) + self.assertNotEqual( + self.baseline, + tag_of(self.root), + "a Containerfile.kernel recipe change that leaves ARG BASE_IMAGE= " + "alone did not change the tag, so the published cache image would " + "be reused for a recipe that no longer builds it", + ) + + def test_base_image_pin_still_moves_the_tag(self): + """Widening the key must not drop what it already covered.""" + path = self.root / "Containerfile.kernel" + original = path.read_text() + mutated = "\n".join( + line.replace("sha256:", "sha256:0") if line.startswith("ARG BASE_IMAGE=") else line + for line in original.splitlines() + ) + self.assertNotEqual(original, mutated, "no ARG BASE_IMAGE= digest to mutate") + path.write_text(mutated + "\n") + self.addCleanup(path.write_text, original) + self.assertNotEqual(self.baseline, tag_of(self.root)) + + +if __name__ == "__main__": + unittest.main()