Specify offline recovery for the Gentoo base

2026-10-13 21:29:35 +03:00
parent 71fb8eacbd
commit bc4fe60947
2 changed files with 106 additions and 0 deletions
@@ -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.