phoebus_os/docs/ARCHITECTURE.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

8 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

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

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.
  • 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 profiles

Two sessions are generated, and each starts exactly one compositor and one set of shell services:

  • dwl (desktop.profile = "dwl"): the proven session — dwl, waybar, wofi, mako, swaybg, swayidle, swaylock, the polkit agent. Entry point /usr/local/bin/phoebus-session, session file phoebus-dwl.desktop.
  • Mango + DankMaterialShell (desktop.profile = "mango"): gui-wm/mangowm plus the DMS shell (panel, launcher, notifications, lock, idle, audio/network/ Bluetooth/display controls) from the GURU overlay. Entry point /usr/local/bin/phoebus-session-mango, session file phoebus-mango.desktop. The dwl session is installed alongside as a fallback. The Mango session never starts the dwl helpers. See ADR 0009.

desktop.profile selects both the Gentoo desktop/systemd profile and the package set; the plan shows the selected session before installation, and the installer writes both session entry points for the Mango profile so the user can return to dwl.

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.