Rollback & Transaction Undo

Zoi includes a robust rollback and transaction undo system designed to recover from failed installations or problematic updates. This guide explains the two levels of reversion and the underlying transaction mechanism.

Transaction Undo

Every operation that modifies your Zoi installation (install, uninstall, upgrade) is wrapped in a transaction.

• Transaction Begin: Zoi generates a UUID v7 transaction ID and creates a temporary JSON log in the user state directory under zoi/transactions/.
• Recording Operations: Package install, uninstall, and upgrade operations are recorded with their manifests, including the files listed in those manifests.
• Atomic Commits: If all steps in the operation succeed, Zoi moves the transaction log to its history directory.
• Failure Rollback: If an install, uninstall, or update fails after a transaction starts, Zoi attempts to revert the operations recorded in the current transaction.
• Incomplete Rollback: If any rollback step fails, Zoi retains the active transaction log and returns an error. After correcting the underlying problem, you can retry the rollback instead of losing the recovery record.

Reverting a Transaction

Use zoi transaction undo to revert all operations recorded in a transaction. It defaults to the most recent transaction.

# Undo the most recent transaction
zoi transaction undo

# Undo a specific transaction by ID
zoi transaction undo abc123-def456

# Skip confirmation prompt
zoi transaction undo --yes

When undoing, Zoi reads the transaction log and reverses every operation in order: installs are uninstalled, uninstalls are restored, and upgrades are downgraded to their previous version.

Inspecting Transactions

Before undoing, you can inspect what a transaction contains:

# List recent transactions
zoi transaction list

# Show operations in a specific transaction
zoi transaction show <id>

# List files modified by a transaction
zoi transaction files <id>

Per-Package Rollback

While zoi transaction undo reverts an entire transaction, zoi rollback reverts a single package to its previous version.

# Roll back a package to its previously installed version
zoi rollback @core/curl

# Roll back a specific sub-package
zoi rollback @core/linux:headers

This is useful when you want to undo a single package upgrade without affecting other packages installed in the same transaction.

Zoi keeps the previous version's directory in the store (if rollback_enabled is true in config.yaml). Rolling back swaps the latest symlink and re-links the binaries.

Downgrading to Specific Versions

For jumping back multiple versions, use zoi downgrade:

# Interactive version selection
zoi downgrade @core/curl

This command scans your local installation store, archive cache, and registry metadata to find every version of the package that has ever been on your system. You can then select which version to install.

Limitations and Caveats

While Zoi strives for reliable recovery, there are inherent limitations, particularly regarding external tools.

Native Dependency Limitations

Zoi can install dependencies via over 40 external package managers (APT, Homebrew, Cargo, etc.). However, Zoi cannot guarantee rollbacks for these native dependencies.

• No Snapshotting: Zoi does not snapshot your entire OS. If apt install upgrades a system library, Zoi cannot "undo" that library upgrade.
• Dependency Persistence: If a native package manager is used to fulfill a dependency, Zoi will attempt to uninstall it during a rollback if it was newly added, but it won't revert it to a previous version if it was merely upgraded.
• Side Effects: Scripts run in post_install or pre_upgrade hooks might perform actions (like starting a service or creating a database) that Zoi doesn't know how to reverse automatically.

Manual Cleanup

In rare cases where a transaction log is corrupted (e.g. a power loss during the undo itself), you may need to use zoi doctor to identify broken symlinks or inconsistent records.

Configuration

You can control rollback behavior in your config.yaml:

# Keep previous versions for rollbacks (default: true)
rollback_enabled: true

If disabled, Zoi will delete old versions immediately to save space, making zoi rollback <package> impossible.