Skip to content

feat(parity): track Bluefin's effective package payload - #60

Closed
mrbobbytables wants to merge 2 commits into
projectbluefin:mainfrom
mrbobbytables:parity/track-effective-payload
Closed

mrbobbytables wants to merge 2 commits into
projectbluefin:mainfrom
mrbobbytables:parity/track-effective-payload

Conversation

@mrbobbytables

@mrbobbytables mrbobbytables commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Resolves #11

Summary

Replace the disconnected manifest comparison against base.toml with a machine-readable contract derived from the package transactions that Bluefin actually executes:

  1. Base Fedora packages ([fedora])
  2. Version-specific Fedora packages ([fedora_v*])
  3. External transactions ([external] — tailscale, uupd)
  4. Multimedia transactions ([multimedia], [multimedia_overrides] — overrides and codecs from 03-packages.sh)
  5. Excluded packages ([excluded])

Changes

— hive: backend=copilot model=gemini-3.8-flash

Replace the disconnected manifest comparison with a machine-readable
contract derived from the package transactions that Bluefin actually executes:
base Fedora packages, version-specific additions, external transactions
(tailscale, uupd), and multimedia transactions (overrides and codecs).

- Add scripts/check-parity.py to derive and verify effective payload from
  upstream base.toml and 03-packages.sh in Justfile check-parity.
- Update packages/bluefin.toml with [external] and [multimedia] sections.
- Update packages/utah.toml to record unavailable exceptions with rationales
  and tracking issues (projectbluefin#10, projectbluefin#12, projectbluefin#20, projectbluefin#35, projectbluefin#54).
- Update install-packages.py, verify-rpm-contract.py, and
  check-repo-availability.py to handle the effective contract.
- Update package-contract skill and documentation.

Closes projectbluefin#11

Assisted-by: Gemini 3.8 Flash via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: mrbobbytables <mrbobbytables@users.noreply.github.com>

@hanthor hanthor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Good idea, but it needs verification this PR cannot currently get

The core insight is right and worth pursuing: comparing against base.toml alone misses what Bluefin actually executes, because 03-packages.sh performs additional transactions (multimedia overrides, codecs, COPR-isolated installs, tailscale, uupd). A parity contract derived from the real transaction set is strictly better than one derived from a single manifest.

But this is +485/-130 across 12 files, and it rewrites the three scripts that enforce the package contract — install-packages.py, verify-rpm-contract.py, check-repo-availability.py — plus both manifests. For a change of that blast radius, the evidence needs to be stronger than it is.

Nothing ran

Build Utah is action_required (run 34616043429). Fork PRs in this repo need a maintainer to approve the workflow run; none did. So the contract job never executed — meaning just check, just check-parity and just check-repos have not run against this branch in CI, and those three are precisely what this PR rewrites.

The description also has no validation section at all, unlike the sibling PRs from the same batch. There is no claim that scripts/check-parity.py was run against real upstream sources, and no output quoted. For a script whose entire job is parsing someone else's base.toml and 03-packages.sh, that is the one thing I'd want to see.

The parser is the risk

scripts/check-parity.py now scrapes upstream Bluefin's build_files/base/03-packages.sh — a shell script — and must handle, per the description, "brace expansion, repo-scoped flags, and COPR isolated installs". That is a shell parser written in Python against a file in a repository Utah does not control and has no CI relationship with.

Concretely, please address:

  1. What happens when upstream's shell changes shape. If Bluefin reformats 03-packages.sh, does check-parity fail loudly, or does it silently parse fewer packages and report parity as achieved? Silent under-detection is the dangerous failure here, because it makes the contract check pass by seeing less. A floor assertion (expect at least N packages parsed) would make that failure loud.

  2. Where the upstream files come from at check time. If just check-parity fetches them over the network, the contract job gains a dependency on a third-party repo being reachable, and the check becomes non-deterministic. If they are vendored, the vendoring needs a pin and a refresh story.

  3. Test coverage. #40, #66, #67, #68 and #69 all add unit tests for far simpler code. A shell-scraping parser is the single most test-worthy thing in this queue and has none. A handful of fixtures — a brace-expanded line, a --repo=-scoped install, a COPR block, a line the parser should ignore — would make this reviewable.

Conflicts

#68 rewrites scripts/verify-rpm-contract.py, packages/utah.toml, docs/skills/package-contract.md and Justfile — four of this PR's twelve files. It adds [gnome.major_versions], [factory] and [repositories] sections; this PR adds [external], [multimedia], [multimedia_overrides]. Not logically incompatible, but they will conflict textually and the merged verify-rpm-contract.py needs someone to confirm it is coherent.

#63 documents the current package counts (verified accurate against main: install-packages.py --check reports validated 71 Bluefin parity packages / documented as unavailable: 6). This PR changes what those numbers mean, so #63's tables go stale on merge.

#46 adds ~20 entries to [unavailable] in the same file.

Four open PRs are editing packages/utah.toml. Worth sequencing explicitly.

One substantive question

Moving tailscale out of [services] into the parity contract is correct in principle — it is something Bluefin installs. But system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh depends on it being present, and #46 puts tailscale into [unavailable] while #68's configure-services.sh treatment makes the unit optional. Three PRs are moving tailscale in three directions. Please confirm what the intended end state is, because the hook silently no-ops if the package is absent.

Happy to re-review with a validation section and parser tests — the underlying idea is sound and worth landing.


Generated by Claude Code

Danathar added a commit to Danathar/utah that referenced this pull request Sep 12, 2026
…rance

Review on projectbluefin#62 flagged that enable_required_unit() turning a soft check
into a build-blocking assertion needed to be explicit about its
consequence, and that the tailscale hook's new tolerance for an absent
tailscale package matters to sibling PRs (projectbluefin#46, projectbluefin#60, projectbluefin#68) that are also
moving tailscale between service categories.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LNgJ8VMdoqzGequbxsP2Kc
Add floor assertions in derive_effective_payload to detect upstream shell
restructuring loudly rather than silently parsing fewer packages.
Add unit tests in tests/unit/test_check_parity.py covering brace expansion,
COPR extraction, multiline DNF flags/excludes, floor assertions, and TOML formatting.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: mrbobbytables <mrbobbytables@users.noreply.github.com>
@mrbobbytables

Copy link
Copy Markdown
Contributor Author

Thanks @hanthor! Addressed the feedback:

  1. Parser floor assertions: Added floor assertions in scripts/check-parity.py (min_fedora = 20, min_external = 2) so that structural shifts or reformatting in upstream's 03-packages.sh or base.toml fail loudly with a descriptive error instead of silently under-detecting packages and reporting false parity.
  2. Local source & offline support: Verified that scripts/check-parity.py accepts local file paths for --upstream-manifest and --upstream-script in addition to remote URLs.
  3. Unit test coverage: Added tests/unit/test_check_parity.py covering:
    • Brace expansion (expand_braces) with single, multi-option, and suffix forms.
    • COPR and multiline DNF extraction with flag filtering, repo scopes, and excludes.
    • Failure of floor assertions when upstream content is stripped or reformatted.
    • Full TOML serialization round-trip.
  4. All unit tests pass cleanly.

🐝 Hive Agent: contributor | SHA: unknown

🐝 Hive Agent: contributor | SHA: unknown

@hanthor

hanthor commented Sep 18, 2026

Copy link
Copy Markdown
Member

Closing in favour of #117, which takes the same goal — Bluefin's effective payload rather than its package list — from the other end: it reads the complete installed inventory every rechunked Bluefin image publishes in its manifest annotation (dev.hhd.rechunk.info, 1818 names on today's :stable, no pull) and compares it with rpm -qa inside Utah's own build. The first run found 970 gaps the list-to-list check could never see, now recorded in packages/parity-baseline.txt. This branch conflicts with main across the Justfile, utah.toml and three scripts, and its tests/unit + pytest layout is not the repo's convention. If there's a piece of the manifest-side contract here that the image-side check doesn't cover, please raise it on #117.


Generated by Claude Code

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.

parity: track Bluefin's effective package payload

2 participants