phoebus_os/docs/adr/0006-package-lanes.md
Phoebus 25f7381b4a
Some checks are pending
ci / test (push) Waiting to run
feat(desktop): add Mango + DankMaterialShell profile with rollback, assistant and release foundations
- Mango + DankMaterialShell desktop option (desktop.profile = "mango") through
  the GURU overlay with scoped ~amd64 keywords, a sealed session entry point and
  a dwl fallback session (ADR 0009).
- Coherent rollback/recovery: coordinated @ + @var snapshots, fstab and BLS
  root-subvolume rewriting, matching-kernel selection, snapshot recovery entry,
  retention/space gates and sys undo (ADR 0007).
- Installed assistant (sys ask) with an OS-level systemd sandbox boundary and
  fail-closed typed plans; resolved package effects bound to approval.
- Nix build isolation enforced (sandbox, no fallback) plus lifecycle/cleanup.
- Desktop helpers (menu/lock/idle), transaction log, release gates with atomic
  publish and signing helpers, and a Debian-Live appliance VM harness.
2026-09-21 03:46:52 -07:00

167 lines
7.8 KiB
Markdown

# ADR 0006: Package lanes — Portage, Flatpak, and Nix (built in)
- **Status:** Accepted
- **Date:** 2026-09-20
## Context
Phoebus is built on Gentoo/Portage and must stay a thin layer over it. There is
a real need for **binary options for non-core software** (developer tooling,
alternate versions, packages awkward or slow to compile) without (a)
maintaining a private Gentoo binhost, or (b) letting a second package manager
claim ownership of the system.
The decision here is that **Nix is part of the distro by default** — the same
way the AI assistant is: always present and ready, but never authoritative and
never required. A Phoebus system must remain completely usable with Portage
alone; a user who ignores Nix must not notice it.
Options considered: a second distro via Distrobox/pacman, Nix, Homebrew, native
`-bin` ebuilds, a third-party Gentoo binhost, and Flatpak.
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 sandboxed
GUI apps.
## Decision
Adopt **three package lanes**, all present on a default install, with strict
ownership:
| Lane | Owns | Availability |
| ---- | ---- | ------------ |
| **Portage** (authoritative) | kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot stack, system services, compilers/toolchain | always |
| **Flatpak** | graphical desktop apps (Chromium, Firefox, Spotify, Electron), sandboxed | always |
| **Nix** | developer tools, alternate versions, reproducible per-project environments, packages inconvenient in Portage | always, user-level use |
Portage's native **`-bin` ebuilds** (`google-chrome`, `steam-launcher`,
`discord-bin`, ...) remain the vendor-blob lane; no new tool is introduced for
them.
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 Nix is baked in without surrendering ownership
A normal binary ebuild is **not possible**: the upstream Nix installer hardcodes
`/nix`, calls `sudo`, and runs `nix-store --load-db` against the real root, with
no `DESTDIR`/`--root` support. Repackaging it into a target image would require
re-implementing that bootstrap; building Nix from source is a separate, large
option.
1. **Bootstrap the pinned, verified official release** with discrete commands in
the target chroot (no `curl | sh`, no `sh -c`), reproducing the installer's
steps: copy the store, `nix-store --load-db`, create the `nixbld` group and
users, wire the profile, and install/enable the `nix-daemon` units.
2. **Multi-user, systemd-managed.** `nix-daemon.service`/`.socket` are installed
and enabled; the store lives at `/nix`.
3. **Pinned and verified.** The Nix version and tarball SHA-256 are embedded and
checked fail-closed; nixpkgs is pinned per environment (flake lock / channel
revision), never "latest".
4. **No NixOS model.** No `configuration.nix`, no system profiles, no
Nix-managed services. Nix manages user environments only.
5. **On by default, VM-verified.** A disposable-VM install confirmed the
bootstrap (`nix-daemon` active, `nix shell nixpkgs#hello` works), so
`packages.nix` is on by default; `NIX_ENABLED='no'` opts out. Nix is never a
hard dependency of boot, run or recovery.
## Rules
1. **Portage is the only authority over the running system.** Nix and Flatpak
never provide kernel, drivers, Mesa, PipeWire, systemd, core libraries or
boot.
2. **Nix is user-level in effect.** It provides developer tools and project
environments, never system components.
3. **Never required.** The system is fully functional with Portage alone; the
base image and all services work if Nix is unused or removed.
4. **GUI apps go to Flatpak, not Nix.**
5. **No arbitrary remote evaluation by default.** Nix commands run by the
assistant are bounded (no arbitrary flakes or URLs), so eval-time fetching
is not an AI-reachable supply-chain surface.
## AI integration
The differentiated use is a typed, assistant-driven action:
```
CreateDevEnvironment { name, packages[], versions[] }
```
- executed unprivileged through `Exec` (no shell, no root for the user action);
- inputs validated against a bounded set;
- never mutates the base system;
- the deterministic broker reports which lane satisfied a request.
A future `sys` chooser must prefer deterministically: system/compiler/Mesa/
drivers → Portage only; GUI → Flatpak; per-project/dev → Nix.
## Explicit non-goals
- A universal `pkg install` meta-manager that silently picks a source (deferred;
provenance and support burden).
- NixOS-style system configuration.
- A second full distro (Distrobox, pacman) — rejected: a second rootfs to
maintain with weaker isolation than Flatpak.
- A third-party Gentoo binhost — rejected: trust, signature and availability.
- Homebrew — rejected: not packaged for Gentoo, FHS prefix shadowing, and it
adds nothing over Nix for the developer lane.
## Consequences and risks
- Every install now carries the Nix toolchain, a root daemon, and a growing
`/nix` store; image and disk usage increase.
- There are now two trust/update pipelines (`gentoo` + `nixpkgs`) on every
system, each with its own CVEs and update cadence. The daemon being
Portage-managed keeps ownership clear, but the risk is real and must be
documented to users.
- GUI/GPU stays Flatpak's job, consistent with this session's finding that Nix
is a poor fit there.
- The `nix-daemon` runs as root; it is a privileged component and must be
treated as one (service hardening, update tracking).
## Next steps
1. Finish Flatpak integration: a documented app-install path and desktop
integration. The `xdg-desktop-portal` (+ `-gtk`/`-wlr` backends) are
installed, bounded `flatpak_install`/`flatpak_remove`/`flatpak_list` typed
actions exist, and flathub is configured; an actual app install and the file
chooser/screencast portals still need VM verification.
2. Author the Phoebus overlay `sys-apps/nix` ebuild (a bootstrap-style ebuild;
see ADR 0008) so `emerge` owns installation, upgrades and removal. Until it
ships, the installer provisions the same lifecycle directly.
3. `CreateDevEnvironment`/`nix_prepare` bounded typed actions: `nix_prepare` is
implemented; a richer per-project environment action remains.
4. Consider a thin `sys`-level source chooser (not a general `pkg`).
## Binary strategy (reconciled)
The roadmap once proposed publishing a private signed binhost to stop the
desktop set compiling. That conflicts with the rejection of a private/third-party
binhost above and would add infrastructure and trust obligations silently.
The sustainable strategy is:
- **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** for sandboxed GUI applications that the official binhost cannot
serve (Chromium, Spotify, Electron).
- **Nix** for developer tools, alternate versions and reproducible per-project
environments (ADR 0008).
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.