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

170 lines
8 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
```
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.