Some checks are pending
ci / test (push) Waiting to run
- Default natural-language and conversational routing for sys install, sys please install, and sys ask through shared AI workflow - Constrain AI candidate evaluation when source flags are supplied without bypassing the model - Enforce explicit --legacy flag for deterministic administration; legacy install without a source flag refuses execution and offers choices - Audit --action and --action-file entry points to require --legacy or --broker - Provide truthful guidance on absent or failing AI models without silent mutation or unverified fallback - Implement package correctness safeguards: Nix attribute evaluation probe, Portage binary check with source compile abort guard, cross-source installed application tracking, and data preservation on removal - Provide Quickshell desktop assistant (phoebus-assistant) backed by stdio JSON-RPC bridge (sys --assistant-bridge) and desktop integration - Implement unified multi-source update checking across all package lanes - Implement quiet proactive assistance monitor with alert deduplication and snoozing - Expand acceptance suite in installer/tests/vm/sys-acceptance.sh to 22 cases (22/22 PASS)
220 lines
12 KiB
Markdown
220 lines
12 KiB
Markdown
# 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.
|
|
- `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.
|
|
|