You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iggy.apache.org by kr...@apache.org on 2026/08/12 03:50:08 UTC

(iggy) 01/10: feat(metadata): version the snapshot format with a release stamp

This is an automated email from the ASF dual-hosted git repository.

krishvishal pushed a commit to branch vsr-cleanup
in repository https://gitbox.apache.org/repos/asf/iggy.git

commit af0b9101b370b935ac2909ea4ed1be43a77385dd
Author: Krishna Vishal <kr...@gmail.com>
AuthorDate: Tue Aug 11 13:21:27 2026 +0530

    feat(metadata): version the snapshot format with a release stamp
---
 Cargo.lock                          |   1 +
 Cargo.toml                          |   1 +
 core/metadata/Cargo.toml            |   1 +
 core/metadata/src/impls/metadata.rs |  29 +++--
 core/metadata/src/impls/recovery.rs |  89 ++++++++-------
 core/metadata/src/stm/snapshot.rs   | 209 ++++++++++++++++++++++++++++++++++--
 6 files changed, 278 insertions(+), 52 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 0cf2039bd..6fdd97140 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -8488,6 +8488,7 @@ dependencies = [
  "left-right",
  "message_bus",
  "paste",
+ "rmp",
  "rmp-serde",
  "serde",
  "server_common",
diff --git a/Cargo.toml b/Cargo.toml
index f33c0eddc..d11853cd9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -279,6 +279,7 @@ reqwest-tracing = "0.7.1"
 ring = "0.17.14"
 ringbuffer = "0.16.0"
 rmcp = "2.2.0"
+rmp = "0.8.15"
 rmp-serde = "1.3.1"
 rolling-file = "0.2.0"
 rust-embed = "8.12.0"
diff --git a/core/metadata/Cargo.toml b/core/metadata/Cargo.toml
index 681ff73ea..347b85c1b 100644
--- a/core/metadata/Cargo.toml
+++ b/core/metadata/Cargo.toml
@@ -48,6 +48,7 @@ journal = { workspace = true }
 left-right = { workspace = true }
 message_bus = { workspace = true }
 paste = { workspace = true }
+rmp = { workspace = true }
 rmp-serde = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 server_common = { workspace = true }
diff --git a/core/metadata/src/impls/metadata.rs b/core/metadata/src/impls/metadata.rs
index 9643493fa..f80507340 100644
--- a/core/metadata/src/impls/metadata.rs
+++ b/core/metadata/src/impls/metadata.rs
@@ -43,7 +43,7 @@ use iggy_binary_protocol::requests::topics::CreateTopicRequest as WireCreateTopi
 use iggy_binary_protocol::requests::topics::CreateTopicWithAssignmentsRequest as PersistedCreateTopicRequest;
 use iggy_binary_protocol::{
     Command2, ConsensusHeader, EvictionReason, GenericHeader, Operation, PrepareHeader,
-    PrepareOkHeader, ReplyHeader, RequestHeader, WireDecode, WireEncode, WireName,
+    PrepareOkHeader, ProtocolVersion, ReplyHeader, RequestHeader, WireDecode, WireEncode, WireName,
 };
 use iggy_common::IggyError;
 use iggy_common::UserId;
@@ -189,15 +189,17 @@ impl IggySnapshot {
     ///
     /// The checksum comes from the file's bytes, never from re-encoding what was
     /// decoded: the pairing must survive a schema change. Adding a trailing
-    /// `#[serde(default)]` field is the repo's forward-compatible migration, and an
-    /// older file re-encodes with one MORE msgpack array element after it, so a
-    /// re-encode checksum would diverge on the first boot of the new build and refuse
-    /// every checkpointed node with its WAL prefix already drained.
+    /// `#[serde(default)]` field is the repo's forward-compatible migration (see
+    /// [`SNAPSHOT_FORMAT_VERSION`](crate::stm::snapshot::SNAPSHOT_FORMAT_VERSION) for
+    /// the rules), and an older file re-encodes with one MORE msgpack array element
+    /// after it, so a re-encode checksum would diverge on the first boot of the new
+    /// build and refuse every checkpointed node with its WAL prefix already drained.
     ///
     /// # Errors
     /// `SnapshotError::ChecksumMismatch` if the file carries an integrity trailer that
-    /// does not match its payload, or `SnapshotError` if the file cannot be read or
-    /// deserialized.
+    /// does not match its payload, `SnapshotError::UnsupportedFormatVersion` if it was
+    /// written in a format version this build does not read, or `SnapshotError` if the
+    /// file cannot be read or deserialized.
     pub fn load(path: &Path) -> Result<(Self, u128), SnapshotError> {
         let data = std::fs::read(path)?;
         let (payload, checksum) = split_trailer(&data, path)?;
@@ -1545,7 +1547,7 @@ where
     /// # Panics
     /// If called on a shard without consensus (state transfer is a shard-0
     /// concern).
-    #[allow(clippy::future_not_send)]
+    #[allow(clippy::future_not_send, clippy::too_many_lines)]
     pub async fn install_state_transfer(
         &self,
         snapshot_bytes: &[u8],
@@ -1561,9 +1563,20 @@ where
             .as_ref()
             .expect("install_state_transfer: consensus only exists on shard 0");
 
+        // Refuses a format version this build does not read, ahead of every frontier
+        // move below: the bytes come from a peer, so its build picked the shape.
         let snapshot = IggySnapshot::decode(snapshot_bytes)?;
         let snapshot_seq = snapshot.sequence_number();
 
+        // The one place a snapshot crosses builds, so the only place the release
+        // stamp answers a question the local logs cannot.
+        tracing::info!(
+            snapshot_seq,
+            format_version = snapshot.snapshot().version,
+            release_format = %ProtocolVersion(snapshot.snapshot().release_format),
+            "decoded a transferred metadata snapshot"
+        );
+
         // Manifest coherence. `commit_op` and `table_frontier` arrive from the
         // serving peer and are applied to THIS replica's frontiers, so a
         // malformed descriptor would move them somewhere the artifacts do not
diff --git a/core/metadata/src/impls/recovery.rs b/core/metadata/src/impls/recovery.rs
index 286d286e2..451350720 100644
--- a/core/metadata/src/impls/recovery.rs
+++ b/core/metadata/src/impls/recovery.rs
@@ -744,6 +744,7 @@ fn verify_checkpoint_pairing(
 mod tests {
     use super::*;
     use crate::impls::metadata::checkpoint_checksum;
+    use crate::stm::snapshot::SNAPSHOT_FORMAT_VERSION;
     use consensus::CLIENTS_TABLE_MAX;
     use iggy_binary_protocol::consensus::{Command2, Operation};
     use journal::Journal;
@@ -1498,47 +1499,63 @@ mod tests {
     }
 
     #[compio::test]
-    async fn recover_accepts_snapshot_written_before_a_trailing_default_field() {
-        // Appending a `#[serde(default)]` field is this repo's forward-compatible
-        // snapshot migration, and msgpack encodes structs positionally: a file the
-        // previous build wrote decodes fine (the default fills the missing element)
-        // but re-encodes with one MORE element. A pairing checksum recomputed by
-        // re-encoding the decoded snapshot would therefore diverge on the FIRST boot
-        // of the new build and refuse every checkpointed node, with the WAL prefix
-        // already drained. Hashing the bytes on disk is what makes that upgrade boot.
-        //
-        // Emulated in the direction the migration runs: strip the trailing element off
-        // a current-shape file, which is what the pre-`client_table` build wrote.
+    async fn recover_refuses_a_snapshot_from_another_format_version() {
+        // A snapshot shape is only as trustworthy as the version stamped on it, so a
+        // foreign one refuses boot rather than restoring whatever msgpack happens to
+        // make of the bytes. Everything else about the directory is healthy: the
+        // superblock pairs with the file on disk, so the refusal can only be the
+        // version.
+        const CHECKPOINT_OP: u64 = 42;
+        let mut snapshot = IggySnapshot::new(CHECKPOINT_OP);
+        snapshot.snapshot_mut().version = SNAPSHOT_FORMAT_VERSION + 1;
+        let foreign = snapshot.encode().unwrap();
+
+        let dir = tempdir().unwrap();
+        let metadata_dir = dir.path().join("metadata");
+        std::fs::create_dir_all(&metadata_dir).unwrap();
+        std::fs::write(metadata_dir.join("snapshot.bin"), &foreign).unwrap();
+        let state = vsr_state_with_checkpoint(CHECKPOINT_OP, checkpoint_checksum(&foreign));
+        {
+            let superblock = PingPongSuperblock::open(&metadata_dir).await.unwrap();
+            superblock.write(&state.to_bytes()).await.unwrap();
+        }
+
+        match recover::<TestStm>(
+            dir.path(),
+            CLUSTERED,
+            journal::prepare_journal::DEFAULT_SLOT_COUNT,
+            CLIENTS_TABLE_MAX,
+            |_| {},
+        )
+        .await
+        {
+            Err(RecoveryError::Snapshot(SnapshotError::UnsupportedFormatVersion {
+                found,
+                expected,
+            })) => {
+                assert_eq!(found, SNAPSHOT_FORMAT_VERSION + 1);
+                assert_eq!(expected, SNAPSHOT_FORMAT_VERSION);
+            }
+            Err(other) => panic!("expected a format-version refusal, got {other}"),
+            Ok(_) => panic!("expected a foreign format version to refuse boot"),
+        }
+    }
+
+    #[compio::test]
+    async fn recover_pairs_the_checkpoint_against_the_bytes_on_disk() {
+        // The pairing checksum is taken over the file's bytes, never over a re-encode
+        // of the decoded snapshot. Re-encoding would tie recovery to
+        // decode-then-encode staying byte-identical across every serde and rmp
+        // release, and a divergence there would refuse boot on every checkpointed node
+        // with its WAL prefix already drained.
         const CHECKPOINT_OP: u64 = 42;
         let encoded = IggySnapshot::new(CHECKPOINT_OP).encode().unwrap();
-        assert_eq!(
-            encoded[0] & 0xf0,
-            0x90,
-            "snapshot must encode as a msgpack fixarray for this emulation"
-        );
-        assert_eq!(
-            *encoded.last().unwrap(),
-            0xC0,
-            "the trailing snapshot field must encode as nil here; adjust the emulation \
-             if the last field stops being an Option"
-        );
-        let mut legacy = vec![0x90 | ((encoded[0] & 0x0f) - 1)];
-        legacy.extend_from_slice(&encoded[1..encoded.len() - 1]);
-
-        let decoded = IggySnapshot::decode(&legacy).unwrap();
-        assert_eq!(decoded.sequence_number(), CHECKPOINT_OP);
-        assert_ne!(
-            decoded.encode().unwrap(),
-            legacy,
-            "the emulated legacy file must NOT round-trip byte-identically, else this \
-             test cannot distinguish the two checksum sources"
-        );
 
         let dir = tempdir().unwrap();
         let metadata_dir = dir.path().join("metadata");
         std::fs::create_dir_all(&metadata_dir).unwrap();
-        std::fs::write(metadata_dir.join("snapshot.bin"), &legacy).unwrap();
-        let state = vsr_state_with_checkpoint(CHECKPOINT_OP, checkpoint_checksum(&legacy));
+        std::fs::write(metadata_dir.join("snapshot.bin"), &encoded).unwrap();
+        let state = vsr_state_with_checkpoint(CHECKPOINT_OP, checkpoint_checksum(&encoded));
         {
             let superblock = PingPongSuperblock::open(&metadata_dir).await.unwrap();
             superblock.write(&state.to_bytes()).await.unwrap();
@@ -1556,7 +1573,7 @@ mod tests {
         assert_eq!(recovered.snapshot_checkpoint.0, CHECKPOINT_OP);
         assert_eq!(
             recovered.snapshot_checkpoint.1,
-            checkpoint_checksum(&legacy),
+            checkpoint_checksum(&encoded),
             "the verified pairing must be the checksum of the bytes on disk"
         );
     }
diff --git a/core/metadata/src/stm/snapshot.rs b/core/metadata/src/stm/snapshot.rs
index ca28a30a4..e2194a277 100644
--- a/core/metadata/src/stm/snapshot.rs
+++ b/core/metadata/src/stm/snapshot.rs
@@ -15,12 +15,48 @@
 // specific language governing permissions and limitations
 // under the License.
 
+use iggy_binary_protocol::IGGY_PROTOCOL_VERSION;
 use serde::{Deserialize, Serialize, de::DeserializeOwned};
 use std::fmt;
 
 use crate::stm::stream::StreamsSnapshot;
 use crate::stm::user::UsersSnapshot;
 
+/// The version of the snapshot format in use, reserved for breaking changes.
+///
+/// One version means exactly one serialized shape, and [`MetadataSnapshot::decode`]
+/// accepts nothing else. Bump it in the same change that alters the shape: append,
+/// remove, reorder, retype, or redefine the meaning of any field, at any depth
+/// under [`MetadataSnapshot`]. There is no accepted range and no per-version
+/// translation. A snapshot this build cannot read is refused, not best-effort
+/// decoded.
+///
+/// Nothing softer would hold. msgpack encodes a struct positionally, so a field one
+/// build appends reaches another as an unexplained extra array element; without the
+/// version the reader either fails on an unrelated msgpack error or, for a
+/// same-length change, silently reads one field's bytes as another's.
+///
+/// Bumping it invalidates every `snapshot.bin` already on disk, and a node whose
+/// snapshot is refused refuses boot. That is deliberate. The metadata plane is
+/// pre-production, so the cost is clearing a data directory; once it ships, a bump
+/// needs an explicit translation path added here alongside it.
+pub const SNAPSHOT_FORMAT_VERSION: u32 = 1;
+
+/// The release that wrote a snapshot: the packed `iggy_binary_protocol` semver of
+/// this build. [`iggy_binary_protocol::ProtocolVersion`] documents the packing and
+/// renders it as `major.minor.patch`.
+///
+/// Provenance, never a gate. The format version says whether the bytes are
+/// readable; this says which build produced them, which matters most for a snapshot
+/// that arrived over state transfer from a machine whose build this node otherwise
+/// has no record of.
+///
+/// A build constant, identical on every replica, so two replicas holding identical
+/// state still serialize identically (see [`MetadataSnapshot`]).
+pub const SNAPSHOT_RELEASE_FORMAT: u32 = IGGY_PROTOCOL_VERSION;
+
+const _: () = assert!(SNAPSHOT_RELEASE_FORMAT > 0);
+
 #[derive(Debug)]
 pub enum SnapshotError {
     /// Serialization failed.
@@ -42,6 +78,12 @@ pub enum SnapshotError {
     ChecksumMismatch { expected: u128, actual: u128 },
     /// Snapshot file is too short to contain a valid checksum.
     Truncated { size: u64 },
+    /// The snapshot was written in a format version this build does not read: a
+    /// different build wrote it, on this disk or on a state-transfer peer. Refuse it
+    /// rather than let msgpack read one field's bytes as another's. The version is
+    /// peeked ahead of the rest of the payload, so this fires even when nothing past
+    /// it is recognizable.
+    UnsupportedFormatVersion { found: u32, expected: u32 },
     /// A state-transfer descriptor's frontiers contradict its artifacts: a
     /// `commit_op` below the snapshot the same offer ships, or a client-table
     /// frontier above that commit point. Both are impossible from a
@@ -93,6 +135,13 @@ impl fmt::Display for SnapshotError {
                     "snapshot file truncated: {size} bytes (too short for checksum)"
                 )
             }
+            Self::UnsupportedFormatVersion { found, expected } => {
+                write!(
+                    f,
+                    "snapshot format version {found} is incompatible with this build, which \
+                     reads version {expected}"
+                )
+            }
             Self::IncoherentManifest {
                 snapshot_seq,
                 commit_op,
@@ -116,6 +165,7 @@ impl std::error::Error for SnapshotError {
             Self::Io(e) | Self::Persist { source: e, .. } => Some(e),
             Self::ChecksumMismatch { .. }
             | Self::Truncated { .. }
+            | Self::UnsupportedFormatVersion { .. }
             | Self::IncoherentManifest { .. } => None,
         }
     }
@@ -140,8 +190,12 @@ impl From<std::io::Error> for SnapshotError {
 /// `impls::metadata::tests::populated_snapshot_reencode_and_checksum_are_stable`.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MetadataSnapshot {
-    /// Snapshot format version for forward/backward compatibility.
-    /// TODO(krishvishal): Properly handle versioning for snapshot. This is a placeholder for now.
+    /// The version of the snapshot format in use, reserved for breaking changes.
+    /// See [`SNAPSHOT_FORMAT_VERSION`]; [`Self::decode`] refuses anything else.
+    ///
+    /// First field deliberately: msgpack encodes the struct positionally, so this is
+    /// the one element [`peek_format_version`] can pull out before it knows the rest
+    /// of the layout.
     pub version: u32,
     /// Timestamp when the snapshot was created (microseconds since epoch).
     pub created_at: u64,
@@ -154,10 +208,11 @@ pub struct MetadataSnapshot {
     pub streams: Option<StreamsSnapshot>,
     /// Client-table state (sessions + at-most-once dedup replies) at the checkpoint
     /// op. Not a state machine, but folded in so a restart that drained the WAL
-    /// prefix still recovers pre-checkpoint sessions. `#[serde(default)]` so a
-    /// snapshot predating this field decodes as `None`.
-    #[serde(default)]
+    /// prefix still recovers pre-checkpoint sessions.
     pub client_table: Option<consensus::ClientTableSnapshot>,
+    /// The release that wrote this snapshot, as a packed `iggy_binary_protocol`
+    /// semver. Provenance only, never a gate. See [`SNAPSHOT_RELEASE_FORMAT`].
+    pub release_format: u32,
 }
 
 impl Default for MetadataSnapshot {
@@ -171,7 +226,7 @@ impl MetadataSnapshot {
     #[must_use]
     pub const fn new(sequence_number: u64) -> Self {
         Self {
-            version: 1,
+            version: SNAPSHOT_FORMAT_VERSION,
             // Deterministic placeholder. The real creation time is stamped by
             // `Snapshot::create` from the consensus-injected clock (see
             // `VsrConsensus::clock_realtime_micros`) so a replayed simulator
@@ -182,6 +237,7 @@ impl MetadataSnapshot {
             users: None,
             streams: None,
             client_table: None,
+            release_format: SNAPSHOT_RELEASE_FORMAT,
         }
     }
 
@@ -193,15 +249,51 @@ impl MetadataSnapshot {
         rmp_serde::to_vec(self).map_err(SnapshotError::Serialize)
     }
 
-    /// Decode a snapshot from msgpack bytes.
+    /// Decode a snapshot from msgpack bytes, refusing a format version this build
+    /// does not read.
+    ///
+    /// The version is checked before the payload is deserialized, so a snapshot
+    /// whose layout past that field is unknown is refused by version rather than by
+    /// whichever later field happened to misparse.
     ///
     /// # Errors
-    /// Returns `SnapshotError::Deserialize` if msgpack deserialization fails.
+    /// [`SnapshotError::UnsupportedFormatVersion`] when the stamped version is not
+    /// [`SNAPSHOT_FORMAT_VERSION`], or [`SnapshotError::Deserialize`] if msgpack
+    /// deserialization fails.
     pub fn decode(bytes: &[u8]) -> Result<Self, SnapshotError> {
+        // Bytes carrying no readable version are not a snapshot at all, so they fall
+        // through to the deserializer, whose error names what actually went wrong.
+        if let Some(version) = peek_format_version(bytes)
+            && version != SNAPSHOT_FORMAT_VERSION
+        {
+            return Err(SnapshotError::UnsupportedFormatVersion {
+                found: version,
+                expected: SNAPSHOT_FORMAT_VERSION,
+            });
+        }
         rmp_serde::from_slice(bytes).map_err(SnapshotError::Deserialize)
     }
 }
 
+/// The format version stamped in encoded snapshot bytes, read without decoding the
+/// rest of them.
+///
+/// `None` for anything that is not a msgpack array whose first element is an
+/// unsigned integer, which covers every input that is not a snapshot.
+///
+/// Reading the version on its own is what keeps the check working across a layout
+/// change: deserializing the whole struct first would let some later field fail and
+/// report a msgpack error naming no version, which is the difference between "this
+/// file came from a newer build" and "this file is corrupt". `journal::superblock`
+/// reads its own version field the same way, ahead of the length and checksum it
+/// cannot yet trust.
+#[must_use]
+pub fn peek_format_version(encoded: &[u8]) -> Option<u32> {
+    let mut cursor = encoded;
+    rmp::decode::read_array_len(&mut cursor).ok()?;
+    rmp::decode::read_int(&mut cursor).ok()
+}
+
 /// Trait for metadata snapshot implementations.
 ///
 /// This is the high-level interface that concrete snapshot types (e.g. `IggySnapshot`)
@@ -435,11 +527,112 @@ mod tests {
         let decoded = MetadataSnapshot::decode(&encoded).unwrap();
 
         assert_eq!(decoded.sequence_number, 42);
+        assert_eq!(decoded.version, SNAPSHOT_FORMAT_VERSION);
+        assert_eq!(decoded.release_format, SNAPSHOT_RELEASE_FORMAT);
         assert!(decoded.users.is_none());
         assert!(decoded.streams.is_none());
         assert!(decoded.client_table.is_none());
     }
 
+    #[test]
+    fn a_build_decodes_what_it_writes() {
+        // Exact-equality versioning makes this the one thing that could go wrong
+        // silently: a stamp the writer picks and the reader rejects would refuse every
+        // node its own snapshot on the next boot.
+        let encoded = MetadataSnapshot::new(5).encode().unwrap();
+        MetadataSnapshot::decode(&encoded).expect("a build must read its own snapshot");
+    }
+
+    #[test]
+    fn release_stamp_is_a_build_constant() {
+        // Two replicas holding identical state must serialize identically, which a
+        // per-node or per-write release stamp would break.
+        assert_eq!(
+            MetadataSnapshot::new(1).encode().unwrap(),
+            MetadataSnapshot::new(1).encode().unwrap()
+        );
+    }
+
+    #[test]
+    fn encoded_snapshot_leads_with_the_version_element() {
+        // `peek_format_version` rests on this shape: a msgpack array (`rmp_serde`'s
+        // compact struct encoding) whose first element is `version`. Switching to
+        // `to_vec_named` would encode a map instead and silently blind the peek, so
+        // pin it here.
+        let encoded = MetadataSnapshot::new(3).encode().unwrap();
+        assert_eq!(
+            encoded[0] & 0xf0,
+            0x90,
+            "snapshot must encode as a msgpack fixarray"
+        );
+        assert_eq!(
+            peek_format_version(&encoded),
+            Some(SNAPSHOT_FORMAT_VERSION),
+            "the first array element must be the format version"
+        );
+    }
+
+    #[test]
+    fn peek_format_version_ignores_bytes_that_are_not_a_snapshot() {
+        assert_eq!(peek_format_version(&[]), None);
+        // A msgpack string, not an array.
+        assert_eq!(peek_format_version(&[0xa1, b'x']), None);
+        // An array whose first element is not an unsigned integer.
+        assert_eq!(peek_format_version(&[0x91, 0xc0]), None);
+    }
+
+    #[test]
+    fn decode_refuses_any_other_format_version() {
+        // Newer and older alike: there is no accepted window, so both directions are
+        // the same refusal. Version 0 is what a zeroed or absent stamp reads as.
+        for forged in [SNAPSHOT_FORMAT_VERSION + 1, 0] {
+            let mut snapshot = MetadataSnapshot::new(9);
+            snapshot.version = forged;
+            let encoded = snapshot.encode().unwrap();
+
+            match MetadataSnapshot::decode(&encoded) {
+                Err(SnapshotError::UnsupportedFormatVersion { found, expected }) => {
+                    assert_eq!(found, forged);
+                    assert_eq!(expected, SNAPSHOT_FORMAT_VERSION);
+                }
+                other => panic!("expected an unsupported-version refusal, got {other:?}"),
+            }
+        }
+    }
+
+    #[test]
+    fn decode_refuses_a_shape_change_by_version_not_by_msgpack() {
+        // The reason the version is peeked instead of read off the decoded struct: a
+        // future build's layout need not decode at all under this one, and the refusal
+        // must still name the version rather than whichever field happened to
+        // misparse. Emulated by appending an element, which is what a field append
+        // looks like on the wire.
+        let mut snapshot = MetadataSnapshot::new(4);
+        snapshot.version = SNAPSHOT_FORMAT_VERSION + 1;
+        let current = snapshot.encode().unwrap();
+        assert_eq!(current[0] & 0xf0, 0x90, "expected a msgpack fixarray");
+        let mut future = vec![0x90 | ((current[0] & 0x0f) + 1)];
+        future.extend_from_slice(&current[1..]);
+        future.push(0xc0);
+
+        match MetadataSnapshot::decode(&future) {
+            Err(SnapshotError::UnsupportedFormatVersion { found, .. }) => {
+                assert_eq!(found, SNAPSHOT_FORMAT_VERSION + 1);
+            }
+            other => panic!("expected an unsupported-version refusal, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn decode_reports_deserialization_when_no_version_is_readable() {
+        // Bytes carrying no version field are corruption, not a version skew, and the
+        // msgpack error names that far better than a fabricated version would.
+        match MetadataSnapshot::decode(&[0xa3, b'n', b'o', b'!']) {
+            Err(SnapshotError::Deserialize(_)) => {}
+            other => panic!("expected a deserialization error, got {other:?}"),
+        }
+    }
+
     #[test]
     fn roundtrip_with_data() {
         let ts = IggyTimestamp::from(1_694_968_446_131_680_u64);