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).
143 lines
6.4 KiB
Markdown
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`.
|