phoebus_os/docs/adr/0006-package-lanes.md
Phoebus ab7408cdcf docs: make AI and Nix defining, offline-capable subsystems
AI and Nix are now always-present parts of Phoebus (not optional add-ons):
the assistant ships with a local model so it works offline and in recovery,
and Nix is a second package lane shipped and updated through Portage.
Installation needs the network; the installed system must boot, run and
recover without it. The assistant is the preferred front-end, never a gate:
the deterministic CLI (sys, emerge, nix, flatpak) is always available. The
model still never holds privilege. Records ADR 0006 (package lanes).
2026-09-20 14:27:02 -07:00

136 lines
6.3 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
1. **Ship it as a Portage package, not the upstream installer.** Provide a
Phoebus overlay ebuild for Nix (e.g. `sys-apps/nix`) that installs the
toolchain, creates the store and `nixbld` build users, and installs a
`nix-daemon.service` unit. The installer adds the overlay and emerges it as
part of the base/desktop package set.
2. **Multi-user, system-managed.** Because it is a real package, a root
`nix-daemon` is acceptable: it is enabled like any other service, updated
through `emerge`, and audited with the rest of the system.
3. **Pinned and verified.** The ebuild pins the Nix version and verifies the
upstream release tarball by SHA-256. The upstream `curl | sh` installer is
never used. nixpkgs itself is pinned per environment (flake lock / channel
revision), not "latest".
4. **No NixOS model.** No `configuration.nix`, no system profiles, no
Nix-managed services. Nix manages user environments only.
## 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`).