fix(sys): aggregate cleanup intents into plan binding; record VM acceptance and defect evidence
Some checks are pending
ci / test (push) Waiting to run
Some checks are pending
ci / test (push) Waiting to run
This commit is contained in:
parent
58e0f70879
commit
bab5f413ed
7 changed files with 294 additions and 174 deletions
|
|
@ -3,6 +3,72 @@
|
|||
All notable changes are recorded here. The authoritative history is `git log`;
|
||||
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)
|
||||
|
||||
Adds a complete package catalogue on top of the typed-action architecture. AI is
|
||||
|
|
|
|||
259
docs/HANDOFF.md
259
docs/HANDOFF.md
|
|
@ -3,159 +3,126 @@
|
|||
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.
|
||||
|
||||
- **Last updated:** this session (2026-09-25), completion of the `sys`
|
||||
package-management interface: unified cross-source search, installed-package
|
||||
inventory, package information, consistent per-source update check/apply, and
|
||||
maintenance (depclean/cache/owners/deps), all as validated typed actions
|
||||
shared by the CLI and assistant. AI remains the default for every operation;
|
||||
`--legacy` is the only user-facing opt-in to deterministic handling. A source
|
||||
flag constrains the AI workflow and never bypasses it. See
|
||||
`docs/SYS.md` "Package catalogue" and the CHANGELOG entry.
|
||||
- **Current focus:**
|
||||
1. **New typed actions (`phoebus-core::action`):** `SearchPackages` gained an
|
||||
optional `backend`; added `ListPackages`, `PackageInfo`, `PackageOwners`,
|
||||
`PackageDependencies`, `Depclean`, `CleanCache`, `CheckUpdates`,
|
||||
`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).
|
||||
- **Last updated:** this session (2026-09-25). Follow-up to commit `05d7075`:
|
||||
the seven review findings on the `sys` package-management interface are fixed
|
||||
(host/target rooting, maintenance effect revalidation, exact Flatpak/Snap
|
||||
update effects, complete source constraints, truthful cache-cleanup outcomes,
|
||||
Nix active-profile inventory, VDB-based dependency inspection), with
|
||||
regression tests. The disposable-VM acceptance matrix is extended and the
|
||||
fresh-install / mutating / rollback journeys below were completed.
|
||||
- **Interface contract (unchanged):** every ordinary request uses the AI
|
||||
workflow; only an explicit `--legacy` selects deterministic handling; source
|
||||
flags constrain the AI and never bypass it; a missing model stops the workflow
|
||||
and offers the exact `--legacy` command without executing it; both modes share
|
||||
the same validated typed actions, approval controls and execution layer.
|
||||
|
||||
## Next actions (in order)
|
||||
## What this session changed (code)
|
||||
|
||||
1. **Installed-VM read-only acceptance of the catalogue** on the booted disk:
|
||||
```sh
|
||||
# serve the static sys first:
|
||||
cp installer-rs/target/x86_64-unknown-linux-gnu/release/sys /home/dominic/vmlab/serve/
|
||||
env DISK=/var/tmp/phoebus-vm/disks/<clone>.qcow2 \
|
||||
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
|
||||
OVMF_VARS=/var/tmp/phoebus-vm/OVMF_VARS.fd \
|
||||
BOOT_CHECKS='... curl .../sys ...; SYS_BIN=/tmp/sys bash .../sys-acceptance.sh ...' \
|
||||
python3 installer/tests/vm/serial-driver.py boot
|
||||
```
|
||||
Expect `SUMMARY PASS=34 FAIL=0` (non-root), including the `search-legacy`,
|
||||
`list-legacy`, `info-legacy`, `updates-legacy`, `search-no-model-offer`,
|
||||
`search-flag-constraint` and non-root maintenance cases. Already run this
|
||||
session on a clone of `verify-disk2.qcow2` (34/34).
|
||||
2. **Privileged `--broker` acceptance in a seat-providing VM.** The remaining
|
||||
unverified path is the actual `pkexec` elevation into
|
||||
`sys --broker --execute-plan` (replacement during authentication, replay
|
||||
after deleting user plan state, cancellation, a real privileged `chown`). It
|
||||
needs a graphical Polkit agent or a passwordless-sudo disposable test image.
|
||||
3. **AI-selected install journey (needs an authorised provider)**: boot the
|
||||
installed disk, serve the built `sys` and a 0600 key file, then:
|
||||
```sh
|
||||
sudo sys --ai-provider deepseek --ai-api-key-file /run/phoebus/ai.key \
|
||||
install <application>
|
||||
# and the no-model control in the same run:
|
||||
PHOEBUS_AI_PROVIDER= sudo sys install <application>
|
||||
```
|
||||
Confirm the model requests evidence, the resolver confirms the candidate,
|
||||
the plan is presented before approval, and the transaction is recorded. No
|
||||
credential is available here; do not invent one.
|
||||
4. **Rollback VM acceptance** (`serial-driver.py rollback`) on a cloned
|
||||
disposable image of the installed system.
|
||||
5. **NVIDIA hardware acceptance (BLOCKED)**: needs an NVIDIA GPU.
|
||||
6. **Interactive graphical user session** login into Mango / DankMaterialShell
|
||||
under a physical seat or nested Wayland compositor.
|
||||
1. **Host/target rooting (finding 1).** `Exec::tool_in_target` resolves tools
|
||||
from the target; `actions::target_spec` is shared by catalogue, chooser and
|
||||
update paths. Snap is host-only and is reported unavailable (and refused for
|
||||
mutation) for an alternate root. Recording-runner tests assert no host
|
||||
`flatpak`/`snap` process is invoked for an alternate root.
|
||||
2. **Maintenance revalidation (finding 2).** `resolves_effects` covers
|
||||
`Depclean`/`ApplyUpdates`/`CleanCache`; depclean removals are structured
|
||||
`PackageEffect`s parsed from `emerge --pretend --depclean`, so a changed
|
||||
removal set changes the digest and aborts at the execution boundary (and
|
||||
within multi-action plans). Plan aggregation now carries `cleanup` intents.
|
||||
3. **Exact update effects (finding 3).** `ApplyUpdates` resolves per-source
|
||||
effects (each Flatpak app by ref, each snap by name) bound to approval and
|
||||
revalidated; unrestricted update-all is gone. Lanes with no safe transaction
|
||||
are refused. Cache cleanup reviews each cleaner's dry run via
|
||||
`ResolvedPlan.cleanup`.
|
||||
4. **Source constraints (finding 4).** `backend()` classifies Portage-only
|
||||
actions; `constrain_action` rewrites `DiscoverCandidates`/`ChoosePackage` and
|
||||
refuses the cross-lane `InspectInstallation` before querying.
|
||||
5. **Cache-cleanup truthfulness (finding 5).** A cleaner that ran and failed
|
||||
fails the action (partial successes preserved); unavailable is distinct;
|
||||
the report reaches exit status, assistant response and transaction history.
|
||||
6. **Nix inventory (finding 6).** Active-profile `manifest.json` (v1/v2/v3)
|
||||
packages are enumerated with profile/user scope and identity; historical
|
||||
generations and realised store paths are separate; unsupported formats and
|
||||
base profiles are stated explicitly.
|
||||
7. **Dependencies (finding 7).** Forward/reverse dependencies use installed VDB
|
||||
`DEPEND`/`RDEPEND`/`BDEPEND` (`qdepends` tree fallback), include
|
||||
already-satisfied/conditional/versioned deps, never self, and distinguish a
|
||||
failed query from an empty set.
|
||||
|
||||
Unit tests: `cargo test --workspace` (all green; see CHANGELOG). Build/static
|
||||
binaries: `make build` and `make static`; the static `sys` built from the final
|
||||
tree has SHA-256 `22232a25…` (see the VM log `SYS_SHA`).
|
||||
|
||||
## 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
|
||||
|
||||
- **A full VM install still takes hours** (base stage ~116 min). Use the already
|
||||
installed disposable disk (clone it) for `sys install` journeys rather than a
|
||||
fresh install.
|
||||
- **No NVIDIA GPU** (and no authorised passthrough).
|
||||
- **Snap needs network and AppArmor** for meaningful confinement; the lane
|
||||
detects confinement honestly.
|
||||
- **AppImage provides no sandbox**; do not describe it as one.
|
||||
- **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).
|
||||
- A full VM install takes ~2 h; the fresh `fresh-install-1.qcow2` is now
|
||||
available for future work. `make doctor` reports low host disk space; delete
|
||||
build/VMs deliberately, never a physical disk.
|
||||
- The pre-existing `test-disk.qcow2` still cannot be unlocked (unknown
|
||||
passphrase); do not guess or brute-force.
|
||||
- OpenCode transport concatenates messages; multi-turn AI investigation is
|
||||
best-effort there.
|
||||
|
||||
## Environment notes
|
||||
## Next actions (in order)
|
||||
|
||||
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo
|
||||
present. `flatpak` and `snap` clients are present on the host (not proof of
|
||||
the VM lanes).
|
||||
- VM harnesses: `installer/tests/vm/{gui-driver,serial-driver,appliance-driver,live-driver}.py`
|
||||
and `sys-acceptance.sh`. `DISK` must be a disposable qcow2; never `/dev/*`.
|
||||
- Serve fixtures from `/home/dominic/vmlab/serve` with
|
||||
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`).
|
||||
- The static binaries for the VM: `make static` builds `phoebus-installer` and
|
||||
`sys` under `installer-rs/target/x86_64-unknown-linux-gnu/release/`.
|
||||
1. **pkexec/Polkit broker acceptance** in a seat-providing or passwordless-agent
|
||||
disposable VM: successful approval, cancelled authentication, plan
|
||||
replacement during authentication, replay after deleting user-owned plan
|
||||
state, and real ownership of personal settings.
|
||||
2. **Nix profile journey** with `NIX_ENABLED=yes` and a profile containing a
|
||||
known package (`nodejs`), verifying inventory, filtering and generations.
|
||||
3. **Snap/AppImage/custom-ebuild lane journeys** with benign fixtures and
|
||||
recorded confinement limitations.
|
||||
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
|
||||
|
||||
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated;
|
||||
`docs/HANDOFF.md` updated; committed (via `scripts/agent-commit.sh`) and
|
||||
pushed (`scripts/publish.sh`).
|
||||
- `make test` passes; `docs/STATUS.md`, `docs/CHANGELOG.md` and this file
|
||||
updated; committed (`scripts/agent-commit.sh`) and pushed
|
||||
(`scripts/publish.sh`).
|
||||
|
|
|
|||
|
|
@ -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 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 |
|
||||
| Installed `sys` acceptance matrix (read-only/failure) | yes | yes | yes (installed VM: `PASS=34 FAIL=0`, catalogue group included) | 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 |
|
||||
| Privileged `--broker` plan execution + replay rejection in a VM | yes | yes (privileged entry point) | no (needs root/Polkit agent; unit-tested only) | n/a |
|
||||
| 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 (fresh VM install: 0755/0644 out of the box; non-root `search` returns 3 results, `updates` reports 10) | no |
|
||||
| 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 |
|
||||
| Flatpak/Nix bounded typed actions | 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 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 |
|
||||
| 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 |
|
||||
| Package information (`sys info`, `--legacy`) | yes | yes (installed/available, version/deps/size/provenance; ambiguity flagged) | no | no |
|
||||
| Cross-source update check/apply (`sys updates`, `apply updates`) | yes | yes (per-source outcomes; manual/project-specific explained) | no | no |
|
||||
| Catalogue maintenance (`depclean`, `clean cache`, `owners`, `deps`/`rdeps`) | yes | yes (Portage/Nix; unsupported reported explicitly) | no | no |
|
||||
| AI-default catalogue routing (source flags constrain, never bypass) | yes | yes (investigation loop, constraint rewrite/refusal, fallback offers exact `--legacy` command) | 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) | yes (VM read-only group) | 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 (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, 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 |
|
||||
| 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 |
|
||||
|
|
|
|||
53
docs/SYS.md
53
docs/SYS.md
|
|
@ -290,27 +290,40 @@ sys rdeps vim --legacy # reverse dependencies (equery)
|
|||
custom ebuilds. Entries show source, identity, version, description and
|
||||
installed status where the backend provides them.
|
||||
- **Inventory** covers the Portage VDB, `flatpak list`, `snap list`,
|
||||
Phoebus-managed AppImages and **Nix profiles**. Nix store paths are reported
|
||||
separately as realised dependencies, never as installed programs. Custom
|
||||
ebuilds install through Portage and are listed once, under Portage.
|
||||
Phoebus-managed AppImages and the **packages of the active Nix profiles**
|
||||
(parsed from each profile's `manifest.json`; historical generations and
|
||||
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,
|
||||
repository, `RDEPEND`) with resolved candidates and policy metadata. When more
|
||||
than one real package matches, the report is marked **ambiguous** and lists
|
||||
every match instead of guessing.
|
||||
- **Updates** check every supported lane. Applying updates reports a truthful
|
||||
per-source outcome; AppImage (pinned URL+SHA) and Nix (project/declarative)
|
||||
are explained as manual/project-specific and are never reported as updated. A
|
||||
source that was attempted and failed fails the whole action while the report
|
||||
still shows the sources that succeeded. Background **preparation**
|
||||
(`prepare updates`, `what are you compiling`) remains distinct from
|
||||
**activation**.
|
||||
- **Maintenance**: `depclean` previews its removal set with
|
||||
`emerge --pretend --depclean` at review time and refuses when nothing is
|
||||
selected; it preserves config files and user data. `clean cache` uses
|
||||
`eclean-dist`/`eclean-pkg` (Portage) or `nix-store --gc` (Nix) and never
|
||||
removes an installed package. `package_owners` and `package_dependencies`
|
||||
require `app-portage/portage-utils`/`gentoolkit` and report an explicit
|
||||
unsupported error when the tool is absent.
|
||||
repository, `DEPEND`/`RDEPEND`/`BDEPEND`) with resolved candidates and policy
|
||||
metadata. When more than one real package matches, the report is marked
|
||||
**ambiguous** and lists every match instead of guessing.
|
||||
- **Updates** check every supported lane. Applying updates resolves the exact
|
||||
affected identities per source immediately before execution (each Flatpak app
|
||||
by ref, each snap by name) and re-checks the reviewed effect set at the
|
||||
execution boundary; a changed set aborts as a stale plan. AppImage (pinned
|
||||
URL+SHA) and Nix (project/declarative) are refused as a system-level
|
||||
transaction rather than reported as updated. A source that was attempted and
|
||||
failed fails the whole action while the report still shows the sources that
|
||||
succeeded. Background **preparation** (`prepare updates`, `what are you
|
||||
compiling`) remains distinct from **activation**.
|
||||
- **Maintenance**: `depclean` records its removal set as **structured package
|
||||
effects** (not only prose) from `emerge --pretend --depclean` at review time,
|
||||
so a changed removal set is caught before execution; it refuses when the
|
||||
selection cannot be established, and preserves config files and user data.
|
||||
`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
|
||||
inspection (use `info` for packages).
|
||||
|
||||
|
|
|
|||
|
|
@ -542,6 +542,29 @@ Total: 5 packages (2 upgrades, 2 new, 1 uninstall), Size of downloads: 10,240 Ki
|
|||
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]
|
||||
fn render_states_source_binary_and_consequences() {
|
||||
let plan = parse_emerge_pretend(PRETEND);
|
||||
|
|
|
|||
|
|
@ -1644,6 +1644,26 @@ mod tests {
|
|||
.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]
|
||||
fn apply_updates_never_runs_host_snap_for_an_alternate_root() {
|
||||
let runner = RecordingRunner::new();
|
||||
|
|
|
|||
|
|
@ -442,6 +442,7 @@ fn validate_effect_bindings(plan: &PreparedPlan, steps: &[ResolvedPlan]) -> Resu
|
|||
};
|
||||
for step in steps {
|
||||
combined.effects.extend(step.effects.clone());
|
||||
combined.cleanup.extend(step.cleanup.clone());
|
||||
combined.consequences.extend(step.consequences.clone());
|
||||
}
|
||||
combined.recompute_digest();
|
||||
|
|
@ -1303,6 +1304,7 @@ pub fn plan_general(
|
|||
eff.recompute_digest();
|
||||
if eff.established {
|
||||
combined_effects.effects.extend(eff.effects.clone());
|
||||
combined_effects.cleanup.extend(eff.cleanup.clone());
|
||||
combined_effects
|
||||
.consequences
|
||||
.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)?;
|
||||
if eff.established {
|
||||
combined.effects.extend(eff.effects);
|
||||
combined.cleanup.extend(eff.cleanup);
|
||||
combined.consequences.extend(eff.consequences);
|
||||
}
|
||||
}
|
||||
|
|
@ -3731,6 +3734,7 @@ mod tests {
|
|||
};
|
||||
for step in &steps {
|
||||
combined.effects.extend(step.effects.clone());
|
||||
combined.cleanup.extend(step.cleanup.clone());
|
||||
combined.consequences.extend(step.consequences.clone());
|
||||
}
|
||||
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]
|
||||
fn constrain_action_rewrites_optional_backend_discovery_before_querying() {
|
||||
let discover = constrain_action(
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue