phoebus_os/docs/ARCHITECTURE.md
Phoebus fe8de3904b
Some checks are pending
ci / test (push) Waiting to run
refactor(desktop): unify desktop stack on Mango + DarkMaterial and excise standalone dwl
- Excised standalone dwl packages: gui-wm/dwl, waybar, wofi, mako, swaybg, swayidle, swaylock
- Removed standalone dwl session and helper assets: PHOEBUS_SESSION_SCRIPT, PHOEBUS_MENU_SCRIPT, PHOEBUS_LOCK_SCRIPT, PHOEBUS_IDLE_SCRIPT, WAYBAR_CONFIG, WAYBAR_STYLE, phoebus-dwl.desktop
- Consolidated DesktopProfile enum to Mango (default) and None (headless), rejecting legacy dwl configurations
- PHOEBUS_MANGO_SESSION_SCRIPT (/usr/local/bin/phoebus-session-mango) fails visibly/diagnostically on error without silent fallback
- Provided /usr/local/bin/phoebus-session as a direct wrapper to phoebus-session-mango
- Live ISO emitted assets reduced from 24 to 17 and verified clean
2026-09-24 15:49:15 -07:00

8.6 KiB

Architecture

Phoebus ships one installer implementation: the Rust workspace in installer-rs/. It reproduces the proven encrypted UEFI VM boot path and is the only implementation on the install path. The retired Bash prototype is kept in git history, tagged v0.1.0-bash-reference; see docs/BASH-MIGRATION.md for the evidence-gated retirement.

The disposable VM harness lives in installer/tests/vm/ and drives the static Rust binary.

Layering

Graphical welcome + installer    Quickshell/QML (live only; typed JSON protocol)
        |                        phoebus-welcome, phoebus-install
        v
TUI / CLI / sys                 front-ends (phoebus-tui, phoebus-installer)
        |
        v
Orchestration + plan            staged execution, single source of truth
        |
        v
Executor                        commands, storage, Portage, boot, services
        |
        v
Core                            typed config, models, policy, validation

The graphical frontend is one of several front-ends; it never contains installation logic. phoebus-installer --gui-bridge speaks newline-delimited JSON on stdin/stdout, reuses the same Installer, plan, validation and DestructiveAuthorization flow, and reports real stages through Installer::install_observed. The QML only renders typed state and submits bounded requests (ADR 0010).

phoebus-core

Pure, non-privileged logic with no external commands except reading /proc, /sys and small system files:

  • config — InstallConfig (nested sections, enums for closed sets); TOML and legacy flat-format loading (format is detected structurally).
  • validate — hostname/username/locale/timezone/keymap/password checks.
  • disk / hardware — models and protection classification (pure).
  • plan — InstallPlan with the canonical step order and human rendering.
  • policy — deterministic source/binary decisions + policy context.
  • emergelog — parses Portage emerge.log into measured compile times.
  • target — TargetRoot, which rejects absolute paths and .. traversal.
  • secret — SecretString (redacted Debug, zeroized on drop) + Redactor.
  • snapshot — deterministic snapshot names + TOML transaction history.
  • boot — BLS entry parse/render and root-subvolume selection for rollback.
  • rollback — rollback state machine, retention and mount/fstab planners.
  • effects — parse emerge --pretend into resolved effects + plan digest.
  • transaction — the user-queryable log of executed actions and outcomes.
  • action — closed SystemAction schema and a small deterministic parser.
  • brand — the visual identity (palette tokens, sun emblem, wordmark, wallpaper) as deterministic SVG/tokens shared by the QML frontend.
  • update — preparation policy and real Portage argument builders.

phoebus-executor

The only crate that runs privileged commands.

  • command — CommandSpec, ProcessRunner (real / recording / never) with arguments always separate; there is no sh -c.
  • exec — Exec centralises logging, redaction, dry-run, chroot mounts and target writes.
  • log — file + optional stderr logging; every line is redacted.
  • auth — DestructiveAuthorization, issued only after ERASE + final confirmation.
  • storage, encryption, portage, kernel, boot, users, services, desktop — the install backend, mirroring the proven order.
  • probe — read-only hardware and disk discovery.
  • snapshot, update, admin, actions — post-install foundations.
  • rollback — coordinated root/var/fstab/BLS rollback (ADR 0007).
  • nix — pinned Nix bootstrap, sandboxed build config, lifecycle and cleanup.
  • sandbox — the hardened systemd-run boundary for model execution.
  • transaction — persists the transaction log into the target.

phoebus-ai

  • Typed AiProposal / SystemAction (unknown actions fail closed; no shell).
  • assistant — the installed conversational plan schema (AssistantPlan) and its fail-closed parser; the model proposes the same actions sys executes.
  • privacy — PrivacyPolicy + ContextBundle; forbidden-path checks. The collector in phoebus-executor::admin only reads system sources.

phoebus-installer

  • orchestrate — Installer runs the plan stages and stops on first failure.
  • release — ReleaseManifest create/verify, candidate gates, atomic publish and signing command helpers.
  • Binaries: phoebus-installer, sys, phoebus-release.

Safety model

  • Every command goes through Exec, which logs a redacted command line, exit status and duration, and honours dry-run centrally.
  • Destructive functions take &DestructiveAuthorization; the token is created only after the destructive preview and confirmations.
  • All target writes go through TargetRoot; host-versus-target mistakes are caught by construction and covered by tests.
  • Secrets travel over stdin only and are registered with the redactor before any logging. They never enter the config.
  • The AI cannot execute; it can only propose typed changes that the backend validates and the user approves. The assistant's model call additionally runs inside an unprivileged, hardened systemd-run unit (sandbox), so the boundary is enforced by the OS and not only by the schema.
  • Approval is bound to the reviewed resolved plan: package effects are resolved again before execution and a material change aborts.

Rollback and recovery

A recovery point is a snapshot set: @ and the separate @var (Portage state) together; /home is excluded. Rollback creates a writable root generation, rewrites subvol= in both the restored root's fstab and the BLS entry options (the explicit argument overrides the Btrfs default), selects a kernel entry whose modules match the restored root, and writes previous/recovery entries. See ADR 0007.

Desktop environment: Mango + DarkMaterial

Phoebus OS has one desktop experience only: Mango + DarkMaterial (desktop.profile = "mango").

  • Mango + DankMaterialShell: gui-wm/mangowm (a wlroots-based tiling compositor) plus the DMS shell (panel, launcher, notifications, lock, idle, audio/network/Bluetooth/display controls) from the GURU overlay.
  • Entry points: Session entry point /usr/local/bin/phoebus-session-mango (with convenience wrapper /usr/local/bin/phoebus-session), session file /usr/share/wayland-sessions/phoebus-mango.desktop.
  • Display Manager: greetd with tuigreet configured to launch the canonical session upon authentication.
  • Headless: Systems requiring no graphical desktop can set desktop.profile = "none".

desktop.profile selects both the Gentoo desktop/systemd profile and the package set; the plan displays the canonical desktop session before installation.

Installation order (do not regress)

storage_prepare -> stage_install -> fstab_generate -> portage_configure
-> packages_base -> kernel_install -> boot_install -> users_configure
-> services_configure -> desktop_install -> finalize

Storage order: partition GPT, create ESP, LUKS format/open, mkfs.btrfs, mount top-level, create subvolumes, unmount, mount the subvolume layout. fstab and crypttab are generated after stage3 extraction (stage3 ships its own /etc/fstab).

Configuration and plan

InstallConfig is canonical data; the plan and all rendering derive from it. The same plan drives the review screen, the destructive preview, dry-run and the actual execution, so the UI cannot diverge from the backend.

Post-install foundations

  • Snapshots: read-only Btrfs snapshots under /.snapshots, recorded in a TOML history. A snapshot set captures @ and the separate @var; /home is intentionally not snapshotted so user documents survive a rollback.
  • Rollback: sys undo restores a committed snapshot as the next boot root with coordinated fstab, BLS and kernel selection (ADR 0007); a persisted state file makes an interrupted rollback resumable.
  • Background updates: emerge --fetchonly then --buildpkgonly stage distfiles and reusable local binary packages without installing; activation stays explicit.
  • Kernel/boot: sys-kernel/gentoo-kernel-bin (safe) or gentoo-kernel (optimized), dracut initramfs, systemd-boot BLS entries, plus a snapshot-based recovery entry that does not depend on the live root.

Extension points

  • ProcessRunner — swap the real runner for a recording/never runner in tests, or for a different execution backend.
  • InstallStep — add stages in plan.rs and handle them in orchestrate.rs.
  • SystemAction — add closed verbs; the policy engine classifies and previews them, and the broker executes them after approval.