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

143 lines
6.4 KiB
Markdown

# 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`.