# 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. - `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. ### phoebus-ai - Typed `AiProposal` / `SystemAction` (unknown actions fail closed; no shell). - `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, assemble command. - 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. ## 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. `/home` is intentionally not snapshotted by default. - **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 recovery entry booting `rescue.target`. ## 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.