phoebus_os/docs/STATUS.md
Phoebus b4a6b5df80
Some checks are pending
ci / test (push) Waiting to run
feat(nvidia): hardware-driven driver policy, installed integration and live payload
- resolve the NVIDIA branch and kernel-module flavor from PCI device IDs
  (Turing+ open modules; Maxwell/Pascal/Volta proprietary, masked below 595;
  Fermi/Kepler fall back to nouveau, reported; unknown IDs reported)
- capture pci_id/pci_address in the probe; drive VIDEO_CARDS, package.use,
  package.accept_keywords, package.mask, modprobe.d and dracut from the plan,
  preserving hybrid Intel/AMD
- add the nvidia_drivers install stage (after the kernel, before boot) that
  emerges the driver, regenerates the initramfs, records /etc/phoebus/nvidia and
  fails the install on failure; sys update rebuilds modules and the initramfs
- refuse AI changes to x11-drivers/nvidia-drivers
- live ISO: signed non-free components, stable-kernel pin (testing 7.2 breaks
  the 550 driver), DKMS build for the exact kernel, gated pre-greetd load,
  fail-safe entry, gpu-report, and a --verify-live-nvidia build gate that runs
  on cached rootfs builds and fails on any missing component
- docs: ADR 0012, STATUS/CHANGELOG/HANDOFF, live README
- also carries the pending OpenCode model-variant/streaming changes and fixes
  the GUI bridge install thread join that could hang
2026-09-22 21:53:28 -07:00

212 lines
13 KiB
Markdown

# Status
Truthful implementation/verification matrix. Vocabulary:
- **Implemented** — code exists.
- **Unit tested** — covered by automated tests that run on any host.
- **VM verified** — exercised in the disposable QEMU/OVMF VM.
- **Hardware verified** — exercised on real hardware.
- **Not verified** — do not claim it works.
## Proven baseline (do not regress)
A complete installation in a disposable UEFI VM, booted with the ISO detached:
```
QEMU + OVMF (UEFI)
30 GiB qcow2, virtio-blk (/dev/vda); live ISO at /dev/sr0
GPT: 1 GiB FAT32 ESP + LUKS2 remainder
Btrfs: @ @home @var @snapshots @swap
Gentoo systemd stage3 (default/linux/amd64/23.0/systemd)
systemd-boot + BLS entry + dracut initramfs
LUKS2 passphrase unlock at boot
systemd PID 1, login, networking
systemctl is-system-running = running; 0 failed units
```
Boot timing (Rust installer): 1.378 s kernel + 5.238 s initrd + 4.114 s
userspace = 10.730 s.
The committed VM harness (`installer/tests/vm/serial-driver.py` +
`install.sh`) drives the **static Rust binary**; the Bash installer is no longer
on the install path (Bash migration Phase 2, see
`docs/VM-BOOT-VERIFICATION.md`).
A second harness (`installer/tests/vm/appliance-driver.py` +
`appliance-guest.sh`) drives the Debian-Live appliance ISO. On 2026-09-21 it
produced `INSTALL-RC=0`, `NO_SECRET_LEAK`, and a detached boot
(`systemd`, running, 0 failed units) whose Btrfs history contains the installer's
coordinated `@` + `@var` **initial known-good** snapshot and a snapshot-based
recovery boot entry (see `docs/VM-BOOT-VERIFICATION.md`). `sys undo` itself is
still not VM-verified.
## Matrix
| Area | Implemented | Unit tested | VM verified | Hardware verified |
|------|-------------|-------------|-------------|-------------------|
| Config (TOML + legacy), validation | yes | yes | yes | n/a |
| Hardware/disk discovery, protection | yes | yes | yes | no |
| Install plan + destructive preview | yes | yes | yes | n/a |
| Destructive authorization (ERASE) | yes | yes | yes | n/a |
| GPT partitioning + ESP | yes | yes | yes | no |
| LUKS2 format/open/close | yes | yes | yes | no |
| Btrfs subvolumes + swapfile | yes | yes | yes | no |
| fstab / crypttab generation | yes | yes | yes | no |
| stage3 fetch + SHA-256 verify + extract | yes | yes | yes | n/a |
| Portage config + sync + getuto | yes | yes | yes | n/a |
| Signed Gentoo binary install | yes | yes | yes | n/a |
| Source package compilation | yes | yes | yes | n/a |
| Kernel install + dracut initramfs | yes | yes | yes | no |
| systemd-boot + BLS | yes | yes | yes | no |
| Boot default pins the real kernel (not recovery) | yes | yes | yes | no |
| Recovery BLS entry (rescue.target) | yes | yes | boots (not default) | no |
| Users, passwords, sudo | yes | yes | yes | n/a |
| Locale/timezone/keymap/services | yes | yes | yes | n/a |
| Rust VM boot parity | yes | yes | yes | no |
| Rust TUI | yes | yes | smoke test | no |
| Typed GUI bridge (`--gui-bridge`) | yes | yes (dry-run) | live VM + full journey | n/a |
| Graphical welcome + install wizard (Quickshell) | yes | yes | live graphical VM + full GUI journey | no |
| Phoebus brand system (SVG + tokens) | yes | yes | live VM | n/a |
| Desktop profile (dwl/waybar/mako/swaybg) | yes | partial | headless only | no |
| Desktop session script (socket wait, polkit, cleanup) | yes | yes | functional test (stubs) | no |
| PipeWire/WirePlumber | yes | no | headless (`wpctl`) | no |
| Flatpak + flathub | yes | no | installed + remote | no |
| XWayland / polkit agent / kitty / wofi | yes | no | installed, not launched | no |
| Package policy + measured history | yes | yes | yes (326 entries) | no |
| Background update preparation | yes | yes | yes (fetch; buildpkgonly skipped) | no |
| Btrfs snapshots + history | yes | yes | yes | no |
| Coordinated snapshot sets (`@` + `@var`) | yes | yes | no | no |
| Btrfs rollback (`sys undo`) | yes | yes | no | no |
| Recovery/known-good BLS entry | yes | yes | no | no |
| Snapshot retention + free-space gate | yes | yes | no | no |
| AI typed proposals + evidence review | yes | yes | fixture end-to-end | n/a |
| AI guided install (DeepSeek/OpenAI) | yes | yes | fixture path only (no live call) | n/a |
| AI privacy boundary (facts only) | yes | yes | no | n/a |
| AI OS sandbox (systemd hardened unit) | yes | yes | no | no |
| Installed assistant (`sys ask`) | yes | yes | fixture path only (no live call) | n/a |
| Resolved package effects + approval binding | yes | yes (empty vs unestablished) | no | n/a |
| Transaction log (outcomes, protective snapshots) | yes | yes | no | no |
| Flatpak/Nix bounded typed actions | yes | yes | no | no |
| `sys` consistent target-root execution | yes | yes | no | no |
| `sys` validation at the execution boundary | yes | yes | no | n/a |
| `sys ask` truthful failure (nonzero, stop, record) | yes | yes | no | n/a |
| Service start/stop/restart + flatpak/nix/snapshot commands | yes | yes | no | no |
| Desktop session helpers (menu/lock/idle) | yes | yes | functional test (stubs) | no |
| Mango + DankMaterialShell profile | yes | yes | live graphical VM yes; installed no | no |
| Mango is the default desktop | yes | yes | live graphical VM yes; installed install pending | no |
| greetd login (Mango default, dwl fallback) | yes | yes | no | no |
| Live desktop ISO (Mango + DMS) | yes | guards tested | graphical VM + GUI journey + detached boot | no |
| Live welcome autostart + duplicate prevention | yes | guards tested | live graphical VM | no |
| Welcome primary action keyboard-focus | yes | guards tested | live graphical VM | no |
| VM harness disk safety + structured results | yes | yes (16 tests) | n/a | n/a |
| Target disk revalidation before partition | yes | yes | no | n/a |
| Bridge replay/concurrency + input bounds | yes | yes | no | n/a |
| Provider transport endpoint/size hardening | yes | yes | no | n/a |
| `TargetRoot` symlink-escape guard | yes | yes | n/a | n/a |
| OpenCode server capability probe | yes | yes | real host probe + auth + policy | n/a |
| OpenCode proposal adapter (real inference) | yes | yes | real model (`deepseek-v4-flash`) | n/a |
| OpenCode in GUI / CLI / `sys ask` | yes | yes | GUI AI step + `sys ask` live | n/a |
| OpenCode full graphical install | yes | yes | journey + backend stages; completion host-blocked | n/a |
| GUI readiness refresh / AI revalidation / keyboard nav | yes | yes (Rust) | VM harness regressions | n/a |
| Mandatory AI requires a validated interaction | yes | yes | bridge + CLI | n/a |
| GURU packaging (scoped keywords) | yes | yes | no (build/install unverified) | no |
| Release gates + atomic publish | yes | yes | no | n/a |
| `sys` verbs | yes | yes | yes | no |
| OpenCode pinned bootstrap | yes | yes | no | n/a |
| Release manifest/verify | yes | yes | no | n/a |
| NVIDIA PCI device classification + branch/flavor policy | yes | yes | no | no |
| NVIDIA installed Gentoo integration (Portage/modprobe/dracut/initramfs) | yes | yes | no | no |
| NVIDIA live ISO payload (bundled modules/firmware/userspace) | yes | yes (verifier + guards) | no | no |
| NVIDIA kernel/module/initramfs update coordination (`@module-rebuild`) | yes | yes | no | no |
| UKI | no (deferred) | no | no | no |
## Known limitations
- **Desktop graphical session** was verified with the *headless* wlroots
backend because the serial-only VM has no logind seat. The DRM path and a
real VT login are not yet exercised. `phoebus-session` is written by the
installer for that purpose.
- **Flatpak apps** were not installed from the remote; only the runtime and
the flathub remote were verified.
- **NVIDIA** is implemented (hardware-driven branch/flavor policy, scoped
Portage configuration, a live payload that is build-time verified, and
kernel/module/initramfs update coordination) and covered by Rust tests and the
live-payload verifier. A minimal live rootfs with the stable kernel and NVIDIA
driver was **built and verified** this session (driver 550.163.01, kernel
6.12.107+deb13-amd64, modules `nvidia-current*`). It is **not verified on
hardware**: this host has no NVIDIA GPU and QEMU's virtual GPU cannot
establish NVIDIA acceleration; no passthrough setup is available or
authorized. The full desktop ISO was not assembled here (the host has ~10 GiB
free; the build wants more) and the live/installed NVIDIA boot gates are
unrun. See `docs/VM-BOOT-VERIFICATION.md` for the exact unblock commands. The
live kernel is pinned to Debian stable (trixie 6.12 LTS) because testing's
kernel (7.2) breaks Debian's 550 driver; the bundled branch covers Maxwell
through Ada/Hopper, and Blackwell falls back to nouveau on the live medium.
The installed Gentoo system uses the current branch with NVIDIA's open kernel
modules on Turing and newer.
- **UKI** is deferred; the dracut UKI generator did not embed the kernel
command line, so BLS is used (and verified).
- **Rollback is NOT VM-verified.** It is implemented and unit-tested end to end
at the command/text layer (snapshot sets, root/var generation, fstab and BLS
rewriting, kernel selection, interruption resume, retention, free-space
gate), but the destructive acceptance test (deliberately broken update ->
`sys undo` -> detached reboot -> package-state check -> recovery with no
network/model) was **not run in this session**. Blockers: (1) `make doctor`
reports only ~13 GiB free versus the >=20 GiB the VM harness wants, and the
root filesystem has ~12 GiB free; (2) the committed appliance/serial harness
only implements `install` and `boot` modes — there is no automated driver for
the break-update / `sys undo` / recovery-boot sequence, which is documented as
an interactive procedure. `sys undo` is present; treat VM verification as the
gate before relying on it.
- **Mango + DankMaterialShell** is the default desktop
(`desktop.profile = "mango"`, Flatpak on). It is implemented with Mango
0.17.2, DMS (pinned release), Quickshell 0.3.1 and scenefx 0.5 from the GURU
overlay, a dwl fallback session and scoped `~amd64` keywords. The default is
set by explicit owner decision; it has not been installed or booted in a
graphical VM, so **no desktop stability is claimed**. `docs/STATUS.md`
distinguishes "default in configuration", "successfully built" and
"graphically verified".
- **The live desktop ISO** (`installer/live/build.sh`) builds a Debian testing
rootfs with Mango + DMS, live-only autologin, a branded welcome window and a
graphical installer frontend over the typed bridge. Its desktop-payload
guards are unit-tested. The rebuilt ISO
(`sha256 0c386a1b…`, 1.6 GiB, build id in `/etc/phoebus/build`) was booted in
a graphical, seat-providing VM. The `gui` journey passed **28/28** checks
(welcome autostart, launcher from the keyboard, duplicate prevention, the live
medium protected, keyboard suggestion selection, the network and AI steps,
the AI gate refused without a model and reported inline, no bridge errors) and
the `opencode` journey passed **18/18** (real model response, validated
proposal, and editing the model invalidating the validated state). The new
`gui-install` journey passed every assertion on a fresh 30 GiB qcow2 —
OpenCode connect/review/accept, disk, account, ERASE and confirmation — and
the backend then reported real stages with elapsed time and no fabricated
percentage. The **completed** install timed out in the harness after four
hours because the base-package stage takes ~116 min and the AI-selected
optimized kernel was still compiling after 100 min on this host, so two
completed fresh-disk GUI installs + detached boot remain **BLOCKED on host
build time**. An appliance build of the same boot path was installed
non-interactively (`INSTALL-RC=0`, `NO_SECRET_LEAK`) and booted **with the
ISO detached** (systemd running, 0 failed units, LUKS2, all Btrfs subvolumes,
network). The **installed** Mango system (GURU + compiled Quickshell/DMS) and
the dwl fallback in a VM are not yet verified.
- **AI sandbox** is implemented (`systemd-run` hardening properties, tested at
the argv level) and fails closed without `systemd-run`; it has not been
exercised in a VM. Only typed actions and the privacy boundary were previously
enforced.
- **Release automation** now has gates, a report, atomic publish and signing
command helpers, but no gate has been executed by a configured CI runner; the
report records unexecuted gates as `NotRun`.
- The desktop transaction compiles heavily because desktop USE does not match
the signed binhost (~26 min for the desktop set on 8 vCPUs in the test VM).
The official Gentoo binhost is OpenRC/hardened, so a systemd system can only
reuse binaries for packages whose USE matches; the policy still requests
signed binaries where it can. Publishing a matching binhost is future work.
- **Live AI provider calls are not verified.** DeepSeek/OpenAI requests are
built and reviewed by fixtures (`phoebus-ai::provider::TestTransport`) and the
curl transport is covered by a recording runner; no call was made with a real
key.
- The installer rebuilds `sys-apps/systemd` from source because
boot/policykit/cryptsetup USE differ from the binhost.
- `sys undo` is implemented with the default-subvolume, fstab, kernel-cmdline
and BLS handling described in ADR 0007; its destructive VM acceptance test is
the remaining safety gate.