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`;
|
All notable changes are recorded here. The authoritative history is `git log`;
|
||||||
this file is the curated, human-readable summary.
|
this file is the curated, human-readable summary.
|
||||||
|
|
||||||
|
## 2026-09-25 — Fix the `sys` catalogue review findings (host/target, revalidation, update effects, Nix inventory, dependencies)
|
||||||
|
|
||||||
|
Follow-up to the package-management interface: seven review findings are fixed,
|
||||||
|
each with regression tests, and the installed-system acceptance matrix is
|
||||||
|
extended and re-run.
|
||||||
|
|
||||||
|
- **Host/target confusion closed (finding 1).** Every catalogue, update-check,
|
||||||
|
information and maintenance query is now built for the *intended target* —
|
||||||
|
directly for `/`, or inside the target chroot for an alternate root. Snap acts
|
||||||
|
on the running daemon and is reported unavailable (and refused for mutation)
|
||||||
|
for an alternate root instead of ever touching the host. Availability checks
|
||||||
|
resolve tools from the target (`Exec::tool_in_target`), so a host Flatpak,
|
||||||
|
`eclean` or `qdepends` cannot leak into a target operation. Recording-runner
|
||||||
|
tests assert alternate-root search/update/cleanup and Snap paths issue no host
|
||||||
|
commands.
|
||||||
|
- **Maintenance revalidation (finding 2).** `resolves_effects` now covers
|
||||||
|
`Depclean`, `ApplyUpdates` and `CleanCache`, so they are re-resolved at the
|
||||||
|
privileged execution boundary and within multi-action plans. Depclean removals
|
||||||
|
are parsed into **structured `PackageEffect`s** (`emerge --pretend
|
||||||
|
--depclean`), so a changed removal set changes the digest and aborts before an
|
||||||
|
unapproved mutation; a regression test proves drift is refused with no
|
||||||
|
destructive command run.
|
||||||
|
- **Exact Flatpak/Snap update effects (finding 3).** `ApplyUpdates` resolves a
|
||||||
|
reviewable per-source plan with the affected identities and versions; each
|
||||||
|
Flatpak app is updated by ref and each snap by name, and the plan is bound to
|
||||||
|
approval and re-checked immediately before execution. Unrestricted update-all
|
||||||
|
is gone. Lanes with no safe system-level transaction (Nix/AppImage/custom
|
||||||
|
ebuild) are refused with a clear limitation. Destructive cache cleanup now
|
||||||
|
reviews each cleaner's non-destructive dry run and binds the item set to
|
||||||
|
approval (`ResolvedPlan.cleanup`), which is part of the digest.
|
||||||
|
- **Complete source constraints (finding 4).** `SystemAction::backend()`
|
||||||
|
classifies Portage-only actions (`UpdateSystem`, `RemovePackage`,
|
||||||
|
`Depclean`, `PrepareUpdates`, `InspectUpdates`, `PackageOwners`,
|
||||||
|
`PackageDependencies`); `constrain_action` rewrites optional-backend discovery
|
||||||
|
and selection (`DiscoverCandidates`, `ChoosePackage`) to the constrained lane
|
||||||
|
*before* querying, and refuses the cross-lane `InspectInstallation`. Unit tests
|
||||||
|
prove a Flatpak-constrained request cannot investigate or mutate
|
||||||
|
Portage/Snap/Nix through any action variant.
|
||||||
|
- **Cache-cleanup truthfulness (finding 5).** Portage cleaner errors are no
|
||||||
|
longer converted to text while the action returns success. A cleaner that ran
|
||||||
|
and failed fails the whole action (with partial successes preserved), an
|
||||||
|
unavailable cleaner is reported distinctly from one that found nothing, and
|
||||||
|
the report reaches the command exit status, assistant response and transaction
|
||||||
|
history.
|
||||||
|
- **Nix inventory (finding 6).** Inventory enumerates the packages of the active
|
||||||
|
Nix profiles from each profile's `manifest.json` (v1/v2/v3), retaining profile
|
||||||
|
and user scope and package identity; historical generations and realised store
|
||||||
|
paths are reported separately. Unsupported manifest formats and base profiles
|
||||||
|
are stated explicitly rather than shown as an empty inventory. Filtering finds
|
||||||
|
a package such as `nodejs` in a supported profile.
|
||||||
|
- **Dependency inspection (finding 7).** Forward and reverse dependencies now
|
||||||
|
come from the authoritative installed VDB metadata
|
||||||
|
(`DEPEND`/`RDEPEND`/`BDEPEND`, with a `qdepends` tree fallback) instead of an
|
||||||
|
`emerge --pretend` merge plan. Already-satisfied, conditional/versioned and
|
||||||
|
blocker dependencies are preserved; the requested package is never its own
|
||||||
|
dependency; a failed query is distinguished from a genuinely empty set.
|
||||||
|
- **Tests:** +28 (core/executor/installer) covering alternate-root chrooting,
|
||||||
|
structured depclean effects and digest drift, exact Flatpak identities, cache
|
||||||
|
cleanup review and failure propagation, constraint rewrite/refusal, Nix
|
||||||
|
manifest parsing, and dependency parsing/inspection. `make test` passes
|
||||||
|
(`cargo test --workspace`).
|
||||||
|
- **VM-verified (disposable installed clone):** the read-only acceptance matrix
|
||||||
|
is extended with `snap-alternate-root`, `list-nix-legacy` and `deps-legacy`,
|
||||||
|
and reports `SUMMARY PASS=37 FAIL=0`. _(Fresh-install and mutating journeys:
|
||||||
|
see `docs/HANDOFF.md` for the current verified/blocked state.)_
|
||||||
|
|
||||||
## 2026-09-25 — Complete the `sys` package-management interface (search/list/info/updates/maintenance)
|
## 2026-09-25 — Complete the `sys` package-management interface (search/list/info/updates/maintenance)
|
||||||
|
|
||||||
Adds a complete package catalogue on top of the typed-action architecture. AI is
|
Adds a complete package catalogue on top of the typed-action architecture. AI is
|
||||||
|
|
|
||||||
259
docs/HANDOFF.md
259
docs/HANDOFF.md
|
|
@ -3,159 +3,126 @@
|
||||||
Rolling note between work sessions. **Update this file before you finish**, then
|
Rolling note between work sessions. **Update this file before you finish**, then
|
||||||
commit it. It should be short and current; use `git log` for detail.
|
commit it. It should be short and current; use `git log` for detail.
|
||||||
|
|
||||||
- **Last updated:** this session (2026-09-25), completion of the `sys`
|
- **Last updated:** this session (2026-09-25). Follow-up to commit `05d7075`:
|
||||||
package-management interface: unified cross-source search, installed-package
|
the seven review findings on the `sys` package-management interface are fixed
|
||||||
inventory, package information, consistent per-source update check/apply, and
|
(host/target rooting, maintenance effect revalidation, exact Flatpak/Snap
|
||||||
maintenance (depclean/cache/owners/deps), all as validated typed actions
|
update effects, complete source constraints, truthful cache-cleanup outcomes,
|
||||||
shared by the CLI and assistant. AI remains the default for every operation;
|
Nix active-profile inventory, VDB-based dependency inspection), with
|
||||||
`--legacy` is the only user-facing opt-in to deterministic handling. A source
|
regression tests. The disposable-VM acceptance matrix is extended and the
|
||||||
flag constrains the AI workflow and never bypasses it. See
|
fresh-install / mutating / rollback journeys below were completed.
|
||||||
`docs/SYS.md` "Package catalogue" and the CHANGELOG entry.
|
- **Interface contract (unchanged):** every ordinary request uses the AI
|
||||||
- **Current focus:**
|
workflow; only an explicit `--legacy` selects deterministic handling; source
|
||||||
1. **New typed actions (`phoebus-core::action`):** `SearchPackages` gained an
|
flags constrain the AI and never bypass it; a missing model stops the workflow
|
||||||
optional `backend`; added `ListPackages`, `PackageInfo`, `PackageOwners`,
|
and offers the exact `--legacy` command without executing it; both modes share
|
||||||
`PackageDependencies`, `Depclean`, `CleanCache`, `CheckUpdates`,
|
the same validated typed actions, approval controls and execution layer.
|
||||||
`ApplyUpdates`. Read-only variants are non-mutating and need no root;
|
|
||||||
`ApplyUpdates`/`Depclean` are High risk (protective snapshot), `CleanCache`
|
|
||||||
Medium.
|
|
||||||
2. **Executor catalogue (`phoebus-executor::query`, `phoebus-core::catalog`):**
|
|
||||||
search/inventory/info across Portage, Flatpak, Snap, managed AppImages, Nix
|
|
||||||
and staged custom ebuilds. Each lane reports unavailable / failed / empty
|
|
||||||
distinctly. Nix profiles are listed; store paths are reported separately as
|
|
||||||
realised dependencies. Custom ebuilds are never double-counted (they appear
|
|
||||||
under Portage). Portage VDB reading (`portage::installed_packages`) and
|
|
||||||
`emerge --search` parsing (`portage::parse_search`) added.
|
|
||||||
3. **Updates + maintenance:** `check_updates` filters the unified overview;
|
|
||||||
`apply_updates` runs each lane and returns a truthful per-source report,
|
|
||||||
failing the action when an attempted source fails; AppImage/Nix are
|
|
||||||
explained as manual/project-specific. `depclean` and Portage `ApplyUpdates`
|
|
||||||
are previewed from `emerge --pretend` at review time and bound by digest.
|
|
||||||
4. **AI-default routing (`phoebus-ai::assistant::run_assistant`):** the general
|
|
||||||
assistant now runs a bounded read-only investigation loop
|
|
||||||
(`kind:"investigate"` / `kind:"plan"`, `parse_step`, `is_general_investigation_action`)
|
|
||||||
before answering. `service::plan_general` supplies the read-only executor,
|
|
||||||
applies the source constraint to investigation requests and the final plan
|
|
||||||
(`constrain_action`: rewrite lane-selectable queries, refuse a foreign
|
|
||||||
lane), and accepts an empty action list as a pure answer. `sys` renders an
|
|
||||||
answer without executing; a missing model prints the exact `--legacy`
|
|
||||||
command.
|
|
||||||
- **Last verified (this session):**
|
|
||||||
- `cargo fmt --all -- --check` clean; `cargo clippy --workspace --all-targets`
|
|
||||||
exits 0 (only pre-existing lints remain).
|
|
||||||
- `cargo test --workspace`: 645 passed, 0 failed (was 602). New coverage
|
|
||||||
includes: catalogue action classification/validation and natural phrases;
|
|
||||||
catalogue report rendering (unavailable/failed/empty, installed/scope);
|
|
||||||
per-lane search/inventory/info with a recording runner; VDB metadata and
|
|
||||||
no-double-count; ambiguity; depclean preview/skip; per-source update
|
|
||||||
failure; forward dependencies; AI step parsing, the general investigation
|
|
||||||
loop, mutating-investigation refusal; `plan_general` investigation/answer,
|
|
||||||
foreign-lane refusal and constraint rewrite; and CLI routing: search/list/
|
|
||||||
info/updates without `--legacy` enter the AI workflow and never run
|
|
||||||
deterministically, a source flag constrains and never bypasses, `--legacy`
|
|
||||||
never contacts a model, read-only catalogue commands need no root and write
|
|
||||||
no transaction.
|
|
||||||
- Host smoke test of `sys search/list/info/updates --legacy` against the live
|
|
||||||
host (real Flatpak inventory and update list rendered).
|
|
||||||
- **Disposable-VM read-only acceptance** (`serial-driver.py boot` on a qcow2
|
|
||||||
clone of the installed disk, `SYS_BIN=/tmp/sys`): `sys-acceptance.sh`
|
|
||||||
reports `SUMMARY PASS=34 FAIL=0`, including `search-legacy`, `list-legacy`,
|
|
||||||
`info-legacy`, `updates-legacy`, `search-no-model-offer`,
|
|
||||||
`search-flag-constraint`, and the non-root maintenance refusals. Found and
|
|
||||||
fixed a real defect: the installed system left `/etc/portage/repos.conf` and
|
|
||||||
`/etc/portage/package.use/phoebus` root-only, so `emerge --search` failed for
|
|
||||||
a normal account. `portage::normalize_config_permissions` (unit-tested,
|
|
||||||
keyring excluded) makes the non-secret Portage config world-readable and
|
|
||||||
runs at config write and at finalize; with the same permissions applied to
|
|
||||||
the clone, `search-legacy` returns real results (3) and `updates-legacy`
|
|
||||||
reports 10 available. The fresh-install re-run is pending (base install is
|
|
||||||
~2 h).
|
|
||||||
- **Not yet verified (BLOCKED):**
|
|
||||||
- **A fresh VM install with the permission fix** (so the catalogue works
|
|
||||||
out of the box) has not been re-run; the base install is ~2 h. The fix is
|
|
||||||
unit-tested and its effect was demonstrated on the disposable clone.
|
|
||||||
- **Mutating catalogue journeys** (`apply updates`, `depclean`, `clean cache`)
|
|
||||||
are not exercised in a VM; they need a disposable installed disk and, for
|
|
||||||
`apply updates`, network.
|
|
||||||
- The privileged `sys --broker --execute-plan` path and replay rejection remain
|
|
||||||
unit-tested only: the serial console has no root access and no Polkit agent
|
|
||||||
(`sudo -n` denied), so `pkexec` elevation cannot complete. A
|
|
||||||
graphical/seat-providing VM or a passwordless-sudo test image is required.
|
|
||||||
- No AI provider credential is present; do not invent one. The general
|
|
||||||
investigation loop is fixture-verified (scripted transport), not live.
|
|
||||||
- The pre-existing `test-disk.qcow2` still cannot be unlocked (unknown
|
|
||||||
passphrase); do not guess or brute-force.
|
|
||||||
- A real privileged `chown` could not be exercised on this unprivileged host;
|
|
||||||
verified through the injectable fixer seam and the cross-uid refusal test.
|
|
||||||
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
|
|
||||||
(remote `origin`, SSH port 2222).
|
|
||||||
|
|
||||||
## Next actions (in order)
|
## What this session changed (code)
|
||||||
|
|
||||||
1. **Installed-VM read-only acceptance of the catalogue** on the booted disk:
|
1. **Host/target rooting (finding 1).** `Exec::tool_in_target` resolves tools
|
||||||
```sh
|
from the target; `actions::target_spec` is shared by catalogue, chooser and
|
||||||
# serve the static sys first:
|
update paths. Snap is host-only and is reported unavailable (and refused for
|
||||||
cp installer-rs/target/x86_64-unknown-linux-gnu/release/sys /home/dominic/vmlab/serve/
|
mutation) for an alternate root. Recording-runner tests assert no host
|
||||||
env DISK=/var/tmp/phoebus-vm/disks/<clone>.qcow2 \
|
`flatpak`/`snap` process is invoked for an alternate root.
|
||||||
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
|
2. **Maintenance revalidation (finding 2).** `resolves_effects` covers
|
||||||
OVMF_VARS=/var/tmp/phoebus-vm/OVMF_VARS.fd \
|
`Depclean`/`ApplyUpdates`/`CleanCache`; depclean removals are structured
|
||||||
BOOT_CHECKS='... curl .../sys ...; SYS_BIN=/tmp/sys bash .../sys-acceptance.sh ...' \
|
`PackageEffect`s parsed from `emerge --pretend --depclean`, so a changed
|
||||||
python3 installer/tests/vm/serial-driver.py boot
|
removal set changes the digest and aborts at the execution boundary (and
|
||||||
```
|
within multi-action plans). Plan aggregation now carries `cleanup` intents.
|
||||||
Expect `SUMMARY PASS=34 FAIL=0` (non-root), including the `search-legacy`,
|
3. **Exact update effects (finding 3).** `ApplyUpdates` resolves per-source
|
||||||
`list-legacy`, `info-legacy`, `updates-legacy`, `search-no-model-offer`,
|
effects (each Flatpak app by ref, each snap by name) bound to approval and
|
||||||
`search-flag-constraint` and non-root maintenance cases. Already run this
|
revalidated; unrestricted update-all is gone. Lanes with no safe transaction
|
||||||
session on a clone of `verify-disk2.qcow2` (34/34).
|
are refused. Cache cleanup reviews each cleaner's dry run via
|
||||||
2. **Privileged `--broker` acceptance in a seat-providing VM.** The remaining
|
`ResolvedPlan.cleanup`.
|
||||||
unverified path is the actual `pkexec` elevation into
|
4. **Source constraints (finding 4).** `backend()` classifies Portage-only
|
||||||
`sys --broker --execute-plan` (replacement during authentication, replay
|
actions; `constrain_action` rewrites `DiscoverCandidates`/`ChoosePackage` and
|
||||||
after deleting user plan state, cancellation, a real privileged `chown`). It
|
refuses the cross-lane `InspectInstallation` before querying.
|
||||||
needs a graphical Polkit agent or a passwordless-sudo disposable test image.
|
5. **Cache-cleanup truthfulness (finding 5).** A cleaner that ran and failed
|
||||||
3. **AI-selected install journey (needs an authorised provider)**: boot the
|
fails the action (partial successes preserved); unavailable is distinct;
|
||||||
installed disk, serve the built `sys` and a 0600 key file, then:
|
the report reaches exit status, assistant response and transaction history.
|
||||||
```sh
|
6. **Nix inventory (finding 6).** Active-profile `manifest.json` (v1/v2/v3)
|
||||||
sudo sys --ai-provider deepseek --ai-api-key-file /run/phoebus/ai.key \
|
packages are enumerated with profile/user scope and identity; historical
|
||||||
install <application>
|
generations and realised store paths are separate; unsupported formats and
|
||||||
# and the no-model control in the same run:
|
base profiles are stated explicitly.
|
||||||
PHOEBUS_AI_PROVIDER= sudo sys install <application>
|
7. **Dependencies (finding 7).** Forward/reverse dependencies use installed VDB
|
||||||
```
|
`DEPEND`/`RDEPEND`/`BDEPEND` (`qdepends` tree fallback), include
|
||||||
Confirm the model requests evidence, the resolver confirms the candidate,
|
already-satisfied/conditional/versioned deps, never self, and distinguish a
|
||||||
the plan is presented before approval, and the transaction is recorded. No
|
failed query from an empty set.
|
||||||
credential is available here; do not invent one.
|
|
||||||
4. **Rollback VM acceptance** (`serial-driver.py rollback`) on a cloned
|
Unit tests: `cargo test --workspace` (all green; see CHANGELOG). Build/static
|
||||||
disposable image of the installed system.
|
binaries: `make build` and `make static`; the static `sys` built from the final
|
||||||
5. **NVIDIA hardware acceptance (BLOCKED)**: needs an NVIDIA GPU.
|
tree has SHA-256 `22232a25…` (see the VM log `SYS_SHA`).
|
||||||
6. **Interactive graphical user session** login into Mango / DankMaterialShell
|
|
||||||
under a physical seat or nested Wayland compositor.
|
## Verified in disposable VMs (this session)
|
||||||
|
|
||||||
|
- **Fresh install** (`fresh-install-1.qcow2`, test.conf `DESKTOP_PROFILE=none`,
|
||||||
|
`NIX_ENABLED=no`): `===INSTALL-RC=0===`, `NO_SECRET_LEAK`, then a detached
|
||||||
|
boot: `boot-systemd-running` PASS.
|
||||||
|
- **Out-of-box Portage permissions:** `/etc/portage` 755,
|
||||||
|
`repos.conf` 755, `repos.conf/gentoo.conf` 644,
|
||||||
|
`package.use/phoebus` 644 → non-root `sys search firefox --legacy` returns 3
|
||||||
|
real results and `sys updates --legacy` reports 10 available. This is the
|
||||||
|
fresh-install proof that `normalize_config_permissions` works without manual
|
||||||
|
repair.
|
||||||
|
- **Acceptance matrix:** `installer/tests/vm/sys-acceptance.sh` `SUMMARY PASS=37
|
||||||
|
FAIL=0` on both an existing installed clone and the fresh install, including
|
||||||
|
the new regressions `snap-alternate-root`, `list-nix-legacy`, `deps-legacy`.
|
||||||
|
- **Privileged mutating journeys** on the fresh install (via root; see blocked
|
||||||
|
note): install + VDB, remove, history, depclean, cache cleanup (honest
|
||||||
|
nonzero failure with no cleaner), alternate-root Snap refusal, and a Portage
|
||||||
|
`apply updates` journey — 7/7 PASS.
|
||||||
|
- **Rollback acceptance** on a disposable clone: snapshot → controlled change
|
||||||
|
(root marker + `app-misc/hello`) → `sys undo` → detached boot. The package
|
||||||
|
database fingerprint returned to the pre-change value, the root marker is
|
||||||
|
absent, the `/home` marker survives, and systemd is running.
|
||||||
|
- **Revision:** the installed `sys` on the fresh disk matches the static build
|
||||||
|
(`SYS_SHA:22232a25…`).
|
||||||
|
|
||||||
|
## Blocked / not yet verified
|
||||||
|
|
||||||
|
- **pkexec/Polkit `sys --broker --execute-plan` path:** the serial console has no
|
||||||
|
Polkit agent, so `pkexec` elevation cannot complete. Privileged execution was
|
||||||
|
exercised by running the same reviewed plan as root (initiator uid 0); the
|
||||||
|
ledger/replacement/replay logic remains unit-tested and was previously
|
||||||
|
reviewed. To unblock: a seat-providing/graphical VM with a working Polkit
|
||||||
|
agent, or a disposable test image with a passwordless-sudo polkit agent.
|
||||||
|
- **Nix profile journey:** the disposable install sets `NIX_ENABLED=no`, so no
|
||||||
|
Nix profile exists in the VM. The manifest parser (v1/v2/v3, unsupported
|
||||||
|
formats, inactive elements, historical generations) is unit-tested with
|
||||||
|
realistic fixtures. To unblock: install with Nix enabled and a known profile.
|
||||||
|
- **Snap install/refresh/remove:** no snapd/AppArmor in the minimal image; the
|
||||||
|
lane journey would need `app-containers/snapd`, AppArmor and network.
|
||||||
|
- **Managed AppImage acquire/launch/remove** and **custom-ebuild
|
||||||
|
stage/build/install/remove:** not run in the VM (no AppImage fixture/FUSE and
|
||||||
|
no build budget); the code paths are unit-tested.
|
||||||
|
- **Live AI:** no provider credential is present. `sys ask`/guided install and
|
||||||
|
source-constrained live AI remain unverified; do not invent a credential.
|
||||||
|
- **NVIDIA:** no GPU.
|
||||||
|
|
||||||
## Known blockers / risks
|
## Known blockers / risks
|
||||||
|
|
||||||
- **A full VM install still takes hours** (base stage ~116 min). Use the already
|
- A full VM install takes ~2 h; the fresh `fresh-install-1.qcow2` is now
|
||||||
installed disposable disk (clone it) for `sys install` journeys rather than a
|
available for future work. `make doctor` reports low host disk space; delete
|
||||||
fresh install.
|
build/VMs deliberately, never a physical disk.
|
||||||
- **No NVIDIA GPU** (and no authorised passthrough).
|
- The pre-existing `test-disk.qcow2` still cannot be unlocked (unknown
|
||||||
- **Snap needs network and AppArmor** for meaningful confinement; the lane
|
passphrase); do not guess or brute-force.
|
||||||
detects confinement honestly.
|
- OpenCode transport concatenates messages; multi-turn AI investigation is
|
||||||
- **AppImage provides no sandbox**; do not describe it as one.
|
best-effort there.
|
||||||
- **Custom ebuilds remain separately reviewed, untrusted artifacts**; the
|
|
||||||
install workflow never builds one during investigation.
|
|
||||||
- **OpenCode transport** concatenates messages, so multi-turn investigation is
|
|
||||||
best-effort there; the direct providers carry the full conversation.
|
|
||||||
- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git).
|
|
||||||
|
|
||||||
## Environment notes
|
## Next actions (in order)
|
||||||
|
|
||||||
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo
|
1. **pkexec/Polkit broker acceptance** in a seat-providing or passwordless-agent
|
||||||
present. `flatpak` and `snap` clients are present on the host (not proof of
|
disposable VM: successful approval, cancelled authentication, plan
|
||||||
the VM lanes).
|
replacement during authentication, replay after deleting user-owned plan
|
||||||
- VM harnesses: `installer/tests/vm/{gui-driver,serial-driver,appliance-driver,live-driver}.py`
|
state, and real ownership of personal settings.
|
||||||
and `sys-acceptance.sh`. `DISK` must be a disposable qcow2; never `/dev/*`.
|
2. **Nix profile journey** with `NIX_ENABLED=yes` and a profile containing a
|
||||||
- Serve fixtures from `/home/dominic/vmlab/serve` with
|
known package (`nodejs`), verifying inventory, filtering and generations.
|
||||||
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`).
|
3. **Snap/AppImage/custom-ebuild lane journeys** with benign fixtures and
|
||||||
- The static binaries for the VM: `make static` builds `phoebus-installer` and
|
recorded confinement limitations.
|
||||||
`sys` under `installer-rs/target/x86_64-unknown-linux-gnu/release/`.
|
4. **Live AI** (`sys ask`, source-constrained discovery, reviewed install,
|
||||||
|
missing-model/provider-failure) once a credential or local model exists.
|
||||||
|
|
||||||
## Definition of a good stopping point
|
## Definition of a good stopping point
|
||||||
|
|
||||||
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated;
|
- `make test` passes; `docs/STATUS.md`, `docs/CHANGELOG.md` and this file
|
||||||
`docs/HANDOFF.md` updated; committed (via `scripts/agent-commit.sh`) and
|
updated; committed (`scripts/agent-commit.sh`) and pushed
|
||||||
pushed (`scripts/publish.sh`).
|
(`scripts/publish.sh`).
|
||||||
|
|
|
||||||
|
|
@ -93,9 +93,11 @@ still not VM-verified.
|
||||||
| Personal preferences + alert state (user-owned, system-default precedence) | yes | yes (save/reload/isolation/precedence/failure) | yes (installed VM: saved to user config, exit 0) | no |
|
| Personal preferences + alert state (user-owned, system-default precedence) | yes | yes (save/reload/isolation/precedence/failure) | yes (installed VM: saved to user config, exit 0) | no |
|
||||||
| Personal write ownership (elevated chown, symlink refusal, cross-uid refusal) | yes | yes (ownership-fixer seam + CLI refusal) | no | no |
|
| Personal write ownership (elevated chown, symlink refusal, cross-uid refusal) | yes | yes (ownership-fixer seam + CLI refusal) | no | no |
|
||||||
| Personal preference does not need the root-owned system transaction log | yes | yes (CLI regression: read-only transaction dir) | yes (installed VM acceptance) | n/a |
|
| Personal preference does not need the root-owned system transaction log | yes | yes (CLI regression: read-only transaction dir) | yes (installed VM acceptance) | n/a |
|
||||||
| Installed `sys` acceptance matrix (read-only/failure) | yes | yes | yes (installed VM: `PASS=34 FAIL=0`, catalogue group included) | no |
|
| Installed `sys` acceptance matrix (read-only/failure) | yes | yes | yes (installed VM: `PASS=37 FAIL=0`, catalogue + regression group) | no |
|
||||||
| Portage config readable for non-root queries (`normalize_config_permissions`) | yes | yes (modes + keyring exclusion) | yes (disposable VM: search returns real results after normalisation; fresh-install re-run pending) | no |
|
| Portage config readable for non-root queries (`normalize_config_permissions`) | yes | yes (modes + keyring exclusion) | yes (fresh VM install: 0755/0644 out of the box; non-root `search` returns 3 results, `updates` reports 10) | no |
|
||||||
| Privileged `--broker` plan execution + replay rejection in a VM | yes | yes (privileged entry point) | no (needs root/Polkit agent; unit-tested only) | n/a |
|
| Privileged catalogue mutations (install/remove/depclean/cache/apply updates, alternate-root) | yes | yes (unit) | yes (fresh installed VM via root: 7/7 PASS) | no |
|
||||||
|
| Rollback acceptance (snapshot -> change -> `sys undo` -> detached verify) | yes | yes | yes (clone: package DB restored, root marker gone, `/home` survives, boot running) | no |
|
||||||
|
| Privileged `--broker` plan execution + replay rejection in a VM (pkexec path) | yes | yes (privileged entry point) | no (serial console has no Polkit agent; direct privileged execution exercised via root) | n/a |
|
||||||
| Transaction log (outcomes, protective snapshots) | yes | yes | read-only in installed VM; write path needs root | no |
|
| Transaction log (outcomes, protective snapshots) | yes | yes | read-only in installed VM; write path needs root | no |
|
||||||
| Flatpak/Nix bounded typed actions | yes | yes | no | no |
|
| Flatpak/Nix bounded typed actions | yes | yes | no | no |
|
||||||
| Shared hardware-aware source selection (all lanes) | yes | yes | no | no |
|
| Shared hardware-aware source selection (all lanes) | yes | yes | no | no |
|
||||||
|
|
@ -114,11 +116,12 @@ still not VM-verified.
|
||||||
| `sys` validation at the execution boundary | yes | yes | no | n/a |
|
| `sys` validation at the execution boundary | yes | yes | no | n/a |
|
||||||
| `sys ask` truthful failure (nonzero, stop, record) | yes | yes | no | n/a |
|
| `sys ask` truthful failure (nonzero, stop, record) | yes | yes | no | n/a |
|
||||||
| Unified package search (`sys search`, all lanes, `--legacy`) | yes | yes (cross-lane; unavailable/failed/empty distinguished; source filter) | no | no |
|
| Unified package search (`sys search`, all lanes, `--legacy`) | yes | yes (cross-lane; unavailable/failed/empty distinguished; source filter) | no | no |
|
||||||
| Installed-package inventory (`sys list`, all lanes, `--legacy`) | yes | yes (VDB/Flatpak/Snap/AppImage; Nix profiles vs store; custom ebuild never double-counted) | no | no |
|
| Installed-package inventory (`sys list`, all lanes, `--legacy`) | yes | yes (VDB/Flatpak/Snap/AppImage; **Nix active-profile packages** vs generations/store; custom ebuild never double-counted) | yes (VM read-only group) | no |
|
||||||
| Package information (`sys info`, `--legacy`) | yes | yes (installed/available, version/deps/size/provenance; ambiguity flagged) | no | no |
|
| Package information (`sys info`, `--legacy`) | yes | yes (installed/available, version/deps/size/provenance; ambiguity flagged) | yes (VM read-only group) | no |
|
||||||
| Cross-source update check/apply (`sys updates`, `apply updates`) | yes | yes (per-source outcomes; manual/project-specific explained) | no | no |
|
| Cross-source update check/apply (`sys updates`, `apply updates`) | yes | yes (exact per-source identities bound to approval + revalidated; manual/project-specific refused) | yes (VM: check read-only; Portage apply journey) | no |
|
||||||
| Catalogue maintenance (`depclean`, `clean cache`, `owners`, `deps`/`rdeps`) | yes | yes (Portage/Nix; unsupported reported explicitly) | no | no |
|
| Catalogue maintenance (`depclean`, `clean cache`, `owners`, `deps`/`rdeps`) | yes | yes (structured depclean effects; cache-cleanup dry-run review + failure propagation; VDB dependency metadata) | yes (VM: depclean + cache-cleanup journeys; deps read-only) | no |
|
||||||
| AI-default catalogue routing (source flags constrain, never bypass) | yes | yes (investigation loop, constraint rewrite/refusal, fallback offers exact `--legacy` command) | no | no |
|
| AI-default catalogue routing (source flags constrain, never bypass) | yes | yes (investigation loop, full backend classification + optional-backend rewrite, fallback offers exact `--legacy` command) | yes (read-only routing cases) | no |
|
||||||
|
| Alternate-root catalogue/update/maintenance rooting | yes | yes (chroot for Portage/Flatpak/Nix; Snap refused; recording-runner no-host-command tests) | yes (VM: alternate-root Snap refused) | no |
|
||||||
| Service start/stop/restart + flatpak/nix/snapshot commands | yes | yes | no | no |
|
| Service start/stop/restart + flatpak/nix/snapshot commands | yes | yes | no | no |
|
||||||
| Desktop session helpers (DMS bar/launcher/lock/idle) | yes | yes | functional test (stubs) | no |
|
| Desktop session helpers (DMS bar/launcher/lock/idle) | yes | yes | functional test (stubs) | no |
|
||||||
| Mango + DankMaterialShell profile | yes | yes | live VM yes; installed desktop_install yes (174 pkgs) | no |
|
| Mango + DankMaterialShell profile | yes | yes | live VM yes; installed desktop_install yes (174 pkgs) | no |
|
||||||
|
|
|
||||||
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
|
custom ebuilds. Entries show source, identity, version, description and
|
||||||
installed status where the backend provides them.
|
installed status where the backend provides them.
|
||||||
- **Inventory** covers the Portage VDB, `flatpak list`, `snap list`,
|
- **Inventory** covers the Portage VDB, `flatpak list`, `snap list`,
|
||||||
Phoebus-managed AppImages and **Nix profiles**. Nix store paths are reported
|
Phoebus-managed AppImages and the **packages of the active Nix profiles**
|
||||||
separately as realised dependencies, never as installed programs. Custom
|
(parsed from each profile's `manifest.json`; historical generations and
|
||||||
ebuilds install through Portage and are listed once, under Portage.
|
realised store paths are reported separately, never as installed programs).
|
||||||
|
Custom ebuilds install through Portage and are listed once, under Portage.
|
||||||
- **Information** combines installed copies (VDB metadata: version, size,
|
- **Information** combines installed copies (VDB metadata: version, size,
|
||||||
repository, `RDEPEND`) with resolved candidates and policy metadata. When more
|
repository, `DEPEND`/`RDEPEND`/`BDEPEND`) with resolved candidates and policy
|
||||||
than one real package matches, the report is marked **ambiguous** and lists
|
metadata. When more than one real package matches, the report is marked
|
||||||
every match instead of guessing.
|
**ambiguous** and lists every match instead of guessing.
|
||||||
- **Updates** check every supported lane. Applying updates reports a truthful
|
- **Updates** check every supported lane. Applying updates resolves the exact
|
||||||
per-source outcome; AppImage (pinned URL+SHA) and Nix (project/declarative)
|
affected identities per source immediately before execution (each Flatpak app
|
||||||
are explained as manual/project-specific and are never reported as updated. A
|
by ref, each snap by name) and re-checks the reviewed effect set at the
|
||||||
source that was attempted and failed fails the whole action while the report
|
execution boundary; a changed set aborts as a stale plan. AppImage (pinned
|
||||||
still shows the sources that succeeded. Background **preparation**
|
URL+SHA) and Nix (project/declarative) are refused as a system-level
|
||||||
(`prepare updates`, `what are you compiling`) remains distinct from
|
transaction rather than reported as updated. A source that was attempted and
|
||||||
**activation**.
|
failed fails the whole action while the report still shows the sources that
|
||||||
- **Maintenance**: `depclean` previews its removal set with
|
succeeded. Background **preparation** (`prepare updates`, `what are you
|
||||||
`emerge --pretend --depclean` at review time and refuses when nothing is
|
compiling`) remains distinct from **activation**.
|
||||||
selected; it preserves config files and user data. `clean cache` uses
|
- **Maintenance**: `depclean` records its removal set as **structured package
|
||||||
`eclean-dist`/`eclean-pkg` (Portage) or `nix-store --gc` (Nix) and never
|
effects** (not only prose) from `emerge --pretend --depclean` at review time,
|
||||||
removes an installed package. `package_owners` and `package_dependencies`
|
so a changed removal set is caught before execution; it refuses when the
|
||||||
require `app-portage/portage-utils`/`gentoolkit` and report an explicit
|
selection cannot be established, and preserves config files and user data.
|
||||||
unsupported error when the tool is absent.
|
`clean cache` reviews each cleaner's non-destructive dry run and binds it to
|
||||||
|
approval; a cleaner that ran and failed propagates as a failed action while
|
||||||
|
partial successes are preserved, and an unavailable cleaner is reported
|
||||||
|
distinctly from one that found nothing. `package_owners` and
|
||||||
|
`package_dependencies` use the installed VDB metadata (forward dependencies
|
||||||
|
include already-satisfied and conditional/versioned dependencies, never the
|
||||||
|
requested package itself) with `qdepends`/`equery` as the tree fallback, and
|
||||||
|
report an explicit unsupported error when the tool is absent.
|
||||||
|
- **Rooting**: every catalogue, update-check and maintenance command is built
|
||||||
|
for the *intended target* — directly for `/`, or inside the target chroot for
|
||||||
|
an alternate root. Snap acts on the running daemon and is therefore reported
|
||||||
|
unavailable (and refused for mutation) for an alternate root rather than ever
|
||||||
|
touching the host.
|
||||||
- `sys inspect <service> --legacy` is unchanged: `inspect` always means service
|
- `sys inspect <service> --legacy` is unchanged: `inspect` always means service
|
||||||
inspection (use `info` for packages).
|
inspection (use `info` for packages).
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -542,6 +542,29 @@ Total: 5 packages (2 upgrades, 2 new, 1 uninstall), Size of downloads: 10,240 Ki
|
||||||
assert!(!real.effects.is_empty());
|
assert!(!real.effects.is_empty());
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn cleanup_intents_are_part_of_the_digest_and_material_change() {
|
||||||
|
let mut a = ResolvedPlan::default();
|
||||||
|
a.cleanup.push(CleanupEffect {
|
||||||
|
cleaner: "eclean-dist".into(),
|
||||||
|
items: vec!["app-misc/one".into()],
|
||||||
|
unavailable: false,
|
||||||
|
});
|
||||||
|
a.recompute_digest();
|
||||||
|
let mut b = a.clone();
|
||||||
|
b.cleanup[0].items = vec!["app-misc/two".into()];
|
||||||
|
b.recompute_digest();
|
||||||
|
assert_ne!(a.digest, b.digest);
|
||||||
|
assert!(changed_materially(&a, &b));
|
||||||
|
assert!(!approval_holds(&a, &b, &[]));
|
||||||
|
|
||||||
|
let mut unavailable = a.clone();
|
||||||
|
unavailable.cleanup[0].unavailable = true;
|
||||||
|
unavailable.cleanup[0].items.clear();
|
||||||
|
unavailable.recompute_digest();
|
||||||
|
assert!(changed_materially(&a, &unavailable));
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn render_states_source_binary_and_consequences() {
|
fn render_states_source_binary_and_consequences() {
|
||||||
let plan = parse_emerge_pretend(PRETEND);
|
let plan = parse_emerge_pretend(PRETEND);
|
||||||
|
|
|
||||||
|
|
@ -1644,6 +1644,26 @@ mod tests {
|
||||||
.any(|e| e.target == "org.gnome.Calc-46" && e.previous.as_deref() == Some("45")));
|
.any(|e| e.target == "org.gnome.Calc-46" && e.previous.as_deref() == Some("45")));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn alternate_root_flatpak_search_is_chrooted_and_never_host() {
|
||||||
|
let runner = RecordingRunner::new();
|
||||||
|
runner.set_response("chroot", ok("org.mozilla.firefox\t128\tFirefox\n"));
|
||||||
|
let exec = make_exec(runner.clone());
|
||||||
|
let root = Path::new(&exec.root);
|
||||||
|
install_fake_tool(root, "flatpak");
|
||||||
|
let report = search(&exec, root, "firefox", Some(Backend::Flatpak));
|
||||||
|
assert!(report.sources[0].supported, "{:?}", report.sources[0]);
|
||||||
|
// No host flatpak/snap process may be invoked for an alternate root.
|
||||||
|
assert!(
|
||||||
|
!runner
|
||||||
|
.recorded()
|
||||||
|
.iter()
|
||||||
|
.any(|s| s.program == "flatpak" || s.program == "snap"),
|
||||||
|
"{:?}",
|
||||||
|
runner.programs()
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn apply_updates_never_runs_host_snap_for_an_alternate_root() {
|
fn apply_updates_never_runs_host_snap_for_an_alternate_root() {
|
||||||
let runner = RecordingRunner::new();
|
let runner = RecordingRunner::new();
|
||||||
|
|
|
||||||
|
|
@ -442,6 +442,7 @@ fn validate_effect_bindings(plan: &PreparedPlan, steps: &[ResolvedPlan]) -> Resu
|
||||||
};
|
};
|
||||||
for step in steps {
|
for step in steps {
|
||||||
combined.effects.extend(step.effects.clone());
|
combined.effects.extend(step.effects.clone());
|
||||||
|
combined.cleanup.extend(step.cleanup.clone());
|
||||||
combined.consequences.extend(step.consequences.clone());
|
combined.consequences.extend(step.consequences.clone());
|
||||||
}
|
}
|
||||||
combined.recompute_digest();
|
combined.recompute_digest();
|
||||||
|
|
@ -1303,6 +1304,7 @@ pub fn plan_general(
|
||||||
eff.recompute_digest();
|
eff.recompute_digest();
|
||||||
if eff.established {
|
if eff.established {
|
||||||
combined_effects.effects.extend(eff.effects.clone());
|
combined_effects.effects.extend(eff.effects.clone());
|
||||||
|
combined_effects.cleanup.extend(eff.cleanup.clone());
|
||||||
combined_effects
|
combined_effects
|
||||||
.consequences
|
.consequences
|
||||||
.extend(eff.consequences.clone());
|
.extend(eff.consequences.clone());
|
||||||
|
|
@ -1585,6 +1587,7 @@ fn revalidate_plan_state(exec: &Exec, root: &Path, plan: &PreparedPlan) -> Resul
|
||||||
let eff = actions::resolve_effects(exec, act, root)?;
|
let eff = actions::resolve_effects(exec, act, root)?;
|
||||||
if eff.established {
|
if eff.established {
|
||||||
combined.effects.extend(eff.effects);
|
combined.effects.extend(eff.effects);
|
||||||
|
combined.cleanup.extend(eff.cleanup);
|
||||||
combined.consequences.extend(eff.consequences);
|
combined.consequences.extend(eff.consequences);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
@ -3731,6 +3734,7 @@ mod tests {
|
||||||
};
|
};
|
||||||
for step in &steps {
|
for step in &steps {
|
||||||
combined.effects.extend(step.effects.clone());
|
combined.effects.extend(step.effects.clone());
|
||||||
|
combined.cleanup.extend(step.cleanup.clone());
|
||||||
combined.consequences.extend(step.consequences.clone());
|
combined.consequences.extend(step.consequences.clone());
|
||||||
}
|
}
|
||||||
combined.recompute_digest();
|
combined.recompute_digest();
|
||||||
|
|
@ -4057,6 +4061,30 @@ mod tests {
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn effect_binding_aggregates_cleanup_intents_for_a_clean_cache_step() {
|
||||||
|
let root = tempdir().unwrap();
|
||||||
|
let mut step = ResolvedPlan {
|
||||||
|
established: true,
|
||||||
|
..Default::default()
|
||||||
|
};
|
||||||
|
step.cleanup.push(phoebus_core::effects::CleanupEffect {
|
||||||
|
cleaner: "eclean-dist".into(),
|
||||||
|
items: vec!["app-misc/one".into()],
|
||||||
|
unavailable: false,
|
||||||
|
});
|
||||||
|
let plan = general_portage_plan(
|
||||||
|
"plan-cleanup",
|
||||||
|
vec![SystemAction::CleanCache { backend: None }],
|
||||||
|
vec![step],
|
||||||
|
root.path(),
|
||||||
|
effective_uid(),
|
||||||
|
);
|
||||||
|
let steps = reviewed_steps(&plan).unwrap();
|
||||||
|
validate_effect_bindings(&plan, &steps)
|
||||||
|
.expect("cleanup intents must aggregate into the bound plan");
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn constrain_action_rewrites_optional_backend_discovery_before_querying() {
|
fn constrain_action_rewrites_optional_backend_discovery_before_querying() {
|
||||||
let discover = constrain_action(
|
let discover = constrain_action(
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue