0030 - Linux package rollback
Status: Implemented (2026-11-18; explicit caller-supplied rollback package staged through the updater, plus an opt-in helper rollback when a package-manager apply fails; Auro never obtains a previous package on its own)
Spec 0027 applies a staged .deb/.rpm and spec 0029 elevates that path. A failed or unwanted
package update still needs an exit. This spec adds an explicit rollback operation for an older
package that the caller already has; it does not invent, download or derive one.
Scope
Updater::stage_rollback_from_pathandUpdater::download_rollbackfor a signed, strictly older manifest and artifact.LinuxPackageInstaller::rollback(&StagedUpdate).PackageRollbackandApplyPlan::with_package_rollbackfor an opt-in automatic rollback.- Helper-side rollback when a
.deb/.rpmapply fails withInstallerFailed. dpkg --force-downgrade -ifor a.deb.rpm -U --oldpackagefor an.rpm.- Reuse of
LinuxElevation::Pkexecand the held-descriptor command path. - Typed
InstallerFailed/ElevationFailedon failure.
Out of scope
- Automatic rollback without a caller-supplied older package.
- Downloading, discovering, repacking or retaining the previous package.
- Deciding whether a downgrade is safe for dependencies or the system.
- Package holds, pinning, channels and downgrade approval policy.
Decisions
D1 - The caller supplies the older package
rollback takes the same StagedUpdate contract as install. The caller must authenticate,
download and stage the older package; the manifest/artifact verification that produced it is the
caller's responsibility. Auro does not query the package manager for a cached package or guess a
version.
The staging side has an explicit rollback path, because the normal updater refuses to stage an older version:
#![allow(unused)] fn main() { impl Updater { pub fn stage_rollback_from_path( &self, manifest: &Manifest, artifact: &Path, ) -> Result<StagedUpdate, UpdateError>; pub fn download_rollback(&self, manifest: &Manifest) -> Result<StagedUpdate, UpdateError>; } }
Both verify the manifest signature, format, platform and artifact size/SHA-256 exactly like
spec 0013, then require offered < running. Equal or newer offers are
NotOlder. This keeps a signed older manifest from being replayed through the normal update path
while still allowing a deliberate rollback.
Rejected: selecting a previous version from the package manager cache. The cache is not an update contract, may contain untrusted local state, and differs between dpkg and rpm. Rejected: using the network inside the installer. Download policy and signature verification belong to the updater, not to the privileged apply step.
D2 - Use the package manager's explicit downgrade flag
| Format | Program | Arguments |
|---|---|---|
.deb | /usr/bin/dpkg | --force-downgrade -i <artifact> |
.rpm | /usr/bin/rpm | -U --oldpackage <artifact> |
The flags are explicit so a rollback is not silently interpreted as a normal upgrade. dpkg's
manual warns that it does not perform dependency checking on downgrades; that risk belongs to the
caller and the package manager, not to an implicit Auro policy.
Rejected: dpkg -i without the downgrade flag. It makes the operation depend on the installed
dpkg version's default and obscures intent. Rejected: removing and reinstalling a package; that
loses configuration and is not a rollback.
D3 - Elevation and failure semantics are unchanged
The rollback path uses the same LinuxElevation::Pkexec held-descriptor command as install.
pkexec codes 126/127 (authorization/execution) are ElevationFailed; a package-manager
failure is InstallerFailed (spec 0029). The operation never
relaunches the app itself.
D4 - Automatic rollback is opt-in and only follows a package-manager failure
ApplyPlan::with_package_rollback attaches an already-staged older package to a
DebPackage/RpmPackage plan. The journal stores the older artifact, its signed manifest and its
pinned key. If the primary apply fails with InstallerFailed, the helper:
- re-verifies the older manifest, artifact size/SHA-256 and host platform;
- requires the older manifest version to be strictly lower than the journal version;
- runs the elevated
rollbackpath (dpkg --force-downgrade/rpm -U --oldpackage); - marks the journal
RolledBackand relaunches the old app without overwriting that state.
It does not roll back on ElevationFailed (the user declined or pkexec failed), a missing or
tampered artifact, a platform mismatch, or any non-package apply. Those are not evidence that the
package manager changed the installation. A rollback failure leaves the journal Failed with both
the apply and rollback diagnostics.
The caller still chooses the target version and supplies the package. Auro does not keep a
package-manager cache, synthesize a .deb/.rpm from installed files, or decide that a downgrade
is dependency-safe. RollbackVersionNotOlder rejects a same/newer "rollback"
(ADR 0021).
Interfaces
#![allow(unused)] fn main() { impl LinuxPackageInstaller { pub fn rollback(&self, staged: &StagedUpdate) -> Result<LinuxPackageKind, UpdateError>; } pub struct PackageRollback { pub artifact: PathBuf, pub manifest: Manifest, pub public_key: PublicKey, } impl ApplyPlan { pub fn with_package_rollback(self, rollback: PackageRollback) -> Self; } impl ApplyJournal { pub fn rollback_artifact(&self) -> Option<&Path>; } }
The method uses the same LinuxElevation policy as install:
let older_staged = updater.stage_rollback_from_path(&older_manifest, &older_package)?;
let installer = auro::update::LinuxPackageInstaller::new().elevated();
let kind = installer.rollback(&older_staged)?;
The snippet is an intended call shape; obtaining and authorizing older_manifest and
older_package is app/release policy. For an automatic retry after a package-manager failure,
attach the same staged package to the plan:
let plan = ApplyPlan::new(
ApplyKind::DebPackage,
staged.path(),
None,
manifest,
updater.public_key(),
)
.with_package_rollback(PackageRollback::new(
older_staged.path(),
older_manifest,
updater.public_key(),
));
Acceptance
.rpmrollback runs/usr/bin/rpm -U --oldpackage <staged>(rollback_rpm_uses_oldpackage)..debrollback runs/usr/bin/dpkg --force-downgrade -i <staged>(rollback_deb_forces_a_downgrade).- Elevated rollback passes the held
/proc/<pid>/fd/<fd>path throughpkexec(elevated_rollback_uses_the_held_descriptor). - A package-manager failure is
InstallerFailedwith the exit code (rollback_reports_package_manager_failure). - A missing staged artifact or unknown extension follows the install contract
(
StagedArtifactMissing/UnsupportedInstaller). stage_rollback_from_pathstages a signed older artifact, reuses a staged file that still verifies, and rejects equal/newer offers withNotOlder(stages_a_signed_older_artifact_for_rollback,rollback_staging_rejects_newer_equal_and_tampered_offers).download_rollbackstages a signed older artifact and refuses a newer one before the network (downloads_a_signed_rollback_artifact,refuses_a_rollback_download_before_the_network).- A journal round-trips the rollback artifact and rejects a rollback plan for a non-package apply
(
round_trips_a_package_rollback_plan,rejects_a_rollback_plan_for_a_non_package_apply). - Helper rollback verification refuses a same/newer version, a wrong platform and a tampered
artifact (
rollback_verification_requires_an_older_verified_package), and an elevated package-manager failure isInstallerFailedso the auto-rollback branch can see it (elevated_package_manager_failure_is_an_installer_failure). cargo fmt --all --check,cargo clippy --workspace --all-targets --locked -- -D warnings,cargo test --workspace --locked, andmdbook build docspass.
Open questions
| Question | Where it settles |
|---|---|
| Automatic rollback with a package obtained by Auro | Package transaction policy; Auro cannot obtain a previous package |
Automatic rollback of AppImage/MSI/.app applies | Platform installer receipts (specs 0014/0025) |
| Retaining or downloading the previous package | Release artifact retention |
| Dependency-safe downgrade and holds | Package-manager policy |
| Journal-driven rollback execution | Apply journal follow-up |