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