phoebus_os/docs/adr/0008-nix-isolation-lifecycle.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

93 lines
3.9 KiB
Markdown

# ADR 0008: Nix lifecycle, build isolation, and packaging
- **Status:** Accepted
- **Date:** 2026-09-21
## Context
The first Nix bootstrap wrote `sandbox = false`, and the lifecycle (upgrade,
removal, store cleanup) was undefined. ADR 0006 claimed a normal binary ebuild
is impossible because the upstream installer hardcodes `/nix`, calls `sudo` and
uses `nix-store --load-db` with no `DESTDIR`. That claim was re-examined rather
than assumed.
## Decision
### Build isolation is on and does not silently fall back
`/etc/nix/nix.conf` now sets:
```
sandbox = true
sandbox-fallback = false
auto-optimise-store = true
min-free = 1073741824
max-free = 10737418240
```
The Nix sandbox uses Linux user namespaces. `sandbox-fallback = false` means a
build that cannot be sandboxed fails instead of silently building with host
access. This is the same principle as "never weaken a protection for
convenience": a build-time sandbox that can be transparently disabled provides
no guarantee. The Phoebus kernel (distribution kernel plus the conservative
fragments) includes `CONFIG_USER_NS`.
`min-free`/`max-free` bound the store so `/nix` cannot fill the root
filesystem; `auto-optimise-store` deduplicates.
### Store cleanup and rollback interaction
- `/nix` lives inside `@`, so a system rollback restores the store together with
the OS package state. This is intended: the Nix store is OS state.
- Garbage collection is explicit (`nix-store --gc`, bounded by `min-free`/
`max-free`), never automatic on a timer.
- Removing Nix removes the daemon units and profile wiring; purging the store is
a separate, explicit choice, because it also removes user environments.
### Portage-managed lifecycle
The requirement is that Portage owns Nix: installation, upgrades, daemon
integration and removal. The upstream installer's lack of `DESTDIR` blocks a
*conventional binary ebuild*, but it does **not** block an ebuild that performs
the same bootstrap the installer performs:
- `src_unpack` fetches the pinned, SHA-256-verified release tarball.
- `src_install` copies the release's `store/` into `${D}` (the ebuild's image),
so the files are package-owned.
- `pkg_postinst` runs `nix-store --load-db` against the live root, creates the
`nixbld` group/users, and enables `nix-daemon.service`/`.socket`.
This is a *bootstrap-style* ebuild, not a `DESTDIR` install of a build tree; it
is the standard technique for packages that must initialise state at install
time (the same shape as `sys-apps/portage`'s news/`env-update` handling). It
belongs in the Phoebus overlay as `sys-apps/nix`.
Until the overlay ebuild is published, the installer provisions the same
lifecycle directly (discrete, no `curl | sh`, no `sh -c`), and the runtime
lifecycle operations are implemented in `phoebus-executor::nix`:
`install`, `remove(purge)`, `gc`, and `valid_nix_attribute` for bounded
developer-package realisation. `sys` exposes `nix_prepare { packages }` as a
bounded typed action.
### Authority
Nix remains a **developer lane only** (ADR 0006): no core component, service,
library or boot path depends on it. Portage owns the kernel, drivers, systemd,
Mesa, PipeWire, core libraries and the boot stack.
## Consequences
- A build that needs user namespaces now fails closed where they are absent.
- The store is bounded; growth is visible and managed.
- The overlay ebuild is the remaining Portage-ownership step; it is documented
and its lifecycle is already exercised by the installer and `nix_*`
operations. It is not yet shipped in a repository.
## Verification
- Unit tests assert the generated `/etc/nix/nix.conf` enables the enforced
sandbox and store bounds, and that removal unlinks units and only purges on
request.
- VM verification of a sandboxed source build (`nix build` of a package with a
derivation that would fail without isolation) and of the ebuild lifecycle is
recorded in `docs/STATUS.md` as outstanding.