Adds the documentation a new session needs: AGENTS.md (read-first contract), docs/OBJECTIVES.md, ROADMAP.md, STATUS.md, ARCHITECTURE.md, DEVELOPMENT.md, CONTRIBUTING.md, GIT-WORKFLOW.md and CHANGELOG.md. STATUS.md records an honest implemented/unit-tested/VM-verified matrix and known limitations.
121 lines
5.1 KiB
Markdown
121 lines
5.1 KiB
Markdown
# Architecture
|
|
|
|
Phoebus currently ships two installer implementations:
|
|
|
|
1. **Bash** (`installer/`) — the proven prototype and executable reference.
|
|
2. **Rust** (`installer-rs/`) — the production installer. It reproduces the
|
|
proven VM boot path and is the intended long-term backend.
|
|
|
|
The Bash implementation stays until hardware-level desktop verification exists.
|
|
|
|
## 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.
|