229 lines
12 KiB
Markdown
229 lines
12 KiB
Markdown
# ADR 0006: Package lanes and hardware-aware software selection
|
|
|
|
- **Status:** Accepted, revised 2026-09-24
|
|
- **Date:** 2026-09-20 (revised 2026-09-24)
|
|
|
|
## Context
|
|
|
|
Phoebus is built on Gentoo/Portage and must stay a thin layer over it. There is
|
|
a real need for **binary and sandboxed options for non-core software** without
|
|
maintaining a private Gentoo binhost or letting a second package manager claim
|
|
ownership of the system.
|
|
|
|
The original decision (2026-09-20) adopted three lanes and a **fixed category
|
|
routing**: system/compiler/driver → Portage; GUI → Flatpak; per-project/dev →
|
|
Nix. In practice that routing is wrong. A given application can be a good fit
|
|
for different lanes on different machines and for different users:
|
|
|
|
- a GUI application available both as a cheap, well-integrated Gentoo source
|
|
build and as a heavier Flatpak might be better from source on a
|
|
high-core workstation with a matching USE set, and better as a Flatpak on a
|
|
low-RAM laptop or when a sandbox is required;
|
|
- a developer tool may be best from Nix for a pinned, reproducible, per-project
|
|
version, and best from Portage when it is already installed or cheap to
|
|
compile;
|
|
- some software has no maintained candidate at all and needs a local ebuild.
|
|
|
|
Category is therefore a **hint**, not a decision. This ADR revises the decision
|
|
to a shared, inspectable, hardware- and preference-aware selection policy, and
|
|
extends the lane set.
|
|
|
|
Options considered for the selection problem: fixed category routing
|
|
(rejected), a fully scripted per-application table (rejected: opaque,
|
|
unmaintainable, still wrong on other hardware), and a shared deterministic
|
|
policy consuming resolved backend metadata (adopted).
|
|
|
|
Relevant facts established:
|
|
|
|
- The official Gentoo binhost is a single non-systemd (hardened) baseline, so
|
|
systemd/desktop packages mostly compile from source. We will not maintain a
|
|
private binhost.
|
|
- `nix` is not in the Gentoo main tree, so Phoebus ships and manages it itself.
|
|
- Nix is strong for reproducible, multi-version developer environments and poor
|
|
for GPU/Wayland desktop apps on a non-NixOS host (`nixGL`, Electron sandbox).
|
|
- Flatpak is already designed into Phoebus and is the right fit for many
|
|
sandboxed GUI apps.
|
|
- Snap can be added through Gentoo's `app-containers/snapd` package (systemd is
|
|
mandatory, AppArmor recommended; verified against the Gentoo wiki). It brings
|
|
channel/refresh semantics and its own confinement model.
|
|
- AppImages are single executable files with **no built-in sandbox**; they are
|
|
useful when no maintained package exists, but must be managed honestly.
|
|
- A local ebuild is occasionally the only correct answer; it is executable
|
|
untrusted code and needs an explicit, isolated build path.
|
|
|
|
## Decision
|
|
|
|
Adopt **lanes with strict ownership** plus a **single shared selection policy**
|
|
used by both the deterministic `sys` front-end and the assistant.
|
|
|
|
| Lane | Owns / is suitable for | Availability |
|
|
| ---- | ---------------------- | ------------ |
|
|
| **Portage source** (authoritative) | kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot stack, system services, compilers/toolchain; cheap, well-integrated source builds | always |
|
|
| **Portage binary** (official binhost) | packages whose USE matches the signed official binhost and whose local compile cost is high with little practical benefit | when a binhost is configured |
|
|
| **Portage vendor (`-bin`/`-launcher`)** | vendor blobs (`google-chrome`, `steam-launcher`, `discord-bin`, …) | vendor ebuild present |
|
|
| **Flatpak** | sandboxed graphical applications; multi-distro binaries | always (default desktop) |
|
|
| **Nix** | developer tools, alternate versions, reproducible per-project environments | always, user-level use |
|
|
| **Snap** | applications distributed as snaps, when the user wants the Snap Store and its channel/refresh model | ready on the default desktop; `app-containers/snapd` through Portage, with socket activation |
|
|
| **AppImage** | a single-file application with no maintained package, adopted with pinned integrity | opt-in, managed inventory |
|
|
| **Custom ebuild** | a maintained package that is unsuitable or absent and cannot be met otherwise | Phoebus overlay, approval-gated |
|
|
|
|
Portage's ownership is unchanged: **Snap, AppImage and the custom overlay may
|
|
never provide kernel, drivers, Mesa, PipeWire, systemd, core libraries or
|
|
boot.** The custom overlay is compiled by Portage; Snap and AppImage are
|
|
explicitly non-authoritative.
|
|
|
|
## The selection policy
|
|
|
|
The policy lives in `phoebus-core::selection` and is pure: it consumes
|
|
already-resolved candidates (real backend metadata gathered by
|
|
`phoebus-executor::chooser`) plus hardware facts and user preferences, and
|
|
returns a reproducible decision with the reasons alternatives were rejected.
|
|
Priority order:
|
|
|
|
1. **Hard compatibility constraints beat preferences.** Architecture mismatch,
|
|
a required sandbox a lane cannot provide, insufficient storage, a required
|
|
proprietary artifact, GPU incompatibility, or an unavailable backend remove
|
|
a candidate regardless of preference.
|
|
2. **Base components stay Portage.** A `base-system` request may only resolve to
|
|
a Portage lane. This is the ownership rule above.
|
|
3. **Explicit compatible user choices win, and are persisted.** A per-app or
|
|
global preference is honoured when a compatible candidate exists; when it
|
|
does not, selection **fails with an explanation** and never silently switches
|
|
lane.
|
|
4. **No automatic category routing.** Suitability is decided from candidate
|
|
evidence: measured/estimated compile time, download and install size, shared
|
|
runtime cost, sandbox strength, Wayland and desktop integration, provenance,
|
|
update reliability, permissions, and the actual hardware (cores, RAM, free
|
|
storage, GPU, Wayland session).
|
|
5. **No silent migration or duplication.** A lane that already owns an
|
|
installed copy is preferred, so an application is not installed twice or
|
|
moved between lanes behind the user's back.
|
|
6. **Honest estimates.** Compile times are labelled measured (from the
|
|
`emerge.log` history) or estimated; compilation is not assumed to be faster
|
|
or worth its cost. Unknowns are stated as unknowns.
|
|
|
|
The review shows the selected package identity, lane, version, provenance,
|
|
integrity status, sandbox level, sizes, update behaviour and the rejected
|
|
alternatives with their reasons. The same facts, metadata and preferences always
|
|
produce the same decision.
|
|
|
|
### Acquisition and integrity
|
|
|
|
- Portage source/binary: the existing signed Gentoo verification (ADR 0004).
|
|
- Flatpak: flathub GPG; Snap: store signatures; both are sandboxed.
|
|
- AppImage: a Phoebus-managed record stores the pinned SHA-256, source URL,
|
|
architecture and size; acquisition is refused without a real pinned hash.
|
|
- Custom ebuild: staged in the Phoebus overlay with a recorded rationale and a
|
|
SHA-256 of the exact ebuild content; approval binds to that digest and any
|
|
change invalidates it.
|
|
|
|
### Nix is baked in, but "baked in" describes availability, not authority
|
|
|
|
- the Nix toolchain and daemon are shipped and configured by the installer;
|
|
- Portage still installs and updates Nix itself, so the daemon is system-managed
|
|
rather than a stray `curl | sh` artifact;
|
|
- no core component, service, library or application depends on Nix being used;
|
|
- ignoring Nix has no effect on the system.
|
|
|
|
How the pinned, verified Nix bootstrap works without surrendering ownership is
|
|
recorded in ADR 0008.
|
|
|
|
## Rules
|
|
|
|
1. **Portage is the only authority over the running system.** Nix, Flatpak,
|
|
Snap, AppImage and the custom overlay never provide kernel, drivers, Mesa,
|
|
PipeWire, systemd, core libraries or boot.
|
|
2. **Base components are Portage-only.** The selector enforces this as a hard
|
|
constraint.
|
|
3. **No silent backend switching.** A failed install is reported; any
|
|
replacement plan is resolved and approved through the normal path.
|
|
4. **Explicit choices are respected and persisted; incompatible ones error.**
|
|
5. **Snap and AppImage are honest about their guarantees.** Snap confinement is
|
|
detected, not assumed; classic confinement is a security downgrade and is
|
|
explicit; AppImage is never described as sandboxed and is never executed just
|
|
to inspect it.
|
|
6. **Removal preserves user data by default.** Each lane's removal removes only
|
|
what Phoebus manages; a Btrfs snapshot does not automatically reverse another
|
|
lane's state or external side effects, and this is stated.
|
|
7. **No arbitrary remote evaluation by default.** Nix commands run by the
|
|
assistant are bounded (no arbitrary flakes or URLs). Snap/Flatpak/AppImage
|
|
operations use bounded identifiers/URLs and pinned hashes.
|
|
8. **The custom overlay is untrusted code.** The model may propose an ebuild;
|
|
staging never runs it. Building happens only through the deterministic broker
|
|
after approval of the exact digest, inside the target with Portage's build
|
|
sandbox.
|
|
|
|
## AI integration
|
|
|
|
The assistant and the deterministic CLI emit the same typed schema. Software
|
|
selection is a typed, read-only action:
|
|
|
|
```
|
|
ChoosePackage { name, kind?, backend?, gui?, requires_sandbox? }
|
|
```
|
|
|
|
The selector reports the lane and the rejected alternatives. Persisting a
|
|
choice is a separate, audited action:
|
|
|
|
```
|
|
SetPackagePreference { name, backend? } // backend unset clears it
|
|
```
|
|
|
|
Lane-specific mutations (`snap_*`, `appimage_*`, `custom_ebuild_*`) are bounded
|
|
and validated, and a custom ebuild is staged for review before it can build.
|
|
The model never gets a shell, and approval binds to the reviewed plan/artifact.
|
|
|
|
## Explicit non-goals
|
|
|
|
- **Fixed category routing.** Rejected: it is wrong on other hardware and for
|
|
other users; suitability is decided from candidate evidence.
|
|
- A universal `pkg install` meta-manager that silently picks a source.
|
|
`ChoosePackage` is an *inspectable decision*, not a hidden installer, and it
|
|
never executes.
|
|
- NixOS-style system configuration.
|
|
- A second full distro (Distrobox, pacman) — rejected: a second rootfs to
|
|
maintain with weaker isolation than Flatpak.
|
|
- A third-party/private Gentoo binhost — rejected: trust, signature and
|
|
availability.
|
|
- Homebrew — rejected: not packaged for Gentoo, FHS prefix shadowing.
|
|
- Treating AppImage as a sandbox — rejected: it is not one.
|
|
|
|
## Consequences and risks
|
|
|
|
- Every install carries the Nix toolchain and `/nix`; Snap and AppImage add
|
|
opt-in stores/inventories with their own CVEs and update cadences. The
|
|
selector surfaces update reliability per lane.
|
|
- The policy is a transparent heuristic, not a benchmark. It labels measured vs
|
|
estimated data and reports unknowns; it must not be presented as measured
|
|
performance.
|
|
- Two trust/update pipelines (`gentoo` + `nixpkgs`) exist on every system; the
|
|
daemon being Portage-managed keeps ownership clear.
|
|
- The custom overlay increases the support surface; it is approval-gated and
|
|
records why each entry exists.
|
|
|
|
## Binary strategy (reconciled)
|
|
|
|
The sustainable strategy remains:
|
|
|
|
- **Portage source or the official signed Gentoo binhost**, whichever matches
|
|
the package's USE. Signature verification stays on (ADR 0004); no private
|
|
binhost is maintained.
|
|
- **Flatpak / Snap** for sandboxed applications the official binhost cannot
|
|
serve.
|
|
- **Nix** for developer tools, alternate versions and reproducible per-project
|
|
environments (ADR 0008).
|
|
- **AppImage / custom ebuild** only when no maintained candidate is suitable,
|
|
with explicit integrity and an approval gate.
|
|
|
|
Packages the official OpenRC/hardened binhost cannot satisfy (systemd, polkit,
|
|
NetworkManager, a desktop USE set) compile from source. That cost is accepted
|
|
and measured (`docs/STATUS.md` records the compile times), not hidden behind a
|
|
new binhost.
|
|
|
|
## Next steps
|
|
|
|
1. Wire `ChoosePackage` into the installed assistant and GUI so a user can see
|
|
the lane decision and override it without a model.
|
|
2. VM-verify each new lane end to end: Snap install/refresh/remove, AppImage
|
|
acquire/launch/remove, and one custom-ebuild build.
|
|
3. Add `pkgcheck`-based QA to the custom-ebuild stage gate.
|