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