Compare commits

..

2 commits

10 changed files with 1702 additions and 419 deletions

View file

@ -3,6 +3,61 @@
All notable changes are recorded here. The authoritative history is `git log`;
this file is the curated, human-readable summary.
## 2026-09-25 — Second-round `sys` fixes: safe cleanup previews, exact update transactions, reverse dependencies
Follow-up review found three further confirmed defects; all three are fixed with
regression tests, and the disposable-VM acceptance is extended. This entry
supersedes any earlier claim that every review finding was already fixed.
- **Cache-cleanup preview no longer deletes (finding 1).** `eclean-dist`/
`eclean-pkg` **delete by default**; only `--pretend` previews. The planner now
runs `--pretend --deep` (the same selection policy as the destructive run) and
combines stdout and stderr into a sorted, bound item set. The Nix preview uses
the documented `nix-store --gc --print-dead` (a bare `--gc`, and the
undocumented `--dry-run`, were unsafe assumptions). Tests prove reconciliation
and cancelled approval run no destructive cleaner.
- **Exact Flatpak/Snap update transactions (finding 2).** A reviewed update now
carries a structured `UpdateTransaction`: the full Flatpak ref (from
`remote-ls`) plus installed and remote **full commits** (from `flatpak info`,
because Flatpak's `commit` column is abbreviated), or the snap name plus
old/new revisions and tracking channel. Execution consumes the reviewed
transaction, is pinned (`flatpak update --commit=<commit>`), and revalidates
each source immediately before its mutation — including after an earlier
source has run. A commit republished under an unchanged human version, a newly
appearing update, or a non-exact transaction is refused; a source whose
resolution failed is never re-discovered at execution.
- **Reverse-dependency self-reference (finding 3).** The reverse branch compared
the dependency target with the queried package and dropped exactly the valid
matches. It now excludes only a genuine self-reference (the *dependent* is the
queried package), so installed targets, full and bare names, and
conditional/versioned dependencies are reported.
- **Determinism and execution robustness.** `All selected packages:` removals
are sorted so depclean previews are order-independent (previously a false
"plan changed"); `emerge --depclean` runs with `--ask=n`; plan aggregation
includes `updates`.
- **Tests:** +22 (workspace `cargo test --workspace` green, 661 → 683). New
regressions cover the non-destructive preview, drift/failed/cancelled
cleanup, exact Flatpak identities/commits, Snap revisions, reverse
dependencies, and Nix generation handling.
- **VM-verified (disposable images):** real `eclean` preview/approve/cancel/
drift/failed and `depclean` cancel/approve with history and preserved user
data; real reverse dependencies (`sys-libs/glibc`, `sys-libs/zlib`); a real
Flatpak reviewed update (Portage-installed Flatpak, flathub, downgraded commit,
reviewed update to the reviewed full commit, verified); custom-ebuild
stage/build/install/remove; managed AppImage acquire/list/launch/remove with a
tampered-SHA refusal; a Nix-enabled install with a real `nodejs-slim` profile
(inventory, filtering, generations); and the **non-root `pkexec sys --broker`
path** (cancelled authentication, successful broker execution, replay
rejection) after installing the shipped polkit action and the standard
wheel-admin rule. The read-only acceptance matrix re-run on the final static
`sys` (`dd61c610…`) reports `PASS=38 FAIL=0` (the matrix gained a reverse-
dependency regression).
- **Not completed (see `docs/HANDOFF.md`):** Snap install/refresh/remove (no
snapd in the image; needs `app-containers/snapd`, AppArmor and network); live
AI (a local model was served, but the sandboxed call exceeds the 120 s
transport timeout on CPU); and the distinct recovery boot (the recovery BLS
entry is present; selecting it interactively is not automated).
## 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,

View file

@ -3,126 +3,104 @@
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). 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.
- **Last updated:** this session (2026-09-25), second-round `sys` review fixes.
Follow-up to `d3f676a`. Three further confirmed defects are fixed with
regression tests: unsafe cleanup previews, non-exact Flatpak/Snap update
execution, and reverse-dependency self-reference. `make test` is green
(661 → 683 tests). This corrects the earlier blanket claim that every review
finding was already fixed.
- **Interface contract (unchanged):** ordinary requests use AI; only 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.
## What this session changed (code)
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.
1. **Cleanup previews are non-destructive (finding 1).** `eclean-dist`/
`eclean-pkg` delete by default, so `portage_cleaners` now previews with
`--pretend --deep` (same selection policy as execution) and executes with
`--deep`; the Nix preview uses the documented `nix-store --gc --print-dead`.
Items are read from stdout+stderr, sorted and bound. Tests prove a cleaner
never runs destructively during planning, revalidation or cancelled approval.
2. **Exact Flatpak/Snap update transactions (finding 2).**
`ResolvedPlan.updates` carries `UpdateTransaction`s: full Flatpak ref + full
installed/remote commits (via `flatpak info`, since the `commit` column is
abbreviated), or snap name + old/new revisions + channel. Execution consumes
the reviewed transaction (`add_executable`… `flatpak update --commit=<c>`),
revalidates each source immediately before its mutation, verifies the
resulting commit/revision, and refuses non-exact transactions. A source whose
resolution failed is never re-discovered. `PlanStore` aggregation includes
`updates`.
3. **Reverse dependencies (finding 3).** The reverse branch no longer drops
valid matches; it excludes only a genuine self-reference (the *dependent* is
the queried package).
4. **Determinism.** `All selected packages:` removals are sorted (depclean
previews are now order-independent); `emerge --depclean --ask=n`.
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 `65307d85…` (see the VM log `TEST_SYS_SHA`).
## Verified in disposable VMs
## Verified in disposable VMs (this session)
- **Cache cleanup + depclean (real tools):** `eclean` upstream preview is
non-destructive; `sys clean cache` preview/cancelled/approved/drift/failed all
behave correctly; depclean cancel/approve with transaction history and
preserved `/home`.
- **Reverse dependencies:** `sys-libs/glibc` and `sys-libs/zlib` report real
dependents (conditional/versioned included).
- **Flatpak:** installed via Portage (`sys-apps/flatpak`, enabling
`media-libs/freetype[harfbuzz]`), flathub added, an app installed and
downgraded, then `sys apply updates --flatpak` resolved full ref+commits,
deployed the pinned commit, and verified it.
- **Custom ebuild:** stage → build/install (VDB entry + installed file) →
remove.
- **Managed AppImage:** acquire with pinned SHA-256, list, run the managed ELF,
remove; a placeholder SHA is refused.
- **Nix:** a `NIX_ENABLED=yes` install bootstraps Nix; `nix profile install
nixpkgs#nodejs-slim` into `/nix/var/nix/profiles/profile` is enumerated by
`sys list --nix` and found by `sys list nodejs --nix`, with store paths and
generations reported separately.
- **Non-root `pkexec sys --broker`:** with the shipped polkit action and the
standard wheel-admin rule installed on the disposable image, a wheel user
authenticated through a terminal agent; cancellations changed nothing, the
approved removal returned the broker JSON outcome, and the replay was
rejected. The shipped privilege policy is unchanged.
- **Read-only acceptance:** `installer/tests/vm/sys-acceptance.sh` `PASS=38
FAIL=0` re-run against the final static `sys` (`dd61c610…`), including the new
`rdeps-legacy` reverse-dependency regression.
- **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 final static `sys` (`TEST_SYS_SHA:65307d85…`) was re-fetched
into the fresh VM and the acceptance matrix re-run against it: `PASS=37
FAIL=0`. The installed `/usr/local/bin/sys` from the install-time build was
`SYS_SHA:22232a25…`; the only delta is the cleanup-intent plan-binding fix,
which the read-only matrix does not exercise.
## Not completed / blocked
## 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.
- **Snap install/refresh/remove:** no snapd in the image. Prerequisite:
`app-containers/snapd` + AppArmor + network, installed through the supported
integration. The Snap transaction code is unit-tested only.
- **Live AI:** a local OpenAI-compatible model (`llama-server` + a GGUF model)
was served on the host; the AI workflow reached the model, but the sandboxed
call exceeded the 120 s transport timeout on CPU (`curl` exit 28). Needs a
faster model/GPU or a remote provider credential. Fixture-backed routing and
failure tests pass (`ask-offline`, missing-model offer, source constraint).
- **Recovery boot (distinct from rollback):** the recovery BLS entry is present
and asserted in the rollback acceptance, but booting it interactively was not
automated. Method: select "Phoebus Recovery (known-good snapshot)" in the
systemd-boot menu with no network.
- **Nix re-run flakiness:** a later `sys list --nix` re-run reported the profile
link dangling (the profile store path was gone) and correctly listed no
packages; the first run with a real profile is the positive evidence.
## Known blockers / risks
- 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.
- VM serial login is occasionally flaky; retry the boot when `detached-boot-login`
fails.
- `make doctor` passes (KVM accessible via an ACL). Disk is shared by build and
VM; watch free space.
- The pre-existing `test-disk.qcow2` cannot be unlocked (unknown passphrase); do
not guess or brute-force it.
## Next actions (in order)
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.
1. **Snap lane acceptance** with `app-containers/snapd` (install/refresh/remove,
confinement recorded).
2. **Recovery boot** by selecting the recovery BLS entry with the network down.
3. **Live AI** with a faster local model/GPU or an authorized provider
credential (natural-language discovery, source constraints, reviewed install).
4. **Nix profile GC stability** if the dangling re-run is reproducible.
## Definition of a good stopping point

View file

@ -93,17 +93,19 @@ 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=37 FAIL=0`, catalogue + regression group) | no |
| Installed `sys` acceptance matrix (read-only/failure) | yes | yes | yes (installed VM: `PASS=38 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 |
| Privileged `--broker` plan execution + replay rejection in a VM (pkexec path) | yes | yes (privileged entry point) | yes (non-root `pkexec` with a terminal polkit agent: cancelled auth, broker JSON success, replay rejected; required the shipped policy + wheel-admin rule) | n/a |
| Cache-cleanup preview is non-destructive (real `eclean`/`nix-store`) | yes | yes (preview uses `--pretend --deep` / `--print-dead`; sorted bound items) | yes (real `eclean`: upstream preview, cancelled approval, approved run, drift refusal, failed cleaner; user data preserved) | n/a |
| Reverse-dependency inspection includes installed targets | yes | yes (self-reference compares the dependent, not the target) | yes (real `sys-libs/glibc`, `sys-libs/zlib` dependents) | 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 |
| Snap lane (detect/install/list/remove/refresh/connections) | yes | yes | no | no |
| AppImage lane (import/acquire/integrity/desktop/remove) | yes | yes | no | no |
| Custom ebuild overlay (stage/approve/build/remove) | yes | yes | no | no |
| Snap lane (detect/install/list/remove/refresh/connections) | yes | yes (incl. exact revisions) | no (no snapd in the image; needs `app-containers/snapd`, AppArmor, network) | no |
| AppImage lane (import/acquire/integrity/desktop/remove) | yes | yes | yes (VM: acquire with pinned SHA, list, launch fixture, remove; tampered SHA refused) | no |
| Custom ebuild overlay (stage/approve/build/remove) | yes | yes | yes (VM: stage → build/install → VDB+file present → remove) | no |
| `sys` installed into the target + verified in chroot | yes | yes (unit) | yes (detached boot verified) | no |
| AI-first install workflow (`sys install`, `sys ask`) | yes | yes | explicit-backend journey; AI-selected not run | no |
| Bounded AI investigation (typed read-only evidence) | yes | yes | read-only actions on a booted VM | no |
@ -118,7 +120,8 @@ still not VM-verified.
| 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 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 |
| Cross-source update check/apply (`sys updates`, `apply updates`) | yes | yes (exact per-source transactions with full Flatpak commits/snap revisions, pinned and revalidated; manual/project-specific refused) | Flatpak verified in VM (reviewed ref+commit, pinned update, verified); Snap unit-tested only; Portage verified | no |
| Nix active-profile inventory (`sys list --nix`) | yes | yes (manifest v1/v2/v3; scope; generations vs store) | yes (NIX_ENABLED=yes install: real `nodejs-slim` profile listed and filtered; a re-run correctly reported a dangling profile) | 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 |

View file

@ -298,27 +298,40 @@ sys rdeps vim --legacy # reverse dependencies (equery)
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**.
- **Updates** check every supported lane. Applying a Flatpak or Snap update
**executes exactly the reviewed transaction**: the plan binds the full Flatpak
ref (`app/…/arch/branch`, from `remote-ls`) plus the installed and remote
**full commits** (from `flatpak info`, since Flatpak's `commit` column is
abbreviated), or the snap name plus its old/new revisions and tracking
channel. Execution is pinned (`flatpak update --commit=<commit>`) and the
source is revalidated immediately before its mutation — including after an
earlier source has run — so a commit republished under an unchanged human
version, a newly appearing update, or a change in the active installation
aborts as stale. A source whose resolution failed is never re-discovered and
executed later. `flatpak` and `snap` both require backend prerequisites and
are refused explicitly when they cannot run. 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
`clean cache` reviews each cleaner's real **non-destructive preview**
(`eclean-dist`/`eclean-pkg` delete by default, so the preview passes
`--pretend` with the same `--deep` selection as the destructive run;
`nix-store --gc`'s documented preview is `--print-dead`) and binds the item
set 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.
requested package itself; reverse dependencies exclude only a genuine
self-reference where the *dependent* is the queried package) 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

View file

@ -63,6 +63,55 @@ pub struct CleanupEffect {
pub unavailable: bool,
}
/// A non-Portage package source whose update is a single, reviewable
/// transaction (Flatpak or Snap). Portage updates are represented as
/// [`PackageEffect`]s from `emerge --pretend` instead.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum UpdateSource {
Flatpak,
Snap,
}
impl UpdateSource {
pub fn as_str(self) -> &'static str {
match self {
UpdateSource::Flatpak => "flatpak",
UpdateSource::Snap => "snap",
}
}
}
/// One exact, reviewable update transaction for a non-Portage lane.
///
/// Execution consumes these transactions rather than re-discovering updates,
/// so a changed revision, a newly appearing update, or a different installation
/// cannot be smuggled in after review. `exact` records whether the backend can
/// actually guarantee the reviewed identity and immutable revision; when it is
/// false the source must be refused rather than executed approximately.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct UpdateTransaction {
pub source: UpdateSource,
/// The immutable backend identity: a full Flatpak ref
/// (`app/org.x/x86_64/stable`) or a snap name.
pub identity: String,
/// Human-readable version before the update, when the backend reports it.
pub previous_version: Option<String>,
/// Human-readable version after the update.
pub next_version: String,
/// Immutable revision before the update (Flatpak commit / snap revision).
pub previous_revision: Option<String>,
/// Immutable revision after the update.
pub next_revision: Option<String>,
/// Installation scope (Flatpak `system`/`user`; Snap tracking channel).
pub scope: Option<String>,
/// Material changes the update pulls in beyond the primary identity (for
/// example an updated Flatpak runtime), or a confinement note.
pub related: Vec<String>,
/// The backend can guarantee this exact identity and immutable revision.
pub exact: bool,
}
/// A fully resolved, human-reviewable plan.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
@ -70,6 +119,10 @@ pub struct ResolvedPlan {
pub effects: Vec<PackageEffect>,
/// Destructive cache-cleanup intents, each bound to its reviewed dry run.
pub cleanup: Vec<CleanupEffect>,
/// Exact per-source update transactions (Flatpak/Snap), bound to approval
/// and consumed by execution. Freshly discovered updates are never a
/// substitute for these.
pub updates: Vec<UpdateTransaction>,
pub download_bytes: Option<u64>,
/// A recovery point that will exist before the change (snapshot id).
pub recovery_point: Option<String>,
@ -158,6 +211,31 @@ impl ResolvedPlan {
}
hasher.update(b"\0");
}
// Exact update transactions (identity + immutable revision) are part of
// the approved material change.
for txn in &self.updates {
hasher.update(b"update\0");
hasher.update(txn.source.as_str().as_bytes());
hasher.update(b"\0");
hasher.update(txn.identity.as_bytes());
hasher.update(b"\0");
hasher.update(txn.previous_version.as_deref().unwrap_or("").as_bytes());
hasher.update(b"\0");
hasher.update(txn.next_version.as_bytes());
hasher.update(b"\0");
hasher.update(txn.previous_revision.as_deref().unwrap_or("").as_bytes());
hasher.update(b"\0");
hasher.update(txn.next_revision.as_deref().unwrap_or("").as_bytes());
hasher.update(b"\0");
hasher.update(txn.scope.as_deref().unwrap_or("").as_bytes());
hasher.update(b"\0");
hasher.update([txn.exact as u8]);
for related in &txn.related {
hasher.update(related.as_bytes());
hasher.update(b"\n");
}
hasher.update(b"\0");
}
self.digest = format!("{:x}", hasher.finalize());
}
@ -214,6 +292,33 @@ impl ResolvedPlan {
}
}
}
for txn in &self.updates {
let revisions = match (&txn.previous_revision, &txn.next_revision) {
(Some(prev), Some(next)) => format!(" [{prev} -> {next}]"),
(None, Some(next)) => format!(" [-> {next}]"),
_ => String::new(),
};
let scope = txn
.scope
.as_deref()
.map(|s| format!(" ({s})"))
.unwrap_or_default();
let exact_note = if txn.exact {
""
} else {
" — NOT EXACTLY BINDABLE"
};
out.push_str(&format!(
" [{}] {}{scope} {}{revisions} -> {}{exact_note}\n",
txn.source.as_str(),
txn.identity,
txn.previous_version.as_deref().unwrap_or("?"),
txn.next_version,
));
for related in &txn.related {
out.push_str(&format!(" ~ {related}\n"));
}
}
if let Some(bytes) = self.download_bytes {
out.push_str(&format!(" download: {} MiB\n", bytes / (1024 * 1024)));
}
@ -331,12 +436,18 @@ pub fn parse_emerge_pretend(text: &str) -> ResolvedPlan {
source,
});
}
// `emerge --unmerge --pretend` does not use the `[ebuild ...]` form; it
// lists the packages slated for removal. Parse them so a removal has a
// concrete, reviewable plan instead of being refused as unestablished.
// `emerge --unmerge --pretend`/`--depclean --pretend` do not use the
// `[ebuild ...]` form; they list the packages slated for removal. Parse
// them so a removal has a concrete, reviewable plan instead of being
// refused as unestablished. Portage does not guarantee the order of this
// list, so sort and dedupe it: otherwise two previews of the *same*
// selection would produce different digests and falsely report drift.
for line in text.lines() {
if let Some(rest) = line.trim().strip_prefix("All selected packages:") {
for atom in rest.split_whitespace() {
let mut atoms: Vec<&str> = rest.split_whitespace().collect();
atoms.sort_unstable();
atoms.dedup();
for atom in atoms {
plan.effects.push(PackageEffect {
target: atom.to_string(),
previous: None,
@ -513,6 +624,16 @@ Total: 5 packages (2 upgrades, 2 new, 1 uninstall), Size of downloads: 10,240 Ki
assert_eq!(plan.digest.len(), 64);
}
#[test]
fn depclean_selection_parsing_is_order_independent() {
// Portage does not guarantee the order of `All selected packages`.
let a = parse_emerge_pretend("All selected packages: app-misc/one-1.0 app-misc/two-2.0\n");
let b = parse_emerge_pretend("All selected packages: app-misc/two-2.0 app-misc/one-1.0\n");
assert_eq!(a.effects.len(), 2);
assert_eq!(a.digest, b.digest);
assert!(!changed_materially(&a, &b));
}
#[test]
fn parses_unmerge_pretend_output() {
let text = "\n>>> These are the packages that would be unmerged:\n\n \
@ -565,6 +686,39 @@ Total: 5 packages (2 upgrades, 2 new, 1 uninstall), Size of downloads: 10,240 Ki
assert!(changed_materially(&a, &unavailable));
}
#[test]
fn update_transactions_are_part_of_the_digest_and_material_change() {
let txn = UpdateTransaction {
source: UpdateSource::Flatpak,
identity: "app/org.mozilla.firefox/x86_64/stable".into(),
previous_version: Some("128".into()),
next_version: "129".into(),
previous_revision: Some("OLD".into()),
next_revision: Some("NEW".into()),
scope: Some("system".into()),
related: Vec::new(),
exact: true,
};
let mut a = ResolvedPlan::default();
a.updates.push(txn.clone());
a.recompute_digest();
// A different immutable revision with the *same* human version must be
// a material change.
let mut b = a.clone();
b.updates[0].next_revision = Some("OTHER".into());
b.recompute_digest();
assert_ne!(a.digest, b.digest);
assert!(changed_materially(&a, &b));
assert!(!approval_holds(&a, &b, &[]));
// A loss of exactness is also material.
let mut c = a.clone();
c.updates[0].exact = false;
c.recompute_digest();
assert!(changed_materially(&a, &c));
}
#[test]
fn render_states_source_binary_and_consequences() {
let plan = parse_emerge_pretend(PRETEND);

View file

@ -8,7 +8,7 @@ use std::path::Path;
use phoebus_core::action::SystemAction;
use phoebus_core::effects::{
changed_materially, parse_emerge_pretend, CleanupEffect, EffectKind, EffectSource,
PackageEffect, ResolvedPlan,
PackageEffect, ResolvedPlan, UpdateSource, UpdateTransaction,
};
use phoebus_core::selection::{Backend, Need};
use phoebus_core::transaction::TransactionOutcome;
@ -301,10 +301,51 @@ fn flatpak_available(exec: &Exec, root: &Path) -> bool {
crate::query::flatpak_available(exec, root)
}
/// Exact per-application Flatpak update effects. Each affected application is
/// an identity plus its planned new version, so approval cannot authorize an
/// unrestricted update-all.
fn flatpak_update_effects(exec: &Exec, root: &Path) -> Result<Vec<PackageEffect>> {
/// Split a Flatpak `--columns=` row (tab-separated) or whitespace fallback.
fn flatpak_cols(line: &str) -> Vec<String> {
if line.contains('\t') {
line.split('\t').map(|s| s.trim().to_string()).collect()
} else {
line.split_whitespace().map(|s| s.to_string()).collect()
}
}
/// Parse `flatpak info --system <ref>`: the installed `Version`, the installed
/// `Active commit` and the remote `Latest commit`. Flatpak's `--columns=commit`
/// truncates to 12 characters, so `info` is used for full immutable commits.
pub(crate) fn parse_flatpak_info(text: &str) -> (Option<String>, Option<String>, Option<String>) {
fn nonempty(value: &str) -> Option<String> {
let value = value.trim();
if value.is_empty() {
None
} else {
Some(value.to_string())
}
}
let (mut version, mut active, mut latest) = (None, None, None);
for line in text.lines() {
let t = line.trim();
if let Some(v) = t.strip_prefix("Version:") {
version = nonempty(v);
} else if let Some(v) = t.strip_prefix("Active commit:") {
active = nonempty(v);
} else if let Some(v) = t.strip_prefix("Latest commit:") {
latest = nonempty(v);
}
}
(version, active, latest)
}
/// Resolve the exact Flatpak update transactions for the target.
///
/// `remote-ls` provides the remote refs with updates and their latest version;
/// `flatpak info` supplies the installed and remote full commits. A transaction
/// is `exact` only when both commits are known; otherwise the source is refused
/// rather than approximated.
pub(crate) fn flatpak_update_transactions(
exec: &Exec,
root: &Path,
) -> Result<Vec<UpdateTransaction>> {
if !flatpak_available(exec, root) {
return Err(ExecError::operation(
"sys",
@ -321,8 +362,9 @@ fn flatpak_update_effects(exec: &Exec, root: &Path) -> Result<Vec<PackageEffect>
"flatpak",
&[
"remote-ls".into(),
"--system".into(),
"--updates".into(),
"--columns=application,version,branch".into(),
"--columns=ref,version".into(),
],
))
.map_err(|e| {
@ -342,49 +384,132 @@ fn flatpak_update_effects(exec: &Exec, root: &Path) -> Result<Vec<PackageEffect>
),
));
}
let mut current = std::collections::BTreeMap::new();
if let Ok(list) = exec.runner.execute(&target_spec(
let mut txns = Vec::new();
for line in updates.stdout_lossy().lines() {
if line.trim().is_empty() {
continue;
}
let cols = flatpak_cols(line);
let Some(identity) = cols.first().filter(|s| !s.is_empty()).cloned() else {
continue;
};
// `remote-ls` reports refs with the `app/`/`runtime/` type prefix, which
// is exactly what `flatpak info` and `flatpak update --commit` accept.
let next_version = cols.get(1).cloned().unwrap_or_default();
let info = exec
.runner
.execute(&target_spec(
root,
"sys",
"resolve flatpak updates",
"flatpak",
&["info".into(), "--system".into(), identity.to_string()],
))
.map_err(|e| {
ExecError::operation(
"sys",
"resolve flatpak updates",
format!("flatpak info {identity} could not run: {e}"),
)
})?;
if !info.success {
return Err(ExecError::operation(
"sys",
"resolve flatpak updates",
format!(
"flatpak info {identity} failed: {}",
info.stderr_lossy().trim()
),
));
}
let (installed_version, active, latest) = parse_flatpak_info(&info.stdout_lossy());
txns.push(UpdateTransaction {
source: UpdateSource::Flatpak,
identity,
previous_version: installed_version,
next_version,
previous_revision: active,
next_revision: latest,
scope: Some("system".to_string()),
related: Vec::new(),
exact: false,
});
}
// `remote-ls --system` covers the system installation only. If the user
// installation also has applications, we cannot bind their updates here,
// so refuse the operation rather than approve an incomplete transaction.
let user_apps = exec.runner.execute(&target_spec(
root,
"sys",
"resolve flatpak updates",
"flatpak",
&[
"list".into(),
"--app".into(),
"--columns=application,version".into(),
],
)) {
if list.success {
for line in list.stdout_lossy().lines() {
let mut parts = line.split_whitespace();
if let (Some(id), Some(version)) = (parts.next(), parts.next()) {
current.insert(id.to_string(), version.to_string());
}
}
}
&["list".into(), "--user".into(), "--columns=ref".into()],
));
let user_present =
matches!(&user_apps, Ok(o) if o.success && !o.stdout_lossy().trim().is_empty());
for txn in &mut txns {
txn.exact = txn.next_revision.is_some() && txn.previous_revision.is_some() && !user_present;
}
let mut effects = Vec::new();
for line in updates.stdout_lossy().lines() {
let mut parts = line.split_whitespace();
let (Some(id), Some(new_version)) = (parts.next(), parts.next()) else {
continue;
};
if id.is_empty() || new_version.is_empty() {
continue;
}
effects.push(PackageEffect {
target: format!("{id}-{new_version}"),
previous: current.get(id).cloned(),
kind: EffectKind::Upgrade,
source: EffectSource::Binary,
});
}
Ok(effects)
txns.sort_by(|a, b| a.identity.cmp(&b.identity));
Ok(txns)
}
/// Exact per-snap update effects. Snaps act on the running daemon, so an
/// alternate root is refused before any command is issued.
fn snap_update_effects(exec: &Exec, root: &Path) -> Result<Vec<PackageEffect>> {
/// Parse `snap refresh --list` and `snap list` output into exact update
/// transactions. Columns: `Name Version Rev Tracking Publisher Notes`; the
/// revision is the immutable identity and the tracking channel is the scope.
pub(crate) fn parse_snap_transactions(refresh: &str, installed: &str) -> Vec<UpdateTransaction> {
use std::collections::BTreeMap;
// name -> (version, revision, tracking, notes)
let mut current: BTreeMap<String, (Option<String>, Option<String>, Option<String>, String)> =
BTreeMap::new();
for line in installed.lines().skip(1) {
let cols: Vec<&str> = line.split_whitespace().collect();
if cols.len() < 4 || cols[0].is_empty() {
continue;
}
current.insert(
cols[0].to_string(),
(
Some(cols[1].to_string()),
Some(cols[2].to_string()),
Some(cols[3].to_string()),
cols.get(5..).map(|n| n.join(" ")).unwrap_or_default(),
),
);
}
let mut txns = Vec::new();
for line in refresh.lines().skip(1) {
let cols: Vec<&str> = line.split_whitespace().collect();
if cols.len() < 3 || cols[0].is_empty() {
continue;
}
let name = cols[0].to_string();
let previous = current.get(&name);
let mut related = Vec::new();
if let Some((_, _, _, notes)) = previous {
if !notes.trim().is_empty() {
related.push(format!("notes: {notes}"));
}
}
txns.push(UpdateTransaction {
source: UpdateSource::Snap,
identity: name,
previous_version: previous.and_then(|(v, _, _, _)| v.clone()),
next_version: cols[1].to_string(),
previous_revision: previous.and_then(|(_, r, _, _)| r.clone()),
next_revision: Some(cols[2].to_string()),
scope: Some(cols[3].to_string()),
related,
exact: !cols[2].is_empty(),
});
}
txns.sort_by(|a, b| a.identity.cmp(&b.identity));
txns
}
/// Resolve the exact Snap update transactions. Snaps act on the running
/// daemon, so an alternate root is refused before any command is issued.
pub(crate) fn snap_update_transactions(exec: &Exec, root: &Path) -> Result<Vec<UpdateTransaction>> {
if !is_host_root(root) {
return Err(ExecError::operation(
"sys",
@ -401,42 +526,45 @@ fn snap_update_effects(exec: &Exec, root: &Path) -> Result<Vec<PackageEffect>> {
"snapd is not installed or active",
));
}
let updates = exec.runner.execute(
let refresh = exec.runner.execute(
&CommandSpec::new("sys", "resolve snap updates", "snap").args(["refresh", "--list"]),
)?;
if !updates.success {
if !refresh.success {
return Err(ExecError::operation(
"sys",
"resolve snap updates",
format!(
"snap refresh --list failed: {}",
updates.stderr_lossy().trim()
refresh.stderr_lossy().trim()
),
));
}
let mut current = std::collections::BTreeMap::new();
if let Ok(entries) = snap::list(exec) {
for entry in entries {
current.insert(entry.name, entry.version);
}
let installed = exec
.runner
.execute(&CommandSpec::new("sys", "resolve snap updates", "snap").args(["list"]))?;
if !installed.success {
return Err(ExecError::operation(
"sys",
"resolve snap updates",
format!("snap list failed: {}", installed.stderr_lossy().trim()),
));
}
let mut effects = Vec::new();
for line in updates.stdout_lossy().lines().skip(1) {
let mut parts = line.split_whitespace();
let (Some(name), Some(new_version)) = (parts.next(), parts.next()) else {
continue;
};
if name.is_empty() || new_version.is_empty() {
continue;
}
effects.push(PackageEffect {
target: format!("{name}-{new_version}"),
previous: current.get(name).cloned(),
Ok(parse_snap_transactions(
&refresh.stdout_lossy(),
&installed.stdout_lossy(),
))
}
/// The human-readable `PackageEffect` summary for a set of update transactions.
fn update_effect_summary(txns: &[UpdateTransaction]) -> Vec<PackageEffect> {
txns.iter()
.map(|txn| PackageEffect {
target: format!("{}-{}", txn.identity, txn.next_version),
previous: txn.previous_version.clone(),
kind: EffectKind::Upgrade,
source: EffectSource::Binary,
});
}
Ok(effects)
})
.collect()
}
/// Resolve a reviewable, per-source update plan. Each lane contributes exact
@ -489,16 +617,22 @@ fn resolve_update_effects(
}
plan.consequences.extend(parsed.consequences);
} else if lane == Backend::Flatpak {
match flatpak_update_effects(exec, root) {
Ok(effects) => plan.effects.extend(effects),
match flatpak_update_transactions(exec, root) {
Ok(txns) => {
plan.effects.extend(update_effect_summary(&txns));
plan.updates.extend(txns);
}
Err(e) if backend.is_none() => plan
.consequences
.push(format!("[flatpak] updates could not be resolved: {e}")),
Err(e) => return Err(e),
}
} else if lane == Backend::Snap {
match snap_update_effects(exec, root) {
Ok(effects) => plan.effects.extend(effects),
match snap_update_transactions(exec, root) {
Ok(txns) => {
plan.effects.extend(update_effect_summary(&txns));
plan.updates.extend(txns);
}
Err(e) if backend.is_none() => plan
.consequences
.push(format!("[snap] updates could not be resolved: {e}")),
@ -534,18 +668,53 @@ fn resolve_update_effects(
Ok(plan)
}
/// The cache cleaners for a lane, as `(cleaner, dry-run args, destructive args)`.
/// The cache cleaners for a lane, as `(cleaner, preview args, destructive args)`.
///
/// `eclean-dist`/`eclean-pkg` **delete by default**; only `--pretend` previews
/// (verified against the upstream `gentoolkit` CLI). The preview therefore
/// passes `--pretend` explicitly, and both the preview and the destructive run
/// use the *same* selection policy (`--deep`), so what is reviewed is exactly
/// what is removed.
pub(crate) fn portage_cleaners(root: &Path) -> Vec<(&'static str, Vec<String>, Vec<String>)> {
let mut cleaners = Vec::new();
if crate::exec::tool_in_target(root, "eclean-dist") {
cleaners.push(("eclean-dist", vec![], vec!["-d".to_string()]));
}
if crate::exec::tool_in_target(root, "eclean-pkg") {
cleaners.push(("eclean-pkg", vec![], vec!["-d".to_string()]));
for cleaner in ["eclean-dist", "eclean-pkg"] {
if crate::exec::tool_in_target(root, cleaner) {
cleaners.push((
cleaner,
vec!["--pretend".to_string(), "--deep".to_string()],
vec!["--deep".to_string()],
));
}
}
cleaners
}
/// Collect the items a cleaner reported, from *both* streams.
///
/// The upstream tools do not guarantee which stream the reviewable list lands
/// on, so stdout and stderr are combined; only non-empty, trimmed lines become
/// bound items.
fn cleanup_items(output: &CommandOutput) -> Vec<String> {
let mut text = output.stdout_lossy();
if !output.stderr.is_empty() {
if !text.is_empty() && !text.ends_with('\n') {
text.push('\n');
}
text.push_str(&output.stderr_lossy());
}
let mut items: Vec<String> = text
.lines()
.map(str::trim)
.filter(|l| !l.is_empty())
.map(str::to_string)
.collect();
// The upstream cleaner does not guarantee output order; sort and dedupe so
// two previews of the same selection bind to the same digest.
items.sort();
items.dedup();
items
}
/// Resolve a reviewable cache-cleanup plan from non-destructive dry runs. A
/// cleaner that cannot run is recorded as unavailable, distinct from one that
/// ran and found nothing.
@ -564,26 +733,19 @@ fn resolve_cleanup_effects(
};
for lane in lanes {
if lane.is_portage() {
for (cleaner, dry_args, _) in portage_cleaners(root) {
for (cleaner, preview_args, _) in portage_cleaners(root) {
let out = exec.runner.execute(&target_spec(
root,
"sys",
"resolve cache cleanup",
cleaner,
&dry_args,
&preview_args,
));
match out {
Ok(output) if output.success => {
let items = output
.stdout_lossy()
.lines()
.map(str::trim)
.filter(|l| !l.is_empty())
.map(str::to_string)
.collect();
plan.cleanup.push(CleanupEffect {
cleaner: cleaner.to_string(),
items,
items: cleanup_items(&output),
unavailable: false,
});
}
@ -591,14 +753,14 @@ fn resolve_cleanup_effects(
return Err(ExecError::operation(
"sys",
"resolve cache cleanup",
format!("{cleaner} dry run failed: {}", output.stderr_lossy().trim()),
format!("{cleaner} preview failed: {}", output.stderr_lossy().trim()),
));
}
Err(e) => {
return Err(ExecError::operation(
"sys",
"resolve cache cleanup",
format!("{cleaner} dry run could not run: {e}"),
format!("{cleaner} preview could not run: {e}"),
));
}
}
@ -611,25 +773,21 @@ fn resolve_cleanup_effects(
unavailable: true,
});
} else {
// `nix-store --gc` deletes by default; the documented,
// non-destructive preview is `--print-dead` (the `--dry-run`
// global is not documented for the `--gc` operation).
let out = exec.runner.execute(&target_spec(
root,
"sys",
"resolve cache cleanup",
"/nix/var/nix/profiles/default/bin/nix-store",
&["--gc".into(), "--dry-run".into()],
&["--gc".into(), "--print-dead".into()],
));
match out {
Ok(output) if output.success => {
let items = output
.stdout_lossy()
.lines()
.map(str::trim)
.filter(|l| !l.is_empty())
.map(str::to_string)
.collect();
plan.cleanup.push(CleanupEffect {
cleaner: "nix-store --gc".into(),
items,
items: cleanup_items(&output),
unavailable: false,
});
}
@ -637,14 +795,17 @@ fn resolve_cleanup_effects(
return Err(ExecError::operation(
"sys",
"resolve cache cleanup",
format!("nix-store --gc failed: {}", output.stderr_lossy().trim()),
format!(
"nix-store --gc preview failed: {}",
output.stderr_lossy().trim()
),
));
}
Err(e) => {
return Err(ExecError::operation(
"sys",
"resolve cache cleanup",
format!("nix-store --gc could not run: {e}"),
format!("nix-store --gc preview could not run: {e}"),
));
}
}
@ -677,7 +838,7 @@ pub fn execute_checked(
root: &Path,
approved: Option<&ResolvedPlan>,
) -> Result<ActionOutcome> {
if let Some(approved) = approved {
let current = if let Some(approved) = approved {
let current = resolve_effects(exec, action, root)?;
if changed_materially(approved, &current) {
return Err(ExecError::operation(
@ -691,8 +852,11 @@ pub fn execute_checked(
),
));
}
}
execute(exec, action, auth, root)
Some(current)
} else {
None
};
execute_inner(exec, action, auth, root, current.as_ref())
}
/// The result of running a reviewed multi-action plan.
@ -807,6 +971,21 @@ pub fn execute(
action: &SystemAction,
auth: Option<&DestructiveAuthorization>,
root: &Path,
) -> Result<ActionOutcome> {
execute_inner(exec, action, auth, root, None)
}
/// Execute an action, optionally carrying the reviewed plan through to
/// execution. Actions whose mutation must equal the reviewed transaction
/// (Flatpak/Snap updates, cache cleanup) consume `resolved` instead of
/// re-discovering state; without it they refuse the mutation rather than
/// presenting approximate approval as exact.
pub fn execute_inner(
exec: &Exec,
action: &SystemAction,
auth: Option<&DestructiveAuthorization>,
root: &Path,
resolved: Option<&ResolvedPlan>,
) -> Result<ActionOutcome> {
// The execution boundary validates every action regardless of its source
// (manual phrase, JSON, or AI plan), so an invalid value can never reach a
@ -1290,7 +1469,7 @@ pub fn execute(
crate::query::check_updates(exec, root, *backend).render()
}
SystemAction::ApplyUpdates { backend } => {
crate::query::apply_updates(exec, root, *backend)?
crate::query::apply_updates(exec, root, *backend, resolved)?
}
SystemAction::ListPackages { backend, filter } => {
crate::query::inventory(exec, root, *backend, filter.as_deref()).render()
@ -1303,7 +1482,9 @@ pub fn execute(
crate::query::package_dependencies(exec, root, package, *reverse)?
}
SystemAction::Depclean => crate::query::depclean(exec, root)?,
SystemAction::CleanCache { backend } => crate::query::clean_cache(exec, root, *backend)?,
SystemAction::CleanCache { backend } => {
crate::query::clean_cache(exec, root, *backend, resolved)?
}
SystemAction::CreateSnapshot { operation } => {
let auth = auth.ok_or_else(|| ExecError::NotAuthorized(action.describe()))?;
let source = root.to_string_lossy().to_string();
@ -1960,6 +2141,200 @@ Total: 1 package (1 new), Size of downloads: 512 KiB
assert_eq!(runner.recorded().len(), 1, "{:?}", runner.recorded());
}
fn install_fake_tool(root: &Path, name: &str) {
use std::os::unix::fs::PermissionsExt;
let bin = root.join("usr/bin");
std::fs::create_dir_all(&bin).unwrap();
let tool = bin.join(name);
std::fs::write(&tool, "#!/bin/sh\n").unwrap();
std::fs::set_permissions(&tool, std::fs::Permissions::from_mode(0o755)).unwrap();
}
#[test]
fn cleaner_preview_is_non_destructive_and_matches_execution_policy() {
let root = tempfile::tempdir().unwrap();
install_fake_tool(root.path(), "eclean-dist");
let cleaners = portage_cleaners(root.path());
assert_eq!(cleaners.len(), 1);
let (_, preview, destructive) = &cleaners[0];
// `eclean` deletes by default: the preview must be explicit.
assert!(preview.iter().any(|a| a == "--pretend"), "{preview:?}");
assert!(
!destructive.iter().any(|a| a == "--pretend"),
"the destructive run must not pretend: {destructive:?}"
);
// Same selection policy: the only difference is the preview flag.
let mut selection = preview.clone();
selection.retain(|a| a != "--pretend");
assert_eq!(
&selection, destructive,
"preview policy must match execution"
);
}
#[test]
fn cleanup_items_are_order_independent() {
let mk = |s: &str| CommandOutput {
status: 0,
success: true,
stdout: s.as_bytes().to_vec(),
stderr: Vec::new(),
duration: std::time::Duration::from_millis(1),
};
let a = cleanup_items(&mk("b.tar.gz\na.tar.gz\n"));
let b = cleanup_items(&mk("a.tar.gz\nb.tar.gz\n"));
assert_eq!(a, b);
assert_eq!(a, vec!["a.tar.gz", "b.tar.gz"]);
}
#[test]
fn resolve_cleanup_effects_never_runs_a_destructive_cleaner() {
let runner = RecordingRunner::new();
runner.set_response(
"chroot",
CommandOutput {
status: 0,
success: true,
stdout: b"/var/cache/distfiles/old.tar.gz\n".to_vec(),
stderr: b"Here are the distfiles that would be deleted:\n".to_vec(),
duration: std::time::Duration::from_millis(1),
},
);
let exec = make_exec(runner.clone());
let root = Path::new(&exec.root);
install_fake_tool(root, "eclean-dist");
let plan = resolve_effects(
&exec,
&SystemAction::CleanCache {
backend: Some(Backend::PortageSource),
},
root,
)
.unwrap();
// Items are taken from both streams and bound to the plan.
let items = &plan.cleanup[0].items;
assert!(items.iter().any(|i| i.contains("old.tar.gz")), "{items:?}");
assert!(
items.iter().any(|i| i.contains("would be deleted")),
"{items:?}"
);
// Every invocation was a preview; no destructive `eclean` ran.
for spec in runner.recorded() {
assert!(
spec.args.iter().any(|a| a == "--pretend"),
"planning must only preview: {spec:?}"
);
}
}
#[test]
fn clean_cache_revalidation_only_previews_and_aborts_on_drift() {
// Rank 1: reviewed preview (items X).
let approved_runner = RecordingRunner::new();
approved_runner.set_response(
"chroot",
response("Here are the distfiles that would be deleted:\n/var/cache/old-a.tar.gz\n"),
);
let approved_exec = make_exec(approved_runner);
let approved_root = Path::new(&approved_exec.root);
install_fake_tool(approved_root, "eclean-dist");
let approved = resolve_effects(
&approved_exec,
&SystemAction::CleanCache {
backend: Some(Backend::PortageSource),
},
approved_root,
)
.unwrap();
// Execution-time re-resolution previews a *different* item set.
let runner = RecordingRunner::new();
runner.set_response(
"chroot",
response("Here are the distfiles that would be deleted:\n/var/cache/old-b.tar.gz\n"),
);
let exec = make_exec(runner.clone());
let root = Path::new(&exec.root);
install_fake_tool(root, "eclean-dist");
let err = execute_checked(
&exec,
&SystemAction::CleanCache {
backend: Some(Backend::PortageSource),
},
Some(&auth()),
root,
Some(&approved),
)
.unwrap_err();
assert!(err.to_string().contains("plan changed"), "{err}");
// Only the non-destructive preview ran; the destructive `--deep`-only
// invocation never did.
for spec in runner.recorded() {
assert!(
spec.args.iter().any(|a| a == "--pretend"),
"a destructive cleaner ran during revalidation: {spec:?}"
);
}
}
#[test]
fn clean_cache_without_authorization_runs_no_cleaner() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let root = Path::new(&exec.root);
install_fake_tool(root, "eclean-dist");
let err = execute(
&exec,
&SystemAction::CleanCache {
backend: Some(Backend::PortageSource),
},
None,
root,
)
.unwrap_err();
assert!(matches!(err, ExecError::NotAuthorized(_)));
// A cancelled/unauthorized approval must not touch the cache.
assert!(runner.recorded().is_empty(), "{:?}", runner.recorded());
}
#[test]
fn nix_cleanup_preview_uses_the_documented_print_dead_and_not_gc() {
let runner = RecordingRunner::new();
runner.set_response(
"chroot",
CommandOutput {
status: 0,
success: true,
stdout: b"/nix/store/dead-path-1\n".to_vec(),
stderr: Vec::new(),
duration: std::time::Duration::from_millis(1),
},
);
let exec = make_exec(runner.clone());
let root = Path::new(&exec.root);
// Pretend Nix is installed by creating the pinned store path.
std::fs::create_dir_all(root.join(format!("nix/store/{}", crate::nix::NIX_STORE_NAME)))
.unwrap();
let plan = resolve_effects(
&exec,
&SystemAction::CleanCache {
backend: Some(Backend::Nix),
},
root,
)
.unwrap();
assert_eq!(plan.cleanup[0].cleaner, "nix-store --gc");
assert!(!runner.recorded().is_empty());
for spec in runner.recorded() {
let has_gc = spec.args.iter().any(|a| a == "--gc");
let has_print_dead = spec.args.iter().any(|a| a == "--print-dead");
assert!(
!has_gc || has_print_dead,
"a bare `--gc` deletes; preview must use --print-dead: {spec:?}"
);
}
}
#[test]
fn portage_apply_updates_previews_the_world_plan() {
let runner = RecordingRunner::new();

View file

@ -19,7 +19,7 @@ pub const NIX_URL: &str =
"https://releases.nixos.org/nix/nix-2.24.9/nix-2.24.9-x86_64-linux.tar.xz";
pub const NIX_SHA256: &str = "3c0779e4878d1289cf3fbb158ec5ea9bdf61dfb9b4efac6b3b0b6bec5ba4cf13";
const NIX_TARBALL_DIR: &str = "nix-2.24.9-x86_64-linux";
const NIX_STORE_NAME: &str = "2nhrwv91g6ycpyxvhmvc0xs8p92wp4bk-nix-2.24.9";
pub(crate) const NIX_STORE_NAME: &str = "2nhrwv91g6ycpyxvhmvc0xs8p92wp4bk-nix-2.24.9";
const NIX_BUILD_USERS: u32 = 8;
fn nix_store_bin() -> String {
@ -521,12 +521,20 @@ fn historical_generation_count(root: &Path) -> usize {
let base = target_path(root, "nix/var/nix/profiles");
let mut count = 0;
let mut visit = |dir: &Path| {
// The current generation is the one the active `profile` link points
// at; only the other `profile-N-link` generations are historical.
let active = std::fs::canonicalize(dir.join("profile")).ok();
if let Ok(entries) = std::fs::read_dir(dir) {
for entry in entries.flatten() {
let name = entry.file_name().to_string_lossy().to_string();
if name.starts_with("profile-") && name.ends_with("-link") {
count += 1;
if !(name.starts_with("profile-") && name.ends_with("-link")) {
continue;
}
let target = std::fs::canonicalize(entry.path()).ok();
if active.is_some() && target == active {
continue;
}
count += 1;
}
}
};
@ -749,6 +757,34 @@ mod tests {
.any(|n| n.contains("historical profile generation")));
}
#[test]
fn current_generation_is_not_counted_as_historical() {
let runner = RecordingRunner::new();
let exec = make_exec(runner, false);
let root = Path::new(&exec.root);
let store = root.join("nix/store/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-nodejs-22.11.0");
std::fs::create_dir_all(&store).unwrap();
std::fs::write(store.join("manifest.json"), profile_manifest_v3()).unwrap();
let profiles = root.join("nix/var/nix/profiles");
std::fs::create_dir_all(&profiles).unwrap();
// `profile` points at the current generation, which is a package
// profile (it has a manifest), not a historical generation.
std::os::unix::fs::symlink(&store, profiles.join("profile-1-link")).unwrap();
std::os::unix::fs::symlink("profile-1-link", profiles.join("profile")).unwrap();
let inventory = installed_packages(root);
assert_eq!(inventory.packages.len(), 1);
assert_eq!(inventory.packages[0].profile, "profile");
assert!(
!inventory
.notes
.iter()
.any(|n| n.contains("historical profile generation")),
"{:?}",
inventory.notes
);
}
#[test]
fn installed_packages_reports_unsupported_manifest_formats_explicitly() {
let runner = RecordingRunner::new();

File diff suppressed because it is too large Load diff

View file

@ -443,6 +443,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.updates.extend(step.updates.clone());
combined.consequences.extend(step.consequences.clone());
}
combined.recompute_digest();
@ -1305,6 +1306,7 @@ pub fn plan_general(
if eff.established {
combined_effects.effects.extend(eff.effects.clone());
combined_effects.cleanup.extend(eff.cleanup.clone());
combined_effects.updates.extend(eff.updates.clone());
combined_effects
.consequences
.extend(eff.consequences.clone());
@ -1588,6 +1590,7 @@ fn revalidate_plan_state(exec: &Exec, root: &Path, plan: &PreparedPlan) -> Resul
if eff.established {
combined.effects.extend(eff.effects);
combined.cleanup.extend(eff.cleanup);
combined.updates.extend(eff.updates);
combined.consequences.extend(eff.consequences);
}
}
@ -1874,10 +1877,10 @@ fn execute_claimed(
// `validate_prepared_plan` (install revalidation / installed-copy
// checks); re-resolving them here would see an empty plan and falsely
// report drift.
let mut current = ResolvedPlan::default();
let mut current: Option<ResolvedPlan> = None;
if actions::resolves_effects(action) {
let reviewed = &reviewed_steps[idx];
current = match actions::resolve_effects(exec, action, root) {
let resolved = match actions::resolve_effects(exec, action, root) {
Ok(current) => current,
Err(e) => {
let detail = format!("effect resolution failed for `{described}`: {e}");
@ -1889,7 +1892,7 @@ fn execute_claimed(
continue;
}
};
if !approval_holds(reviewed, &current, &introduced) {
if !approval_holds(reviewed, &resolved, &introduced) {
let detail = format!(
"the reviewed effects for `{described}` changed materially before execution"
);
@ -1900,9 +1903,17 @@ fn execute_claimed(
drift = Some(format!("stale plan: {detail}"));
continue;
}
current = Some(resolved);
}
match actions::execute(exec, action, auth, root) {
// Execution carries the *reviewed* transaction for actions that must
// not re-discover state (Flatpak/Snap updates, cache cleanup).
let carried = if actions::resolves_effects(action) {
Some(&reviewed_steps[idx])
} else {
None
};
match actions::execute_inner(exec, action, auth, root, carried) {
Ok(result) => {
if result.snapshot.is_some() {
snapshot = result.snapshot;
@ -1911,7 +1922,9 @@ fn execute_claimed(
completed.push((described, result.output));
// Packages this approved action installed may legitimately
// appear in a later step's re-resolution.
introduced.extend(current.effects);
if let Some(current) = current {
introduced.extend(current.effects);
}
}
Err(e) => {
let detail = e.to_string();
@ -3735,6 +3748,7 @@ mod tests {
for step in &steps {
combined.effects.extend(step.effects.clone());
combined.cleanup.extend(step.cleanup.clone());
combined.updates.extend(step.updates.clone());
combined.consequences.extend(step.consequences.clone());
}
combined.recompute_digest();
@ -4085,6 +4099,38 @@ mod tests {
.expect("cleanup intents must aggregate into the bound plan");
}
#[test]
fn effect_binding_aggregates_update_transactions() {
let root = tempdir().unwrap();
let mut step = ResolvedPlan {
established: true,
..Default::default()
};
step.updates.push(phoebus_core::effects::UpdateTransaction {
source: phoebus_core::effects::UpdateSource::Flatpak,
identity: "app/org.mozilla.firefox/x86_64/stable".into(),
previous_version: Some("128".into()),
next_version: "129".into(),
previous_revision: Some("OLD".into()),
next_revision: Some("NEW".into()),
scope: Some("system".into()),
related: Vec::new(),
exact: true,
});
let plan = general_portage_plan(
"plan-updates",
vec![SystemAction::ApplyUpdates {
backend: Some(Backend::Flatpak),
}],
vec![step],
root.path(),
effective_uid(),
);
let steps = reviewed_steps(&plan).unwrap();
validate_effect_bindings(&plan, &steps)
.expect("update transactions must aggregate into the bound plan");
}
#[test]
fn constrain_action_rewrites_optional_backend_discovery_before_querying() {
let discover = constrain_action(

View file

@ -185,6 +185,16 @@ elif grep -qi "app-portage/portage-utils\|qdepends\|not installed" "$WORK/deps.e
else
report deps-legacy FAIL "rc=$? $(head -c 200 "$WORK/deps.err" | tr '\n' ' ')"
fi
# Regression: reverse dependencies of an installed library must include its
# dependents (a self-reference bug previously reported none).
"$SYS" --legacy --action \
'{"action":"package_dependencies","package":"sys-libs/glibc","reverse":true}' \
>"$WORK/rdeps.out" 2>"$WORK/rdeps.err"
if grep -q "installed packages depending on sys-libs/glibc" "$WORK/rdeps.out"; then
report rdeps-legacy PASS "$(head -c 140 "$WORK/rdeps.out" | tr '\n' ' ')"
else
report rdeps-legacy FAIL "$(head -c 200 "$WORK/rdeps.out$WORK/rdeps.err" | tr '\n' ' ')"
fi
# A recognizable catalogue command without --legacy must enter the AI workflow
# and must not run deterministically when no model is available.