fix(sys): aggregate cleanup intents into plan binding; record VM acceptance and defect evidence
Some checks are pending
ci / test (push) Waiting to run

This commit is contained in:
Phoebus 2026-09-25 05:35:08 -07:00
parent 58e0f70879
commit bab5f413ed
7 changed files with 294 additions and 174 deletions

View file

@ -3,6 +3,72 @@
All notable changes are recorded here. The authoritative history is `git log`; All notable changes are recorded here. The authoritative history is `git log`;
this file is the curated, human-readable summary. this file is the curated, human-readable summary.
## 2026-09-25 — Fix the `sys` catalogue review findings (host/target, revalidation, update effects, Nix inventory, dependencies)
Follow-up to the package-management interface: seven review findings are fixed,
each with regression tests, and the installed-system acceptance matrix is
extended and re-run.
- **Host/target confusion closed (finding 1).** Every catalogue, update-check,
information and maintenance query is now built for the *intended target* —
directly for `/`, or inside the target chroot for an alternate root. Snap acts
on the running daemon and is reported unavailable (and refused for mutation)
for an alternate root instead of ever touching the host. Availability checks
resolve tools from the target (`Exec::tool_in_target`), so a host Flatpak,
`eclean` or `qdepends` cannot leak into a target operation. Recording-runner
tests assert alternate-root search/update/cleanup and Snap paths issue no host
commands.
- **Maintenance revalidation (finding 2).** `resolves_effects` now covers
`Depclean`, `ApplyUpdates` and `CleanCache`, so they are re-resolved at the
privileged execution boundary and within multi-action plans. Depclean removals
are parsed into **structured `PackageEffect`s** (`emerge --pretend
--depclean`), so a changed removal set changes the digest and aborts before an
unapproved mutation; a regression test proves drift is refused with no
destructive command run.
- **Exact Flatpak/Snap update effects (finding 3).** `ApplyUpdates` resolves a
reviewable per-source plan with the affected identities and versions; each
Flatpak app is updated by ref and each snap by name, and the plan is bound to
approval and re-checked immediately before execution. Unrestricted update-all
is gone. Lanes with no safe system-level transaction (Nix/AppImage/custom
ebuild) are refused with a clear limitation. Destructive cache cleanup now
reviews each cleaner's non-destructive dry run and binds the item set to
approval (`ResolvedPlan.cleanup`), which is part of the digest.
- **Complete source constraints (finding 4).** `SystemAction::backend()`
classifies Portage-only actions (`UpdateSystem`, `RemovePackage`,
`Depclean`, `PrepareUpdates`, `InspectUpdates`, `PackageOwners`,
`PackageDependencies`); `constrain_action` rewrites optional-backend discovery
and selection (`DiscoverCandidates`, `ChoosePackage`) to the constrained lane
*before* querying, and refuses the cross-lane `InspectInstallation`. Unit tests
prove a Flatpak-constrained request cannot investigate or mutate
Portage/Snap/Nix through any action variant.
- **Cache-cleanup truthfulness (finding 5).** Portage cleaner errors are no
longer converted to text while the action returns success. A cleaner that ran
and failed fails the whole action (with partial successes preserved), an
unavailable cleaner is reported distinctly from one that found nothing, and
the report reaches the command exit status, assistant response and transaction
history.
- **Nix inventory (finding 6).** Inventory enumerates the packages of the active
Nix profiles from each profile's `manifest.json` (v1/v2/v3), retaining profile
and user scope and package identity; historical generations and realised store
paths are reported separately. Unsupported manifest formats and base profiles
are stated explicitly rather than shown as an empty inventory. Filtering finds
a package such as `nodejs` in a supported profile.
- **Dependency inspection (finding 7).** Forward and reverse dependencies now
come from the authoritative installed VDB metadata
(`DEPEND`/`RDEPEND`/`BDEPEND`, with a `qdepends` tree fallback) instead of an
`emerge --pretend` merge plan. Already-satisfied, conditional/versioned and
blocker dependencies are preserved; the requested package is never its own
dependency; a failed query is distinguished from a genuinely empty set.
- **Tests:** +28 (core/executor/installer) covering alternate-root chrooting,
structured depclean effects and digest drift, exact Flatpak identities, cache
cleanup review and failure propagation, constraint rewrite/refusal, Nix
manifest parsing, and dependency parsing/inspection. `make test` passes
(`cargo test --workspace`).
- **VM-verified (disposable installed clone):** the read-only acceptance matrix
is extended with `snap-alternate-root`, `list-nix-legacy` and `deps-legacy`,
and reports `SUMMARY PASS=37 FAIL=0`. _(Fresh-install and mutating journeys:
see `docs/HANDOFF.md` for the current verified/blocked state.)_
## 2026-09-25 — Complete the `sys` package-management interface (search/list/info/updates/maintenance) ## 2026-09-25 — Complete the `sys` package-management interface (search/list/info/updates/maintenance)
Adds a complete package catalogue on top of the typed-action architecture. AI is Adds a complete package catalogue on top of the typed-action architecture. AI is

View file

@ -3,159 +3,126 @@
Rolling note between work sessions. **Update this file before you finish**, then Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail. commit it. It should be short and current; use `git log` for detail.
- **Last updated:** this session (2026-09-25), completion of the `sys` - **Last updated:** this session (2026-09-25). Follow-up to commit `05d7075`:
package-management interface: unified cross-source search, installed-package the seven review findings on the `sys` package-management interface are fixed
inventory, package information, consistent per-source update check/apply, and (host/target rooting, maintenance effect revalidation, exact Flatpak/Snap
maintenance (depclean/cache/owners/deps), all as validated typed actions update effects, complete source constraints, truthful cache-cleanup outcomes,
shared by the CLI and assistant. AI remains the default for every operation; Nix active-profile inventory, VDB-based dependency inspection), with
`--legacy` is the only user-facing opt-in to deterministic handling. A source regression tests. The disposable-VM acceptance matrix is extended and the
flag constrains the AI workflow and never bypasses it. See fresh-install / mutating / rollback journeys below were completed.
`docs/SYS.md` "Package catalogue" and the CHANGELOG entry. - **Interface contract (unchanged):** every ordinary request uses the AI
- **Current focus:** workflow; only an explicit `--legacy` selects deterministic handling; source
1. **New typed actions (`phoebus-core::action`):** `SearchPackages` gained an flags constrain the AI and never bypass it; a missing model stops the workflow
optional `backend`; added `ListPackages`, `PackageInfo`, `PackageOwners`, and offers the exact `--legacy` command without executing it; both modes share
`PackageDependencies`, `Depclean`, `CleanCache`, `CheckUpdates`, the same validated typed actions, approval controls and execution layer.
`ApplyUpdates`. Read-only variants are non-mutating and need no root;
`ApplyUpdates`/`Depclean` are High risk (protective snapshot), `CleanCache`
Medium.
2. **Executor catalogue (`phoebus-executor::query`, `phoebus-core::catalog`):**
search/inventory/info across Portage, Flatpak, Snap, managed AppImages, Nix
and staged custom ebuilds. Each lane reports unavailable / failed / empty
distinctly. Nix profiles are listed; store paths are reported separately as
realised dependencies. Custom ebuilds are never double-counted (they appear
under Portage). Portage VDB reading (`portage::installed_packages`) and
`emerge --search` parsing (`portage::parse_search`) added.
3. **Updates + maintenance:** `check_updates` filters the unified overview;
`apply_updates` runs each lane and returns a truthful per-source report,
failing the action when an attempted source fails; AppImage/Nix are
explained as manual/project-specific. `depclean` and Portage `ApplyUpdates`
are previewed from `emerge --pretend` at review time and bound by digest.
4. **AI-default routing (`phoebus-ai::assistant::run_assistant`):** the general
assistant now runs a bounded read-only investigation loop
(`kind:"investigate"` / `kind:"plan"`, `parse_step`, `is_general_investigation_action`)
before answering. `service::plan_general` supplies the read-only executor,
applies the source constraint to investigation requests and the final plan
(`constrain_action`: rewrite lane-selectable queries, refuse a foreign
lane), and accepts an empty action list as a pure answer. `sys` renders an
answer without executing; a missing model prints the exact `--legacy`
command.
- **Last verified (this session):**
- `cargo fmt --all -- --check` clean; `cargo clippy --workspace --all-targets`
exits 0 (only pre-existing lints remain).
- `cargo test --workspace`: 645 passed, 0 failed (was 602). New coverage
includes: catalogue action classification/validation and natural phrases;
catalogue report rendering (unavailable/failed/empty, installed/scope);
per-lane search/inventory/info with a recording runner; VDB metadata and
no-double-count; ambiguity; depclean preview/skip; per-source update
failure; forward dependencies; AI step parsing, the general investigation
loop, mutating-investigation refusal; `plan_general` investigation/answer,
foreign-lane refusal and constraint rewrite; and CLI routing: search/list/
info/updates without `--legacy` enter the AI workflow and never run
deterministically, a source flag constrains and never bypasses, `--legacy`
never contacts a model, read-only catalogue commands need no root and write
no transaction.
- Host smoke test of `sys search/list/info/updates --legacy` against the live
host (real Flatpak inventory and update list rendered).
- **Disposable-VM read-only acceptance** (`serial-driver.py boot` on a qcow2
clone of the installed disk, `SYS_BIN=/tmp/sys`): `sys-acceptance.sh`
reports `SUMMARY PASS=34 FAIL=0`, including `search-legacy`, `list-legacy`,
`info-legacy`, `updates-legacy`, `search-no-model-offer`,
`search-flag-constraint`, and the non-root maintenance refusals. Found and
fixed a real defect: the installed system left `/etc/portage/repos.conf` and
`/etc/portage/package.use/phoebus` root-only, so `emerge --search` failed for
a normal account. `portage::normalize_config_permissions` (unit-tested,
keyring excluded) makes the non-secret Portage config world-readable and
runs at config write and at finalize; with the same permissions applied to
the clone, `search-legacy` returns real results (3) and `updates-legacy`
reports 10 available. The fresh-install re-run is pending (base install is
~2 h).
- **Not yet verified (BLOCKED):**
- **A fresh VM install with the permission fix** (so the catalogue works
out of the box) has not been re-run; the base install is ~2 h. The fix is
unit-tested and its effect was demonstrated on the disposable clone.
- **Mutating catalogue journeys** (`apply updates`, `depclean`, `clean cache`)
are not exercised in a VM; they need a disposable installed disk and, for
`apply updates`, network.
- The privileged `sys --broker --execute-plan` path and replay rejection remain
unit-tested only: the serial console has no root access and no Polkit agent
(`sudo -n` denied), so `pkexec` elevation cannot complete. A
graphical/seat-providing VM or a passwordless-sudo test image is required.
- No AI provider credential is present; do not invent one. The general
investigation loop is fixture-verified (scripted transport), not live.
- The pre-existing `test-disk.qcow2` still cannot be unlocked (unknown
passphrase); do not guess or brute-force.
- A real privileged `chown` could not be exercised on this unprivileged host;
verified through the injectable fixer seam and the cross-uid refusal test.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order) ## What this session changed (code)
1. **Installed-VM read-only acceptance of the catalogue** on the booted disk: 1. **Host/target rooting (finding 1).** `Exec::tool_in_target` resolves tools
```sh from the target; `actions::target_spec` is shared by catalogue, chooser and
# serve the static sys first: update paths. Snap is host-only and is reported unavailable (and refused for
cp installer-rs/target/x86_64-unknown-linux-gnu/release/sys /home/dominic/vmlab/serve/ mutation) for an alternate root. Recording-runner tests assert no host
env DISK=/var/tmp/phoebus-vm/disks/<clone>.qcow2 \ `flatpak`/`snap` process is invoked for an alternate root.
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \ 2. **Maintenance revalidation (finding 2).** `resolves_effects` covers
OVMF_VARS=/var/tmp/phoebus-vm/OVMF_VARS.fd \ `Depclean`/`ApplyUpdates`/`CleanCache`; depclean removals are structured
BOOT_CHECKS='... curl .../sys ...; SYS_BIN=/tmp/sys bash .../sys-acceptance.sh ...' \ `PackageEffect`s parsed from `emerge --pretend --depclean`, so a changed
python3 installer/tests/vm/serial-driver.py boot removal set changes the digest and aborts at the execution boundary (and
``` within multi-action plans). Plan aggregation now carries `cleanup` intents.
Expect `SUMMARY PASS=34 FAIL=0` (non-root), including the `search-legacy`, 3. **Exact update effects (finding 3).** `ApplyUpdates` resolves per-source
`list-legacy`, `info-legacy`, `updates-legacy`, `search-no-model-offer`, effects (each Flatpak app by ref, each snap by name) bound to approval and
`search-flag-constraint` and non-root maintenance cases. Already run this revalidated; unrestricted update-all is gone. Lanes with no safe transaction
session on a clone of `verify-disk2.qcow2` (34/34). are refused. Cache cleanup reviews each cleaner's dry run via
2. **Privileged `--broker` acceptance in a seat-providing VM.** The remaining `ResolvedPlan.cleanup`.
unverified path is the actual `pkexec` elevation into 4. **Source constraints (finding 4).** `backend()` classifies Portage-only
`sys --broker --execute-plan` (replacement during authentication, replay actions; `constrain_action` rewrites `DiscoverCandidates`/`ChoosePackage` and
after deleting user plan state, cancellation, a real privileged `chown`). It refuses the cross-lane `InspectInstallation` before querying.
needs a graphical Polkit agent or a passwordless-sudo disposable test image. 5. **Cache-cleanup truthfulness (finding 5).** A cleaner that ran and failed
3. **AI-selected install journey (needs an authorised provider)**: boot the fails the action (partial successes preserved); unavailable is distinct;
installed disk, serve the built `sys` and a 0600 key file, then: the report reaches exit status, assistant response and transaction history.
```sh 6. **Nix inventory (finding 6).** Active-profile `manifest.json` (v1/v2/v3)
sudo sys --ai-provider deepseek --ai-api-key-file /run/phoebus/ai.key \ packages are enumerated with profile/user scope and identity; historical
install <application> generations and realised store paths are separate; unsupported formats and
# and the no-model control in the same run: base profiles are stated explicitly.
PHOEBUS_AI_PROVIDER= sudo sys install <application> 7. **Dependencies (finding 7).** Forward/reverse dependencies use installed VDB
``` `DEPEND`/`RDEPEND`/`BDEPEND` (`qdepends` tree fallback), include
Confirm the model requests evidence, the resolver confirms the candidate, already-satisfied/conditional/versioned deps, never self, and distinguish a
the plan is presented before approval, and the transaction is recorded. No failed query from an empty set.
credential is available here; do not invent one.
4. **Rollback VM acceptance** (`serial-driver.py rollback`) on a cloned Unit tests: `cargo test --workspace` (all green; see CHANGELOG). Build/static
disposable image of the installed system. binaries: `make build` and `make static`; the static `sys` built from the final
5. **NVIDIA hardware acceptance (BLOCKED)**: needs an NVIDIA GPU. tree has SHA-256 `22232a25…` (see the VM log `SYS_SHA`).
6. **Interactive graphical user session** login into Mango / DankMaterialShell
under a physical seat or nested Wayland compositor. ## Verified in disposable VMs (this session)
- **Fresh install** (`fresh-install-1.qcow2`, test.conf `DESKTOP_PROFILE=none`,
`NIX_ENABLED=no`): `===INSTALL-RC=0===`, `NO_SECRET_LEAK`, then a detached
boot: `boot-systemd-running` PASS.
- **Out-of-box Portage permissions:** `/etc/portage` 755,
`repos.conf` 755, `repos.conf/gentoo.conf` 644,
`package.use/phoebus` 644 → non-root `sys search firefox --legacy` returns 3
real results and `sys updates --legacy` reports 10 available. This is the
fresh-install proof that `normalize_config_permissions` works without manual
repair.
- **Acceptance matrix:** `installer/tests/vm/sys-acceptance.sh` `SUMMARY PASS=37
FAIL=0` on both an existing installed clone and the fresh install, including
the new regressions `snap-alternate-root`, `list-nix-legacy`, `deps-legacy`.
- **Privileged mutating journeys** on the fresh install (via root; see blocked
note): install + VDB, remove, history, depclean, cache cleanup (honest
nonzero failure with no cleaner), alternate-root Snap refusal, and a Portage
`apply updates` journey — 7/7 PASS.
- **Rollback acceptance** on a disposable clone: snapshot → controlled change
(root marker + `app-misc/hello`) → `sys undo` → detached boot. The package
database fingerprint returned to the pre-change value, the root marker is
absent, the `/home` marker survives, and systemd is running.
- **Revision:** the installed `sys` on the fresh disk matches the static build
(`SYS_SHA:22232a25…`).
## Blocked / not yet verified
- **pkexec/Polkit `sys --broker --execute-plan` path:** the serial console has no
Polkit agent, so `pkexec` elevation cannot complete. Privileged execution was
exercised by running the same reviewed plan as root (initiator uid 0); the
ledger/replacement/replay logic remains unit-tested and was previously
reviewed. To unblock: a seat-providing/graphical VM with a working Polkit
agent, or a disposable test image with a passwordless-sudo polkit agent.
- **Nix profile journey:** the disposable install sets `NIX_ENABLED=no`, so no
Nix profile exists in the VM. The manifest parser (v1/v2/v3, unsupported
formats, inactive elements, historical generations) is unit-tested with
realistic fixtures. To unblock: install with Nix enabled and a known profile.
- **Snap install/refresh/remove:** no snapd/AppArmor in the minimal image; the
lane journey would need `app-containers/snapd`, AppArmor and network.
- **Managed AppImage acquire/launch/remove** and **custom-ebuild
stage/build/install/remove:** not run in the VM (no AppImage fixture/FUSE and
no build budget); the code paths are unit-tested.
- **Live AI:** no provider credential is present. `sys ask`/guided install and
source-constrained live AI remain unverified; do not invent a credential.
- **NVIDIA:** no GPU.
## Known blockers / risks ## Known blockers / risks
- **A full VM install still takes hours** (base stage ~116 min). Use the already - A full VM install takes ~2 h; the fresh `fresh-install-1.qcow2` is now
installed disposable disk (clone it) for `sys install` journeys rather than a available for future work. `make doctor` reports low host disk space; delete
fresh install. build/VMs deliberately, never a physical disk.
- **No NVIDIA GPU** (and no authorised passthrough). - The pre-existing `test-disk.qcow2` still cannot be unlocked (unknown
- **Snap needs network and AppArmor** for meaningful confinement; the lane passphrase); do not guess or brute-force.
detects confinement honestly. - OpenCode transport concatenates messages; multi-turn AI investigation is
- **AppImage provides no sandbox**; do not describe it as one. best-effort there.
- **Custom ebuilds remain separately reviewed, untrusted artifacts**; the
install workflow never builds one during investigation.
- **OpenCode transport** concatenates messages, so multi-turn investigation is
best-effort there; the direct providers carry the full conversation.
- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git).
## Environment notes ## Next actions (in order)
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo 1. **pkexec/Polkit broker acceptance** in a seat-providing or passwordless-agent
present. `flatpak` and `snap` clients are present on the host (not proof of disposable VM: successful approval, cancelled authentication, plan
the VM lanes). replacement during authentication, replay after deleting user-owned plan
- VM harnesses: `installer/tests/vm/{gui-driver,serial-driver,appliance-driver,live-driver}.py` state, and real ownership of personal settings.
and `sys-acceptance.sh`. `DISK` must be a disposable qcow2; never `/dev/*`. 2. **Nix profile journey** with `NIX_ENABLED=yes` and a profile containing a
- Serve fixtures from `/home/dominic/vmlab/serve` with known package (`nodejs`), verifying inventory, filtering and generations.
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`). 3. **Snap/AppImage/custom-ebuild lane journeys** with benign fixtures and
- The static binaries for the VM: `make static` builds `phoebus-installer` and recorded confinement limitations.
`sys` under `installer-rs/target/x86_64-unknown-linux-gnu/release/`. 4. **Live AI** (`sys ask`, source-constrained discovery, reviewed install,
missing-model/provider-failure) once a credential or local model exists.
## Definition of a good stopping point ## Definition of a good stopping point
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated; - `make test` passes; `docs/STATUS.md`, `docs/CHANGELOG.md` and this file
`docs/HANDOFF.md` updated; committed (via `scripts/agent-commit.sh`) and updated; committed (`scripts/agent-commit.sh`) and pushed
pushed (`scripts/publish.sh`). (`scripts/publish.sh`).

View file

@ -93,9 +93,11 @@ still not VM-verified.
| Personal preferences + alert state (user-owned, system-default precedence) | yes | yes (save/reload/isolation/precedence/failure) | yes (installed VM: saved to user config, exit 0) | no | | Personal preferences + alert state (user-owned, system-default precedence) | yes | yes (save/reload/isolation/precedence/failure) | yes (installed VM: saved to user config, exit 0) | no |
| Personal write ownership (elevated chown, symlink refusal, cross-uid refusal) | yes | yes (ownership-fixer seam + CLI refusal) | no | no | | Personal write ownership (elevated chown, symlink refusal, cross-uid refusal) | yes | yes (ownership-fixer seam + CLI refusal) | no | no |
| Personal preference does not need the root-owned system transaction log | yes | yes (CLI regression: read-only transaction dir) | yes (installed VM acceptance) | n/a | | Personal preference does not need the root-owned system transaction log | yes | yes (CLI regression: read-only transaction dir) | yes (installed VM acceptance) | n/a |
| Installed `sys` acceptance matrix (read-only/failure) | yes | yes | yes (installed VM: `PASS=34 FAIL=0`, catalogue group included) | no | | Installed `sys` acceptance matrix (read-only/failure) | yes | yes | yes (installed VM: `PASS=37 FAIL=0`, catalogue + regression group) | no |
| Portage config readable for non-root queries (`normalize_config_permissions`) | yes | yes (modes + keyring exclusion) | yes (disposable VM: search returns real results after normalisation; fresh-install re-run pending) | no | | Portage config readable for non-root queries (`normalize_config_permissions`) | yes | yes (modes + keyring exclusion) | yes (fresh VM install: 0755/0644 out of the box; non-root `search` returns 3 results, `updates` reports 10) | no |
| Privileged `--broker` plan execution + replay rejection in a VM | yes | yes (privileged entry point) | no (needs root/Polkit agent; unit-tested only) | n/a | | Privileged catalogue mutations (install/remove/depclean/cache/apply updates, alternate-root) | yes | yes (unit) | yes (fresh installed VM via root: 7/7 PASS) | no |
| Rollback acceptance (snapshot -> change -> `sys undo` -> detached verify) | yes | yes | yes (clone: package DB restored, root marker gone, `/home` survives, boot running) | no |
| Privileged `--broker` plan execution + replay rejection in a VM (pkexec path) | yes | yes (privileged entry point) | no (serial console has no Polkit agent; direct privileged execution exercised via root) | n/a |
| Transaction log (outcomes, protective snapshots) | yes | yes | read-only in installed VM; write path needs root | no | | Transaction log (outcomes, protective snapshots) | yes | yes | read-only in installed VM; write path needs root | no |
| Flatpak/Nix bounded typed actions | yes | yes | no | no | | Flatpak/Nix bounded typed actions | yes | yes | no | no |
| Shared hardware-aware source selection (all lanes) | yes | yes | no | no | | Shared hardware-aware source selection (all lanes) | yes | yes | no | no |
@ -114,11 +116,12 @@ still not VM-verified.
| `sys` validation at the execution boundary | yes | yes | no | n/a | | `sys` validation at the execution boundary | yes | yes | no | n/a |
| `sys ask` truthful failure (nonzero, stop, record) | yes | yes | no | n/a | | `sys ask` truthful failure (nonzero, stop, record) | yes | yes | no | n/a |
| Unified package search (`sys search`, all lanes, `--legacy`) | yes | yes (cross-lane; unavailable/failed/empty distinguished; source filter) | no | no | | Unified package search (`sys search`, all lanes, `--legacy`) | yes | yes (cross-lane; unavailable/failed/empty distinguished; source filter) | no | no |
| Installed-package inventory (`sys list`, all lanes, `--legacy`) | yes | yes (VDB/Flatpak/Snap/AppImage; Nix profiles vs store; custom ebuild never double-counted) | no | no | | Installed-package inventory (`sys list`, all lanes, `--legacy`) | yes | yes (VDB/Flatpak/Snap/AppImage; **Nix active-profile packages** vs generations/store; custom ebuild never double-counted) | yes (VM read-only group) | no |
| Package information (`sys info`, `--legacy`) | yes | yes (installed/available, version/deps/size/provenance; ambiguity flagged) | no | no | | Package information (`sys info`, `--legacy`) | yes | yes (installed/available, version/deps/size/provenance; ambiguity flagged) | yes (VM read-only group) | no |
| Cross-source update check/apply (`sys updates`, `apply updates`) | yes | yes (per-source outcomes; manual/project-specific explained) | no | no | | Cross-source update check/apply (`sys updates`, `apply updates`) | yes | yes (exact per-source identities bound to approval + revalidated; manual/project-specific refused) | yes (VM: check read-only; Portage apply journey) | no |
| Catalogue maintenance (`depclean`, `clean cache`, `owners`, `deps`/`rdeps`) | yes | yes (Portage/Nix; unsupported reported explicitly) | no | no | | Catalogue maintenance (`depclean`, `clean cache`, `owners`, `deps`/`rdeps`) | yes | yes (structured depclean effects; cache-cleanup dry-run review + failure propagation; VDB dependency metadata) | yes (VM: depclean + cache-cleanup journeys; deps read-only) | no |
| AI-default catalogue routing (source flags constrain, never bypass) | yes | yes (investigation loop, constraint rewrite/refusal, fallback offers exact `--legacy` command) | no | no | | AI-default catalogue routing (source flags constrain, never bypass) | yes | yes (investigation loop, full backend classification + optional-backend rewrite, fallback offers exact `--legacy` command) | yes (read-only routing cases) | no |
| Alternate-root catalogue/update/maintenance rooting | yes | yes (chroot for Portage/Flatpak/Nix; Snap refused; recording-runner no-host-command tests) | yes (VM: alternate-root Snap refused) | no |
| Service start/stop/restart + flatpak/nix/snapshot commands | yes | yes | no | no | | Service start/stop/restart + flatpak/nix/snapshot commands | yes | yes | no | no |
| Desktop session helpers (DMS bar/launcher/lock/idle) | yes | yes | functional test (stubs) | no | | Desktop session helpers (DMS bar/launcher/lock/idle) | yes | yes | functional test (stubs) | no |
| Mango + DankMaterialShell profile | yes | yes | live VM yes; installed desktop_install yes (174 pkgs) | no | | Mango + DankMaterialShell profile | yes | yes | live VM yes; installed desktop_install yes (174 pkgs) | no |

View file

@ -290,27 +290,40 @@ sys rdeps vim --legacy # reverse dependencies (equery)
custom ebuilds. Entries show source, identity, version, description and custom ebuilds. Entries show source, identity, version, description and
installed status where the backend provides them. installed status where the backend provides them.
- **Inventory** covers the Portage VDB, `flatpak list`, `snap list`, - **Inventory** covers the Portage VDB, `flatpak list`, `snap list`,
Phoebus-managed AppImages and **Nix profiles**. Nix store paths are reported Phoebus-managed AppImages and the **packages of the active Nix profiles**
separately as realised dependencies, never as installed programs. Custom (parsed from each profile's `manifest.json`; historical generations and
ebuilds install through Portage and are listed once, under Portage. realised store paths are reported separately, never as installed programs).
Custom ebuilds install through Portage and are listed once, under Portage.
- **Information** combines installed copies (VDB metadata: version, size, - **Information** combines installed copies (VDB metadata: version, size,
repository, `RDEPEND`) with resolved candidates and policy metadata. When more repository, `DEPEND`/`RDEPEND`/`BDEPEND`) with resolved candidates and policy
than one real package matches, the report is marked **ambiguous** and lists metadata. When more than one real package matches, the report is marked
every match instead of guessing. **ambiguous** and lists every match instead of guessing.
- **Updates** check every supported lane. Applying updates reports a truthful - **Updates** check every supported lane. Applying updates resolves the exact
per-source outcome; AppImage (pinned URL+SHA) and Nix (project/declarative) affected identities per source immediately before execution (each Flatpak app
are explained as manual/project-specific and are never reported as updated. A by ref, each snap by name) and re-checks the reviewed effect set at the
source that was attempted and failed fails the whole action while the report execution boundary; a changed set aborts as a stale plan. AppImage (pinned
still shows the sources that succeeded. Background **preparation** URL+SHA) and Nix (project/declarative) are refused as a system-level
(`prepare updates`, `what are you compiling`) remains distinct from transaction rather than reported as updated. A source that was attempted and
**activation**. failed fails the whole action while the report still shows the sources that
- **Maintenance**: `depclean` previews its removal set with succeeded. Background **preparation** (`prepare updates`, `what are you
`emerge --pretend --depclean` at review time and refuses when nothing is compiling`) remains distinct from **activation**.
selected; it preserves config files and user data. `clean cache` uses - **Maintenance**: `depclean` records its removal set as **structured package
`eclean-dist`/`eclean-pkg` (Portage) or `nix-store --gc` (Nix) and never effects** (not only prose) from `emerge --pretend --depclean` at review time,
removes an installed package. `package_owners` and `package_dependencies` so a changed removal set is caught before execution; it refuses when the
require `app-portage/portage-utils`/`gentoolkit` and report an explicit selection cannot be established, and preserves config files and user data.
unsupported error when the tool is absent. `clean cache` reviews each cleaner's non-destructive dry run and binds it to
approval; a cleaner that ran and failed propagates as a failed action while
partial successes are preserved, and an unavailable cleaner is reported
distinctly from one that found nothing. `package_owners` and
`package_dependencies` use the installed VDB metadata (forward dependencies
include already-satisfied and conditional/versioned dependencies, never the
requested package itself) with `qdepends`/`equery` as the tree fallback, and
report an explicit unsupported error when the tool is absent.
- **Rooting**: every catalogue, update-check and maintenance command is built
for the *intended target* — directly for `/`, or inside the target chroot for
an alternate root. Snap acts on the running daemon and is therefore reported
unavailable (and refused for mutation) for an alternate root rather than ever
touching the host.
- `sys inspect <service> --legacy` is unchanged: `inspect` always means service - `sys inspect <service> --legacy` is unchanged: `inspect` always means service
inspection (use `info` for packages). inspection (use `info` for packages).

View file

@ -542,6 +542,29 @@ Total: 5 packages (2 upgrades, 2 new, 1 uninstall), Size of downloads: 10,240 Ki
assert!(!real.effects.is_empty()); assert!(!real.effects.is_empty());
} }
#[test]
fn cleanup_intents_are_part_of_the_digest_and_material_change() {
let mut a = ResolvedPlan::default();
a.cleanup.push(CleanupEffect {
cleaner: "eclean-dist".into(),
items: vec!["app-misc/one".into()],
unavailable: false,
});
a.recompute_digest();
let mut b = a.clone();
b.cleanup[0].items = vec!["app-misc/two".into()];
b.recompute_digest();
assert_ne!(a.digest, b.digest);
assert!(changed_materially(&a, &b));
assert!(!approval_holds(&a, &b, &[]));
let mut unavailable = a.clone();
unavailable.cleanup[0].unavailable = true;
unavailable.cleanup[0].items.clear();
unavailable.recompute_digest();
assert!(changed_materially(&a, &unavailable));
}
#[test] #[test]
fn render_states_source_binary_and_consequences() { fn render_states_source_binary_and_consequences() {
let plan = parse_emerge_pretend(PRETEND); let plan = parse_emerge_pretend(PRETEND);

View file

@ -1644,6 +1644,26 @@ mod tests {
.any(|e| e.target == "org.gnome.Calc-46" && e.previous.as_deref() == Some("45"))); .any(|e| e.target == "org.gnome.Calc-46" && e.previous.as_deref() == Some("45")));
} }
#[test]
fn alternate_root_flatpak_search_is_chrooted_and_never_host() {
let runner = RecordingRunner::new();
runner.set_response("chroot", ok("org.mozilla.firefox\t128\tFirefox\n"));
let exec = make_exec(runner.clone());
let root = Path::new(&exec.root);
install_fake_tool(root, "flatpak");
let report = search(&exec, root, "firefox", Some(Backend::Flatpak));
assert!(report.sources[0].supported, "{:?}", report.sources[0]);
// No host flatpak/snap process may be invoked for an alternate root.
assert!(
!runner
.recorded()
.iter()
.any(|s| s.program == "flatpak" || s.program == "snap"),
"{:?}",
runner.programs()
);
}
#[test] #[test]
fn apply_updates_never_runs_host_snap_for_an_alternate_root() { fn apply_updates_never_runs_host_snap_for_an_alternate_root() {
let runner = RecordingRunner::new(); let runner = RecordingRunner::new();

View file

@ -442,6 +442,7 @@ fn validate_effect_bindings(plan: &PreparedPlan, steps: &[ResolvedPlan]) -> Resu
}; };
for step in steps { for step in steps {
combined.effects.extend(step.effects.clone()); combined.effects.extend(step.effects.clone());
combined.cleanup.extend(step.cleanup.clone());
combined.consequences.extend(step.consequences.clone()); combined.consequences.extend(step.consequences.clone());
} }
combined.recompute_digest(); combined.recompute_digest();
@ -1303,6 +1304,7 @@ pub fn plan_general(
eff.recompute_digest(); eff.recompute_digest();
if eff.established { if eff.established {
combined_effects.effects.extend(eff.effects.clone()); combined_effects.effects.extend(eff.effects.clone());
combined_effects.cleanup.extend(eff.cleanup.clone());
combined_effects combined_effects
.consequences .consequences
.extend(eff.consequences.clone()); .extend(eff.consequences.clone());
@ -1585,6 +1587,7 @@ fn revalidate_plan_state(exec: &Exec, root: &Path, plan: &PreparedPlan) -> Resul
let eff = actions::resolve_effects(exec, act, root)?; let eff = actions::resolve_effects(exec, act, root)?;
if eff.established { if eff.established {
combined.effects.extend(eff.effects); combined.effects.extend(eff.effects);
combined.cleanup.extend(eff.cleanup);
combined.consequences.extend(eff.consequences); combined.consequences.extend(eff.consequences);
} }
} }
@ -3731,6 +3734,7 @@ mod tests {
}; };
for step in &steps { for step in &steps {
combined.effects.extend(step.effects.clone()); combined.effects.extend(step.effects.clone());
combined.cleanup.extend(step.cleanup.clone());
combined.consequences.extend(step.consequences.clone()); combined.consequences.extend(step.consequences.clone());
} }
combined.recompute_digest(); combined.recompute_digest();
@ -4057,6 +4061,30 @@ mod tests {
); );
} }
#[test]
fn effect_binding_aggregates_cleanup_intents_for_a_clean_cache_step() {
let root = tempdir().unwrap();
let mut step = ResolvedPlan {
established: true,
..Default::default()
};
step.cleanup.push(phoebus_core::effects::CleanupEffect {
cleaner: "eclean-dist".into(),
items: vec!["app-misc/one".into()],
unavailable: false,
});
let plan = general_portage_plan(
"plan-cleanup",
vec![SystemAction::CleanCache { backend: None }],
vec![step],
root.path(),
effective_uid(),
);
let steps = reviewed_steps(&plan).unwrap();
validate_effect_bindings(&plan, &steps)
.expect("cleanup intents must aggregate into the bound plan");
}
#[test] #[test]
fn constrain_action_rewrites_optional_backend_discovery_before_querying() { fn constrain_action_rewrites_optional_backend_discovery_before_querying() {
let discover = constrain_action( let discover = constrain_action(