Snapshot & Rollback System
Relevant source files
The following files were used as context for generating this wiki page:
The Snapshot & Rollback system in Numan provides a mechanism for capturing immutable states of the Numan-managed environment and restoring them when necessary. It is designed to ensure safety during potentially destructive operations such as installs, updates, removals, and activations. By creating a snapshot before mutations, Numan allows users to undo changes and return to a verified, consistent state.
The system encompasses the authoritative lockfile, module-autoload projections (including the exact content of numan.nu), and nupm-import provenance. While state files are snapshotted, package payloads themselves are not duplicated; instead, they are referenced via content-addressed revision hashes to ensure integrity during restoration. Sources: src/state/snapshot.rs:1-8, AGENTS.md:154-157
Architecture and Components
The system is built on time-sortable, collision-resistant UUIDv7 identifiers. Each snapshot is stored in its own directory within the Numan root under state/snapshots/<uuid-v7>/. The architecture relies on atomic writes to a staging directory before final publication to the snapshot store. Sources: src/state/snapshot.rs:10-14, src/state/snapshot.rs:109-112
Data Structures
The core of the system is the SnapshotManifest, which serves as the authoritative header for a committed snapshot.
| Field | Type | Description |
|---|---|---|
id | String | UUIDv7 identifier for the snapshot. |
reason | SnapshotReason | The intent (e.g., pre_mutation, pre_rollback). |
trigger | SnapshotTrigger | The command that triggered the snapshot (e.g., install, update). |
sidecar_digests | SidecarDigests | SHA256 hashes of the sidecar JSON files for integrity verification. |
payload_revisions | BTreeMap<String, String> | Map of package IDs to their computed revision IDs. |
Sources: src/state/snapshot.rs:20-37
Snapshot Lifecycle
Snapshots are created via the create_snapshot function. The process involves capturing the current lockfile, detecting the current Nu identity, capturing the managed autoload projection, and computing revisions for all installed payloads. Sources: src/state/snapshot.rs:118-132
The diagram above shows the atomic publication flow of a snapshot. Sources: src/state/snapshot.rs:118-170
Rollback Mechanism
Rollback is a journaled operation that restores Numan-owned state to an exact snapshot. It operates through dedicated rollback stages in the PendingLifecycle journal, ensuring that interruptions can be recovered by re-running the same rollback. Sources: src/state/rollback.rs:1-13
Pre-Rollback Validation
Before any mutation occurs, the system performs strict precondition checks:
- Payload Verification: Every payload referenced by the snapshot must exist and match the recorded revision hash. Numan refuses to substitute different versions during rollback. Sources: src/state/rollback.rs:36-39, src/state/rollback.rs:77-90
- Root Identity: The snapshot must have been created for the current Numan root, as autoload content contains absolute paths. Sources: src/state/rollback.rs:93-107
- Nu Identity: If an activation graph is present, the current Nu executable hash must match the hash recorded in the snapshot to prevent unvalidated activation graphs. Sources: src/state/rollback.rs:110-132
Rollback Execution Flow
The restoration process follows a specific order of atomic commits to ensure consistency.
This sequence ensures that the rollback itself is reversible by creating a "PreRollback" snapshot before applying changes. Sources: src/state/rollback.rs:152-225
Integrity and Safety
Revision Hashing
Integrity is maintained by comparing computed revision IDs of payload directories. The verify_payloads function ensures that the environment matches the snapshot's state exactly. Sources: src/state/snapshot.rs:265-275
Deletion Safety
Snapshots cannot be deleted if they are referenced by an in-flight transaction (e.g., an interrupted rollback or activation). The system checks both PendingLifecycle and PendingAutoload journals before allowing snapshot removal. Sources: src/state/snapshot.rs:231-252
Managed File Ownership
During rollback, the system only replaces or deletes files that bear the OWNERSHIP_MARKER. This prevents Numan from overwriting foreign files or user-modified autoload scripts. Sources: src/state/rollback.rs:232-235, src/nu/autoload.rs:364-370
Conclusion
The Snapshot & Rollback system provides Numan with high-fidelity state recovery. By combining immutable snapshot storage with journaled restoration, the project guarantees that configuration drift or failed updates can be remediated without data loss or manual intervention. Sources: src/state/rollback.rs:1-13, AGENTS.md:154-157