phoebus_os/docs/adr/0001-rust-installer.md
Phoebus 83368f774c
Some checks are pending
ci / test (push) Waiting to run
feat(git): add session context, host doctor, ADRs and git hygiene
Adds scripts/context.sh + 'make context' (one-screen session briefing),
scripts/doctor.sh + 'make doctor' (host prerequisites), docs/HANDOFF.md
(rolling cross-session note), docs/adr/ (BLS, desktop profile, keyring, Rust),
.githooks/commit-msg (Conventional Commits), .gitattributes, scripts/backup-git.sh
+ 'make backup', and a Forgejo Actions CI workflow. Updates AGENTS.md reading
order/work loop and DEVELOPMENT.md.
2026-09-20 02:36:32 -07:00

1.2 KiB

ADR 0001: Rust installer as production; Bash retained as reference

  • Status: Accepted
  • Date: 2026-09-20

Context

System software that partitions disks, formats LUKS2, installs Portage and writes bootloaders should not permanently live in several thousand lines of privileged, dynamically scoped shell. The Bash prototype proved the full path in a VM and exposed the exact failure modes (subvolume ordering, fstab timing, host-versus-target writes, secret handling).

Decision

Move the production installer/backend to Rust (installer-rs/) with strong types, structured errors, a central command layer, a TargetRoot abstraction and a DestructiveAuthorization token. Keep the Bash installer (installer/) as the executable reference and fallback until hardware-level desktop verification exists; then retire or archive it.

Consequences

  • Host/target path bugs and word-splitting are eliminated by construction.
  • Privileged logic is unit-testable with a fake ProcessRunner.
  • Two implementations must be kept in step during the migration (a plan-parity test compares them).
  • The Rust installer must reproduce the proven VM boot before becoming primary (it now does).