Some checks are pending
ci / test (push) Waiting to run
Replace the fixed category routing (ADR 0006) with a shared, inspectable,
hardware- and preference-aware selection policy over resolved candidates from
Portage (source/binary/vendor), Nix, Flatpak, Snap, AppImage and the Phoebus
overlay. The policy keeps base components under Portage, separates hard
constraints from preferences, honours and persists explicit choices, errors
instead of silently switching lanes, and reuses an already-installed lane.
- phoebus-core::selection: the pure policy (16 tests: base-system, low-memory
vs high-core, sandbox requirement, GPU/arch/storage rejection, explicit
preference, unavailable backend, reproducibility, render).
- phoebus-executor::chooser: resolves real metadata and hardware facts.
- phoebus-executor::{snap,appimage,ebuild}: new lanes. Snap detects daemon and
confinement and installs app-containers/snapd through Portage; AppImage
adopts images with a pinned SHA-256, checks the ELF architecture without
executing, integrates a desktop entry and preserves user data on removal; the
custom ebuild overlay binds approval to the ebuild content digest and builds
through Portage's sandbox.
- Typed actions choose_package / set_package_preference / snap_* / appimage_* /
custom_ebuild_* with strict validators; the assistant prompt and schema are
reconciled (no category routing; custom ebuilds are untrusted).
- Installed sys: the installer locates the trusted static binary, copies it to
/usr/local/bin/sys and proves it runs in the target chroot before the
recovery snapshot, failing closed if absent; the VM harness fetches sys.
- docs/SYS.md: command/action reference and acceptance matrix; ADR 0006 revised.
Host gates pass: fmt, clippy (no new warnings), workspace tests, make test,
release and static sys builds. VM lane journeys remain pending (see HANDOFF).
183 lines
8.5 KiB
Markdown
183 lines
8.5 KiB
Markdown
# `sys` — the deterministic Phoebus system interface
|
||
|
||
`sys` is the typed, validated execution boundary shared by the assistant and
|
||
the offline (no-model) administrator. Whatever the assistant can do, a human can
|
||
do by typing the same action; the assistant only makes it easier. The AI path
|
||
emits the same closed action schema, and the LLM never holds privilege: every
|
||
mutation is reviewed and authenticated by a human through the privileged broker.
|
||
|
||
```
|
||
sys <phrase> # deterministic parser (no model)
|
||
sys --action '<json>' # one typed action
|
||
sys --action-file plan.json # a typed action from a file
|
||
sys ask "<request>" # assistant proposes the same typed actions
|
||
```
|
||
|
||
Run `sys --help` for the flags. Mutating actions require root (`sudo sys ...`).
|
||
Without a model, `sys ask` prints the deterministic equivalent and exits.
|
||
|
||
## Commands and typed actions
|
||
|
||
### Services (Portage/systemd ownership)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `inspect sshd` | `inspect_service` | read |
|
||
| `enable sshd` | `enable_service` | mutate |
|
||
| `disable sshd` | `disable_service` | mutate |
|
||
| `start sshd` | `start_service` | mutate |
|
||
| `stop sshd` | `stop_service` | mutate |
|
||
| `restart sshd` | `restart_service` | mutate |
|
||
|
||
### Packages (Portage)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `install vim` / `add vim` | `install_package` | mutate |
|
||
| `remove vim` / `uninstall vim` | `remove_package` | mutate |
|
||
| `search firefox` / `find firefox` | `search_packages` | read |
|
||
| `update` | `update_system` | mutate |
|
||
| `prepare updates` | `prepare_updates` | mutate |
|
||
| `what are you compiling` | `inspect_updates` | read |
|
||
| *(JSON only)* | `inspect_package` | read |
|
||
|
||
### Source selection (all lanes)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `choose firefox` | `choose_package` | read |
|
||
| `choose firefox via flatpak` | `choose_package` | read |
|
||
| `choose spotify as a gui sandboxed app` | `choose_package` | read |
|
||
| `prefer firefox via flatpak` | `set_package_preference` | mutate |
|
||
| `prefer firefox auto` | `set_package_preference` | mutate |
|
||
|
||
`choose` resolves real backend metadata, applies the shared policy
|
||
(ADR 0006), and prints the selected lane, version, provenance, integrity,
|
||
sandbox level, sizes, update behaviour and the rejected alternatives. It never
|
||
installs anything and never fabricates a candidate.
|
||
|
||
### Flatpak
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `flatpak install org.chromium.Chromium` | `flatpak_install` | mutate |
|
||
| `flatpak remove org.chromium.Chromium` | `flatpak_remove` | mutate |
|
||
| `flatpak list` | `flatpak_list` | read |
|
||
|
||
### Nix (developer lane)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `nix prepare nodejs python312` | `nix_prepare` | mutate |
|
||
|
||
### Snap (opt-in; `app-containers/snapd` through Portage)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `snap find notes` | `snap_find` | read |
|
||
| `snap info thunderbird` | `snap_info` | read |
|
||
| `snap install thunderbird [channel]` | `snap_install` | mutate |
|
||
| `snap remove thunderbird` | `snap_remove` | mutate |
|
||
| `snap list` | `snap_list` | read |
|
||
| `snap refresh [name]` | `snap_refresh` | mutate |
|
||
| `snap connections thunderbird` | `snap_connections` | read |
|
||
|
||
Snap requires a ready `snapd` daemon. If it is absent, `snap_install` installs
|
||
`app-containers/snapd` through Portage and enables `snapd.socket` first.
|
||
Confinement is detected (`strict`/`partial`/`none`); `--classic` is only used
|
||
when the typed action sets `"classic": true` and is shown in the review. The
|
||
plan notes that snapd also refreshes automatically.
|
||
|
||
### AppImage (opt-in; managed, not sandboxed)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `appimage import /path/App.AppImage` | `appimage_import` | mutate |
|
||
| *(JSON only)* | `appimage_acquire` | mutate |
|
||
| *(JSON only)* | `appimage_update` | mutate |
|
||
| `appimage remove name` | `appimage_remove` | mutate |
|
||
| `appimage info name` | `appimage_info` | read |
|
||
| `appimage list` | `appimage_list` | read |
|
||
|
||
Acquisition requires a pinned SHA-256; a placeholder or mismatch is refused and
|
||
the download is discarded. Architecture is read from the ELF header without
|
||
executing the image. Desktop entries are installed, and user data is preserved
|
||
on removal unless `"purge_data": true`. AppImage provides **no application
|
||
sandbox** and is described as such.
|
||
|
||
### Custom ebuilds (Phoebus overlay)
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `ebuilds` / `custom ebuilds` | `custom_ebuild_list` | read |
|
||
| *(JSON only)* | `custom_ebuild_prepare` | mutate |
|
||
| *(JSON only)* | `custom_ebuild_install` | mutate |
|
||
| *(JSON only)* | `custom_ebuild_remove` | mutate |
|
||
|
||
A custom ebuild is untrusted executable code. `custom_ebuild_prepare` writes it
|
||
to `/var/db/repos/phoebus` with a rationale and the SHA-256 of its exact
|
||
content; it does not build it. `custom_ebuild_install` requires that same
|
||
digest, regenerates the `Manifest` and builds through Portage with its sandbox
|
||
enabled. Editing the staged ebuild invalidates the approval.
|
||
|
||
### Snapshots and rollback
|
||
|
||
| Phrase | Typed action | Kind |
|
||
| --- | --- | --- |
|
||
| `snapshot before update` | `create_snapshot` | mutate |
|
||
| `undo` / `rollback` | `undo` | mutate |
|
||
| `undo status` | `rollback_status` | read |
|
||
| `history` | `history` | read |
|
||
|
||
## Acceptance matrix
|
||
|
||
The matrix below is the repeatable acceptance suite. `installer/tests/vm/
|
||
sys-acceptance.sh` runs the deterministic and JSON groups inside a booted,
|
||
installed, detached VM and prints a machine-readable summary; it is safe to run
|
||
with no network and no model.
|
||
|
||
| # | Case | Command | Expected |
|
||
| --- | --- | --- | --- |
|
||
| 1 | Identity | `sys --version` | prints the version, exit 0 |
|
||
| 2 | Read-only history | `sys history` | state, exit 0, no mutation |
|
||
| 3 | Invalid natural operand | `sys -- install --color=n` | rejected, nonzero |
|
||
| 4 | Unknown phrase | `sys frobnicate` | rejected, nonzero, examples shown |
|
||
| 5 | JSON unknown action | `--action '{"action":"run_shell"}'` | fail closed, nonzero |
|
||
| 6 | JSON unknown field | `--action '{"action":"history","x":1}'` | fail closed, nonzero |
|
||
| 7 | Option-like operand (JSON) | `install_package atom="-C"` | rejected before any command |
|
||
| 8 | Invalid Snap name | `snap_install name="Bad Name"` | rejected, nonzero |
|
||
| 9 | Invalid AppImage hash | `appimage_acquire sha256="00"` | rejected, nonzero |
|
||
| 10 | Ebuild path traversal | `custom_ebuild_prepare atom="../../x"` | rejected, nonzero |
|
||
| 11 | Choose with no lane | `sys choose unused-name` | selection or clear failure, never invented |
|
||
| 12 | Inventory (empty root) | `--root T appimage list` / `ebuilds` | "no managed …", exit 0 |
|
||
| 13 | Mutating as non-root | `set_package_preference` | refused: needs root |
|
||
| 14 | Snap daemon absent | `snap list` on a system without snapd | useful error, nonzero |
|
||
| 15 | Install a tiny package | `sys install app-misc/hello` (Portage) | installed; `emerge -p` confirms; recorded in `sys history` |
|
||
| 16 | Remove it | `sys remove app-misc/hello` | removed; recorded |
|
||
| 17 | Service lifecycle | `sys enable/start/stop sshd` | unit state matches `systemctl` |
|
||
| 18 | Update preparation | `sys prepare updates` then `what are you compiling` | state reported truthfully |
|
||
| 19 | Snapshot + undo | `sys snapshot`, mutate, `sys undo`, reboot | root/var/package state restored |
|
||
| 20 | Approval rejected | answer `n` at the prompt | no mutation, nonzero |
|
||
| 21 | Plan changed between review and exec | concurrent metadata change | aborts, nonzero |
|
||
| 22 | Offline `sys ask` | `sys ask "<request>"` with no provider | deterministic fallback, nonzero |
|
||
|
||
Cases 1–14 and 21–22 are covered by host tests
|
||
(`crates/phoebus-core/src/selection.rs`, `.../action.rs`,
|
||
`crates/phoebus-executor/src/{snap,appimage,ebuild,chooser}.rs`, and
|
||
`crates/phoebus-installer/tests/sys_cli.rs`). Cases 15–20 and the in-VM subset
|
||
of 1–14 are exercised by the VM acceptance script; their current verification
|
||
status is recorded in `docs/STATUS.md`.
|
||
|
||
## Security properties
|
||
|
||
- **No shell.** Every command is an argument vector through
|
||
`phoebus-executor::Exec`; there is no `sh -c` on any path.
|
||
- **Validated at the boundary.** Every action (manual, JSON, or AI) is
|
||
re-validated before a command is built; option-like operands are rejected.
|
||
- **Target-root isolation.** Alternate-root operations are chrooted; runtime
|
||
operations (services, Snap) refuse an alternate root.
|
||
- **Approval binding.** A resolved plan has a digest; a material change between
|
||
review and execution aborts. A custom ebuild binds approval to its content
|
||
digest.
|
||
- **Secrets** travel only through mode-0600 files/stdin and are redacted from
|
||
logs and history.
|