phoebus_os/docs/adr/0013-ai-first-installation.md
Phoebus f9e39925b4 feat(install): AI-first sys install workflow
Implement the shared installation workflow (ADR 0013). sys install, sys ask
install and the explicit backend flags all use one path: identify -> evidence
-> AI investigation -> deterministic validation/effects -> review -> approval
-> execute -> verify -> history.

- phoebus-ai::install: bounded, multi-turn investigation. The model may request
  typed read-only evidence (discover_candidates, inspect_candidate,
  check_backend, inspect_installation), ask one bounded question about intent,
  and must return a structured InstallProposal. Turn/request/size limits and
  repeated-request detection bound it; a rejected proposal is revised.
- phoebus-core: add the four read-only investigation actions and strict
  validators; add a transaction id; backend/kind wire names now match as_str.
- phoebus-executor::install: resolve_explicit (no model, no fallback),
  resolve_deterministic and resolve_with_ai; validate_proposal re-resolves the
  candidate against real metadata, rejects fabrication/ambiguity/staleness/
  duplicates, maps it to the existing broker action, and binds approval to a
  digest; revalidate + verify_installed. chooser gains per-lane friendly-name
  resolution and structured evidence.
- transaction::begin/finish record an in-progress transaction before mutation.
- sys: --portage/--flatpak/--nix/--snap/--appimage/--ebuild (mutually
  exclusive) bypass the model; an unqualified install consults the model and,
  with none, prints the deterministic selection and installs nothing.
- The installer persists /etc/phoebus/install.toml; sys loads it and adds free
  space, Wayland, usable lanes, saved preferences and recovery capability to
  the bounded facts.
- Docs: ADR 0013, docs/SYS.md install sections and cases 23-31, CHANGELOG,
  STATUS, HANDOFF, ROADMAP. New live-VM workflow check script.

Host gates pass: fmt, clippy (no new warnings), workspace tests, make test.
VM: verified the workflow CLI and read-only investigation on the reference
LiveGUI ISO; a full target install journey is running (see HANDOFF).
2026-09-23 20:30:13 -07:00

6.4 KiB

ADR 0013: AI-first package installation workflow

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

Context

ADR 0006 made software selection a shared, hardware- and preference-aware policy rather than fixed category routing. The remaining gap was the entry point: sys install <application> was a thin Portage wrapper and ignored the connected model, while Flatpak/Nix/Snap/AppImage each had their own command. A user had to know the right lane in advance.

This ADR defines the installation workflow itself. It supersedes any remaining fixed category-to-backend routing: the model makes the contextual recommendation, and the deterministic system validates and executes it.

Decision

sys install <application> is AI-first. One shared workflow is used by ordinary installation, by sys ask installation requests, and by explicit backend flags:

request -> identify application -> gather evidence -> AI investigation
-> proposed selection -> deterministic resolution/validation -> review
-> approved execution -> verification -> history

The workflow lives in phoebus-executor::install; the model loop lives in phoebus-ai::install. The CLI only wires flags and presentation.

1. The model investigates with typed, read-only tools

The model has no shell and no filesystem access. It runs a bounded multi-turn investigation and may:

  • request evidence with the read-only typed actions discover_candidates, inspect_candidate, check_backend, inspect_installation;
  • ask the user a question about intent when system facts cannot answer it;
  • then return a structured InstallProposal { application, backend, candidate, version, reason, tradeoffs, evidence }.

Bounds: turn limit, per-turn request limit, evidence-size cap, and repeated-request detection (the same evidence is never fetched twice; the model is told to finalise or ask the user). Evidence is untrusted data; it cannot grant capabilities. Only the four read-only actions are permitted; a proposal that requests anything mutating fails closed.

2. The deterministic resolver is authoritative

The model's proposal is never executed directly. validate_proposal:

  • re-resolves the application against real backend metadata, including friendly-name resolution per lane;
  • rejects a candidate that is not exactly one the backend reported (fabricated or stale identifiers), an unavailable candidate, an ambiguous friendly name, or a duplicate of an existing installation;
  • maps the confirmed candidate to the existing broker action (install_package, flatpak_install, snap_install, nix_prepare, custom_ebuild_install), so there is no parallel execution path;
  • computes concrete effects (Portage --pretend, or a synthetic effect for binary lanes) and a single approval digest.

A rejection is returned to the model as a bounded finding, which may revise its proposal up to the turn limit.

3. Hard rules stay outside model discretion

Portage owns the kernel, drivers, systemd, the host graphics/audio stack and boot (enforced by the selection policy). Signature verification, architecture and hardware compatibility, target-root isolation and the privilege boundary are not proposable. A custom ebuild remains a separately reviewed, untrusted artifact; the install workflow never builds one as part of "investigation".

4. Explicit backend flags are authoritative

--portage, --flatpak, --nix, --snap, --appimage, --ebuild:

  • bypass the model entirely and use deterministic resolution within the requested lane;
  • are mutually exclusive (CLI arg group);
  • never fall back to another lane: if the lane cannot satisfy the request, the reason and the alternatives are shown and nothing is installed;
  • still require validation, a protective snapshot where applicable, authentication and review.

Saved preferences inform ordinary AI recommendations; an explicit flag takes precedence over a saved preference.

5. No-model path

For an unqualified install with no reachable provider, the workflow prints the deterministic candidate selection and the explicit-backend commands, then refuses to install. Provider failure is never treated as permission to install through a lane. Explicit-backend installation, service management and recovery remain fully deterministic and model-free.

6. One transaction engine, verification, truthful history

All three selection sources execute through the same broker action and the same transaction engine. The workflow records the transaction before the mutation (so an interrupted run leaves a visible in-progress record), then:

  • revalidates the reviewed plan immediately before execution (candidate, version, action and effects digest); a material change aborts;
  • verifies the installed identity and version after execution (/var/db/pkg, flatpak list, snap list, the managed AppImage record);
  • records the final outcome and the protective snapshot.

Success is never claimed merely because a subprocess exited zero: verification failure is a failed transaction.

Consequences

  • The AI needs bounded, structured tools; the read-only actions are real sys surfaces (sys --action '{"action":"discover_candidates",...}') as well as model tools.
  • A connected model is required for an unqualified sys install; this is the AI-first contract. It is never required to install explicitly, to manage services, or to recover.
  • The resolver and the model must agree on identifiers. The wire names for backends (portage-source, custom-ebuild, ...) are the same as Backend::as_str, so evidence and proposals share one vocabulary.
  • Multi-turn behaviour depends on the transport. The direct providers carry the full conversation; the OpenCode adapter concatenates messages, so investigation is best-effort there.

Non-goals

  • Letting the model execute anything (it cannot).
  • Automatically building generated ebuilds during investigation.
  • Silent lane switching or duplicate installs.
  • Replacing deterministic administration with a model.

Verification

Unit/integration coverage: the AI loop (steps, bounds, repetition, revision, provider failure), the resolver (fabrication, ambiguity, duplicate, changed evidence), the action mapping, the CLI (flag conflicts, no-fallback, no-model offer), and the transaction begin/finish. VM journeys through sys install (AI-selected and explicit-backend) remain the acceptance gate; see docs/SYS.md and docs/STATUS.md.