phoebus_os/docs/adr/0006-package-lanes.md
Phoebus 0718bb34e5 feat(nix): gated bootstrap of the pinned Nix release
A binary ebuild is impossible (the upstream installer has no DESTDIR and runs
nix-store --load-db against the real root), so bootstrap the pinned,
SHA-256-verified official release with discrete commands in the target chroot
(no curl|sh, no sh -c): store copy, DB load, nixbld users, profile wiring and
nix-daemon units. Gated behind packages.nix (default off) until VM-verified.
2026-09-20 14:50:57 -07:00

141 lines
6.5 KiB
Markdown

# ADR 0006: Package lanes — Portage, Flatpak, and Nix (built in)
- **Status:** Proposed
- **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. **Gated until verified.** `packages.nix` defaults off until a disposable-VM
install confirms the bootstrap; Nix never becomes a hard dependency.
## 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: `xdg-desktop-portal` (+ `-gtk`/`-wlr` backends),
a documented app-install path, desktop integration.
2. Author the Phoebus overlay `sys-apps/nix` ebuild (+ `nix-daemon.service`),
install it from the installer, and verify in the disposable VM that a Nix
dev environment works and the base system still boots without using it.
3. Add the `CreateDevEnvironment` typed action with a bounded input set and
tests.
4. Only then consider a thin `sys`-level source chooser (not a general `pkg`).