flash: route all writes through GuardedFlash safety transaction (ADR-021)

Single chokepoint for every flash write. begin() takes a mandatory pre-write
snapshot via the IOC-free diag path and saves it as a recovery image; commit()/
commit_with() run invariant-driven pre/postflight checks with a severity-driven
response. Catches both historical brick mechanisms:

- BootCriticalUnchanged (Critical): no byte of 0x540000-0x5A0000 may change --
  the unrecoverable boot-input zone (the 2026-05-20 BIOS-into-boot-input brick).
- BanksConsistent (Critical): FIRMWARE == BACKUP version (the 2026-05-31
  bank-mismatch brick).
- TargetReadbackMatches (Error): target region reads back == intended bytes.

Reroutes fw write, bios/nvdata write (previously had NO whole-flash check),
recover (commit_with), and enforces a mandatory pre-erase snapshot. Deletes the
two duplicated post_write_whole_flash_verify helpers. Card::write_region gains a
doc safety contract. 13 new pure unit tests (incl. 05-20 brick simulation);
284 total pass; clippy clean.

Author: MattJackson

src/card/mod.rs

@@ -186,10 +186,14 @@ pub trait Card: Send {
         Err(CardError::NotImplemented("read_region_itype"))
     }
 
-    /// Write one flash-chip region (FW / BIOS / NVDATA) via FW_DOWNLOAD.
-    /// DESTRUCTIVE. Shared primitive for `restore` and `fw/bios/nvdata write`.
-    /// (Erase-if-personality-change and HCB-on-lock live in the higher-level
-    /// `fw write` logic, not here — this is the raw region write.)
+    /// Write one flash-chip region (FW / BIOS / NVDATA) via FW_DOWNLOAD. DESTRUCTIVE.
+    ///
+    /// SAFETY CONTRACT (ADR-021): this is the raw, UNGUARDED region write. CLI verbs and any new
+    /// callers MUST NOT call it directly — route through `firmware::guard::GuardedFlash`, which
+    /// takes a mandatory pre-write snapshot and enforces the boot-critical-unchanged + bank-
+    /// consistency postflight invariants. Two cards were bricked by writes that skipped those
+    /// checks. The only legitimate direct callers are `GuardedFlash` itself (and a multi-region
+    /// `restore` invoked *inside* `GuardedFlash::commit_with`).
     fn write_region(
         &mut self,
         _image_type: crate::mpi::messages::ImageType,

src/cli/erase.rs

@@ -30,6 +30,18 @@ pub fn run(
 
     let bdf = crate::card::resolve_bdf(bdf.as_deref())
         .map_err(|e| crate::Error::Other(format!("{}", e)))?;
+
+    // Mandatory pre-erase recovery snapshot (ADR-021). Erase intentionally clears flash, so the
+    // boot-critical-unchanged invariant does not apply — but we MUST have a recovery image first.
+    // This enforces what was previously only a text plea ("ensure a fresh backup exists"): no
+    // snapshot (IOC-free diag read), no erase.
+    let snap_dir = std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."));
+    let txn = crate::firmware::guard::GuardedFlash::begin(&bdf, &snap_dir)?;
+    eprintln!(
+        "erase: pre-erase recovery snapshot captured → {}",
+        txn.snapshot_path().display()
+    );
+
     let mut card = crate::card::discover_one(&bdf)
         .map_err(|e| crate::Error::Other(format!("discover_one({}): {}", bdf, e)))?;
 

src/cli/fw.rs

@@ -9,10 +9,16 @@ use std::path::Path;
 
 use sha2::{Digest, Sha256};
 
+use crate::firmware::guard::{GuardedFlash, WriteIntent};
 use crate::firmware::validate::{check_fit, validate_image};
-use crate::firmware::flash_layout::verify_flash_consistency;
 use crate::mpi::messages::ImageType;
 
+/// Directory where guarded-flash writes drop the pre-write recovery snapshot. Current working
+/// directory — discoverable and deterministic (no timestamp in the path; one snapshot per card).
+fn snapshot_dir() -> std::path::PathBuf {
+    std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."))
+}
+
 fn sha_hex(b: &[u8]) -> String {
     let mut h = Sha256::new();
     h.update(b);
@@ -32,68 +38,6 @@ fn fw_banner(data: &[u8]) -> Option<String> {
     std::str::from_utf8(&data[pos..end]).ok().map(String::from)
 }
 
-/// Perform whole-flash consistency check via diag back-door. Reads full 8MiB from 0xFC000000,
-/// calls verify_flash_consistency, and returns Err if FIRMWARE and BACKUP regions disagree.
-/// If the diag read itself fails, logs a warning but Ok(()) — don't false-fail the write.
-fn post_write_whole_flash_verify(bdf: &str) -> Result<(), crate::Error> {
-    use crate::sbr::transport::Bar1MmapSbrTransport;
-
-    const FLASH_WINDOW_ADDR: u32 = 0xFC000000;
-    const FLASH_WINDOW_SIZE: usize = 8 * 1024 * 1024;
-
-    let mut transport = match Bar1MmapSbrTransport::open(bdf) {
-        Ok(t) => t,
-        Err(e) => {
-            eprintln!(
-                "WARN: post-write whole-flash verify: could not open diag back-door ({}), \
-                 skipping consistency check — verify backup region manually",
-                e
-            );
-            return Ok(());
-        }
-    };
-
-    let chip_mem = match transport.read_chip_mem(FLASH_WINDOW_ADDR, FLASH_WINDOW_SIZE) {
-        Ok(mem) => mem,
-        Err(e) => {
-            eprintln!(
-                "WARN: post-write whole-flash verify: diag read failed ({}), \
-                 skipping consistency check — verify backup region manually",
-                e
-            );
-            return Ok(());
-        }
-    };
-
-    match verify_flash_consistency(&chip_mem) {
-        Ok(consistency) => {
-            if !consistency.consistent {
-                return Err(crate::Error::Other(format!(
-                    "POST-WRITE VERIFICATION FAILED: FIRMWARE region version '{}' \
-                     does not match BACKUP region version '{}'. The card may be bricked. \
-                     Run 'lsi-flash backup' immediately to capture current state, then restore \
-                     from a known-good backup.",
-                    consistency.firmware_version, consistency.backup_version
-                )));
-            }
-            eprintln!(
-                "fw write: whole-flash verify OK (FIRMWARE={}, BACKUP={})",
-                consistency.firmware_version, consistency.backup_version
-            );
-            Ok(())
-        }
-        Err(e) => {
-            // If parsing the layout fails, we can't verify — warn but don't fail the write.
-            eprintln!(
-                "WARN: post-write whole-flash verify: could not parse flash layout ({}), \
-                 skipping consistency check",
-                e
-            );
-            Ok(())
-        }
-    }
-}
-
 /// `fw read` — read the firmware region. By default reads the **flash** copy
 /// (FW_UPLOAD ITYPE 0x01 = FW_FLASH, the persisted image); `--running` reads
 /// the **running** image (ITYPE 0x00 = FW_CURRENT, what the chip booted). The
@@ -206,32 +150,19 @@ pub fn run_write(bdf: String, from_file: &Path, yes: bool) -> Result<(), crate::
         }
     }
 
-    // Write (FW_DOWNLOAD).
-    card.write_region(ImageType::Fw, &image)
-        .map_err(|e| crate::Error::Other(format!("fw write: {}", e)))?;
-
-    // Check 5 — read-back verify (ADR-015 Rule 5).
-    match card.read_region(ImageType::Fw) {
-        Ok(rb) => {
-            let want = sha_hex(&image);
-            let got = sha_hex(&rb[..rb.len().min(image.len())]);
-            if want == got {
-                eprintln!("fw write: OK ({} bytes), read-back verified ✓", image.len());
-            } else {
-                return Err(crate::Error::Other(format!(
-                    "fw write: read-back MISMATCH (wrote {} got {}) — investigate before trusting",
-                    want, got
-                )));
-            }
-        }
-        Err(e) => eprintln!(
-            "fw write: OK ({} bytes), but read-back verify failed: {} (verify manually)",
-            image.len(),
-            e
-        ),
-    }
-
-    // ADR-020 whole-flash consistency gate: after FW_DOWNLOAD, read full flash via diag back-door
-    // and require active == backup. Mismatch → fail loudly with both versions named.
-    post_write_whole_flash_verify(&bdf)
+    // The guarded transaction (ADR-021) is the ONLY path bytes reach flash: it takes a mandatory
+    // pre-write snapshot (recovery image), writes via FW_DOWNLOAD, then enforces the postflight
+    // invariants (boot-critical zone unchanged, banks consistent, read-back matches intent) with
+    // a severity-driven response. Supersedes the old hand-rolled read-back + whole-flash verify.
+    let txn = GuardedFlash::begin(&bdf, &snapshot_dir())?;
+    txn.commit(
+        &mut *card,
+        WriteIntent {
+            region: ImageType::Fw,
+            bytes: image.clone(),
+            label: "firmware".into(),
+        },
+    )?;
+    eprintln!("fw write: OK ({} bytes) — guarded transaction verified ✓", image.len());
+    Ok(())
 }

src/cli/recover.rs

@@ -7,7 +7,6 @@ use std::path::PathBuf;
 use thiserror::Error;
 
 use crate::cli::backup::BackupManifest;
-use crate::firmware::flash_layout::verify_flash_consistency;
 use crate::mpi::messages::MpiError;
 
 #[derive(Debug, Error)]
@@ -159,13 +158,23 @@ pub fn run(
         return Ok(());
     }
 
-    // 6. Real path: dispatch through Card trait (same as backup)
+    // 6. Real path: dispatch through Card trait, wrapped in the guarded transaction (ADR-021).
+    //    `restore` writes multiple regions, so we use commit_with: it snapshots first (recovery
+    //    image), runs the multi-region write, then enforces boot-critical-unchanged + bank
+    //    consistency against the snapshot. A restore that disturbs the boot-input zone is caught.
     let mut card = crate::card::discover_one(&bdf)
         .map_err(|e| crate::Error::Other(format!("recover: discover_one({}): {}", bdf, e)))?;
 
-    let report = card
-        .restore(std::path::Path::new(&backup_dir))
-        .map_err(|e| crate::Error::Other(format!("recover: card.restore: {}", e)))?;
+    let txn = crate::firmware::guard::GuardedFlash::begin(&bdf, &snapshot_dir())?;
+    let mut report_slot = None;
+    txn.commit_with(|| {
+        let report = card
+            .restore(std::path::Path::new(&backup_dir))
+            .map_err(|e| crate::Error::Other(format!("recover: card.restore: {}", e)))?;
+        report_slot = Some(report);
+        Ok(())
+    })?;
+    let report = report_slot.expect("restore returned Ok ⇒ report captured");
 
     // 7. Output (honest about which regions were actually written)
     if json {
@@ -186,69 +195,14 @@ pub fn run(
         }
     }
 
-   // ADR-020 whole-flash consistency gate after restore (same as fw write).
-    post_write_whole_flash_verify(&bdf)?;
-
+    // Whole-flash safety (boot-critical unchanged + banks consistent) was enforced inside the
+    // guarded transaction above (commit_with), against the mandatory pre-write snapshot.
     Ok(())
 }
 
-/// Post-write whole-flash verify helper (mirrors fw.rs implementation).
-fn post_write_whole_flash_verify(bdf: &str) -> Result<(), crate::Error> {
-    use crate::sbr::transport::Bar1MmapSbrTransport;
-
-    const FLASH_WINDOW_ADDR: u32 = 0xFC000000;
-    const FLASH_WINDOW_SIZE: usize = 8 * 1024 * 1024;
-
-    let mut transport = match Bar1MmapSbrTransport::open(bdf) {
-        Ok(t) => t,
-        Err(e) => {
-            eprintln!(
-                "WARN: post-write whole-flash verify: could not open diag back-door ({}), \
-                 skipping consistency check — verify backup region manually",
-                e
-            );
-            return Ok(());
-        }
-    };
-
-    let chip_mem = match transport.read_chip_mem(FLASH_WINDOW_ADDR, FLASH_WINDOW_SIZE) {
-        Ok(mem) => mem,
-        Err(e) => {
-            eprintln!(
-                "WARN: post-write whole-flash verify: diag read failed ({}), \
-                 skipping consistency check — verify backup region manually",
-                e
-            );
-            return Ok(());
-        }
-    };
-
-    match verify_flash_consistency(&chip_mem) {
-        Ok(consistency) => {
-            if !consistency.consistent {
-                return Err(crate::Error::Other(format!(
-                    "POST-RESTORE VERIFICATION FAILED: FIRMWARE region version '{}' \
-                     does not match BACKUP region version '{}'. The card may be bricked. \
-                     Run 'lsi-flash backup' immediately to capture current state, then restore \
-                     from a known-good backup.",
-                    consistency.firmware_version, consistency.backup_version
-                )));
-            }
-            eprintln!(
-                "restore: whole-flash verify OK (FIRMWARE={}, BACKUP={})",
-                consistency.firmware_version, consistency.backup_version
-            );
-            Ok(())
-        }
-        Err(e) => {
-            eprintln!(
-                "WARN: post-write whole-flash verify: could not parse flash layout ({}), \
-                 skipping consistency check",
-                e
-            );
-            Ok(())
-        }
-    }
+/// Directory where guarded-flash writes drop the pre-write recovery snapshot (current dir).
+fn snapshot_dir() -> std::path::PathBuf {
+    std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."))
 }
 
 fn sha256_hex(data: &[u8]) -> String {

src/cli/region.rs

@@ -10,6 +10,7 @@ use std::path::PathBuf;
 use clap::{Args, Subcommand};
 use sha2::{Digest, Sha256};
 
+use crate::firmware::guard::{GuardedFlash, WriteIntent};
 use crate::mpi::messages::ImageType;
 
 /// Shared read/write subcommands for a flash-chip region.
@@ -99,37 +100,34 @@ pub fn run_write(
 
     let mut card = crate::card::discover_one(&bdf)
         .map_err(|e| crate::Error::Other(format!("discover_one({}): {}", bdf, e)))?;
-    card.write_region(image_type, &data)
-        .map_err(|e| crate::Error::Other(format!("{} write: {}", region, e)))?;
 
-    // Read-back verify (ADR-015 Rule 5): re-upload and compare sha.
-    match card.read_region(image_type) {
-        Ok(rb) => {
-            let want = sha_hex(&data);
-            let got = sha_hex(&rb[..rb.len().min(data.len())]);
-            if got == want {
-                eprintln!(
-                    "{} write: OK ({} bytes), read-back verified ✓",
-                    region,
-                    data.len()
-                );
-            } else {
-                return Err(crate::Error::Other(format!(
-                    "{} write: read-back MISMATCH (wrote {} got {}) — investigate before trusting",
-                    region, want, got
-                )));
-            }
-        }
-        Err(e) => eprintln!(
-            "{} write: OK ({} bytes), but read-back verify failed: {} (verify manually)",
-            region,
-            data.len(),
-            e
-        ),
-    }
+    // All flash writes go through the guarded transaction (ADR-021). For bios/nvdata this is the
+    // key fix: previously these writes had NO whole-flash check, so a write that spilled into the
+    // boot-critical region (the 2026-05-20 brick mechanism) went undetected. Now every byte of the
+    // boot-input zone is verified unchanged against the mandatory pre-write snapshot, and banks are
+    // checked for consistency, regardless of which region was targeted.
+    let txn = GuardedFlash::begin(&bdf, &snapshot_dir())?;
+    txn.commit(
+        &mut *card,
+        WriteIntent {
+            region: image_type,
+            bytes: data.clone(),
+            label: region.to_string(),
+        },
+    )?;
+    eprintln!(
+        "{} write: OK ({} bytes) — guarded transaction verified ✓",
+        region,
+        data.len()
+    );
     Ok(())
 }
 
+/// Directory where guarded-flash writes drop the pre-write recovery snapshot (current dir).
+fn snapshot_dir() -> std::path::PathBuf {
+    std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from("."))
+}
+
 /// Dispatch a `bios`/`nvdata` region subcommand (fw has its own enum w/ extras).
 pub fn run(
     bdf: String,