Specify offline recovery for the Gentoo base
This commit is contained in:
Codex
@@ -0,0 +1,53 @@
|
|||||||
|
# Offline Base Recovery Implementation Plan
|
||||||
|
|
||||||
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||||
|
|
||||||
|
**Goal:** Recover Gentoo root, package database, kernel and owned EFI files together
|
||||||
|
while preserving HOME and other systems, using the trusted live ISO.
|
||||||
|
**Architecture:** Offline Btrfs read-only checkpoints and a restartable restore
|
||||||
|
journal outside @root; matching EFI/HydraOS backups; explicit target identities.
|
||||||
|
**Tech Stack:** Python stdlib, Btrfs tools, existing live image and QEMU acceptance.
|
||||||
|
**Spec:** `docs/superpowers/specs/2026-10-13-base-recovery-design.md`
|
||||||
|
|
||||||
|
## Global Constraints
|
||||||
|
|
||||||
|
- No real host devices or existing VM disks may be modified during development.
|
||||||
|
- Only genuine live mode, selected unmounted single-device Btrfs/ESP, explicit UUID.
|
||||||
|
- @home, foreign EFI/BOOT, partition table and firmware state remain unchanged.
|
||||||
|
- Runtime update and full-base checkpoint/recovery remain distinct commands/scopes.
|
||||||
|
- Recovery requires no installed executables/network and retains previous roots.
|
||||||
|
|
||||||
|
## Review Focus
|
||||||
|
|
||||||
|
1. Duplicate/cloned UUIDs or changed PARTUUIDs fail before modifying either target.
|
||||||
|
2. A nested root subvolume or read-write snapshot invalidates the checkpoint contract.
|
||||||
|
3. Interrupted root rename/EFI copy resumes from the durable journal and actual UUIDs.
|
||||||
|
4. Corrupt/path-traversing EFI backups never overwrite foreign files.
|
||||||
|
5. The real VM proves coordinated kernel/package recovery and post-checkpoint HOME.
|
||||||
|
|
||||||
|
## Task 1: Offline command and journal
|
||||||
|
|
||||||
|
**Files:** `hydra/system_recovery.py`, `bin/hydra-system`,
|
||||||
|
`tests/test_system_recovery.py`, `docs/system-recovery.md`.
|
||||||
|
**Consumes:** installer storage.json schema and @root/@home/@snapshots layout.
|
||||||
|
**Produces:** checkpoint/list/restore CLI; root-owned completed metadata and durable
|
||||||
|
restore transaction; module has no import-time mutations and works from live ISO.
|
||||||
|
|
||||||
|
- [ ] Write failing topology/ownership/path/format checks and checkpoint publication tests.
|
||||||
|
- [ ] Implement root/ESP resolution and private mount cleanup, read-only planning.
|
||||||
|
- [ ] Implement offline checkpoint snapshot and EFI backup with exact metadata/hashes.
|
||||||
|
- [ ] Implement restartable restore preserving failed roots and all non-owned data.
|
||||||
|
- [ ] Test process interruption/restart at journal transitions and malformed backups.
|
||||||
|
- [ ] Scoped tests, self-review, commit, independent task review.
|
||||||
|
|
||||||
|
## Task 2: Bootable acceptance and integration
|
||||||
|
|
||||||
|
**Files:** new `dev/system-recovery-smoke.py` or extension to preserve-partition
|
||||||
|
acceptance, associated harness tests, image wiring and release evidence.
|
||||||
|
|
||||||
|
- [ ] Consume completed installer mode; seed and record fresh qcow2 only.
|
||||||
|
- [ ] Install, checkpoint offline, upgrade real fixture package and change HOME.
|
||||||
|
- [ ] Damage selected kernel and owned EFI, recover from live ISO and boot disk-only.
|
||||||
|
- [ ] Verify exact old base/kernel/Portage and unchanged current HOME/foreign data.
|
||||||
|
- [ ] Exercise interrupted restore, record hashes/states and honest limitations.
|
||||||
|
- [ ] Integrate with laptop ISO acceptance and final review before delivery.
|
||||||
@@ -0,0 +1,53 @@
|
|||||||
|
# Offline recovery of the Gentoo base
|
||||||
|
|
||||||
|
This separately verified part of laptop preparation supplies real OS rollback,
|
||||||
|
not just runtime-file rollback. It is deliberately offline: create checkpoints
|
||||||
|
from the trusted live ISO while the installed root and ESP are unmounted, perform
|
||||||
|
ordinary Portage updates in the installed system, and use the ISO to recover if
|
||||||
|
needed. No online application-consistency or automatic failed-boot claim is made.
|
||||||
|
|
||||||
|
The explicit Btrfs layout is @root, @home, @snapshots; /boot, kernel modules,
|
||||||
|
Portage package database and world remain in @root. There must be no nested
|
||||||
|
subvolumes within @root. VM disks and user data in @home survive OS recovery.
|
||||||
|
GRUB/fstab/initramfs select UUID plus subvol=@root, never fixed subvolume IDs.
|
||||||
|
|
||||||
|
`/etc/hydra/storage.json` is the installation ownership marker with exact fields:
|
||||||
|
format=1, install_uuid, root_fs_uuid, root_partuuid, esp_uuid, esp_partuuid,
|
||||||
|
owned_efi_path='EFI/HydraOS', filesystem='btrfs', root_subvolume='@root'. The ESP
|
||||||
|
must be the recorded FAT partition; never operate on foreign EFI paths or NVRAM.
|
||||||
|
|
||||||
|
CLI `hydra-system checkpoint --root-uuid UUID --esp-partuuid PARTUUID --name NAME`,
|
||||||
|
`hydra-system list --root-uuid UUID`, and
|
||||||
|
`hydra-system restore --root-uuid UUID --checkpoint ID`. Changes require --execute
|
||||||
|
and --confirm-root-uuid UUID. Default plans/list are read-only. Require a genuine
|
||||||
|
Hydra live marker, root execution for changes, exactly one matching root and ESP,
|
||||||
|
ordinary unmounted partitions without active swap/holders, single-device Btrfs,
|
||||||
|
matching partition/filesystem/install UUIDs and supported owned layout.
|
||||||
|
|
||||||
|
Checkpoint mounts selected filesystems privately, snapshots @root read-only into
|
||||||
|
@snapshots/ID/root and saves only EFI/HydraOS with a hash/metadata manifest.
|
||||||
|
Preserve exact installed root and EFI state while offline. Durably publish the
|
||||||
|
completed checkpoint descriptor last. Incomplete checkpoints cannot be restored.
|
||||||
|
Snapshots remain on the same disk and are not external backups.
|
||||||
|
|
||||||
|
Restore validates all metadata, recorded source/snapshot UUIDs, readonly snapshot,
|
||||||
|
layout marker and saved EFI bytes before mutation. Prepare a writable snapshot,
|
||||||
|
record a durable transaction outside @root, retain the previous root under a unique
|
||||||
|
failed-root name, rename the new root to @root, then restore only owned EFI files.
|
||||||
|
Keep checkpoints and failed roots. Never delete @home or alter GPT, fallback EFI,
|
||||||
|
foreign partitions/EFI directories or BootOrder. Directory fsync and filesystem
|
||||||
|
sync delimit journal transitions. Lock operations and reject unexplained state.
|
||||||
|
|
||||||
|
Root/ESP replacement is not atomic across Btrfs and FAT. A power interruption can
|
||||||
|
leave the install temporarily unbootable; rerunning restore from the live ISO must
|
||||||
|
verify identities and resume the recorded transaction without guessing or deleting
|
||||||
|
either root. Recovery must not invoke installed programs, fetch files, or require
|
||||||
|
network access. Symlinks, malformed paths, unexpected files and tampered backup
|
||||||
|
metadata fail closed before writes.
|
||||||
|
|
||||||
|
Actual acceptance uses a fresh UEFI VM, preserved foreign EFI/data sentinels,
|
||||||
|
Btrfs install, live checkpoint, a real local Portage package upgrade, changed HOME,
|
||||||
|
and damaged installed kernel/own EFI. After recovery boot without ISO and verify
|
||||||
|
old package database/world/kernel artifacts together, updated HOME retained, and
|
||||||
|
foreign bytes/GPT/BootOrder unchanged. Exercise restart after journal transition
|
||||||
|
failures. Do not claim a two-kernel-version upgrade unless separately exercised.
|
||||||
Reference in New Issue
Block a user