phoebus_os/docs/ARCHITECTURE.md
Phoebus 7ebb616c99
Some checks are pending
ci / test (push) Waiting to run
feat(ai,desktop): unify administration layer, provision QML, and add conversation continuity
Unifies AI-first administration across the CLI (sys) and desktop GUI
(phoebus-assistant) through a shared service layer, fixes installed
desktop QML asset provisioning, adds Polkit elevation, and introduces
contextual conversation continuity.

- Extract phoebus_installer::service shared by CLI and desktop assistant bridge:
  - Reviewable plan staging (PreparedPlan) with SHA-256 cryptographic digests,
    15-minute TTL expiration, and replay prevention (PlanStore).
  - Pre-mutation system state revalidation binding execution strictly to the reviewed plan.
  - Honest recommendations displaying genuine provenance and unmeasured compile times.
  - Two-phase transaction logging (begin before mutation, finish with verification).
- Provision installed desktop assets and Polkit policy in phoebus-executor::desktop:
  - Added gui-apps/quickshell to canonical Mango desktop packages.
  - Embed 13 QML and policy files into target root under /usr/share/phoebus/assistant/.
  - Installed Polkit policy (club.phoebus.sys.policy) allowing unprivileged users to
    authenticate mutating plans via pkexec without blanket passwordless sudo.
- Eliminate startup freeze and polling in phoebus-assistant:
  - Multi-source update queries moved to on-demand tab switching.
  - Handshake timer reduced to one-shot 100ms with fast deterministic check.
- Add phoebus_installer::conversation:
  - Bounded 10-turn history with credential redaction.
  - Contextual follow-up resolution for comparisons, backend switching, and confirmation.
- Implement unified cross-source removal (plan_removal) preserving user data by default.
- Verified: all 486 workspace tests pass, release and crt-static builds succeed,
  and 23/23 VM acceptance cases pass (PASS=23 FAIL=0).
2026-09-24 17:21:16 -07:00

12 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

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.
  • 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.
  • conversation — bounded conversation history and contextual follow-up resolution (tradeoff comparisons, backend switching, and plan confirmation).
  • assistant_bridge — JSON-RPC stdio bridge serving the Quickshell desktop assistant.
  • 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: package effects are resolved again before execution and a material change aborts.
  • 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 <nixpkgs> 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.