# 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 ``` Desktop assistant GUI Quickshell/QML (installed; typed JSON-RPC protocol) | phoebus-assistant +-------------------+ | Graphical welcome + installer Quickshell/QML (live only; typed JSON protocol) | phoebus-welcome, phoebus-install v 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 or administrative 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`. - `sys --assistant-bridge` speaks newline-delimited JSON-RPC on stdin/stdout, providing a uniform interface for the desktop assistant (`phoebus-assistant`) for conversational interaction, legacy actions, unified updates, proactive alerts, and user preferences (ADR 0010, ADR 0013). ### 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, conversational parsing, and options. - `selection` — hardware-aware source scoring, preference profiles (`Balanced`, `FastInstallation`, `NativeIntegration`, `ApplicationIsolation`), project tool environments, and candidate selection. - `update` — unified multi-source update models across all supported package lanes. - `proactive` — quiet proactive alert models, categories, and deferred schedules. - `brand` — the visual identity (palette tokens, sun emblem, wordmark, wallpaper) as deterministic SVG/tokens shared by the QML frontend. ### 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. - `proactive` — quiet proactive monitors for storage, services, transactions, and reboots. Alert snooze/dismiss state is user-owned (0600/0700, bounded). - `personal` — per-user storage resolution (`UserStorage`) and initiating-user resolution across `sudo`/`pkexec` (`PHOEBUS_UID` → `SUDO_UID` → `PKEXEC_UID` → effective uid; home from `/etc/passwd`). Personal preferences and alert state never touch `/etc` or `/var/lib`. - `rollback` — coordinated root/`var`/fstab/BLS rollback (ADR 0007). - `nix` — pinned Nix bootstrap, attribute evaluation probe, sandboxed build config, and lifecycle. - `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. - `service` — shared administration service layer (`PreparedPlan`, `PlanStore`, planning, authorization, Polkit elevation, execution, and verification) shared identically by CLI and GUI. The single authoritative validation boundary (`validate_prepared_plan`) runs before elevation and is repeated in the broker after authentication; plans bind actions, effects, candidate, target root and initiating uid, are stored per-user with an integrity seal, and are atomically claimed before execution. Execution carries the *reviewed* per-step effects forward and compares freshly resolved effects against them (only changes explained by an earlier approved step are allowed), so a material change aborts with a terminal `stale plan` outcome and every started transaction reaches a terminal result. - `approval` — broker-controlled approval ledger (`/var/lib/phoebus/approvals`, 0700/0600, ADR 0014). The plan's integrity seal is both the binding fingerprint and the `O_EXCL` consumption key, so at most one execution may run, replay is refused even after the user deletes every file in their own plan directory, and a replacement under the same identifier is refused before the ledger is touched. The approving digest travels across authentication independently of the plan file (`--approval-digest`), the initiating identity is derived from `PKEXEC_UID`, and a crash leaves a reconciled `interrupted` record. - `ai_setup` — one provider/endpoint/model/credential resolver shared by the CLI and the desktop bridge, so their provider setup cannot diverge. Credentials load from a 0600 file (configured path, `PHOEBUS_AI_API_KEY_FILE`, or `~/.config/phoebus/ai.key`) and never travel through QML, prompts or argv. - `conversation` — bounded, minimized conversation history and contextual follow-up resolution (tradeoff comparisons, backend switching, and plan confirmation). Raw requests are not persisted; registered secrets are redacted; history is 0600/0700, atomic, bounded and clearable. - `assistant_bridge` — JSON-RPC stdio bridge serving the Quickshell desktop assistant. Every plan type returns the same `plan_id`/`digest` review card; `execute` runs only the referenced reviewed plan. - `release` — `ReleaseManifest` create/verify, candidate gates, atomic publish and signing command helpers. - Binaries: `phoebus-installer`, `sys`, `phoebus-release`. ## Safety model and package correctness - 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: the reviewed per-step effects are carried into execution, package effects are resolved again only as evidence to compare against them, and a material change aborts. Privileged consumption is anchored in a root-owned ledger (ADR 0014), so a user-editable plan file cannot be replaced or replayed. - Personal preferences and alert state are user-owned (0600/0700); system-wide policy is root-owned and changed only through the authenticated typed action `set_package_preference { system_wide: true }`. - **Portage binary vs source verification**: Binary package recommendations are verified with `emerge --pretend --usepkgonly`. If a package would compile from source (`EffectSource::Source`), execution halts closed and demands a revised review and approval. - **Nix attribute verification**: Nix packages undergo evaluation probes against `` before inclusion in recommendations or execution. - **Cross-source ownership and data preservation**: Installed applications are tracked across Portage, Flatpak, Snap, and AppImage. Removal preserves user data by default. - **Audited broker entry points**: JSON action calls (`--action`/`--action-file`) fail closed unless passed `--legacy` or `--broker`. ## 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. ## Desktop assistant and administration architecture The desktop assistant (`phoebus-assistant`) is an installed Quickshell GUI application launched from the desktop menu, keybinding, or launcher: - **Shared execution core**: The GUI contains no business logic. It communicates via stdio JSON-RPC over `sys --assistant-bridge`. - **Recommendation cards and options**: Recommends package sources with clear rationale (e.g., "Install Firefox from Flathub. Recommended because it avoids a lengthy build and provides application isolation"), expandable candidate comparisons, and single-approval execution bound to the plan digest. - **Unified multi-source updates**: Queries and displays available updates across Portage, Flatpak, Snap, AppImage, and Nix, with reboot-required notifications. - **Quiet proactive monitoring**: Periodically evaluates bounded deterministic health checks (service failures, disk usage under 5 GiB, failed transactions, pending updates), supporting deduplication, snooze, and user toggle. - **User preferences and profiles**: Exposes inspectable preference profiles (`Balanced`, `FastInstallation`, `NativeIntegration`, `ApplicationIsolation`), per-project tool version mappings, and source pins. - **Deterministic legacy panel**: Structured GUI fallback controls executing deterministic `--legacy` commands directly through the bridge. ## 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.