Skip to content

feat(parity): compare the built image with Bluefin's image, not list with list - #117

Closed
hanthor wants to merge 13 commits into
mainfrom
claude/image-parity
Closed

hanthor wants to merge 13 commits into
mainfrom
claude/image-parity

Conversation

@hanthor

@hanthor hanthor commented Sep 18, 2026 •

Copy link
Copy Markdown
Member

Why

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.

No pull needed for Bluefin's side

Every Bluefin image is rechunked, and the rechunker writes the complete 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, run inside the image build right after the flavor-aware utah-verify-rpm-contract, so every flavor is compared on what it actually installed.

What the first run found

Bluefin installs 1818 packages, this image 892
in Bluefin, not here, unexplained: 970

More than half of Bluefin's inventory is absent, while check-parity has been green. Measured against Hummingbird's repodata and the pinned factory image: 277 are in Hummingbird today, 61 in the factory image, 632 nowhere. One consequence: Wi-Fi is uninstallable on Utah (NetworkManager-wifi needs wpa_supplicant/iwd + wireless-regdb, none exist anywhere) — projectbluefin/utah-packages#136. Details in the comment below.

What it does

  • scripts/check-image-parity.py reads the annotation (following a multi-arch index to linux/amd64), 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 (starts with the three akmods names, the one difference already documented as deliberate).
  • packages/parity-baseline.txt is the debt register: the 970 known gaps, grouped by where each could come from today. The report separates a NEW gap (Bluefin started shipping something Utah lacks) from a known one, and names baseline entries that have closed, so the file gets trimmed. --strict fails only on a new gap.
  • Both the inventory (packages.txt) and the report ship in the image under /usr/share/utah/. just check-image-parity IMAGE runs the strict comparison 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.

Report-only in the Containerfile today; flipping --strict is one word once builds should fail on new drift.

Verification

  • Live registry path exercised from this environment: 1818 packages read, the contract's [unavailable] names correctly explained.
  • Baseline mechanics verified against the reconstructed inventory of this PR's own build (892 names): NEW 0 / known 970 / closed 0 under --strict; drop a baseline name → NEW 1, exit 1; add that package → reported closed.
  • 16 offline tests in tests/test_image_parity.py; 112 pass overall. Every Containerfile RUN parses as bash once joined the way Docker joins continuations. Skill index regenerated; syntax and download-integrity gates clean.
  • The image build is this PR's own CI, which is where the report above came from.

🤖 Generated with Claude Code

https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M

@hanthor

hanthor commented Sep 18, 2026

Copy link
Copy Markdown
Member Author

The first real report

From this PR's own build_main job (run 35316037854), against ghcr.io/ublue-os/bluefin:stable (44.20260915):

Bluefin installs 1818 packages, this image 892
in Bluefin, not here, unexplained: 970
in Bluefin, not here, explained:   9
here, not in Bluefin:              53

So the list-to-list check-parity has been green while more than half of Bluefin's inventory is absent from Utah's image. Measured against public-hummingbird-x86_64-rpms and the pinned factory image (not guessed), the 970 split as:

where the name is today count what it takes
Hummingbird's repository 277 add to the contract (closure permitting)
pinned factory image only 61 add to the contract (closure permitting)
nowhere 632 a factory recipe, or a deliberate exception

Many of the 632 are dependencies that arrive on their own once a top-level package has a recipe (libavcodec ← ffmpeg, the sane-* set, hplip-*, plymouth-*, the qt5-*/qt6-* runtime). Some are deliberate by construction (fedora-release-*, rpm-ostree, hyperv*, zfs, kernel-*).

Two things in that list matter more than the count:

What changed in c00ac03

An exceptions file cannot carry 970 names honestly, and --strict against that many would only ever fail. So the check now has a baseline: packages/parity-baseline.txt records the 970 known gaps, grouped by the table above, and the report separates a NEW gap (Bluefin started shipping something Utah lacks) from a known one, and names baseline entries that have closed so the file gets trimmed. --strict fails only on a new gap. Shrinking the file is how parity gets paid down; growing it is a decision.

Verified against the reconstructed inventory of that build (892 names): NEW 0 / known 970 / closed 0 under --strict; drop one name from the baseline → NEW 1, exit 1; add that package to the inventory → reported closed. Still report-only in the Containerfile; flipping --strict is one word once you want builds to fail on new drift.


Generated by Claude Code

hanthor pushed a commit that referenced this pull request Sep 18, 2026
…ady has

The image-level parity report (#117) found 277 packages in Bluefin's image
that Utah's lacks and that public-hummingbird-x86_64-rpms carries today:
Bluefin never names them because Silverblue's base supplies them, and
Hummingbird's server-shaped bootable base leaves them out. A new [parity]
section in packages/utah.toml adds the desktop-relevant ones -- the
NetworkManager Bluetooth and WWAN plugins and connectivity check, ALSA
use-case profiles, the English language pack and core font set, and the
shell tooling Bluefin users reach for -- 30 names, each with its Requires
resolved against Hummingbird plus the pinned factory repository before it
went in. Dakota ships the same networking, audio and font pieces.

What did not resolve is recorded beside the list rather than dropped
silently: cups needs cups-filters, vim-enhanced needs gpm, the emoji and
math default fonts need google-noto-emoji-color-fonts and stix-fonts, and
fprintd and alsa-utils are in no repository at all. NetworkManager-wifi
waits for the factory image that carries wpa_supplicant and
wireless-regdb (utah-packages#133).

install-packages.py adds the section to the install set, verify-rpm-contract
asserts it on the built image like [hardware], and the tests cover both
paths plus a check that [parity] never duplicates a name another section
already claims (unzip was one, via [build]).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M

@castrojo castrojo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolved the conflict and fixed one defect on the branch. What is left is a design call I do not want to make unilaterally, plus a merge-order question.

Fixed on this branch

8e38fd9 — gpg-pubkey was reported as a permanent false gap. parse_rpm_list strips it from Utah's rpm -qa, but bluefin_inventory returned the rechunk annotation unfiltered (return dict(packages)), so the name existed on exactly one side of the comparison. Your own build shows the consequence: gpg-pubkey is listed among the missing packages, and it was recorded in packages/parity-baseline.txt as permanent debt. gpg-pubkey is RPM key material, not a package, and there is one pseudo-entry per imported key, so an asymmetric filter can only ever manufacture a gap that can never close. Applied the same exclusion on the Bluefin side, dropped the baseline line (970 -> 969), and moved the pinned count in tests/test_image_parity.py.

483404e — regression test + header correction. Added test_gpg_pubkey_is_filtered_out_of_bluefins_inventory. I confirmed it is a real regression test, not decoration: it FAILS against the old return dict(packages) and passes with the filter. Also corrected the baseline provenance header, which still quoted pre-filter totals (now 1817 / 892 / 969, and says both sides exclude gpg-pubkey).

c38284c — merged current main. The conflict was exactly two files, docs/skills/index.json and index.md, and purely generated: main regenerated the catalog for desktop-contract in 68d0432, this branch regenerated it for package-contract in 8c0234d. The underlying skill entries auto-merge. Resolved by regenerating rather than hand-picking a side. generate_skill_index.py --check exits 0 and all 18 tests pass.

I merged rather than rebased deliberately — this branch already uses merge commits, and rebasing would rewrite your commits under you.

For a second reviewer to weigh: the checked-in baseline

packages/parity-baseline.txt is a 969-name derived snapshot with no checked-in generator. The script reads and classifies it but cannot reproduce it, so the three availability groups are hand-curated provenance. That is a new pattern for this repo — packages/ has only held TOML inputs and a repo file until now.

I think it is defensible: it is explicitly a debt register, --strict turns a new gap into a decision, and shrinking it is the stated goal. But "990-line derived file that nothing regenerates" is exactly the kind of thing that rots silently, and it is a taste call about the repo's shape rather than a correctness question — so it should have a second opinion, not just mine.

Also note bluefin_inventory reads ghcr.io/ublue-os/bluefin:stable, a mutable tag, over the network at image-build time. That is deliberate (you want current stable), but it means an image build's parity result is not reproducible from the commit alone, and a Bluefin release can change this check's output with no change here. Worth stating in the skill doc.

Merge order

PR #105 is the semantic successor: its parity commit consumes these measured gaps, and 31 of the names it adds are in this baseline. Land #105 first and this baseline needs those 31 entries removed; land this first and #105 has to update the baseline when it goes in. #105 is currently red and awaiting its author, so this one may well land first — just do not let both land without reconciling the counts.

For the record: 31d765bd (the parity-contract sync that appears in #105 and #112) is not in this branch. This descends from main's already-landed equivalent (83ad691, #110), so there is no duplication.

One thing that is not this PR's fault

pre-commit run --all-files currently fails on this branch with ten label "ubuntu-26.04" is unknown errors from actionlint. That is inherited from main after I merged #123, not something this PR introduced — actionlint's hardcoded label table predates the runner's GA and CI does not run actionlint at all. I have a fix prepared on fix/actionlint-ubuntu-26-label. Ignore those errors when reviewing this.

Not approving: I pushed to this branch, so the approval has to come from someone else regardless, and the baseline-pattern question deserves a fresh pair of eyes.

castrojo pushed a commit that referenced this pull request Sep 18, 2026
…ady has (#129)

The image-level parity report (#117) found 277 packages in Bluefin's image
that Utah's lacks and that public-hummingbird-x86_64-rpms carries today:
Bluefin never names them because Silverblue's base supplies them, and
Hummingbird's server-shaped bootable base leaves them out. A new [parity]
section in packages/utah.toml adds the desktop-relevant ones -- the
NetworkManager connectivity check, ALSA use-case profiles, the English
language pack and core font set, and the shell tooling Bluefin users reach
for -- 28 names.

This is the sweep that briefly rode on #105 and was lifted out at review:
out of scope there, and its first version was red. Three names from that
version are gone because CI's real transaction rejected their closures,
which a first-level Requires check had missed: NetworkManager-wwan needs
ModemManager, whose factory build needs libmbim, libqmi and libqrtr-glib
that nothing provides; NetworkManager-bluetooth needs libnm-wwan.so from
the wwan plugin; poppler-utils needs poppler-data, which Hummingbird does
not ship. Each is recorded beside the list with the others that did not
resolve (cups, vim-enhanced, the emoji and math fonts, fprintd,
alsa-utils), each with its tracking issue.

unzip is listed and kept: it was already in [build], but
configure-services.sh removed the build tooling after the extension
build, so the image did not actually ship it. The removal now skips it
and a test pins both halves.

install-packages.py adds the section to the install set,
verify-rpm-contract asserts it on the built image, and the tests cover
the install path, the verifier, and that [parity] duplicates no other
section's claim. CI's package availability step is the gate on every
name here. Whichever of this and #117 lands second updates
parity-baseline.txt.


Claude-Session: https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M

Co-authored-by: Claude <noreply@anthropic.com>

@castrojo castrojo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up to my earlier review: the merge-order dependency I flagged as hypothetical is now active. #129 landed (22166572), and #116 landed before it (8cf3cefa), so this branch's baseline is stale as of current main.

I measured it rather than estimating. Against origin/main at 22166572, taking the union of what packages/utah.toml now installs ([parity] + [hardware] + [gnome]) and intersecting with this PR's packages/parity-baseline.txt:

117 baseline entries:                                    969
main now installs (parity+hardware+gnome):                39
baseline entries CLOSED by what main now installs:        25

The 25:

NetworkManager-config-connectivity-fedora  abattis-cantarell-fonts
alsa-ucm                                   bash-completion
bind-utils                                 crypto-policies-scripts
dbus-tools                                 default-fonts-core-mono
default-fonts-core-serif                   glibc-all-langpacks
google-noto-sans-math-fonts                google-noto-sans-mono-vf-fonts
google-noto-sans-symbols-2-fonts           google-noto-serif-vf-fonts
hostname                                   iptables-nft
keyutils                                   langpacks-en
langpacks-fonts-en                         man-db
python3-pip                                systemd-container
unzip                                      xxd
zip

glibc-all-langpacks comes from #116; the other 24 from #129.

By the baseline file's own stated rule — "a name that stops being a gap is reported as closed and should be removed. Shrinking this file is progress." — these 25 have to come out, taking the count 969 -> 944, along with the pinned count in tests/test_image_parity.py and the provenance header totals.

This will not fail CI, because the comparison is report-only during image builds and --strict is opt-in through just check-image-parity. That is exactly why I am marking it blocking rather than leaving a note: nothing automated will catch a stale debt register, and a debt register that overstates the debt is worse than none — it trains people to ignore it.

Requesting changes for:

  1. Remove those 25 names from packages/parity-baseline.txt.
  2. Update the pinned count in tests/test_image_parity.py (currently 969 after my 8e38fd9) to match.
  3. Update the header totals, which I already corrected once to 1817 / 892 / 969 — the Utah side and gap count both move again now.
  4. Re-run the image build so the reported numbers come from a real run against current main rather than the pre-#129 snapshot.

Worth regenerating after the rebase rather than hand-editing 25 lines; the numbers should come from the tool.

Everything from my previous review still stands: the conflict is resolved, the gpg-pubkey asymmetry is fixed with a regression test, and the open design question — a 969-line derived baseline with no checked-in generator, plus reading a mutable :stable tag at build time — still deserves a second opinion from someone other than me.

@hanthor

hanthor commented Sep 18, 2026

Copy link
Copy Markdown
Member Author

@castrojo d9c3bb2 merges main and removes the 25 names it now installs (your list matched the file exactly): 969 to 944, 277 to 253 in the Hummingbird group, and 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 now says so; once this build's report prints the post-#129 Utah count I will put that number in rather than guess it.

On the design question (a derived baseline with no checked-in generator, and reading :stable at build time): agreed it deserves another reader. The generator is the report itself — check-image-parity.py --report writes the same grouped list — so the missing piece is a just recipe that regenerates the file from a built image, which I can add here or as a follow-up, whichever you prefer.


Generated by Claude Code

@hanthor
hanthor requested a review from castrojo September 18, 2026 17:38

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correctness review (head d9c3bb2) — no blockers; one edge case worth noting.

  • low — scripts/check-image-parity.py:294-303: the "an unreachable registry fails only under --strict" contract catches URLError, ValueError, KeyError, OSError, but urlopen(...).read() (scripts/check-image-parity.py:64-67) can also raise http.client.HTTPException (e.g. IncompleteRead on a truncated response), which is not an OSError. That escapes the handler, tracebacks, and fails the report-only build step at Containerfile:196 — exactly the outcome the surrounding comment (Containerfile:198-206) says cannot happen. Adding http.client.HTTPException to the catch tuple closes it.
  • info — scripts/check-image-parity.py:232: a baseline name that later gains an exception/[unavailable] entry is routed to explained before the baseline check and never satisfies the closed condition (still in bluefin, still not installed), so it lingers in parity-baseline.txt with no "remove me" signal. Harmless to gating, but it works against the "shrink the baseline" workflow the file header promises.

Verified: comparison/baseline/strict semantics match the PR body; gpg-pubkey is filtered on both sides (scripts/check-image-parity.py:117-122,137); the shipped baseline has 944 unique names, matching tests/test_image_parity.py:151-155. Not verified from here: the live dev.hhd.rechunk.info annotation shape and build-time network access to ghcr.io in CI (report-only, so worst case is a skipped report — per the low finding above, plus the HTTPException crash case).

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78

@hanthor

hanthor commented Sep 19, 2026

Copy link
Copy Markdown
Member Author

Caught up on all three reviews. f8fda0b fixes the one actionable finding from the latest one.

http.client.HTTPException escaping the handler — correct, and it is the failure mode that matters rather than an exotic one. A truncated manifest read raises IncompleteRead, which is not an OSError, so it tracebacked straight out of the step Containerfile:196 runs report-only — the step whose own comment promises a fetch failure cannot fail the build. Now caught, with the comment saying why it is in the tuple. The test patches bluefin_inventory to raise IncompleteRead and asserts both halves of the documented contract (exit 0 report-only, exit 1 under --strict); I confirmed it fails against the old catch tuple before adding the fix.

The explained-before-closed ordering (info): agreed that it works against the "shrink the baseline" workflow — a name that later gains an [unavailable] entry is routed to explained and never reports as removable, so it sits in the file with no signal. I have left it alone here because changing the classification order changes what --strict gates on, and this PR is already carrying a design question. Worth its own change.

@castrojo — your blocking review asked for four things, and I believe all four are done, so this is ready for another look:

  1. The 25 names closed by feat(packages): install what Bluefin inherits from Fedora's base and Hummingbird already has #129 and fix(packages): ship glibc-all-langpacks so a chosen locale exists #116 are out of packages/parity-baseline.txt (d9c3bb2).
  2. The pinned count in tests/test_image_parity.py is 944.
  3. The provenance header totals moved with it.
  4. The numbers come from a run against post-feat(packages): install what Bluefin inherits from Fedora's base and Hummingbird already has #129 main, not the pre-feat(packages): install what Bluefin inherits from Fedora's base and Hummingbird already has #129 snapshot.

The correctness review on that head independently counted 944 unique names in the shipped baseline and confirmed it matches the pinned count, which is a second pair of eyes on point 1 at least.

Still open and still yours to call, not mine: the 944-line derived baseline with no checked-in generator, and bluefin_inventory reading the mutable :stable tag at build time. I have not tried to resolve either unilaterally. On the second one I will add the caveat to the skill doc — that an image build's parity result is not reproducible from the commit alone — since that is worth writing down regardless of which way the first question goes.

Thanks also for 8e38fd9: the gpg-pubkey asymmetry was manufacturing a gap that could never close, and it had already been recorded as permanent debt.


Generated by Claude Code

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed (correctness) — no blockers at head f8fda0b. Three low-severity observations:

  • scripts/check-image-parity.py:277-278 — the --bluefin-inventory JSON path loads the file raw, bypassing the gpg-pubkey filtering that bluefin_inventory() applies to the registry path. Feeding a saved annotation dump through this flag would report the permanent false gap the registry path deliberately excludes.
  • scripts/check-image-parity.py:200-213 — a baseline entry that later gains an [unavailable] or exceptions match is classified explained before the baseline is consulted, and closed only covers in utah or not in bluefin, so such an entry lingers in parity-baseline.txt silently instead of being flagged for removal.
  • tests/test_image_parity.py:150-154 — the test named ...is_sorted_within_each_group... never checks sorting, only dedupe and the hard-coded count 944, which must be hand-edited on every baseline trim the report tells maintainers to make.

All are cosmetic today since the Containerfile step is report-only; none affect the strict exit-code paths, which are well covered by the offline tests.

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed — no findings from this perspective.

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docs-currency

  • README's "Package parity with Bluefin" section (README.md:55-67) still describes only the list-to-list check (bluefin.toml diffed against upstream, contract counts). This PR adds a second, image-level parity mechanism with operator-facing artifacts (/usr/share/utah/packages.txt, /usr/share/utah/parity-report.txt, just check-image-parity, packages/parity-baseline.txt) documented in docs/skills/package-contract.md and ci-workflows.md, but the README section that introduces the parity story wasn't extended to mention it. Low severity, easy addition.

No findings from: security, intent-alignment, style.

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

correctness

  • (low) compare() never reports a baseline entry as closed once it becomes explained. A name in packages/parity-baseline.txt that later gains a parity-exceptions.toml pattern or an [unavailable] entry is diverted into explained before the baseline check (scripts/check-image-parity.py:201-208), and the closed computation only tests name in utah or name not in bluefin (scripts/check-image-parity.py:213). The baseline header's contract — "a name that stops being a gap is reported as closed and should be removed" (packages/parity-baseline.txt:11-13) — is not met for that path, so such entries linger in the register silently. Adding or any explanation matched to the closed set (or asserting baseline ∩ explained is empty) would keep the debt register trimmable as promised.

Verified at head 039b913: the ghcr token is a per-request anonymous pull token, not a secret (scripts/check-image-parity.py:85-87); the baseline holds exactly 944 unique names matching the test's assertion (tests/test_image_parity.py:171-175) and the README's count; the build-time step runs without --strict and the fetch-failure path returns 0 non-strict, so the Containerfile's report-only promise holds (Containerfile:204, scripts/check-image-parity.py:283-296).

No findings from: security, intent-alignment, style, docs-currency.

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

correctness

  • (low) "Report-only" isn't fully non-fatal. The fetch-error handler (scripts/check-image-parity.py:282-296) covers registry failures, but everything after it runs outside any handler: rpm -qa raising CalledProcessError (line 302 → installed_inventory, line 119 check=True), or a malformed /usr/share/utah/parity-exceptions.toml / utah.toml (lines 306-307) tracebacks, exits 1, and fails the &&-chained build step (Containerfile:204) despite the report-only promise. The shipped files parse and are covered by tests, so exposure is low — but wrapping the whole post-fetch path (or the invocation with || true until --strict) would match the stated contract.

intent-alignment

  • (info) The PR body's counts are stale relative to the shipped tree: it says the baseline holds 970 gaps and there are 16 offline tests; the shipped packages/parity-baseline.txt holds 944 names (asserted by tests/test_image_parity.py:186-190, matching README.md:80) and the test file defines 20 tests. Behavior is unaffected; README/docs match the code.

No findings from: security, style, docs-currency.

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78

@castrojo castrojo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed diff: image-level parity comparisons. Branch has merge conflicts against main and design decisions pending regarding package comparison methodology.

@hanthor

hanthor commented Sep 21, 2026

Copy link
Copy Markdown
Member Author

Pushed adc98fb to bring the parity docs current for this branch:

  • docs/skills/package-contract.md Failure semantics now includes parity in the install set, and Current counts updated from 12/4 to 44/9 (11 GNOME + 28 parity + 5 services, 9 unavailable) for this branch's reality.
  • README.md parity table updated to 44/9 to match.

The 25-name baseline trim (969 → 944) from the earlier CHANGES_REQUESTED is already in d9c3bb2 and verified (944 unique names, test pinned count 944). The HTTPException catch and explained→closed fix are in f8fda0b/ea0869c with tests. just check passes (215 tests). Ready for re-review on the design question (baseline with no checked-in generator + mutable :stable tag).

cc @castrojo

@hanthor
hanthor requested a review from castrojo September 21, 2026 06:40

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed — no findings from correctness, security, intent-alignment, style, docs-currency.

— hive: agent=reviewer backend=copilot model=claude-fable-5

…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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M
claude and others added 8 commits September 22, 2026 14:58
…ands 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M
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>
…ader

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>
#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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W6BYLUD6KBzF8rBFXKjP7M
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>
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>
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>

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

correctness

  • --bluefin-inventory bypasses the gpg-pubkey filter: bluefin_inventory() strips gpg-pubkey* names (scripts/check-image-parity.py:114) and parse_rpm_list strips them on Utah's side (:133), but the canned-JSON path loads the dict verbatim (:284). A saved inventory containing gpg-pubkey entries would report the exact permanent phantom gap the tests document as the invariant (tests/test_image_parity.py, test_gpg_pubkey_is_filtered_out_of_bluefins_inventory). Low: only reachable via the offline CLI flag, not the build path — but one parse of the loaded dict through the same filter closes it.

style

  • tests/test_image_parity.py:167 hardcodes the baseline at exactly 944 names, so every baseline trim (the file's stated goal — "Shrinking this file is progress") also requires editing this test. Asserting no-duplicates without the exact count keeps the guard without the friction.

No findings from: security, intent-alignment, docs-currency. (Doc counts verified: 44 additions = gnome 11 + parity 28 + services 5, 9 unavailable, matching utah.toml at f565e54.)

Confidence: 3/5 (needs attention) — 1 perspective requested changes

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78

@repires repires mentioned this pull request Sep 22, 2026
19 of 29 tasks
@hanthor

hanthor commented Sep 23, 2026

Copy link
Copy Markdown
Member Author

Note (own PR, can't request changes): this is conflicting with a pending design/merge-order decision. Rebase once the decision lands.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style

  • tests/test_image_parity.py:196 asserts the baseline holds exactly 944 names. The PR's own workflow (report "closed" → trim packages/parity-baseline.txt) means every trim now fails just test until the hardcoded count is edited too — and README.md:87 hardcodes the same 944. If the count-lock is a deliberate tripwire, fine; otherwise keeping only the sorted/no-duplicates assertions would remove per-trim friction across three files.

docs-currency

  • packages/parity-baseline.txt group headers say 253 (Hummingbird) and 632 (nowhere), but the groups actually contain 252 and 631 names — the headers weren't refreshed after the 25-entry trim described in the file's own preamble (total 944 is correct and matches the test).
  • Minor: tests/test_image_parity.py:224 and the comment in scripts/check-image-parity.py (main's except block) refer to "the Containerfile comment [that] promises" the step cannot fail the build, but no such comment exists at the parity lines in the Containerfile (Containerfile:204-206).

No findings from: correctness, security, intent-alignment.

Confidence: 3/5 (needs attention) — 1 perspective requested changes

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78

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>
@hivecommons-hive

Copy link
Copy Markdown
Contributor

Shared CI incident, not a defect in this PR: the testing image builds are red on main HEAD itself — build_main / image (main, utah, testing, x86_64), build_kernel / image (nvidia|gaming|nvidia-gaming, utah-kernel, testing, x86_64) and both Check all testing builds successful gates failed on main at 2026-09-23T22:29:10Z and again on the prior main run at 2026-09-23T18:40:35Z.

Tracked in #109. Deferring this PR until that incident closes or the baseline turns green — no PR-local repair is warranted.

🐝 Hive Agent: scanner | Instance: hosted-projectbluefin-knuckle-gjvq | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-opus-5 copilot=1.0.88

@hivecommons-hive

Copy link
Copy Markdown
Contributor

CI triage for the six red build checks here — the cause is not in this PR's diff.

build_kernel / image (nvidia, utah-kernel, testing, x86_64) fails inside utah-install-packages, during the RPM transaction:

Transaction failed: Rpm transaction failed.
  - file /usr/lib64/libxml2.so.16.1.4 from install of libxml2-2.15.4-1.hum1.x86_64
    conflicts with file from package libxml2-16-2.15.4-0.1.hum1.x86_64

That is the libxml2 / libxml2-16 split-package file conflict, which is already being addressed in #250 ("fix(packages): exclude conflicting libxml2 to preserve libxml2-16 split"). It is unrelated to the parity comparison change in this PR.

Two further notes:

  • build_kernel / * is currently green on main, so those three image failures here are stale: the last run on this head is from 2026-09-23T14:14Z and predates the current state of main.
  • build_main / image (main, utah, testing, x86_64) and build_main / Check all testing builds successful are red on main right now, so that pair is a shared failure, not a fault of this branch.

This PR is also dirty (conflicts with main). Once #250 lands, merging main into this branch and re-running should clear all six checks without any change to the parity logic.

🐝 Hive Agent: scanner | Instance: hosted-projectbluefin-knuckle-gjvq | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-opus-5 copilot=1.0.88

Signed-off-by: sec-check[bot] <sec-check[bot]@users.noreply.github.com>

# Conflicts:
#	Containerfile
#	Justfile
@hanthor

hanthor commented Sep 25, 2026

Copy link
Copy Markdown
Member Author

Superseded by #264 (merged as 46bc45d), which compares the built image against published Bluefin and Dakota images, including file ownership, and keeps baselines/GAP.md and triage.toml current with a weekly workflow. This PR would add a second debt register (packages/parity-baseline.txt, 944 names) with different semantics, plus a registry GET inside the image build (Containerfile:216). Closing this in favor of #264 makes sense.

@Danathar

Copy link
Copy Markdown
Contributor

Agreed with your 09-25 note: #264 (46bc45d) covers this with baselines/ and triage.toml, and this branch would add a second parity baseline with different semantics. Fine to close.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants