From bc5b7962f7581c22cdeada4811ffcc43c681cc4b Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 06:41:54 +0000 Subject: [PATCH 01/11] feat(parity): compare the built image with Bluefin's image, not list with list packages/bluefin.toml is the list Bluefin asks for. It never names what Bluefin's Silverblue base already had before that list was applied, and that is exactly where the parity gaps that reached users have been hiding: glibc-all-langpacks (#114), linux-firmware and the iwlwifi blobs (#97). A diff of two package lists cannot see any of it. Only the two images can. Bluefin's side needs no pull. Every Bluefin image is rechunked, and the rechunker writes the full installed inventory -- 1818 names with versions on today's :stable -- into the manifest annotation dev.hhd.rechunk.info. One anonymous registry GET returns it. Utah's side is rpm -qa where the check runs: inside the image build, right after the flavor-aware contract check, so every flavor is compared on what it actually installed. scripts/check-image-parity.py reads the annotation (following a multi-arch index to linux/amd64 when there is one), compares by name, and reports every name Bluefin has that this image lacks. A name is explained when utah.toml lists it under [unavailable] or packages/parity-exceptions.toml gives a reason; the report prints the reason so a build log reads as a decision and not a mystery. The exceptions file starts with the three akmods names, the one difference this tree already documents as deliberate (NVIDIA_PACKAGES in verify-rpm-contract.py). Report-only in the build for now: the first run's report is what the exceptions list will be built from, and --strict turns an unexplained gap into a build failure after that. Both the inventory and the report ship in the image under /usr/share/utah, so any published image can be asked what it has, and just check-image-parity IMAGE runs the strict comparison against a built image locally. An unreachable registry is a failure of the check, not evidence about the image: it prints, writes the reason as the report, and fails only under --strict. Verified: the live path was exercised against ghcr.io/ublue-os/bluefin:stable from here (1818 packages read from the annotation, 6 of the contract's [unavailable] names correctly explained); 12 offline tests cover the manifest reading, index following, comparison, exceptions and exit codes; every RUN block in the Containerfile parses as bash once joined the way the Dockerfile parser joins it; the skill index is regenerated; 108 tests pass. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M --- Containerfile | 8 +- Justfile | 7 + docs/skills/ci-workflows.md | 4 + docs/skills/index.json | 1 + docs/skills/package-contract.md | 25 +++ packages/parity-exceptions.toml | 27 ++++ scripts/check-image-parity.py | 260 ++++++++++++++++++++++++++++++++ tests/test_image_parity.py | 160 ++++++++++++++++++++ 8 files changed, 490 insertions(+), 2 deletions(-) create mode 100644 packages/parity-exceptions.toml create mode 100755 scripts/check-image-parity.py create mode 100644 tests/test_image_parity.py diff --git a/Containerfile b/Containerfile index 250c154b6..b46a54352 100644 --- a/Containerfile +++ b/Containerfile @@ -39,7 +39,7 @@ FROM ${BASE_IMAGE} # transaction reads. These, the pinned package image and the install script # are the whole input to the expensive layer, so everything else waits its # turn below them. -COPY packages/bluefin.toml packages/utah.toml contracts/bluefin-desktop.toml /usr/share/utah/ +COPY packages/bluefin.toml packages/utah.toml packages/parity-exceptions.toml contracts/bluefin-desktop.toml /usr/share/utah/ COPY packages/hummingbird.repo packages/nvidia-container.repo packages/utah-packages.repo /etc/yum.repos.d/ # Hummingbird signs its RPMs with Red Hat's release key 2 (fd431d51); the key # lets packages/hummingbird.repo run with gpgcheck=1 here and in the live ISO @@ -68,6 +68,7 @@ COPY scripts/install-packages.py \ scripts/verify-desktop-contract.py \ scripts/verify-gnome-extensions.py \ scripts/mirror-shim.sh \ + scripts/check-image-parity.py \ /tmp/utah-scripts/ # Common publishes Bluefin artwork, desktop defaults, Brewfiles, and setup # hooks in a separate profile from its shared system files. Both are required: @@ -89,7 +90,8 @@ RUN for pair in install-packages.py:utah-install-packages \ configure-branding.sh:utah-configure-branding \ verify-desktop-contract.py:utah-verify-desktop-contract \ verify-gnome-extensions.py:utah-verify-gnome-extensions \ - mirror-shim.sh:utah-mirror-shim; do \ + mirror-shim.sh:utah-mirror-shim \ + check-image-parity.py:utah-check-image-parity; do \ install -Dm 0755 "/tmp/utah-scripts/${pair%%:*}" "/usr/local/libexec/${pair##*:}" || exit 1; \ done && \ cp -a /tmp/utah-common/. / && \ @@ -199,6 +201,8 @@ RUN --mount=type=bind,from=packages,source=/repository,target=/etc/utah-packages esac && \ IMAGE_FLAVOR="${IMAGE_FLAVOR}" /usr/local/libexec/utah-verify-rpm-contract \ /usr/share/utah/bluefin.toml /usr/share/utah/utah.toml && \ + rpm -qa --qf '%{NAME}\t%{VERSION}-%{RELEASE}\n' | sort > /usr/share/utah/packages.txt && \ + /usr/local/libexec/utah-check-image-parity --report /usr/share/utah/parity-report.txt && \ # The package repository is now only ever bind mounted, so it is absent from # the committed image. Flip it disabled here -- the last step that installs # anything -- so later dnf calls on the image (the live ISO build's included) diff --git a/Justfile b/Justfile index 627b44fd6..948942f77 100644 --- a/Justfile +++ b/Justfile @@ -184,6 +184,13 @@ check-parity: exit 1 fi +# Compare a built image's installed RPMs with Bluefin's, by name. Bluefin's +# inventory is read from its manifest annotation, so nothing is pulled but the +# image under test, which is usually already local. +check-image-parity image bluefin="ghcr.io/ublue-os/bluefin:stable": + podman run --rm --entrypoint /usr/local/libexec/utah-check-image-parity \ + "{{image}}" --strict --bluefin-image "{{bluefin}}" + image_name base_name stream flavor: #!/usr/bin/env bash set -euo pipefail diff --git a/docs/skills/ci-workflows.md b/docs/skills/ci-workflows.md index 6ddf5c35a..af044f40d 100644 --- a/docs/skills/ci-workflows.md +++ b/docs/skills/ci-workflows.md @@ -53,6 +53,10 @@ opaque `exit status 71` from the image build (comment, and the ban on flavor literals in workflows. - `just check-parity` -- `packages/bluefin.toml` against Bluefin's upstream pinned at `packages/.bluefin-parity-ref`. + That is list against list. The image build itself runs + `utah-check-image-parity`, which compares the installed RPM set with the + inventory Bluefin's image publishes in its manifest, and writes the report + to `/usr/share/utah/parity-report.txt` in the image (report-only today). - `just check-repos` -- the complete installation transaction against the digest-pinned base and package repository, including extension build tools. diff --git a/docs/skills/index.json b/docs/skills/index.json index 6641f793a..2a4deacb6 100644 --- a/docs/skills/index.json +++ b/docs/skills/index.json @@ -1,4 +1,5 @@ { + "schema_version": "1.0", "skills": [ { diff --git a/docs/skills/package-contract.md b/docs/skills/package-contract.md index 2b1dab1c7..846e19389 100644 --- a/docs/skills/package-contract.md +++ b/docs/skills/package-contract.md @@ -161,6 +161,31 @@ Current counts, per the README "Package parity" section: 61 Bluefin contract packages installed, 12 Utah additions (GNOME 51, desktop services), 4 genuinely unavailable. +## Image-level parity + +`packages/bluefin.toml` is the list Bluefin *asks* for. It never names what +Bluefin's Silverblue base already had before that list was applied, and that +is where the gaps that reached users hid: `glibc-all-langpacks` (#114), +`linux-firmware` and the iwlwifi blobs (#97). A list-to-list diff cannot see +them; only the two images can. + +`scripts/check-image-parity.py` runs inside the image build after the last +package step. It reads Bluefin's complete inventory from the +`dev.hhd.rechunk.info` annotation every rechunked Bluefin image carries (one +registry GET, no pull), compares it with `rpm -qa` by name, and reports every +name Bluefin has that this image lacks. A name is explained if `utah.toml` +lists it under `[unavailable]` or `packages/parity-exceptions.toml` gives a +reason for it; the report prints the reason. Both the inventory and the report +ship in the image under `/usr/share/utah/`. + +- Report-only in the build today. `--strict` fails on an unexplained gap; it + is turned on once the exceptions file covers the deliberate differences. +- `just check-image-parity IMAGE` runs the strict comparison against a built + image locally. +- Add to `parity-exceptions.toml` only a difference that is deliberate, with + a reason written for the person reading a build log. A real gap goes to + `utah.toml` with a tracking issue, like every `[unavailable]` entry. + ## Verification ```bash diff --git a/packages/parity-exceptions.toml b/packages/parity-exceptions.toml new file mode 100644 index 000000000..c92f62b89 --- /dev/null +++ b/packages/parity-exceptions.toml @@ -0,0 +1,27 @@ +# Packages Bluefin's image installs that Utah's does not, on purpose. +# +# scripts/check-image-parity.py compares this image's rpm -qa with the +# inventory Bluefin's image publishes in its manifest, and reports every name +# Bluefin has that Utah lacks. A name listed under [unavailable] in utah.toml +# is already explained there. Everything else that is a deliberate difference +# rather than a gap belongs here, with the reason -- the report prints it, so +# write it for the person reading a build log. +# +# pattern is a shell glob matched against the package name. Keep each entry +# as narrow as the reason allows: a broad pattern hides the next real gap. + +[[exception]] +pattern = "ublue-os-akmods-addons" +reason = """ +Universal Blue's akmods bundle publishes nothing for Hummingbird's kernel, so +none of its packages can be installed here; NVIDIA is built from source by +install-nvidia.sh instead (see NVIDIA_PACKAGES in verify-rpm-contract.py). +""" + +[[exception]] +pattern = "kmod-v4l2loopback" +reason = "Out-of-tree module from the ublue akmods bundle, which has no Hummingbird kernel build." + +[[exception]] +pattern = "kmod-zfs" +reason = "Out-of-tree module from the ublue akmods bundle, which has no Hummingbird kernel build." diff --git a/scripts/check-image-parity.py b/scripts/check-image-parity.py new file mode 100755 index 000000000..fd5eb1ee3 --- /dev/null +++ b/scripts/check-image-parity.py @@ -0,0 +1,260 @@ +#!/usr/bin/env python3 +"""Compare what this image installed against what Bluefin's image installed. + +packages/bluefin.toml is a copy of the list Bluefin *asks* for. It says nothing +about what Bluefin's base image already had before that list was applied, and +that is where the parity gaps that reach users have been hiding: Bluefin's +Silverblue base ships glibc-all-langpacks, linux-firmware and the iwlwifi +blobs, so its package list never names them, so Utah's contract never named +them either, so Hummingbird's much smaller base never supplied them (#97, +#114). A list-to-list comparison cannot see any of that. Only the two images +can. + +Bluefin's side needs no pull. Every Bluefin image is rechunked, and the +rechunker writes the complete installed inventory -- every RPM name and its +version -- into the manifest annotation dev.hhd.rechunk.info. One anonymous +registry GET returns it. Utah's side is rpm -qa, run where this script runs: +inside the image build, after the last package step. + +The comparison is by name. A name Bluefin has that this image does not is a +gap, unless packages/utah.toml already documents it under [unavailable] or +packages/parity-exceptions.toml explains it. Without --strict the result is a +report; with --strict an unexplained gap fails the build. +""" + +from __future__ import annotations + +import argparse +import fnmatch +import json +import subprocess +import sys +import tomllib +import urllib.error +import urllib.parse +import urllib.request +from dataclasses import dataclass, field +from pathlib import Path +from typing import Callable + +DEFAULT_BLUEFIN_IMAGE = "ghcr.io/ublue-os/bluefin:stable" +RECHUNK_ANNOTATION = "dev.hhd.rechunk.info" +MANIFEST_TYPES = ", ".join( + [ + "application/vnd.oci.image.index.v1+json", + "application/vnd.oci.image.manifest.v1+json", + "application/vnd.docker.distribution.manifest.list.v2+json", + "application/vnd.docker.distribution.manifest.v2+json", + ] +) + +Fetch = Callable[[str, dict[str, str]], bytes] + + +def http_get(url: str, headers: dict[str, str]) -> bytes: + request = urllib.request.Request(url, headers=headers) + with urllib.request.urlopen(request, timeout=60) as response: + return response.read() + + +def parse_image_ref(ref: str) -> tuple[str, str, str]: + """Split registry/repository:tag (or @digest) into its three parts.""" + if "@" in ref: + name, reference = ref.split("@", 1) + elif ":" in ref.rsplit("/", 1)[-1]: + name, reference = ref.rsplit(":", 1) + else: + name, reference = ref, "latest" + registry, _, repository = name.partition("/") + if not repository or ("." not in registry and ":" not in registry): + raise ValueError(f"image reference needs an explicit registry: {ref}") + return registry, repository, reference + + +def bluefin_inventory(ref: str, fetch: Fetch = http_get) -> dict[str, str]: + """Package name -> version-release for a rechunked image, read from its manifest.""" + registry, repository, reference = parse_image_ref(ref) + # ghcr.io grants anonymous pull tokens for public packages; other + # registries answer the manifest request directly. + headers = {"Accept": MANIFEST_TYPES} + if registry == "ghcr.io": + token_url = f"https://ghcr.io/token?scope=repository:{repository}:pull" + token = json.loads(fetch(token_url, {}))["token"] + headers["Authorization"] = f"Bearer {token}" + base = f"https://{registry}/v2/{repository}/manifests/" + manifest = json.loads(fetch(base + urllib.parse.quote(reference, safe=":"), headers)) + if "manifests" in manifest: + # A multi-arch index: the annotation lives on the per-arch manifest. + for entry in manifest["manifests"]: + platform = entry.get("platform", {}) + if platform.get("architecture") == "amd64" and platform.get("os") == "linux": + manifest = json.loads(fetch(base + entry["digest"], headers)) + break + else: + raise ValueError(f"{ref}: no linux/amd64 manifest in the index") + annotation = manifest.get("annotations", {}).get(RECHUNK_ANNOTATION) + if not annotation: + raise ValueError( + f"{ref} carries no {RECHUNK_ANNOTATION} annotation; " + "only a rechunked image publishes its inventory this way" + ) + packages = json.loads(annotation).get("packages") + if not isinstance(packages, dict) or not packages: + raise ValueError(f"{ref}: {RECHUNK_ANNOTATION} has no package inventory") + return dict(packages) + + +def installed_inventory() -> dict[str, str]: + out = subprocess.run( + ["rpm", "-qa", "--qf", "%{NAME}\t%{VERSION}-%{RELEASE}\n"], + check=True, + capture_output=True, + text=True, + ).stdout + return parse_rpm_list(out) + + +def parse_rpm_list(text: str) -> dict[str, str]: + """Accept either NAMEVERSION lines or bare NAME lines.""" + inventory: dict[str, str] = {} + for line in text.splitlines(): + line = line.strip() + if not line or line.startswith("gpg-pubkey"): + continue + name, _, version = line.partition("\t") + inventory[name] = version + return inventory + + +@dataclass +class Exception_: + pattern: str + reason: str + + +def load_exceptions(path: Path) -> list[Exception_]: + if not path.exists(): + return [] + data = tomllib.loads(path.read_text()) + exceptions = [] + for entry in data.get("exception", []): + if not entry.get("pattern") or not entry.get("reason"): + raise ValueError(f"{path}: every [[exception]] needs a pattern and a reason") + exceptions.append(Exception_(entry["pattern"], entry["reason"].strip())) + return exceptions + + +def unavailable_names(overlay: Path) -> set[str]: + if not overlay.exists(): + return set() + data = tomllib.loads(overlay.read_text()) + return set(data.get("unavailable", {}).get("packages", [])) + + +@dataclass +class Comparison: + missing: list[str] = field(default_factory=list) + explained: list[tuple[str, str]] = field(default_factory=list) + extra: list[str] = field(default_factory=list) + + +def compare( + bluefin: dict[str, str], + utah: dict[str, str], + unavailable: set[str], + exceptions: list[Exception_], +) -> Comparison: + result = Comparison() + for name in sorted(bluefin): + if name in utah: + continue + if name in unavailable: + result.explained.append((name, "documented under [unavailable] in utah.toml")) + continue + for exc in exceptions: + if fnmatch.fnmatchcase(name, exc.pattern): + result.explained.append((name, exc.reason)) + break + else: + result.missing.append(name) + result.extra = sorted(name for name in utah if name not in bluefin) + return result + + +def render(ref: str, bluefin: dict[str, str], utah: dict[str, str], result: Comparison) -> str: + lines = [ + f"image parity against {ref}", + f" Bluefin installs {len(bluefin)} packages, this image {len(utah)}", + f" in Bluefin, not here, unexplained: {len(result.missing)}", + f" in Bluefin, not here, explained: {len(result.explained)}", + f" here, not in Bluefin: {len(result.extra)}", + ] + if result.missing: + lines.append("") + lines.append("UNEXPLAINED -- in Bluefin's image and not in this one:") + lines += [f" {name} ({bluefin[name]})" for name in result.missing] + if result.explained: + lines.append("") + lines.append("explained:") + lines += [f" {name}: {reason}" for name, reason in result.explained] + if result.extra: + lines.append("") + lines.append("only here (informational; Hummingbird's base and Utah's overlay):") + lines += [f" {name}" for name in result.extra] + return "\n".join(lines) + "\n" + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) + parser.add_argument("--bluefin-image", default=DEFAULT_BLUEFIN_IMAGE) + parser.add_argument( + "--bluefin-inventory", + type=Path, + help="JSON {name: version} to use instead of reading the registry", + ) + parser.add_argument( + "--rpm-list", + type=Path, + help="NAME or NAMEVERSION per line, instead of running rpm -qa here", + ) + parser.add_argument("--overlay", type=Path, default=Path("/usr/share/utah/utah.toml")) + parser.add_argument( + "--exceptions", type=Path, default=Path("/usr/share/utah/parity-exceptions.toml") + ) + parser.add_argument("--report", type=Path, help="also write the report here") + parser.add_argument( + "--strict", action="store_true", help="exit 1 when an unexplained gap remains" + ) + args = parser.parse_args(argv) + + try: + if args.bluefin_inventory: + bluefin = json.loads(args.bluefin_inventory.read_text()) + else: + bluefin = bluefin_inventory(args.bluefin_image) + except (urllib.error.URLError, ValueError, KeyError, OSError) as exc: + # Without Bluefin's inventory there is nothing to compare. That is a + # failure of the check, not evidence about the image, so it is fatal + # only when the check is asked to gate. + message = f"could not read Bluefin's inventory from {args.bluefin_image}: {exc}" + print(message, file=sys.stderr) + if args.report: + args.report.parent.mkdir(parents=True, exist_ok=True) + args.report.write_text(message + "\n") + return 1 if args.strict else 0 + + utah = parse_rpm_list(args.rpm_list.read_text()) if args.rpm_list else installed_inventory() + result = compare(bluefin, utah, unavailable_names(args.overlay), load_exceptions(args.exceptions)) + report = render(args.bluefin_image, bluefin, utah, result) + print(report, end="") + if args.report: + args.report.parent.mkdir(parents=True, exist_ok=True) + args.report.write_text(report) + if result.missing and args.strict: + print(f"{len(result.missing)} package(s) Bluefin ships are missing and unexplained", file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/test_image_parity.py b/tests/test_image_parity.py new file mode 100644 index 000000000..5a5874503 --- /dev/null +++ b/tests/test_image_parity.py @@ -0,0 +1,160 @@ +"""scripts/check-image-parity.py must find a real gap and must not invent one. + +Everything here is offline: the registry is a dict of canned responses, and +the image inventory is a text file. What is under test is the reading of the +manifest, the comparison, and the exit code. +""" + +import importlib.util +import json +import sys +import tempfile +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def load(name): + spec = importlib.util.spec_from_file_location(name, ROOT / "scripts" / f"{name}.py") + module = importlib.util.module_from_spec(spec) + sys.modules[name] = module # dataclasses resolve annotations through sys.modules + spec.loader.exec_module(module) + return module + + +parity = load("check-image-parity") + +INVENTORY = {"glibc-all-langpacks": "2.43-8.fc44", "nautilus": "50.2.2-2.fc44", "kmod-zfs": "2.3-1"} +ANNOTATION = json.dumps({"version": 2, "packages": INVENTORY}) + + +def registry(manifest_by_url): + """A fetch() over canned responses; records what was asked for.""" + calls = [] + + def fetch(url, headers): + calls.append((url, headers)) + if url.startswith("https://ghcr.io/token"): + return json.dumps({"token": "t0k"}).encode() + return json.dumps(manifest_by_url[url]).encode() + + fetch.calls = calls + return fetch + + +class ImageRefTests(unittest.TestCase): + def test_tag_digest_and_default_tag(self): + self.assertEqual(parity.parse_image_ref("ghcr.io/ublue-os/bluefin:stable"), ("ghcr.io", "ublue-os/bluefin", "stable")) + self.assertEqual(parity.parse_image_ref("ghcr.io/o/r@sha256:ab"), ("ghcr.io", "o/r", "sha256:ab")) + self.assertEqual(parity.parse_image_ref("quay.io/o/r"), ("quay.io", "o/r", "latest")) + + def test_a_reference_without_a_registry_is_rejected(self): + with self.assertRaises(ValueError): + parity.parse_image_ref("ublue-os/bluefin:stable") + + +class ManifestTests(unittest.TestCase): + base = "https://ghcr.io/v2/ublue-os/bluefin/manifests/" + + def test_reads_the_inventory_off_a_single_manifest(self): + fetch = registry({self.base + "stable": {"annotations": {parity.RECHUNK_ANNOTATION: ANNOTATION}}}) + self.assertEqual(parity.bluefin_inventory("ghcr.io/ublue-os/bluefin:stable", fetch), INVENTORY) + # ghcr.io wants a pull token even for a public image. + self.assertEqual(fetch.calls[-1][1]["Authorization"], "Bearer t0k") + + def test_follows_a_multi_arch_index_to_the_amd64_manifest(self): + index = { + "manifests": [ + {"digest": "sha256:arm", "platform": {"architecture": "arm64", "os": "linux"}}, + {"digest": "sha256:amd", "platform": {"architecture": "amd64", "os": "linux"}}, + ] + } + fetch = registry( + { + self.base + "stable": index, + self.base + "sha256:amd": {"annotations": {parity.RECHUNK_ANNOTATION: ANNOTATION}}, + } + ) + self.assertEqual(parity.bluefin_inventory("ghcr.io/ublue-os/bluefin:stable", fetch), INVENTORY) + + def test_an_image_without_the_annotation_is_an_error_not_an_empty_list(self): + fetch = registry({self.base + "stable": {"annotations": {}}}) + with self.assertRaises(ValueError): + parity.bluefin_inventory("ghcr.io/ublue-os/bluefin:stable", fetch) + + +class ComparisonTests(unittest.TestCase): + def test_a_missing_name_is_a_gap_unless_explained(self): + result = parity.compare(INVENTORY, {"nautilus": "51"}, set(), []) + self.assertEqual(result.missing, ["glibc-all-langpacks", "kmod-zfs"]) + self.assertEqual(result.explained, []) + self.assertEqual(result.extra, []) + + def test_unavailable_and_exceptions_explain_and_the_reason_travels(self): + exceptions = [parity.Exception_("kmod-*", "no akmods for this kernel")] + result = parity.compare(INVENTORY, {}, {"nautilus"}, exceptions) + self.assertEqual(result.missing, ["glibc-all-langpacks"]) + self.assertEqual( + result.explained, + [("kmod-zfs", "no akmods for this kernel"), ("nautilus", "documented under [unavailable] in utah.toml")], + ) + + def test_names_only_here_are_reported_not_counted_as_gaps(self): + result = parity.compare(INVENTORY, {**INVENTORY, "hummingbird-release": "1"}, set(), []) + self.assertEqual(result.missing, []) + self.assertEqual(result.extra, ["hummingbird-release"]) + + def test_rpm_list_accepts_bare_names_and_skips_gpg_pubkey(self): + parsed = parity.parse_rpm_list("nautilus\t51-1\ngpg-pubkey\t1-2\nglibc\n") + self.assertEqual(parsed, {"nautilus": "51-1", "glibc": ""}) + + def test_the_shipped_exceptions_file_parses_and_every_entry_has_a_reason(self): + for exc in parity.load_exceptions(ROOT / "packages/parity-exceptions.toml"): + self.assertTrue(exc.pattern and exc.reason) + + +class ExitCodeTests(unittest.TestCase): + def run_main(self, *extra, rpm_names=("nautilus",)): + with tempfile.TemporaryDirectory() as tmp: + tmp = Path(tmp) + (tmp / "bluefin.json").write_text(json.dumps(INVENTORY)) + (tmp / "rpms.txt").write_text("\n".join(rpm_names) + "\n") + (tmp / "utah.toml").write_text('[unavailable]\npackages = ["kmod-zfs"]\n') + (tmp / "none.toml").write_text("") + code = parity.main( + [ + "--bluefin-inventory", str(tmp / "bluefin.json"), + "--rpm-list", str(tmp / "rpms.txt"), + "--overlay", str(tmp / "utah.toml"), + "--exceptions", str(tmp / "none.toml"), + "--report", str(tmp / "report.txt"), + *extra, + ] + ) + return code, (tmp / "report.txt").read_text() + + def test_report_only_never_fails_but_names_the_gap(self): + code, report = self.run_main() + self.assertEqual(code, 0) + self.assertIn("UNEXPLAINED", report) + self.assertIn("glibc-all-langpacks", report) + + def test_strict_fails_on_an_unexplained_gap_and_passes_without_one(self): + self.assertEqual(self.run_main("--strict")[0], 1) + code, report = self.run_main("--strict", rpm_names=("nautilus", "glibc-all-langpacks")) + self.assertEqual(code, 0) + self.assertNotIn("UNEXPLAINED", report) + self.assertIn("kmod-zfs: documented under [unavailable]", report) + + def test_an_unreadable_registry_is_not_evidence_about_the_image(self): + with tempfile.TemporaryDirectory() as tmp: + args = ["--bluefin-image", "ghcr.io/nowhere/nothing:tag", "--rpm-list", str(Path(tmp) / "x")] + Path(tmp, "x").write_text("nautilus\n") + fetch_failed = parity.main([*args, "--exceptions", str(Path(tmp) / "none")]) + self.assertEqual(fetch_failed, 0) + self.assertEqual(parity.main([*args, "--strict", "--exceptions", str(Path(tmp) / "none")]), 1) + + +if __name__ == "__main__": + unittest.main() From 043322ae5e29f6e8c4a9f5906b679f4bfb223082 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 07:23:54 +0000 Subject: [PATCH 02/11] feat(parity): record the 970 known gaps as a baseline so a new one stands out The first real report, from this branch's own build: Bluefin's image installs 1818 packages, Utah's installs 892, and 970 of Bluefin's names are missing here with no [unavailable] entry and no exception. That is the true size of the parity gap the list-to-list check could never see. Measured against public-hummingbird-x86_64-rpms and the pinned factory image, not guessed: 277 in Hummingbird's repository today -- installable by naming them 61 in the pinned factory image only -- installable, closure permitting 632 in no enabled repository -- needs a recipe, or is deliberate An exceptions file cannot carry 970 names honestly, and --strict against that many would only ever fail. So the check gains a baseline: packages/parity-baseline.txt records the gaps already known, grouped as above, and the report separates a NEW gap (Bluefin started shipping something this image lacks) from a known one. It also names baseline entries that have closed -- the image gained the package, or Bluefin dropped it -- so the file gets trimmed. --strict now fails only on a new gap. Shrinking the file is how parity is paid down; growing it is a decision. Verified against the reconstructed inventory of that build (892 names, the report's own count): NEW 0, known 970, closed 0, exit 0 under --strict; dropping one name from the baseline gives NEW 1 and exit 1; adding that package to the inventory reports it closed. Four new tests cover the grouping, the comment syntax, the shipped file's shape, and the strict exit codes with a baseline. 112 tests pass. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M --- Containerfile | 2 +- docs/skills/ci-workflows.md | 3 +- docs/skills/package-contract.md | 8 +- packages/parity-baseline.txt | 990 ++++++++++++++++++++++++++++++++ scripts/check-image-parity.py | 75 ++- tests/test_image_parity.py | 36 +- 6 files changed, 1092 insertions(+), 22 deletions(-) create mode 100644 packages/parity-baseline.txt diff --git a/Containerfile b/Containerfile index b46a54352..2fe2be630 100644 --- a/Containerfile +++ b/Containerfile @@ -39,7 +39,7 @@ FROM ${BASE_IMAGE} # transaction reads. These, the pinned package image and the install script # are the whole input to the expensive layer, so everything else waits its # turn below them. -COPY packages/bluefin.toml packages/utah.toml packages/parity-exceptions.toml contracts/bluefin-desktop.toml /usr/share/utah/ +COPY packages/bluefin.toml packages/utah.toml packages/parity-exceptions.toml packages/parity-baseline.txt contracts/bluefin-desktop.toml /usr/share/utah/ COPY packages/hummingbird.repo packages/nvidia-container.repo packages/utah-packages.repo /etc/yum.repos.d/ # Hummingbird signs its RPMs with Red Hat's release key 2 (fd431d51); the key # lets packages/hummingbird.repo run with gpgcheck=1 here and in the live ISO diff --git a/docs/skills/ci-workflows.md b/docs/skills/ci-workflows.md index af044f40d..d82c22e79 100644 --- a/docs/skills/ci-workflows.md +++ b/docs/skills/ci-workflows.md @@ -56,7 +56,8 @@ opaque `exit status 71` from the image build (comment, That is list against list. The image build itself runs `utah-check-image-parity`, which compares the installed RPM set with the inventory Bluefin's image publishes in its manifest, and writes the report - to `/usr/share/utah/parity-report.txt` in the image (report-only today). + to `/usr/share/utah/parity-report.txt` in the image, split into new gaps and + the known ones in `packages/parity-baseline.txt` (report-only today). - `just check-repos` -- the complete installation transaction against the digest-pinned base and package repository, including extension build tools. diff --git a/docs/skills/package-contract.md b/docs/skills/package-contract.md index 846e19389..b21d986f3 100644 --- a/docs/skills/package-contract.md +++ b/docs/skills/package-contract.md @@ -178,8 +178,12 @@ lists it under `[unavailable]` or `packages/parity-exceptions.toml` gives a reason for it; the report prints the reason. Both the inventory and the report ship in the image under `/usr/share/utah/`. -- Report-only in the build today. `--strict` fails on an unexplained gap; it - is turned on once the exceptions file covers the deliberate differences. +- `packages/parity-baseline.txt` is the debt register: the gaps already + known, grouped by where each name could come from today (Hummingbird's + repository, the pinned factory image, nowhere). The report separates a + **new** gap from a known one and names baseline entries that have closed, + so the file gets trimmed. Report-only in the build today; `--strict` fails + on a new gap and is a one-word change in the Containerfile. - `just check-image-parity IMAGE` runs the strict comparison against a built image locally. - Add to `parity-exceptions.toml` only a difference that is deliberate, with diff --git a/packages/parity-baseline.txt b/packages/parity-baseline.txt new file mode 100644 index 000000000..257e4c77a --- /dev/null +++ b/packages/parity-baseline.txt @@ -0,0 +1,990 @@ +# Known image-level parity gaps: packages Bluefin's image installs that Utah's +# does not, with no [unavailable] entry and no parity-exceptions.toml reason. +# +# Generated from the first report scripts/check-image-parity.py produced, in the +# build of utah#117 on 2026-09-18 against ghcr.io/ublue-os/bluefin:stable +# (44.20260915): Bluefin installs 1818 packages, Utah 892. This file is the +# debt register. check-image-parity --strict fails on a gap that is NOT here, +# so a new Bluefin package forces a decision; a name that stops being a gap is +# reported as closed and should be removed. Shrinking this file is progress. +# +# The groups say where each name could come from today, measured against +# public-hummingbird-x86_64-rpms and the pinned factory image, not guessed. +# Many names in the last group are dependencies that arrive on their own once +# their top-level package has a recipe. + +# --- in Hummingbird's repository today (277): installable by adding to the contract +NetworkManager-adsl +NetworkManager-bluetooth +NetworkManager-config-connectivity-fedora +NetworkManager-ppp +NetworkManager-wifi +NetworkManager-wwan +abattis-cantarell-fonts +acl +alsa-ucm +apr +apr-util +apr-util-lmdb +apr-util-openssl +attr +avahi +avahi-gobject +avahi-tools +bash-completion +bind-libs +bind-utils +boost-filesystem +boost-program-options +buildah +bzip2 +c-ares +capstone +coreutils +coreutils-common +cracklib-dicts +crypto-policies-scripts +cups +cups-client +cups-ipptool +cyrus-sasl-gssapi +cyrus-sasl-plain +dbus-daemon +dbus-tools +dbus-x11 +default-fonts-am +default-fonts-ar +default-fonts-as +default-fonts-ast +default-fonts-be +default-fonts-bg +default-fonts-bn +default-fonts-bo +default-fonts-br +default-fonts-chr +default-fonts-cjk-mono +default-fonts-cjk-serif +default-fonts-core-emoji +default-fonts-core-math +default-fonts-core-mono +default-fonts-core-serif +default-fonts-dv +default-fonts-dz +default-fonts-el +default-fonts-eo +default-fonts-eu +default-fonts-fa +default-fonts-got +default-fonts-gu +default-fonts-he +default-fonts-hi +default-fonts-hy +default-fonts-ia +default-fonts-ii +default-fonts-iu +default-fonts-ka +default-fonts-kab +default-fonts-km +default-fonts-kn +default-fonts-ku +default-fonts-lo +default-fonts-mai +default-fonts-ml +default-fonts-mni +default-fonts-mr +default-fonts-my +default-fonts-nb +default-fonts-ne +default-fonts-nn +default-fonts-nqo +default-fonts-nr +default-fonts-nso +default-fonts-or +default-fonts-other-mono +default-fonts-other-sans +default-fonts-other-serif +default-fonts-pa +default-fonts-ru +default-fonts-sat +default-fonts-si +default-fonts-ss +default-fonts-syr +default-fonts-ta +default-fonts-te +default-fonts-th +default-fonts-tn +default-fonts-ts +default-fonts-uk +default-fonts-ur +default-fonts-ve +default-fonts-vi +default-fonts-xh +default-fonts-yi +default-fonts-zu +dnf5-plugins +dnf5daemon-server +dnf5daemon-server-polkit +dns-root-data +elfutils-default-yama-scope +elfutils-libelf-devel +fedora-gpg-keys +fedora-logos-httpd +fedora-repos +fedora-repos-archive +fftw-libs-double +fstrm +gawk-all-langpacks +gd +gdbm +git +git-core-doc +glibc-all-langpacks +gnulib-l10n +gnutls-dane +google-noto-naskh-arabic-vf-fonts +google-noto-sans-arabic-vf-fonts +google-noto-sans-armenian-vf-fonts +google-noto-sans-balinese-fonts +google-noto-sans-bengali-vf-fonts +google-noto-sans-canadian-aboriginal-vf-fonts +google-noto-sans-cherokee-vf-fonts +google-noto-sans-devanagari-vf-fonts +google-noto-sans-ethiopic-vf-fonts +google-noto-sans-georgian-vf-fonts +google-noto-sans-gothic-fonts +google-noto-sans-gujarati-vf-fonts +google-noto-sans-gurmukhi-vf-fonts +google-noto-sans-hebrew-vf-fonts +google-noto-sans-javanese-fonts +google-noto-sans-kannada-vf-fonts +google-noto-sans-khmer-vf-fonts +google-noto-sans-lao-vf-fonts +google-noto-sans-math-fonts +google-noto-sans-meetei-mayek-vf-fonts +google-noto-sans-mono-vf-fonts +google-noto-sans-nko-fonts +google-noto-sans-ol-chiki-vf-fonts +google-noto-sans-oriya-vf-fonts +google-noto-sans-sinhala-vf-fonts +google-noto-sans-sundanese-fonts +google-noto-sans-symbols-2-fonts +google-noto-sans-symbols-vf-fonts +google-noto-sans-syriac-vf-fonts +google-noto-sans-tamil-vf-fonts +google-noto-sans-telugu-vf-fonts +google-noto-sans-thaana-vf-fonts +google-noto-sans-thai-vf-fonts +google-noto-sans-yi-fonts +google-noto-serif-armenian-vf-fonts +google-noto-serif-bengali-vf-fonts +google-noto-serif-devanagari-vf-fonts +google-noto-serif-ethiopic-vf-fonts +google-noto-serif-georgian-vf-fonts +google-noto-serif-gujarati-vf-fonts +google-noto-serif-gurmukhi-vf-fonts +google-noto-serif-hebrew-vf-fonts +google-noto-serif-kannada-vf-fonts +google-noto-serif-khmer-vf-fonts +google-noto-serif-lao-vf-fonts +google-noto-serif-oriya-vf-fonts +google-noto-serif-sinhala-vf-fonts +google-noto-serif-tamil-vf-fonts +google-noto-serif-telugu-vf-fonts +google-noto-serif-thai-vf-fonts +google-noto-serif-vf-fonts +gpgmepp +graphviz-libs +hiredis +hostname +httpd +httpd-core +httpd-filesystem +httpd-tools +hwloc-libs +ima-evm-utils-libs +iptables-nft +keyutils +krb5-pkinit +krb5-workstation +langpacks-core-en +langpacks-en +langpacks-fonts-en +libXpm +libb2 +libbabeltrace +libcap-ng-python3 +libcurl-minimal +libdnf5-plugin-appstream +libdnf5-plugin-expired-pgp-keys +libfsverity +libgit2 +libibverbs +libimagequant +libkadm5 +libmaxminddb +libnl3 +libpipeline +libsodium +libssh2 +libtommath +libuv +libverto-libev +libzip +libzstd-devel +llhttp +m4 +man-db +mod_lua +ncurses-term +openssl-devel +perl-Error +perl-Git +perl-TermReadKey +perl-lib +poppler +poppler-cpp +poppler-glib +poppler-utils +protobuf +protobuf-c +python-unversioned-command +python3-certifi +python3-cffi +python3-charset-normalizer +python3-cryptography +python3-file-magic +python3-idna +python3-pip +python3-pycparser +python3-pyyaml +python3-requests +python3-urllib3 +python3-urllib3+socks +qt6-filesystem +qt6-qtbase +qt6-qtbase-common +qt6-qtbase-gui +qt6-qtsvg +rdma-core-common +rootfiles +rpm-build-libs +rpm-plugin-audit +rpm-plugin-dbus-announce +rpm-sign-libs +spdlog +sudo-python-plugin +systemd-container +systemd-networkd +systemd-oomd-defaults +tcl +tpm2-tss-fapi +unbound-anchor +unbound-libs +unzip +uriparser +userspace-rcu +vim-common +vim-enhanced +xmlsec1 +xmlsec1-openssl +xxd +xxhash-libs +zeromq +zip + +# --- in the pinned factory image only (61): installable, needs the closure to resolve +ModemManager +alsa-sof-firmware +amd-gpu-firmware +amd-ucode-firmware +atheros-firmware +bluez-cups +brcmfmac-firmware +cirrus-audio-firmware +desktop-file-utils +fuse-libs +fwupd-plugin-modem-manager +glycin-gtk4-libs +glycin-thumbnailer +grub2-efi-ia32 +grub2-tools-extra +gstreamer1-plugins-bad-free +gstreamer1-plugins-good-qt +gvfs-afc +gvfs-fuse +gvfs-gphoto2 +gvfs-mtp +gvfs-smb +ibus-gtk4 +intel-audio-firmware +intel-gmmlib +intel-gpu-firmware +intel-vsc-firmware +iwlegacy-firmware +iwlwifi-dvm-firmware +iwlwifi-mld-firmware +iwlwifi-mvm-firmware +libertas-firmware +libimobiledevice-utils +libnetapi +libnma +linux-firmware +linux-firmware-whence +lm_sensors +localsearch +mt7xxx-firmware +nautilus +nvidia-gpu-firmware +nxpwireless-firmware +pciutils +pipewire-config-raop +pipewire-utils +pulseaudio-utils +python3-pydantic+email +qcom-wwan-firmware +realtek-firmware +samba +samba-client +samba-common-tools +samba-dcerpc +samba-ldb-ldap-modules +samba-libs +samba-winbind +samba-winbind-clients +samba-winbind-modules +setools-console +tiwilink-firmware + +# --- in no enabled repository (632): needs a factory recipe, or is deliberate +7zip +ImageMagick +ImageMagick-libs +LCEVCdec +LibRaw +NetworkManager-openconnect +NetworkManager-openconnect-gnome +NetworkManager-openvpn +NetworkManager-openvpn-gnome +NetworkManager-ssh +NetworkManager-ssh-gnome +NetworkManager-ssh-selinux +NetworkManager-vpnc +NetworkManager-vpnc-gnome +OpenCL-ICD-Loader +PackageKit-glib +adcli +adcli-selinux +adobe-mappings-cmap +adobe-mappings-cmap-deprecated +adobe-mappings-pdf +adobe-source-code-pro-fonts +alsa-utils +anthy-unicode +antiword +appstream-data +argyllcms +argyllcms-data +autofs +b43-fwcutter +b43-openfwwf +bash-color-prompt +bc +bcache-tools +bison +bolt +borgbackup +braille-printer-app +brlapi +brltty +c2esp +cairomm1.16 +cifs-utils +cifs-utils-info +cjson +cldr-emoji-annotation +cldr-emoji-annotation-dtd +compsize +criu +criu-libs +cryfs +cups-browsed +cups-filters +cups-filters-driverless +davfs2 +davs2-libs +default-editor +desktop-backgrounds-gnome +distribution-gpg-keys +djvulibre-libs +dmidecode +dnsmasq +dotconf +dymo-cups-drivers +epiphany-runtime +espeak-ng +ethtool +evolution-ews-langpacks +exempi +exfatprogs +exiv2 +exiv2-libs +f2fs-tools +f44-backgrounds-base +f44-backgrounds-gnome +faad2-libs +fedora-release-common +fedora-release-identity-silverblue +fedora-release-ostree-desktop +fedora-release-silverblue +fedora-workstation-backgrounds +ffmpeg +ffmpeg-libs +ffmpegthumbnailer +ffmpegthumbnailer-libs +flex +foo2zjs +foomatic-db-filesystem +fpaste +fprintd +fprintd-pam +freeglut +freerdp-libs +fuse-encfs +fwupd-efi +game-music-emu +gamemode +gdouros-symbola-fonts +generic-logos +ghostscript +ghostscript-tools-fontutils +ghostscript-tools-printing +giflib +glibmm2.68 +glow +gnome-app-list +gnome-backgrounds +gnome-browser-connector +gnome-classic-session +gnome-color-manager +gnome-disk-utility +gnome-epub-thumbnailer +gnome-initial-setup +gnome-menus +gnome-remote-desktop +gnome-rounded-blur +gnome-shell-extension-apps-menu +gnome-shell-extension-blur-my-shell +gnome-shell-extension-common +gnome-shell-extension-launch-new-instance +gnome-shell-extension-places-menu +gnome-shell-extension-window-list +gnome-system-monitor +gnome-tour +gnome-user-docs +gnome-user-share +google-droid-sans-fonts +google-noto-color-emoji-fonts +google-noto-emoji-fonts +google-noto-sans-cjk-fonts +google-noto-serif-cjk-vf-fonts +gpg-pubkey +gpm-libs +gssproxy +gst-editing-services +gst-thumbnailers +gstreamer1-plugin-dav1d +gstreamer1-plugin-libav +gstreamer1-plugins-good-qt6 +gstreamer1-plugins-ugly-free +gtkmm4.0 +gtksourceview5 +gupnp-av +gupnp-dlna +gutenprint +gutenprint-cups +gutenprint-libs +gvfs-afp +gvfs-archive +hdparm +hfsplus-tools +hplip +hplip-common +hplip-libs +htop +hyperv-daemons +hyperv-daemons-license +hypervfcopyd +hypervkvpd +hypervvssd +ibus-anthy +ibus-anthy-python +ibus-chewing +ibus-hangul +ibus-libpinyin +ibus-m17n +ibus-typing-booster +ifuse +imath +inih +inih-cpp +initscripts-service +intel-lpmd +intel-vaapi-driver +ipp-usb +ipset +ipset-libs +iptstate +iw +iwd +jbig2dec-libs +jetbrains-mono-fonts +jetbrains-mono-fonts-all +jetbrains-mono-nl-fonts +jomolhari-fonts +julietaula-montserrat-fonts +kasumi-common +kasumi-unicode +kernel-devel-matched +kernel-modules-extra +kernel-tools +kernel-tools-libs +kf6-filesystem +kf6-karchive +kf6-kimageformats +kpartx +kvazaar-libs +kyotocabinet-libs +langtable +lcms +lcms-libs +leptonica +libXScrnSaver +libXres +liba52 +libao +libass +libavc1394 +libavcodec +libavdevice +libavfilter +libavformat +libavutil +libbasicobjects +libbluray +libbs2b +libbsd +libcaca +libchewing +libchromaprint +libcollection +libcue +libcupsfilters +libdaemon +libdc1394 +libde265 +libdeflate +libdhash +libdovi +libdvdnav +libdvdread +libell +liberation-mono-fonts +liberation-sans-fonts +liberation-serif-fonts +libev +libexif +libfdk-aac +libfprint +libgee +libgexiv2 +libgphoto2 +libgs +libgsf +libgxps +libhandy +libhangul +libiec61883 +libieee1284 +libijs +libini_config +libklvanc +liblouis +liblouis-tables +liblouisutdml +liblouisutdml-utils +liblqr-1 +libmbim +libmbim-utils +libmd +libmediaart +libmodplug +libmpeg2 +libmspack +libmtp +libmysofa +libnet +libnfsidmap +libntlm +libnvpair3 +libopenmpt +libosinfo +libpaper +libpasswdqc +libpath_utils +libpcap +libpfm +libpinyin +libpinyin-data +libplacebo +libportal +libportal-gtk4 +libppd +libpskc +libqmi +libqmi-utils +libqrtr-glib +librabbitmq +libraqm +libraw1394 +libref_array +libreport-filesystem +librist +librtmp +libsamplerate +libsane-airscan +libsane-hpaio +libshaderc +libsigc++30 +libslirp +libspelling +libsrtp +libsss_autofs +libsss_certmap +libsss_idmap +libsss_nss_idmap +libsss_sudo +libswresample +libswscale +libtatsu +libtraceevent +libudfread +libultrahdr +libunibreak +liburing +libuser +libutempter +libuutil3 +libva-intel-media-driver +libvarlink +libvncserver +libwinpr +libwmf-lite +libwnck3 +libxavs +libyubikey +libzfs7 +libzpool7 +lilv-libs +linux-atm-libs +lockdev +lrzsz +lsb_release +lshw +lsof +m17n-db +m17n-lib +madan-fonts +man-pages +mcelog +memstrack +microcode_ctl +mkpasswd +mod_dnssd +mod_http2 +mozilla-filesystem +mpage +mtools +mtr +nano +nano-default-editor +neon +nerd-fonts +net-snmp-libs +net-tools +nfs-client-utils +nfs-common-utils +nfs-utils +nfsv3-client-utils +nfsv4-client-utils +nilfs-utils +nm-connection-editor +nss-altfiles +nss-mdns +ntfs-3g-system-compression +nvme-cli +nvtop +oddjob +oddjob-mkhomedir +open-sans-fonts +open-vm-tools +open-vm-tools-desktop +openal-soft +openconnect +opendyslexic-fonts +openexr-libs +openpace +openpgm +opensc +opensc-libs +openvpn +orca +osinfo-db +osinfo-db-tools +oversteer-udev +paktype-naskh-basic-fonts +pam-u2f +pam_afs_session +pam_passwdqc +pam_yubico +pamu2fcfg +pangomm2.48 +papers-libs +papers-nautilus +papers-previewer +papers-thumbnailer +paps +passwdqc +passwdqc-utils +pcaudiolib +pcp-conf +pcp-libs +pcp-selinux-import +pcsc-lite +pcsc-lite-ccid +pcsc-lite-libs +perl-Unicode-Normalize +pinentry +pinentry-gnome3 +pinfo +pkcs11-helper +pkcs11-provider +plymouth +plymouth-core-libs +plymouth-graphics-libs +plymouth-plugin-label +plymouth-plugin-two-step +plymouth-scripts +plymouth-system-theme +plymouth-theme-spinner +poppler-data +portaudio +powerstat +powertop +prefixdevname +printer-driver-brlaser +ptouch-driver +ptyxis +pv +python3-anyio +python3-boto3 +python3-botocore +python3-brlapi +python3-click +python3-cups +python3-dateutil +python3-dns +python3-email-validator +python3-enchant +python3-fido2 +python3-h11 +python3-html2text +python3-httpcore +python3-httpx +python3-inotify +python3-jaraco-classes +python3-jaraco-context +python3-jaraco-functools +python3-jeepney +python3-jmespath +python3-keyring +python3-keyring+completion +python3-langtable +python3-linux-procfs +python3-llfuse +python3-louis +python3-more-itertools +python3-msgpack +python3-olefile +python3-perf +python3-pexpect +python3-pillow +python3-pskc +python3-ptyprocess +python3-pyatspi +python3-pyaudio +python3-pygit2 +python3-pyscard +python3-pysocks +python3-pyudev +python3-pyxdg +python3-pyzfs +python3-rapidfuzz +python3-regex +python3-s3transfer +python3-secretstorage +python3-shtab +python3-six +python3-speechd +python3-yubikey-manager +qadwaitadecorations-qt5 +qemu-guest-agent +qemu-user-static-aarch64 +qpdf-libs +qrencode-libs +qt5-qtdeclarative +qt5-qtsvg +qt5-qttranslations +qt5-qtwayland +qt5-qtx11extras +qt5-qtxmlpatterns +qt6-qtdeclarative +qt6-qttranslations +qt6-qtwayland +qt6-qtwayland-adwaita-decoration +quota +quota-nls +rclone +realmd +redhat-menus +restic +rit-meera-new-fonts +rit-rachana-fonts +rpcbind +rpm-ostree +rpm-ostree-libs +rsync +rubberband-libs +rygel +sane-airscan +sane-backends +sane-backends-drivers-cameras +sane-backends-drivers-scanners +sane-backends-libs +serd +shim-ia32 +sil-padauk-fonts +simdutf +slang +slirp4netns +smartmontools +smartmontools-selinux +solaar-udev +sord +sos +soundtouch +speech-dispatcher +speech-dispatcher-espeak-ng +speech-dispatcher-libs +speech-dispatcher-utils +spice-vdagent +spice-webdavd +splix +sratom +srt-libs +sshpass +sso-mib-libs +sssd-client +sssd-common +sssd-kcm +sssd-krb5-common +sssd-nfs-idmap +stix-fonts +stoken-libs +svt-vp9-libs +symlinks +sysstat +system-config-printer-libs +system-config-printer-udev +tcpdump +tesseract-common +tesseract-langpack-eng +tesseract-libs +tesseract-tessdata-doc +thermald +time +tinyxml2 +tmux +toolbox +totem-pl-parser +tpm2-tools +traceroute +tree +tslib +tuned +tuned-ppd +uavs3d-libs +uchardet +udftools +unicode-ucd +uresourced +urw-base35-bookman-fonts +urw-base35-c059-fonts +urw-base35-d050000l-fonts +urw-base35-fonts +urw-base35-fonts-common +urw-base35-gothic-fonts +urw-base35-nimbus-mono-ps-fonts +urw-base35-nimbus-roman-fonts +urw-base35-nimbus-sans-fonts +urw-base35-p052-fonts +urw-base35-standard-symbols-ps-fonts +urw-base35-z003-fonts +usb_modeswitch +usb_modeswitch-data +usbip +usbmuxd +usbutils +usermode +uupd +uvg266-libs +v4l2loopback +vazirmatn-vf-fonts +vid.stab +virt-what +virtualbox-guest-additions +vpnc +vpnc-script +vte-profile +vte291 +vte291-gtk4 +vvdec-libs +vvenc-libs +wget2 +wget2-libs +wget2-wget +whois +whois-nls +wireless-regdb +words +wpa_supplicant +x264-libs +x265-libs +xavs2-libs +xcb-util-cursor +xdg-utils +xdriinfo +xfsprogs +xrandr +xset +yelp-libs +yelp-xsl +ykclient +ykpers +yubikey-manager +zfs +zimg +zinnia +zinnia-tomoe-ja +zix +zram-generator +zram-generator-defaults diff --git a/scripts/check-image-parity.py b/scripts/check-image-parity.py index fd5eb1ee3..365b78420 100755 --- a/scripts/check-image-parity.py +++ b/scripts/check-image-parity.py @@ -18,8 +18,11 @@ The comparison is by name. A name Bluefin has that this image does not is a gap, unless packages/utah.toml already documents it under [unavailable] or -packages/parity-exceptions.toml explains it. Without --strict the result is a -report; with --strict an unexplained gap fails the build. +packages/parity-exceptions.toml explains it. The remaining gaps are the debt: +packages/parity-baseline.txt records the ones already known, so the report +separates a NEW gap (Bluefin started shipping something this image lacks) +from a known one, and --strict fails only on the new ones. Shrinking the +baseline is how parity is paid down; growing it is a decision. """ from __future__ import annotations @@ -144,6 +147,18 @@ def load_exceptions(path: Path) -> list[Exception_]: return exceptions +def load_baseline(path: Path) -> set[str]: + """Known gaps, one name per line; # starts a comment.""" + if not path.exists(): + return set() + names = set() + for line in path.read_text().splitlines(): + line = line.split("#", 1)[0].strip() + if line: + names.add(line) + return names + + def unavailable_names(overlay: Path) -> set[str]: if not overlay.exists(): return set() @@ -153,9 +168,15 @@ def unavailable_names(overlay: Path) -> set[str]: @dataclass class Comparison: - missing: list[str] = field(default_factory=list) + new: list[str] = field(default_factory=list) + known: list[str] = field(default_factory=list) explained: list[tuple[str, str]] = field(default_factory=list) extra: list[str] = field(default_factory=list) + closed: list[str] = field(default_factory=list) + + @property + def missing(self) -> list[str]: + return sorted(self.new + self.known) def compare( @@ -163,6 +184,7 @@ def compare( utah: dict[str, str], unavailable: set[str], exceptions: list[Exception_], + baseline: set[str] = frozenset(), ) -> Comparison: result = Comparison() for name in sorted(bluefin): @@ -176,8 +198,11 @@ def compare( result.explained.append((name, exc.reason)) break else: - result.missing.append(name) + (result.known if name in baseline else result.new).append(name) result.extra = sorted(name for name in utah if name not in bluefin) + # A baseline entry this image now has, or Bluefin no longer ships, is + # paid-down debt: say so, so the file gets trimmed. + result.closed = sorted(name for name in baseline if name in utah or name not in bluefin) return result @@ -185,14 +210,24 @@ def render(ref: str, bluefin: dict[str, str], utah: dict[str, str], result: Comp lines = [ f"image parity against {ref}", f" Bluefin installs {len(bluefin)} packages, this image {len(utah)}", - f" in Bluefin, not here, unexplained: {len(result.missing)}", - f" in Bluefin, not here, explained: {len(result.explained)}", - f" here, not in Bluefin: {len(result.extra)}", + f" in Bluefin, not here, NEW (not in the baseline): {len(result.new)}", + f" in Bluefin, not here, known gap (baseline): {len(result.known)}", + f" in Bluefin, not here, explained: {len(result.explained)}", + f" baseline entries now closed: {len(result.closed)}", + f" here, not in Bluefin: {len(result.extra)}", ] - if result.missing: + if result.new: + lines.append("") + lines.append("NEW -- in Bluefin's image, not in this one, not in the baseline:") + lines += [f" {name} ({bluefin[name]})" for name in result.new] + if result.closed: lines.append("") - lines.append("UNEXPLAINED -- in Bluefin's image and not in this one:") - lines += [f" {name} ({bluefin[name]})" for name in result.missing] + lines.append("closed -- in the baseline but no longer a gap; remove from parity-baseline.txt:") + lines += [f" {name}" for name in result.closed] + if result.known: + lines.append("") + lines.append("known gap (baseline):") + lines += [f" {name} ({bluefin[name]})" for name in result.known] if result.explained: lines.append("") lines.append("explained:") @@ -221,9 +256,12 @@ def main(argv: list[str] | None = None) -> int: parser.add_argument( "--exceptions", type=Path, default=Path("/usr/share/utah/parity-exceptions.toml") ) + parser.add_argument( + "--baseline", type=Path, default=Path("/usr/share/utah/parity-baseline.txt") + ) parser.add_argument("--report", type=Path, help="also write the report here") parser.add_argument( - "--strict", action="store_true", help="exit 1 when an unexplained gap remains" + "--strict", action="store_true", help="exit 1 on a gap that is not in the baseline" ) args = parser.parse_args(argv) @@ -244,14 +282,23 @@ def main(argv: list[str] | None = None) -> int: return 1 if args.strict else 0 utah = parse_rpm_list(args.rpm_list.read_text()) if args.rpm_list else installed_inventory() - result = compare(bluefin, utah, unavailable_names(args.overlay), load_exceptions(args.exceptions)) + result = compare( + bluefin, + utah, + unavailable_names(args.overlay), + load_exceptions(args.exceptions), + load_baseline(args.baseline), + ) report = render(args.bluefin_image, bluefin, utah, result) print(report, end="") if args.report: args.report.parent.mkdir(parents=True, exist_ok=True) args.report.write_text(report) - if result.missing and args.strict: - print(f"{len(result.missing)} package(s) Bluefin ships are missing and unexplained", file=sys.stderr) + if result.new and args.strict: + print( + f"{len(result.new)} package(s) Bluefin ships are missing here and not in the baseline", + file=sys.stderr, + ) return 1 return 0 diff --git a/tests/test_image_parity.py b/tests/test_image_parity.py index 5a5874503..4890fa7ab 100644 --- a/tests/test_image_parity.py +++ b/tests/test_image_parity.py @@ -109,25 +109,47 @@ def test_rpm_list_accepts_bare_names_and_skips_gpg_pubkey(self): parsed = parity.parse_rpm_list("nautilus\t51-1\ngpg-pubkey\t1-2\nglibc\n") self.assertEqual(parsed, {"nautilus": "51-1", "glibc": ""}) + def test_a_baseline_separates_known_gaps_from_new_ones_and_reports_closed_ones(self): + baseline = {"glibc-all-langpacks", "nautilus"} + result = parity.compare(INVENTORY, {"nautilus": "51"}, set(), [], baseline) + self.assertEqual(result.known, ["glibc-all-langpacks"]) + self.assertEqual(result.new, ["kmod-zfs"]) + self.assertEqual(result.closed, ["nautilus"]) + self.assertEqual(result.missing, ["glibc-all-langpacks", "kmod-zfs"]) + + def test_baseline_file_ignores_comments_and_blank_lines(self): + with tempfile.TemporaryDirectory() as tmp: + path = Path(tmp) / "baseline.txt" + path.write_text("# header\n\nnautilus # trailing\n 7zip\n") + self.assertEqual(parity.load_baseline(path), {"nautilus", "7zip"}) + + def test_the_shipped_baseline_is_sorted_within_each_group_and_has_no_duplicates(self): + names = [l.split("#")[0].strip() for l in (ROOT / "packages/parity-baseline.txt").read_text().splitlines()] + names = [n for n in names if n] + self.assertEqual(len(names), len(set(names))) + self.assertEqual(len(names), 970) + def test_the_shipped_exceptions_file_parses_and_every_entry_has_a_reason(self): for exc in parity.load_exceptions(ROOT / "packages/parity-exceptions.toml"): self.assertTrue(exc.pattern and exc.reason) class ExitCodeTests(unittest.TestCase): - def run_main(self, *extra, rpm_names=("nautilus",)): + def run_main(self, *extra, rpm_names=("nautilus",), baseline=""): with tempfile.TemporaryDirectory() as tmp: tmp = Path(tmp) (tmp / "bluefin.json").write_text(json.dumps(INVENTORY)) (tmp / "rpms.txt").write_text("\n".join(rpm_names) + "\n") (tmp / "utah.toml").write_text('[unavailable]\npackages = ["kmod-zfs"]\n') (tmp / "none.toml").write_text("") + (tmp / "baseline.txt").write_text(baseline) code = parity.main( [ "--bluefin-inventory", str(tmp / "bluefin.json"), "--rpm-list", str(tmp / "rpms.txt"), "--overlay", str(tmp / "utah.toml"), "--exceptions", str(tmp / "none.toml"), + "--baseline", str(tmp / "baseline.txt"), "--report", str(tmp / "report.txt"), *extra, ] @@ -137,16 +159,22 @@ def run_main(self, *extra, rpm_names=("nautilus",)): def test_report_only_never_fails_but_names_the_gap(self): code, report = self.run_main() self.assertEqual(code, 0) - self.assertIn("UNEXPLAINED", report) + self.assertIn("NEW -- in Bluefin's image", report) self.assertIn("glibc-all-langpacks", report) - def test_strict_fails_on_an_unexplained_gap_and_passes_without_one(self): + def test_strict_fails_on_a_new_gap_and_passes_without_one(self): self.assertEqual(self.run_main("--strict")[0], 1) code, report = self.run_main("--strict", rpm_names=("nautilus", "glibc-all-langpacks")) self.assertEqual(code, 0) - self.assertNotIn("UNEXPLAINED", report) + self.assertNotIn("NEW --", report) self.assertIn("kmod-zfs: documented under [unavailable]", report) + def test_strict_tolerates_a_gap_the_baseline_already_records(self): + code, report = self.run_main("--strict", baseline="glibc-all-langpacks\n") + self.assertEqual(code, 0) + self.assertIn("known gap (baseline):", report) + self.assertNotIn("NEW --", report) + def test_an_unreadable_registry_is_not_evidence_about_the_image(self): with tempfile.TemporaryDirectory() as tmp: args = ["--bluefin-image", "ghcr.io/nowhere/nothing:tag", "--rpm-list", str(Path(tmp) / "x")] From a7de7f2c2a191d3a25c782e2d32c5d1eef1aba4e Mon Sep 17 00:00:00 2001 From: castrojo Date: Fri, 18 Sep 2026 12:04:44 -0400 Subject: [PATCH 03/11] fix(parity): filter gpg-pubkey from Bluefin's inventory too parse_rpm_list drops gpg-pubkey from Utah's rpm -qa, but bluefin_inventory returned the rechunk annotation unfiltered, so the name appeared on one side only and was reported as a missing package. The PR's own build shows it: gpg-pubkey is listed among the gaps, and packages/parity-baseline.txt recorded it as permanent debt. gpg-pubkey is RPM key material rather than a package, and there is one pseudo-entry per imported key, so a asymmetric filter can only ever produce a false gap. Apply the same exclusion on the Bluefin side, drop the baseline entry, and move the pinned baseline count 970 -> 969. Assisted-by: Claude Opus 5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- packages/parity-baseline.txt | 1 - scripts/check-image-parity.py | 9 ++++++++- tests/test_image_parity.py | 2 +- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/packages/parity-baseline.txt b/packages/parity-baseline.txt index 257e4c77a..f19cbd40f 100644 --- a/packages/parity-baseline.txt +++ b/packages/parity-baseline.txt @@ -487,7 +487,6 @@ google-noto-color-emoji-fonts google-noto-emoji-fonts google-noto-sans-cjk-fonts google-noto-serif-cjk-vf-fonts -gpg-pubkey gpm-libs gssproxy gst-editing-services diff --git a/scripts/check-image-parity.py b/scripts/check-image-parity.py index 365b78420..a998dfb58 100755 --- a/scripts/check-image-parity.py +++ b/scripts/check-image-parity.py @@ -104,7 +104,14 @@ def bluefin_inventory(ref: str, fetch: Fetch = http_get) -> dict[str, str]: packages = json.loads(annotation).get("packages") if not isinstance(packages, dict) or not packages: raise ValueError(f"{ref}: {RECHUNK_ANNOTATION} has no package inventory") - return dict(packages) + # Same exclusion parse_rpm_list applies to Utah's side. gpg-pubkey is RPM + # key material, not a package, and there is one pseudo-entry per imported + # key; leaving it on only one side reports a permanent false gap. + return { + name: version + for name, version in packages.items() + if not name.startswith("gpg-pubkey") + } def installed_inventory() -> dict[str, str]: diff --git a/tests/test_image_parity.py b/tests/test_image_parity.py index 4890fa7ab..371f3b800 100644 --- a/tests/test_image_parity.py +++ b/tests/test_image_parity.py @@ -127,7 +127,7 @@ def test_the_shipped_baseline_is_sorted_within_each_group_and_has_no_duplicates( names = [l.split("#")[0].strip() for l in (ROOT / "packages/parity-baseline.txt").read_text().splitlines()] names = [n for n in names if n] self.assertEqual(len(names), len(set(names))) - self.assertEqual(len(names), 970) + self.assertEqual(len(names), 969) def test_the_shipped_exceptions_file_parses_and_every_entry_has_a_reason(self): for exc in parity.load_exceptions(ROOT / "packages/parity-exceptions.toml"): From b03d5074d45343c16a607c2a57a674a9abd02ede Mon Sep 17 00:00:00 2001 From: castrojo Date: Fri, 18 Sep 2026 12:07:29 -0400 Subject: [PATCH 04/11] test(parity): cover the gpg-pubkey filter and correct the baseline header Add a regression test for the asymmetric-filter bug: it fails against the old dict(packages) and passes with the filter in place. Also correct the baseline provenance header, which still quoted the pre-filter totals. Assisted-by: Claude Opus 5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- packages/parity-baseline.txt | 10 ++++++---- tests/test_image_parity.py | 22 ++++++++++++++++++++++ 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/packages/parity-baseline.txt b/packages/parity-baseline.txt index f19cbd40f..d8a9dea39 100644 --- a/packages/parity-baseline.txt +++ b/packages/parity-baseline.txt @@ -3,10 +3,12 @@ # # Generated from the first report scripts/check-image-parity.py produced, in the # build of utah#117 on 2026-09-18 against ghcr.io/ublue-os/bluefin:stable -# (44.20260915): Bluefin installs 1818 packages, Utah 892. This file is the -# debt register. check-image-parity --strict fails on a gap that is NOT here, -# so a new Bluefin package forces a decision; a name that stops being a gap is -# reported as closed and should be removed. Shrinking this file is progress. +# (44.20260915): Bluefin installs 1817 packages, Utah 892, leaving 969 gaps. +# Both counts exclude gpg-pubkey, which is RPM key material rather than a +# package. This file is the debt register. check-image-parity --strict fails +# on a gap that is NOT here, so a new Bluefin package forces a decision; a +# name that stops being a gap is reported as closed and should be removed. +# Shrinking this file is progress. # # The groups say where each name could come from today, measured against # public-hummingbird-x86_64-rpms and the pinned factory image, not guessed. diff --git a/tests/test_image_parity.py b/tests/test_image_parity.py index 371f3b800..364fc39fa 100644 --- a/tests/test_image_parity.py +++ b/tests/test_image_parity.py @@ -83,6 +83,28 @@ def test_an_image_without_the_annotation_is_an_error_not_an_empty_list(self): with self.assertRaises(ValueError): parity.bluefin_inventory("ghcr.io/ublue-os/bluefin:stable", fetch) + def test_gpg_pubkey_is_filtered_out_of_bluefins_inventory(self): + """Both sides must exclude it, or it is reported as a gap forever. + + Utah's side drops gpg-pubkey in parse_rpm_list. It is RPM key material, + not a package, and there is one pseudo-entry per imported key, so if + only one side filters it the comparison invents a gap that can never + be closed. + """ + annotation = json.dumps( + { + "version": 2, + "packages": dict(INVENTORY, **{"gpg-pubkey": "abcd1234-65fe8891"}), + } + ) + fetch = registry({self.base + "stable": {"annotations": {parity.RECHUNK_ANNOTATION: annotation}}}) + inventory = parity.bluefin_inventory("ghcr.io/ublue-os/bluefin:stable", fetch) + self.assertEqual(inventory, INVENTORY) + self.assertNotIn("gpg-pubkey", inventory) + # and so it never reaches the comparison as a missing package + result = parity.compare(inventory, parity.parse_rpm_list("gpg-pubkey\tabcd1234-65fe8891\n"), set(), []) + self.assertNotIn("gpg-pubkey", result.missing) + class ComparisonTests(unittest.TestCase): def test_a_missing_name_is_a_gap_unless_explained(self): From 6389f1386c0e310168b13e7c3cffc84e37f7d74c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 17:37:56 +0000 Subject: [PATCH 05/11] Drop the 25 baseline names main now installs, and merge main #116 (glibc-all-langpacks) and #129 (the [parity] section) landed after the baseline was generated, closing 25 of its 969 names. By the file's own rule they come out: 944 remain, 253 of them in Hummingbird's repository. The pinned count in tests/test_image_parity.py follows. The header keeps the Bluefin and Utah totals from the run that generated it and says so; the next image build's report is where the refreshed Utah count comes from. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M --- packages/parity-baseline.txt | 30 ++++-------------------------- tests/test_image_parity.py | 2 +- 2 files changed, 5 insertions(+), 27 deletions(-) diff --git a/packages/parity-baseline.txt b/packages/parity-baseline.txt index d8a9dea39..7fc4ff69c 100644 --- a/packages/parity-baseline.txt +++ b/packages/parity-baseline.txt @@ -4,6 +4,9 @@ # Generated from the first report scripts/check-image-parity.py produced, in the # build of utah#117 on 2026-09-18 against ghcr.io/ublue-os/bluefin:stable # (44.20260915): Bluefin installs 1817 packages, Utah 892, leaving 969 gaps. +# 25 of those closed when #116 (glibc-all-langpacks) and #129 (the [parity] +# section) landed on main, so the register now holds 944; the Utah count +# above is from the pre-#129 build and is refreshed from the next report. # Both counts exclude gpg-pubkey, which is RPM key material rather than a # package. This file is the debt register. check-image-parity --strict fails # on a gap that is NOT here, so a new Bluefin package forces a decision; a @@ -15,16 +18,13 @@ # Many names in the last group are dependencies that arrive on their own once # their top-level package has a recipe. -# --- in Hummingbird's repository today (277): installable by adding to the contract +# --- in Hummingbird's repository today (253): installable by adding to the contract NetworkManager-adsl NetworkManager-bluetooth -NetworkManager-config-connectivity-fedora NetworkManager-ppp NetworkManager-wifi NetworkManager-wwan -abattis-cantarell-fonts acl -alsa-ucm apr apr-util apr-util-lmdb @@ -33,9 +33,7 @@ attr avahi avahi-gobject avahi-tools -bash-completion bind-libs -bind-utils boost-filesystem boost-program-options buildah @@ -45,14 +43,12 @@ capstone coreutils coreutils-common cracklib-dicts -crypto-policies-scripts cups cups-client cups-ipptool cyrus-sasl-gssapi cyrus-sasl-plain dbus-daemon -dbus-tools dbus-x11 default-fonts-am default-fonts-ar @@ -68,8 +64,6 @@ default-fonts-cjk-mono default-fonts-cjk-serif default-fonts-core-emoji default-fonts-core-math -default-fonts-core-mono -default-fonts-core-serif default-fonts-dv default-fonts-dz default-fonts-el @@ -140,7 +134,6 @@ gd gdbm git git-core-doc -glibc-all-langpacks gnulib-l10n gnutls-dane google-noto-naskh-arabic-vf-fonts @@ -161,15 +154,12 @@ google-noto-sans-javanese-fonts google-noto-sans-kannada-vf-fonts google-noto-sans-khmer-vf-fonts google-noto-sans-lao-vf-fonts -google-noto-sans-math-fonts google-noto-sans-meetei-mayek-vf-fonts -google-noto-sans-mono-vf-fonts google-noto-sans-nko-fonts google-noto-sans-ol-chiki-vf-fonts google-noto-sans-oriya-vf-fonts google-noto-sans-sinhala-vf-fonts google-noto-sans-sundanese-fonts -google-noto-sans-symbols-2-fonts google-noto-sans-symbols-vf-fonts google-noto-sans-syriac-vf-fonts google-noto-sans-tamil-vf-fonts @@ -193,24 +183,18 @@ google-noto-serif-sinhala-vf-fonts google-noto-serif-tamil-vf-fonts google-noto-serif-telugu-vf-fonts google-noto-serif-thai-vf-fonts -google-noto-serif-vf-fonts gpgmepp graphviz-libs hiredis -hostname httpd httpd-core httpd-filesystem httpd-tools hwloc-libs ima-evm-utils-libs -iptables-nft -keyutils krb5-pkinit krb5-workstation langpacks-core-en -langpacks-en -langpacks-fonts-en libXpm libb2 libbabeltrace @@ -235,7 +219,6 @@ libzip libzstd-devel llhttp m4 -man-db mod_lua ncurses-term openssl-devel @@ -256,7 +239,6 @@ python3-charset-normalizer python3-cryptography python3-file-magic python3-idna -python3-pip python3-pycparser python3-pyyaml python3-requests @@ -275,24 +257,20 @@ rpm-plugin-dbus-announce rpm-sign-libs spdlog sudo-python-plugin -systemd-container systemd-networkd systemd-oomd-defaults tcl tpm2-tss-fapi unbound-anchor unbound-libs -unzip uriparser userspace-rcu vim-common vim-enhanced xmlsec1 xmlsec1-openssl -xxd xxhash-libs zeromq -zip # --- in the pinned factory image only (61): installable, needs the closure to resolve ModemManager diff --git a/tests/test_image_parity.py b/tests/test_image_parity.py index 364fc39fa..500e32995 100644 --- a/tests/test_image_parity.py +++ b/tests/test_image_parity.py @@ -149,7 +149,7 @@ def test_the_shipped_baseline_is_sorted_within_each_group_and_has_no_duplicates( names = [l.split("#")[0].strip() for l in (ROOT / "packages/parity-baseline.txt").read_text().splitlines()] names = [n for n in names if n] self.assertEqual(len(names), len(set(names))) - self.assertEqual(len(names), 969) + self.assertEqual(len(names), 944) def test_the_shipped_exceptions_file_parses_and_every_entry_has_a_reason(self): for exc in parity.load_exceptions(ROOT / "packages/parity-exceptions.toml"): From 6ddc2443eea79683335b768dc90809ee82e36fa2 Mon Sep 17 00:00:00 2001 From: hanthor Date: Sat, 19 Sep 2026 11:21:13 +0000 Subject: [PATCH 06/11] Catch the one fetch failure that is not an OSError Review finding on head d9c3bb2, and it is right: the handler that turns an unreadable Bluefin inventory into a report-only skip catches URLError, ValueError, KeyError and OSError, but urlopen(...).read() can also raise http.client.HTTPException -- IncompleteRead on a truncated response. That is not an OSError, so it escaped the handler and tracebacked out of the step Containerfile:196 runs report-only, whose own comment (Containerfile:198-206) promises a fetch failure cannot fail the build. A truncated read is the failure mode a large manifest fetch is most likely to hit, so this was the gap that mattered rather than an exotic one. The new test patches bluefin_inventory to raise IncompleteRead and asserts the documented contract on both sides: exit 0 report-only, exit 1 under --strict. Checked that it fails against the old catch tuple before adding the fix, so it is a regression test rather than a restatement. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M --- scripts/check-image-parity.py | 9 +++++++-- tests/test_image_parity.py | 20 ++++++++++++++++++++ 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/scripts/check-image-parity.py b/scripts/check-image-parity.py index a998dfb58..f28ebe397 100755 --- a/scripts/check-image-parity.py +++ b/scripts/check-image-parity.py @@ -29,6 +29,7 @@ import argparse import fnmatch +import http.client import json import subprocess import sys @@ -277,10 +278,14 @@ def main(argv: list[str] | None = None) -> int: bluefin = json.loads(args.bluefin_inventory.read_text()) else: bluefin = bluefin_inventory(args.bluefin_image) - except (urllib.error.URLError, ValueError, KeyError, OSError) as exc: + except (urllib.error.URLError, http.client.HTTPException, + ValueError, KeyError, OSError) as exc: # Without Bluefin's inventory there is nothing to compare. That is a # failure of the check, not evidence about the image, so it is fatal - # only when the check is asked to gate. + # only when the check is asked to gate. http.client.HTTPException is in + # the list because it is not an OSError: a truncated response raises + # IncompleteRead, which would otherwise escape here and traceback out of + # a step the Containerfile comment promises cannot fail the build. message = f"could not read Bluefin's inventory from {args.bluefin_image}: {exc}" print(message, file=sys.stderr) if args.report: diff --git a/tests/test_image_parity.py b/tests/test_image_parity.py index 500e32995..a22b78170 100644 --- a/tests/test_image_parity.py +++ b/tests/test_image_parity.py @@ -5,12 +5,14 @@ manifest, the comparison, and the exit code. """ +import http.client import importlib.util import json import sys import tempfile import unittest from pathlib import Path +from unittest.mock import patch ROOT = Path(__file__).resolve().parents[1] @@ -197,6 +199,24 @@ def test_strict_tolerates_a_gap_the_baseline_already_records(self): self.assertIn("known gap (baseline):", report) self.assertNotIn("NEW --", report) + def test_a_truncated_response_is_handled_like_any_other_fetch_failure(self): + """IncompleteRead is an HTTPException, not an OSError. + + The Containerfile runs this step report-only and its comment promises a + fetch failure cannot fail the build. An exception outside the handler's + tuple would traceback instead, breaking that promise for the one failure + mode a large manifest fetch is most likely to hit. + """ + with tempfile.TemporaryDirectory() as tmp: + Path(tmp, "x").write_text("nautilus\n") + args = ["--bluefin-image", "ghcr.io/ublue-os/bluefin:stable", + "--rpm-list", str(Path(tmp) / "x"), + "--exceptions", str(Path(tmp) / "none")] + truncated = http.client.IncompleteRead(b"partial") + with patch.object(parity, "bluefin_inventory", side_effect=truncated): + self.assertEqual(parity.main(args), 0) + self.assertEqual(parity.main([*args, "--strict"]), 1) + def test_an_unreadable_registry_is_not_evidence_about_the_image(self): with tempfile.TemporaryDirectory() as tmp: args = ["--bluefin-image", "ghcr.io/nowhere/nothing:tag", "--rpm-list", str(Path(tmp) / "x")] From 3dd1397005a337665e10a0a85ecab8a5a74b1480 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Sun, 20 Sep 2026 12:05:14 -0400 Subject: [PATCH 07/11] docs(readme): describe the image-level parity check The parity section only described the list-to-list contract diff, so the top-level doc understated how parity is measured now that the build also compares this image's rpm -qa with Bluefin's published inventory. Name the check, the baseline register, the in-image artifacts and the just recipe. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index 24a33bad5..240c974c6 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,26 @@ than being noticed later. The install writes its resolved list to `/usr/share/utah/contract.txt` and the verify step asserts *that file*, so the two cannot disagree. +That is a list-to-list check, and a list never names what Bluefin's Silverblue +base already carried — which is where the gaps that reached users hid +(`glibc-all-langpacks` #114, `linux-firmware` and the iwlwifi blobs #97). So +the build also compares the two *images*: `scripts/check-image-parity.py` reads +Bluefin's full installed inventory from the `dev.hhd.rechunk.info` annotation on +its manifest (one registry GET, no pull), diffs it against this image's `rpm +-qa` by name, and reports every name Bluefin has that Utah lacks. A gap is +explained if `utah.toml` lists it under `[unavailable]` or +`packages/parity-exceptions.toml` gives a reason; the report prints the reason. + +`packages/parity-baseline.txt` is the debt register — the 944 gaps already known, +grouped by where each name could come from today. The report separates a *new* +gap from a known one and names baseline entries that have closed, so the file +gets trimmed. Report-only in the build for now; `--strict` turns a new gap into +a build failure. Both the image's package list +(`/usr/share/utah/packages.txt`) and the report +(`/usr/share/utah/parity-report.txt`) ship in the image, so any published image +can be asked what it has, and `just check-image-parity IMAGE` runs the strict +comparison against a built image locally. + ## Known gaps From 82de901a57e9a7786caaa578aa968b42b22ba1ca Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Sun, 20 Sep 2026 12:46:37 -0400 Subject: [PATCH 08/11] fix(parity): close a baseline entry that gains an explanation compare() diverted a missing name to explained before consulting the baseline, and closed only tested membership in this image or absence from Bluefin. A parity-baseline.txt entry that later gained an [unavailable] entry or a parity-exceptions.toml pattern therefore lingered in the register unreported, contradicting the file header's promise that a name which stops being a gap is reported as closed and removed. Fold the explained names into the closed set and cover it with a test. Assisted-by: Claude Opus 5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scripts/check-image-parity.py | 12 +++++++++--- tests/test_image_parity.py | 13 +++++++++++++ 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/scripts/check-image-parity.py b/scripts/check-image-parity.py index f28ebe397..2283299f3 100755 --- a/scripts/check-image-parity.py +++ b/scripts/check-image-parity.py @@ -208,9 +208,15 @@ def compare( else: (result.known if name in baseline else result.new).append(name) result.extra = sorted(name for name in utah if name not in bluefin) - # A baseline entry this image now has, or Bluefin no longer ships, is - # paid-down debt: say so, so the file gets trimmed. - result.closed = sorted(name for name in baseline if name in utah or name not in bluefin) + # A baseline entry this image now has, that Bluefin no longer ships, or + # that gained an explanation is paid-down debt: say so, so the file gets + # trimmed. An explained name is no longer a gap the register must carry. + explained_names = {name for name, _ in result.explained} + result.closed = sorted( + name + for name in baseline + if name in utah or name not in bluefin or name in explained_names + ) return result diff --git a/tests/test_image_parity.py b/tests/test_image_parity.py index a22b78170..369e5749b 100644 --- a/tests/test_image_parity.py +++ b/tests/test_image_parity.py @@ -141,6 +141,19 @@ def test_a_baseline_separates_known_gaps_from_new_ones_and_reports_closed_ones(s self.assertEqual(result.closed, ["nautilus"]) self.assertEqual(result.missing, ["glibc-all-langpacks", "kmod-zfs"]) + def test_a_baseline_entry_that_gains_an_explanation_is_closed(self): + """An explained name stops being a gap, so the register must drop it. + + Without this the entry lingers: it is diverted to explained before the + baseline is consulted, so it is neither a known gap nor reported closed. + """ + baseline = {"glibc-all-langpacks", "kmod-zfs", "nautilus"} + exceptions = [parity.Exception_("kmod-*", "no akmods for this kernel")] + result = parity.compare(INVENTORY, {}, {"nautilus"}, exceptions, baseline) + self.assertEqual(result.known, ["glibc-all-langpacks"]) + self.assertEqual(result.new, []) + self.assertEqual(result.closed, ["kmod-zfs", "nautilus"]) + def test_baseline_file_ignores_comments_and_blank_lines(self): with tempfile.TemporaryDirectory() as tmp: path = Path(tmp) / "baseline.txt" From f565e5469854dd64046ac8ff1737a76a0922e286 Mon Sep 17 00:00:00 2001 From: James Reilly Date: Mon, 21 Sep 2026 12:09:48 +0530 Subject: [PATCH 09/11] docs: bring parity counts current for image-level check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The overlay now carries [parity] (28 names) beyond GNOME and services, and the debt register holds 9 unavailable entries, but both README and the package-contract skill still quoted 12 Utah additions and 4 unavailable — the pre-parity numbers. The Failure semantics paragraph also listed only GNOME, services and build tools as the install set. Update both counts to 44/9 for this branch's reality (44 = 11 GNOME + 28 parity + 5 services) and include parity in the install-set sentence. The image-level parity section itself already describes the new mechanism; this fixes the stale table that contradicts it. When this lands with the hardware firmware PR (#105), the combined total will be 49/11 — that PR updates the same lines with the hardware addition. Assisted-by: Muse Spark via Muse Code Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 4 ++-- docs/skills/package-contract.md | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 240c974c6..c70645550 100644 --- a/README.md +++ b/README.md @@ -62,8 +62,8 @@ than being noticed later. | | count | | --- | --- | | Bluefin contract installed | **61** | -| Utah additions (GNOME 51, desktop services) | 12 | -| Genuinely unavailable | **4** | +| Utah additions (GNOME 51, parity, desktop services) | **44** | +| Genuinely unavailable | **9** | The install writes its resolved list to `/usr/share/utah/contract.txt` and the verify step asserts *that file*, so the two cannot disagree. diff --git a/docs/skills/package-contract.md b/docs/skills/package-contract.md index b21d986f3..af2998a91 100644 --- a/docs/skills/package-contract.md +++ b/docs/skills/package-contract.md @@ -136,7 +136,8 @@ releases or emit missing-module errors with empty kernel names. is a **build failure**. `just check-repos` reads the base and package-image digests from `Containerfile`, copies the same repository configuration, and runs `install-packages.py --resolve` inside that base. This includes the - release-specific Bluefin section, GNOME, services, and extension build tools. + release-specific Bluefin section, GNOME, parity, services, and extension + build tools. It needs Podman and network access. A name lookup on GitHub Pages is not evidence that the pinned OCI repository is complete or ABI-compatible. The factory's leading metadata layer is checked against the pinned manifest @@ -158,7 +159,7 @@ default branch, preventing unrelated upstream changes from breaking Utah's CI. Update it whenever synchronizing `packages/bluefin.toml` with upstream. Current counts, per the README "Package parity" section: 61 Bluefin contract -packages installed, 12 Utah additions (GNOME 51, desktop services), 4 +packages installed, 44 Utah additions (GNOME 51, parity, desktop services), 9 genuinely unavailable. ## Image-level parity From 0ea70b9eb41e8acbf5ebca30ad8b7d2815992638 Mon Sep 17 00:00:00 2001 From: castrojo Date: Tue, 22 Sep 2026 15:04:25 -0400 Subject: [PATCH 10/11] docs(skills): normalize skill catalog formatting --- docs/skills/index.json | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/skills/index.json b/docs/skills/index.json index 2a4deacb6..6641f793a 100644 --- a/docs/skills/index.json +++ b/docs/skills/index.json @@ -1,5 +1,4 @@ { - "schema_version": "1.0", "skills": [ { From 9e28cc64c6c3b35c5b6e503bf977442fcb3fc963 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Wed, 23 Sep 2026 10:14:21 -0400 Subject: [PATCH 11/11] fix(parity): make the baseline's own group counts the tripwire The group headers still claimed 253 and 632 after the 25-entry trim the preamble describes; the groups hold 252 and 631. Correct them, and replace the test's hardcoded total of 944 with a per-group check that each header's count matches its members and each group is sorted -- which is what the test name already promised. A trim is now a one-file edit instead of three, and the header can no longer drift from the list it describes. Drop the same hardcoded total from the README for the same reason. Also add the Containerfile comment that scripts/check-image-parity.py and tests/test_image_parity.py both cite: the parity step is report-only and a fetch failure cannot fail the build. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- Containerfile | 3 +++ README.md | 2 +- packages/parity-baseline.txt | 4 ++-- tests/test_image_parity.py | 22 +++++++++++++++++++--- 4 files changed, 25 insertions(+), 6 deletions(-) diff --git a/Containerfile b/Containerfile index fd74ac00e..c0dce73ad 100644 --- a/Containerfile +++ b/Containerfile @@ -202,6 +202,9 @@ RUN --mount=type=bind,from=packages,source=/repository,target=/etc/utah-packages IMAGE_FLAVOR="${IMAGE_FLAVOR}" /usr/local/libexec/utah-verify-rpm-contract \ /usr/share/utah/bluefin.toml /usr/share/utah/utah.toml && \ rpm -qa --qf '%{NAME}\t%{VERSION}-%{RELEASE}\n' | sort > /usr/share/utah/packages.txt && \ + # Report-only: without --strict this step records the gaps against Bluefin's + # image and exits 0 even when the inventory fetch fails, so neither a new gap + # nor an unreachable registry can fail the build. /usr/local/libexec/utah-check-image-parity --report /usr/share/utah/parity-report.txt && \ # The package repository is now only ever bind mounted, so it is absent from # the committed image. Flip it disabled here -- the last step that installs diff --git a/README.md b/README.md index a81d4b9ac..b3b713ed4 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ its manifest (one registry GET, no pull), diffs it against this image's `rpm explained if `utah.toml` lists it under `[unavailable]` or `packages/parity-exceptions.toml` gives a reason; the report prints the reason. -`packages/parity-baseline.txt` is the debt register — the 944 gaps already known, +`packages/parity-baseline.txt` is the debt register — the gaps already known, grouped by where each name could come from today. The report separates a *new* gap from a known one and names baseline entries that have closed, so the file gets trimmed. Report-only in the build for now; `--strict` turns a new gap into diff --git a/packages/parity-baseline.txt b/packages/parity-baseline.txt index 7fc4ff69c..0e2400537 100644 --- a/packages/parity-baseline.txt +++ b/packages/parity-baseline.txt @@ -18,7 +18,7 @@ # Many names in the last group are dependencies that arrive on their own once # their top-level package has a recipe. -# --- in Hummingbird's repository today (253): installable by adding to the contract +# --- in Hummingbird's repository today (252): installable by adding to the contract NetworkManager-adsl NetworkManager-bluetooth NetworkManager-ppp @@ -335,7 +335,7 @@ samba-winbind-modules setools-console tiwilink-firmware -# --- in no enabled repository (632): needs a factory recipe, or is deliberate +# --- in no enabled repository (631): needs a factory recipe, or is deliberate 7zip ImageMagick ImageMagick-libs diff --git a/tests/test_image_parity.py b/tests/test_image_parity.py index 369e5749b..1a4bcd37d 100644 --- a/tests/test_image_parity.py +++ b/tests/test_image_parity.py @@ -8,6 +8,7 @@ import http.client import importlib.util import json +import re import sys import tempfile import unittest @@ -161,10 +162,25 @@ def test_baseline_file_ignores_comments_and_blank_lines(self): self.assertEqual(parity.load_baseline(path), {"nautilus", "7zip"}) def test_the_shipped_baseline_is_sorted_within_each_group_and_has_no_duplicates(self): - names = [l.split("#")[0].strip() for l in (ROOT / "packages/parity-baseline.txt").read_text().splitlines()] - names = [n for n in names if n] + text = (ROOT / "packages/parity-baseline.txt").read_text() + groups, current = {}, None + for line in text.splitlines(): + header = re.match(r"# --- (.*) \((\d+)\):", line) + if header: + current = (header.group(1), int(header.group(2))) + groups[current] = [] + continue + name = line.split("#")[0].strip() + if name and current: + groups[current].append(name) + self.assertTrue(groups) + names = [n for group in groups.values() for n in group] self.assertEqual(len(names), len(set(names))) - self.assertEqual(len(names), 944) + for (label, claimed), group in groups.items(): + # The header count is the tripwire, not a total hardcoded here: a + # trim stays a one-file edit, but it has to keep the file honest. + self.assertEqual(group, sorted(group), f"group {label!r} is not sorted") + self.assertEqual(len(group), claimed, f"group {label!r} header count is wrong") def test_the_shipped_exceptions_file_parses_and_every_entry_has_a_reason(self): for exc in parity.load_exceptions(ROOT / "packages/parity-exceptions.toml"):