Plan preserved installation and verified Hydra updates

docs/superpowers/specs/2026-10-13-laptop-ready-design.md

@@ -0,0 +1,96 @@
+# Hydra OS laptop preparation
+
+The user authorized autonomous implementation of the agreed scope: preserve all
+existing laptop partitions; install Hydra into an explicitly selected partition;
+obtain updates from the now-public `Emil_Shanaty/Hydra-OS` Gitea repository; verify
+signatures and recover after failed updates; prepare hardware diagnostics; rebuild
+and test an ISO including the generated Fastfetch branding. Technical choices are
+delegated. Actual laptop partitioning/installation and physical hardware checks
+remain operator steps; no physical target is selected or authorized.
+
+## Invariants
+
+- Never modify the physical host's block devices, firmware, services, NixOS
+  configuration, networking, existing containers, or existing VM disks.
+- All installation/recovery execution tests use freshly created private qcow2s.
+- Keep whole-disk installation compatible, but add a distinct existing-partitions
+  mode. No automatic partition selection, shrinking, or repartitioning.
+- Preserve foreign EFI files, the removable fallback loader, and BootOrder.
+- VM disks, profiles, HOME, credentials and network configuration are not runtime
+  update payloads. Release trust is installed independently of untrusted discovery.
+- Prefer the standard library and already installed OpenSSL; no hosted dependency.
+- Hardware detection is evidence about presence, not proof of working devices.
+- A runtime rollback must never be described as rollback of Gentoo or its kernel.
+
+## Existing-partitions installation
+
+Keep `--disk` and `--confirm-erase` for fresh whole-disk installations. Add
+`--root-partition`, `--esp-partition`, `--confirm-format`, `--root-fs ext4|btrfs`
+and opt-in `--register-boot-entry`. A request chooses exactly one mode. Existing
+mode formats only the selected root after full identity revalidation, requires an
+unmounted existing FAT ESP, and never runs disk-label/partition/ESP-format commands.
+
+Require stable canonical paths, block identities, parent/partition identities and
+bounds; reject mounted/active/protected targets, overlaps, aliases, ambiguous
+metadata and devices with holders. Unrelated mounted sibling partitions must not
+cause false rejection. Btrfs mounts must resolve all backing members conservatively.
+Require enough capacity for the installed payload and boot files before erasure.
+
+Write only EFI/HydraOS, refusing an existing collision. Use GRUB --no-nvram without
+--removable, disable os-prober, and leave foreign EFI entries and fallback intact.
+Explicit registration may create a new entry without modifying BootOrder. Default
+output explains manual firmware selection. ESP preflight is read-only and happens
+before root formatting; record and verify unchanged foreign file hashes.
+
+Ext4 remains compatible. Optional Btrfs uses @root, @home, @snapshots. The kernel,
+/boot and Portage database remain within @root; guest disks under HOME remain in
+@home. This layout permits a separately verified system recovery path; it alone
+is not a rollback implementation.
+
+## Signed runtime updates
+
+Use a bounded passive ZIP payload, exact-byte Ed25519-signed JSON manifest and
+detached signature. Manifest records product, scope, format, channel, architecture,
+monotonic sequence, release version, source commit, archive name/size/hash and the
+allowlisted installed paths/modes/hashes. OpenSSL verifies using an installed public
+key. Private release material stays outside Git, the build context and Nix store.
+
+Gitea discovery is unauthenticated HTTPS on the fixed project origin; it is not a
+trust authority. Reject cross-origin/downgrade redirects, malformed URLs, duplicate
+JSON/archive entries, traversal/symlinks/special files, excess sizes, tampering and
+unsupported formats. Verify the manifest before trusting the archive. Empty releases
+are a normal result. No fallback to executing unsigned downloaded Python archives.
+
+CLI: `hydra update check`, `status`, `apply` and `rollback TRANSACTION`, plus a
+standalone `hydra-update-recover` available when the runtime itself is damaged.
+The trusted engine and recovery bootstrap are outside the runtime update allowlist.
+Prefer a protected installed engine imported without arbitrary sys.path entries.
+For local tests/support permit an explicit trusted local artifact directory and a
+staging-root API; production target checks must still require a Hydra installation.
+
+Serialize mutations with a lock. Before the first destination change, validate all
+paths and save original bytes, modes, owners, symlinks and hashes into a durable
+private backup; persist a journal and fsync files/directories. Recover prepared or
+interrupted transactions from independently validated records. Latest-only explicit
+rollback refuses unexpected modifications. Preserve highest accepted sequence when
+rolling back current state; block new changes while recovery is pending. Failure
+must retain the journal and all backups. Include real fresh-process crash tests.
+
+## Diagnostics and delivery
+
+`hydra doctor` collects a bounded read-only report useful on the live ASUS laptop:
+UEFI/Secure Boot, KVM, CPU/RAM, storage visibility, kernel/driver bindings, graphics,
+input devices, network/audio tools and required services. Redact serials, MACs,
+SSID, IP addresses, usernames and machine IDs by default. Print actionable checks
+without implying physical Wi-Fi/audio/brightness/suspend/144Hz delivery were tested.
+
+Rebuild using the isolated existing builder store. Preserve the previous ISO and
+firmware. Run whole-disk acceptance plus a distinct preserve-partitions acceptance:
+seed foreign EFI/fallback/sibling sentinel files, install into only the target,
+compare GPT/BootOrder/sentinels, and boot without ISO. Exercise signed update,
+tamper refusal, rollback and recovery with guest data unchanged. Store reports
+against exact source/ISO hashes. Publish only intended code/artifacts; private
+builder exports, signing keys, VM data and test secrets are never release assets.
+
+Whole-base Portage recovery is a separate design/verification unit. Until its own
+bootable test passes, documentation must retain that limitation explicitly.