Skip to content

docs: describe Utah's current architecture, parity, and installer status - #63

Closed
mrbobbytables wants to merge 1 commit into
projectbluefin:mainfrom
mrbobbytables:docs/architecture-parity-installer-status
Closed

mrbobbytables wants to merge 1 commit into
projectbluefin:mainfrom
mrbobbytables:docs/architecture-parity-installer-status

Conversation

@mrbobbytables

Copy link
Copy Markdown
Contributor

Resolves #23

Summary

Brings user and contributor documentation in line with the implemented Hummingbird-only runtime package model, current contract closure, offline installer payload, documented deferred parity debt packages, and Dakota-style quality gates.

Key Changes

  1. Installer & Offline Payload Status:
    • Updated README.md, docs/skills/local-testing.md, and Justfile to state that the live ISO and offline installer payload are implemented locally (just iso testing && just boot-iso), embedding the org.bootcinstaller.Installer Flatpak and target OCI image in a VFS containers-storage graphroot.
  2. Local Implementation vs Public Distribution:
    • Explicitly differentiated local validation capabilities (local image composition, bootc VM disk install, and live ISO with offline installer) from public distribution availability (no prebuilt OCI images or ISO release artifacts published yet).
  3. Package Parity & Deferred Packages:
    • Synchronized package counts in README.md and docs/skills/package-contract.md with machine-readable manifests (packages/bluefin.toml and packages/utah.toml): 58 Bluefin contract packages installed, 13 Utah additions (10 GNOME 51, 3 desktop services; 71 verified packages), and 6 genuinely unavailable packages.
    • Documented all 6 deferred packages with tracking issues and rationales (evolution-ews-core, firefox, fish, grub2-efi-x64-cdboot, pipewire-libs-extra, zsh).
  4. Runtime Package Sources:
    • Clarified that Utah runtime packages come strictly from Hummingbird and the pinned utah-packages factory; Fedora and Rawhide are never runtime package sources (Fedora 44 is used strictly as a builder-stage toolchain for kernel builds).
    • Corrected multimedia overrides descriptions to state Utah installs Hummingbird's builds of those packages rather than Fedora's builds.
  5. Dakota-Style Quality Gates:
    • Documented the Dakota-style gates across README.md and docs/building.md: preflight contract gate (just check, just check-parity, just check-repos), build matrix gate (clean base vs content-addressed kernel cache), artifact verification verifiers, end-to-end VM & installer testing, and stream promotion and rollback lifecycle (bootc rollback).
  6. Skill Catalog:
    • Regenerated skill catalog (docs/skills/index.json and docs/skills/index.md) following skill documentation updates.

Validation

  • just check passed cleanly (manifests, extension contract, download integrity, package verification, skill index).
  • just check-parity passed (bluefin.toml equals upstream base.toml).
  • pre-commit run --all-files passed cleanly.

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

🐝 Hive Agent: contributor | SHA: 2300e47

Bring documentation in line with the implemented Hummingbird-only runtime
package model, current contract closure, installer and offline payload,
deferred parity debt packages, and Dakota-style quality gates.

- Distinguish local implementation status (VM bootc disk and live ISO with
  offline OCI payload) from public distribution availability.
- Update package parity table and documented deferred packages to match
  machine-readable manifests (58 Bluefin, 13 additions, 71 verified, 6 unavailable).
- Clarify that Fedora and Rawhide are never runtime package sources and that
  Utah installs Hummingbird builds.
- Document Dakota-style preflight, build, artifact verification, E2E VM/installer,
  and promotion/rollback quality gates.

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.

The numeric claims check out against the manifests

Docs PRs that quote counts usually drift, so I verified these rather than reading past them. On main@636b48e:

$ python3 scripts/install-packages.py --check packages/bluefin.toml packages/utah.toml
validated 71 Bluefin parity packages
documented as unavailable: 6

That matches the PR's "71 total verified" and "6 genuinely unavailable" exactly. The split also holds: packages/utah.toml has [gnome] = 10 entries and [services] = 3, so "13 Utah additions (10 GNOME 51, 3 desktop services)" is right, and 71 − 13 = 58 gives the "58 Bluefin contract packages installed" figure. Every number in the README table and in docs/skills/package-contract.md is derivable from the manifests as they stand.

The six deferred packages named — evolution-ews-core, firefox, fish, grub2-efi-x64-cdboot, pipewire-libs-extra, zsh — are exactly the [unavailable] list on main. Good.

The other corrections are worth having too. Separating "builds locally" from "is published" is the honest framing, and clarifying that Utah installs Hummingbird's builds of the multimedia overrides rather than Fedora's fixes a genuinely misleading sentence.

The Fedora-sourcing claim is the one to watch

This PR states, and strengthens, the invariant:

Utah runtime packages come strictly from Hummingbird and the pinned utah-packages factory; Fedora and Rawhide are never runtime package sources (Fedora 44 is used strictly as a builder-stage toolchain for kernel builds).

That is consistent with AGENTS.md:70 and with packages/fedora-44.repo's own header comment today. But #46 is open and green, and it does the opposite — it adds fedora-44 and fedora-44-updates to the runtime REPOS tuple in scripts/install-packages.py, copies packages/fedora-44.repo into the runtime image's /etc/yum.repos.d/, and rewrites that header to "Fedora 44 is the Hummingbird runtime package source". #68 meanwhile adds a fail-closed allowlist to enforce the opposite.

So three open PRs assert three different answers to the same question. If #46 lands first, this PR's documentation ships already false. Worth getting the policy settled before merging docs that assert it.

The counts will also be invalidated by #60

#60 restructures packages/bluefin.toml and packages/utah.toml around [external], [multimedia] and [multimedia_overrides] sections and rewrites check-parity. That changes what "71 validated" means and moves tailscale out of [services]. #46 separately adds ~20 entries to [unavailable], which would take the "6 unavailable" figure to ~26.

Since this PR also edits packages/utah.toml, it will conflict with both. Numbers hard-coded into prose are only as durable as the manifest shape — worth considering whether the README table could be generated by install-packages.py --check into a fenced block, so it cannot drift silently. Not a blocker, but this PR is the third one this cycle correcting package counts.

Status

Build Utah here is action_required (run 34618531783) — fork PRs need maintainer approval to run, so just check never executed despite the description reporting it passed locally. For a docs change that is low-risk, but it does mean the regenerated docs/skills/index.json / index.md have not been checked by scripts/check-skill-index.sh in CI. Worth confirming those were regenerated by the script rather than hand-edited, since a stale catalog is exactly what that check exists to catch.

Content-wise this is the most accurate documentation PR in the queue. The sequencing against #46/#60/#68 is the only real issue.


Generated by Claude Code

@mrbobbytables

Copy link
Copy Markdown
Contributor Author

Thanks for the thorough review and count verification, @hanthor!

Acknowledged on the sequencing with #46, #60, and #68. As the manifest restructuring and repository policies land, we will refresh the derived numbers and skill catalog to ensure docs stay strictly aligned.

🐝 Hive Agent: contributor | SHA: unknown

🐝 Hive Agent: contributor | SHA: unknown

@hanthor

hanthor commented Sep 18, 2026

Copy link
Copy Markdown
Member

Closing as stale: this describes the Sep 11 state of the project, and the parts it documents have since changed materially — the package contract (#70, #110), the E2E gate and ISO (#84, #89), the image-level parity check (#117), and [unavailable] on utah.toml — so merging it would put wrong statements in the README. A documentation refresh against today's main is worth doing, but it needs to start from the current tree rather than rebase this one.


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.

docs: describe Utah's current architecture, parity, and installer status

2 participants