feat(l1): harden state-history invariants

Per review:
- Document the version-bump strategy on JOURNAL_VERSION so PRs 2/3/4 have a
  policy to follow: drain at finality on bump, or grow per-version decode
  arms if history needs to survive the upgrade.
- Add debug_assert!(layers_to_commit.len() == 1) in TrieLayerCache::commit
  to runtime-enforce the single-layer invariant the ATTRIBUTION NOTE
  describes; catches any future change that quietly merges multiple
  blocks into one journal entry.

Author: edg-l

crates/storage/journal.rs

@@ -25,6 +25,16 @@
 use ethrex_common::H256;
 
 /// Current version of the journal entry codec.
+///
+/// Bumping this constant changes the wire format. The decoder rejects any
+/// other version with [`JournalDecodeError::VersionMismatch`]: a v(N) binary
+/// will refuse to interpret v(N+1) entries (forward safety) and will also
+/// refuse to read v(N-1) entries written by a previous binary (no implicit
+/// fallback). The plan for the rollback consumer (PR 2/3/4) is to drain
+/// the journal at a finality boundary on upgrade, so the v(N) journal
+/// starts empty after the bump; a future bump that needs to keep history
+/// across the upgrade should introduce per-version `decode_vN` arms here
+/// rather than re-encoding existing entries.
 pub const JOURNAL_VERSION: u8 = 1;
 
 /// A single reverse-diff entry: `(on_disk_key, previous_value_or_none)`.

crates/storage/layering.rs

@@ -277,6 +277,12 @@ impl TrieLayerCache {
         // rollback consumer (PR 2/3) would then be unable to reconstruct
         // intermediate pre-images. Single-layer commits are an invariant of the
         // current write path; revisit this if that ever changes.
+        debug_assert!(
+            layers_to_commit.len() == 1,
+            "multi-layer commit would corrupt journal attribution (see ATTRIBUTION NOTE above): \
+             got {} layers, expected 1",
+            layers_to_commit.len()
+        );
         let top_layer = layers_to_commit.first()?;
         let top_layer_id = top_layer.id;
         let committed_block_number = top_layer.block_number;