Keep a pristine copy of the flash image, and a way back to it

assets/flash.img was gitignored, so the only copy of the never-booted image lived
on one disk. The emulator writes to that image, so a session can leave edited
settings or a damaged EEPROM behind with nothing to restore from.

assets/pristine/ now holds the image as first generated, gzipped and checksummed,
and is tracked deliberately. Gzip takes it from 2 MiB to 2.3 KiB because the image
is nearly all 0xFF, which is what makes keeping it in git reasonable. The live
image and its .bak-* files stay ignored.

Two checksums are recorded, for the archive and for its contents, so a corrupted
archive is distinguishable from one that was replaced.

tools/restore_flash.sh verifies, diffs, or restores. Restore backs up the current
image first, then re-checks the result, since a restore that silently half-worked
would be worse than none.

Verified by deliberately corrupting the live image: --diff reported 32 differing
bytes, restore backed up and rewrote it, and --diff then reported no change. The
image is currently byte-identical to what make_flash.py produces, so this is the
genuine original rather than a copy of something already used.

tools/restore_flash.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Restore assets/flash.img to its pristine, never-booted state.
+#
+# The emulator writes to the flash image, so a session can leave settings, edited
+# frequencies, or a corrupted EEPROM behind. assets/pristine/ holds a checksummed
+# copy of the image as first generated, so there is always a known-good state to
+# come back to.
+#
+# Usage:
+#   tools/restore_flash.sh            # restore, backing up the current image
+#   tools/restore_flash.sh --verify   # only check the pristine copy is intact
+#   tools/restore_flash.sh --diff     # show whether the live image has changed
+set -euo pipefail
+
+SIM="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LIVE="$SIM/assets/flash.img"
+PRISTINE_GZ="$SIM/assets/pristine/flash-pristine.img.gz"
+SUMS="$SIM/assets/pristine/flash-pristine.img.sha256"
+
+want_plain() { awk '$2 == "flash-pristine.img" {print $1}' "$SUMS"; }
+want_gz()    { awk '$2 == "flash-pristine.img.gz" {print $1}' "$SUMS"; }
+
+verify_pristine() {
+    [ -f "$PRISTINE_GZ" ] || { echo "missing $PRISTINE_GZ" >&2; exit 1; }
+    local got_gz got_plain
+    got_gz=$(sha256sum "$PRISTINE_GZ" | awk '{print $1}')
+    if [ "$got_gz" != "$(want_gz)" ]; then
+        echo "pristine archive is CORRUPT" >&2
+        echo "  expected $(want_gz)" >&2
+        echo "  actual   $got_gz" >&2
+        exit 1
+    fi
+    got_plain=$(gzip -dc "$PRISTINE_GZ" | sha256sum | awk '{print $1}')
+    if [ "$got_plain" != "$(want_plain)" ]; then
+        echo "pristine contents do not match their checksum" >&2
+        exit 1
+    fi
+    echo "pristine copy verified ($(want_plain))"
+}
+
+case "${1:-restore}" in
+--verify)
+    verify_pristine
+    ;;
+--diff)
+    verify_pristine
+    if [ ! -f "$LIVE" ]; then
+        echo "no live image at $LIVE"
+        exit 0
+    fi
+    live=$(sha256sum "$LIVE" | awk '{print $1}')
+    if [ "$live" = "$(want_plain)" ]; then
+        echo "live image is unchanged from pristine"
+    else
+        echo "live image HAS CHANGED from pristine"
+        echo "  pristine $(want_plain)"
+        echo "  live     $live"
+        gzip -dc "$PRISTINE_GZ" > /tmp/.pristine.$$
+        echo "  differing bytes: $(cmp -l /tmp/.pristine.$$ "$LIVE" 2>/dev/null | wc -l)"
+        rm -f /tmp/.pristine.$$
+    fi
+    ;;
+restore)
+    verify_pristine
+    if [ -f "$LIVE" ]; then
+        backup="$LIVE.bak-$(date +%Y%m%d-%H%M%S)"
+        cp -a "$LIVE" "$backup"
+        echo "current image saved to $(basename "$backup")"
+    fi
+    gzip -dc "$PRISTINE_GZ" > "$LIVE"
+    got=$(sha256sum "$LIVE" | awk '{print $1}')
+    [ "$got" = "$(want_plain)" ] || { echo "restore verification FAILED" >&2; exit 1; }
+    echo "restored $LIVE to pristine state"
+    echo "note: the emulator reads the image at boot, so power-cycle to pick it up"
+    ;;
+*)
+    echo "usage: $0 [restore|--verify|--diff]" >&2
+    exit 2
+    ;;
+esac