fix(errors): replace generic HeaderUnverifiable with precise corruption variants

Every structural-decode failure across the btree, catalog, pager,
recovery, segment, snapshot, and txn/rekey code paths previously
collapsed into the same CorruptionDetail::HeaderUnverifiable, hiding
which invariant actually failed. Split it into purpose-built variants
(StructuralHeaderInvalid, FooterFramingInvalid, NodeBodyMalformed,
NodeKindMismatch, OverflowBodyMalformed, JournalRecordMalformed,
SnapshotArtifactInvalid) and route each call site through the matching
constructor with a field name, so operators diagnosing corruption can
tell what broke and where.

Author: farhan-syah

src/btree/internal.rs

@@ -27,9 +27,7 @@ impl Internal {
     pub fn decode(body: &[u8]) -> Result<Self> {
         let h: NodeHeader = validate_node_body(body)?;
         if h.kind != NodeKind::Internal {
-            return Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
-            ));
+            return Err(PagedbError::node_kind_mismatch(None, "internal", "leaf"));
         }
         let prefix_len = h.prefix_len as usize;
         let mut entries = Vec::with_capacity(h.slot_count as usize);
@@ -167,9 +165,7 @@ impl<'a> InternalAccessor<'a> {
     pub fn new(body: &'a [u8]) -> Result<Self> {
         let h = validate_node_body(body)?;
         if h.kind != NodeKind::Internal {
-            return Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
-            ));
+            return Err(PagedbError::node_kind_mismatch(None, "internal", "leaf"));
         }
         // Internal nodes always encode with prefix_len = 0 today; if that ever
         // changes, this accessor needs the same prefix handling as LeafAccessor.

src/btree/leaf.rs

@@ -51,9 +51,7 @@ impl Leaf {
     pub fn decode(body: &[u8]) -> Result<Self> {
         let h: NodeHeader = validate_node_body(body)?;
         if h.kind != NodeKind::Leaf {
-            return Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
-            ));
+            return Err(PagedbError::node_kind_mismatch(None, "leaf", "internal"));
         }
         let prefix_len = h.prefix_len as usize;
         let prefix_bytes = body[HEADER_LEN..HEADER_LEN + prefix_len].to_vec();
@@ -270,9 +268,7 @@ impl<'a> LeafAccessor<'a> {
     pub fn new(body: &'a [u8]) -> Result<Self> {
         let h = validate_node_body(body)?;
         if h.kind != NodeKind::Leaf {
-            return Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
-            ));
+            return Err(PagedbError::node_kind_mismatch(None, "leaf", "internal"));
         }
         Ok(Self {
             body,

src/btree/node.rs

@@ -1,7 +1,7 @@
 //! Node layout shared by leaf and internal pages.
 
 use crate::Result;
-use crate::errors::{CorruptionDetail, PagedbError};
+use crate::errors::PagedbError;
 use crate::pager::format::data_page::ENVELOPE_OVERHEAD;
 
 /// `node_kind` byte value at offset 0 of the node body.
@@ -17,16 +17,24 @@ impl NodeKind {
         match b {
             0x00 => Ok(Self::Internal),
             0x01 => Ok(Self::Leaf),
-            _ => Err(PagedbError::corruption(
-                CorruptionDetail::HeaderUnverifiable,
-            )),
+            _ => Err(PagedbError::node_body_malformed("node_kind_byte")),
         }
     }
 
     #[must_use]
     pub fn as_byte(self) -> u8 {
         self as u8
     }
+
+    /// Stable lowercase name, for naming both sides of a kind disagreement in
+    /// [`CorruptionDetail::NodeKindMismatch`].
+    #[must_use]
+    pub const fn name(self) -> &'static str {
+        match self {
+            Self::Internal => "internal",
+            Self::Leaf => "leaf",
+        }
+    }
 }
 
 pub const HEADER_LEN: usize = 24;
@@ -91,9 +99,7 @@ pub struct NodeHeader {
 
 pub fn read_header(body: &[u8]) -> Result<NodeHeader> {
     if body.len() < HEADER_LEN {
-        return Err(PagedbError::corruption(
-            CorruptionDetail::HeaderUnverifiable,
-        ));
+        return Err(PagedbError::node_body_malformed("header_length"));
     }
     let kind = NodeKind::from_byte(body[OFF_NODE_KIND])?;
     let slot_count = read_u16_le(body, OFF_SLOT_COUNT);
@@ -117,7 +123,7 @@ pub fn read_header(body: &[u8]) -> Result<NodeHeader> {
 /// entry are attacker- or bug-controlled `u16`s that the decoders and the
 /// zero-copy accessors use directly as slice indices. Without this pass a
 /// malformed-but-authenticated page panics the library (an out-of-range slice
-/// index) instead of surfacing as [`CorruptionDetail::HeaderUnverifiable`],
+/// index) instead of surfacing as [`CorruptionDetail::NodeBodyMalformed`],
 /// which is a strictly worse failure than the one it would report.
 ///
 /// Every constructor that turns raw bytes into a node runs this first, so the
@@ -186,7 +192,7 @@ fn field_end(body: &[u8], start: usize, len: usize) -> Result<usize> {
 }
 
 fn malformed() -> PagedbError {
-    PagedbError::corruption(CorruptionDetail::HeaderUnverifiable)
+    PagedbError::node_body_malformed("slot_directory")
 }
 
 pub fn write_header(
@@ -209,6 +215,7 @@ pub fn write_header(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::errors::CorruptionDetail;
 
     const CAP: usize = 4056;
 
@@ -217,10 +224,10 @@ mod tests {
             matches!(
                 validate_node_body(body),
                 Err(PagedbError::Corruption(
-                    CorruptionDetail::HeaderUnverifiable
+                    CorruptionDetail::NodeBodyMalformed { .. }
                 ))
             ),
-            "{label}: expected HeaderUnverifiable"
+            "{label}: expected NodeBodyMalformed"
         );
     }
 

src/btree/overflow.rs

@@ -71,8 +71,8 @@ pub fn encode_overflow(body: &mut [u8], next: u64, data: &[u8]) -> Result<()> {
 /// Decode an overflow chain page body (non-root). Returns `(next, data_slice)`.
 pub fn decode_overflow(body: &[u8]) -> Result<(u64, &[u8])> {
     if body.len() < OVERFLOW_HEADER_LEN {
-        return Err(PagedbError::corruption(
-            crate::errors::CorruptionDetail::HeaderUnverifiable,
+        return Err(PagedbError::overflow_body_malformed(
+            "chain_page.header_length",
         ));
     }
     let mut n = [0u8; 8];
@@ -82,8 +82,8 @@ pub fn decode_overflow(body: &[u8]) -> Result<(u64, &[u8])> {
     l.copy_from_slice(&body[8..12]);
     let data_len = u32::from_le_bytes(l) as usize;
     if 12 + data_len > body.len() {
-        return Err(PagedbError::corruption(
-            crate::errors::CorruptionDetail::HeaderUnverifiable,
+        return Err(PagedbError::overflow_body_malformed(
+            "chain_page.data_length",
         ));
     }
     Ok((next, &body[12..12 + data_len]))
@@ -112,9 +112,7 @@ fn encode_overflow_root(body: &mut [u8], refcount: u32, next: u64, data: &[u8])
 /// Decode an overflow root page body. Returns `(refcount, next, data_slice)`.
 fn decode_overflow_root(body: &[u8]) -> Result<(u32, u64, &[u8])> {
     if body.len() < OVERFLOW_ROOT_HEADER_LEN {
-        return Err(PagedbError::corruption(
-            crate::errors::CorruptionDetail::HeaderUnverifiable,
-        ));
+        return Err(PagedbError::overflow_body_malformed("root.header_length"));
     }
     let mut r = [0u8; 4];
     r.copy_from_slice(&body[0..4]);
@@ -126,9 +124,7 @@ fn decode_overflow_root(body: &[u8]) -> Result<(u32, u64, &[u8])> {
     l.copy_from_slice(&body[12..16]);
     let data_len = u32::from_le_bytes(l) as usize;
     if 16 + data_len > body.len() {
-        return Err(PagedbError::corruption(
-            crate::errors::CorruptionDetail::HeaderUnverifiable,
-        ));
+        return Err(PagedbError::overflow_body_malformed("root.data_length"));
     }
     Ok((refcount, next, &body[16..16 + data_len]))
 }
@@ -323,8 +319,8 @@ pub async fn read_chain<V: Vfs>(
         next = n;
     }
     if out.len() as u64 != total_len {
-        return Err(PagedbError::corruption(
-            crate::errors::CorruptionDetail::HeaderUnverifiable,
+        return Err(PagedbError::overflow_body_malformed(
+            "chain.assembled_length",
         ));
     }
     Ok(out)

src/btree/tree/core.rs

@@ -3,7 +3,7 @@
 use std::collections::HashMap;
 use std::sync::Arc;
 
-use crate::errors::{CorruptionDetail, PagedbError};
+use crate::errors::PagedbError;
 use crate::pager::format::page_kind::PageKind;
 use crate::pager::{PageGuard, Pager};
 use crate::vfs::Vfs;
@@ -253,8 +253,13 @@ impl<V: Vfs> BTree<V> {
             _ => return Err(PagedbError::IllegalPageKind),
         };
         if decoded_kind != expected_kind {
-            return Err(PagedbError::corruption(
-                CorruptionDetail::HeaderUnverifiable,
+            // The envelope is authenticated and the body is not, so name both
+            // and the page: this is a mis-routed page, not damaged content, and
+            // an operator chasing it needs to know which side to trust.
+            return Err(PagedbError::node_kind_mismatch(
+                Some(page_id),
+                expected_kind.name(),
+                decoded_kind.name(),
             ));
         }
         Ok((guard, decoded_kind))

src/catalog/codec.rs

@@ -57,9 +57,7 @@ impl RekeyStage {
             3 => Ok(Self::HeaderTargetPublished),
             4 => Ok(Self::MainDone),
             5 => Ok(Self::SegmentsPending),
-            _ => Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
-            )),
+            _ => Err(PagedbError::catalog_row_invalid("rekey.stage")),
         }
     }
 }
@@ -111,8 +109,8 @@ impl RekeySegmentProgressState {
     fn from_byte(byte: u8) -> Result<Self> {
         match byte {
             1 => Ok(Self::Sealed),
-            _ => Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
+            _ => Err(PagedbError::catalog_row_invalid(
+                "rekey.segment_progress.state",
             )),
         }
     }
@@ -257,12 +255,13 @@ impl Catalog {
     /// positional progress is deliberately preserved only for diagnostics.
     pub fn decode_rekey_state(bytes: &[u8]) -> Result<RekeyStateRow> {
         if bytes.len() == LEGACY_REKEY_STATE_LEN {
-            let target_mk_epoch = u64::from_le_bytes(bytes[0..8].try_into().map_err(|_| {
-                PagedbError::corruption(crate::errors::CorruptionDetail::HeaderUnverifiable)
-            })?);
+            let target_mk_epoch =
+                u64::from_le_bytes(bytes[0..8].try_into().map_err(|_| {
+                    PagedbError::catalog_row_invalid("rekey.legacy.target_mk_epoch")
+                })?);
             if target_mk_epoch == 0 {
-                return Err(PagedbError::corruption(
-                    crate::errors::CorruptionDetail::HeaderUnverifiable,
+                return Err(PagedbError::catalog_row_invalid(
+                    "rekey.legacy.target_mk_epoch",
                 ));
             }
             return Ok(RekeyStateRow::Legacy(LegacyRekeyState {
@@ -271,15 +270,13 @@ impl Catalog {
                     0 => false,
                     1 => true,
                     _ => {
-                        return Err(PagedbError::corruption(
-                            crate::errors::CorruptionDetail::HeaderUnverifiable,
+                        return Err(PagedbError::catalog_row_invalid(
+                            "rekey.legacy.main_db_done",
                         ));
                     }
                 },
                 discarded_segments_index: u32::from_le_bytes(bytes[9..13].try_into().map_err(
-                    |_| {
-                        PagedbError::corruption(crate::errors::CorruptionDetail::HeaderUnverifiable)
-                    },
+                    |_| PagedbError::catalog_row_invalid("rekey.legacy.discarded_segments_index"),
                 )?),
             }));
         }
@@ -289,28 +286,26 @@ impl Catalog {
             || bytes[22..24].iter().any(|byte| *byte != 0)
             || bytes[56..].iter().any(|byte| *byte != 0)
         {
-            return Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
-            ));
+            return Err(PagedbError::catalog_row_invalid("rekey.framing"));
         }
-        let source_mk_epoch = u64::from_le_bytes(bytes[4..12].try_into().map_err(|_| {
-            PagedbError::corruption(crate::errors::CorruptionDetail::HeaderUnverifiable)
-        })?);
-        let target_mk_epoch = u64::from_le_bytes(bytes[12..20].try_into().map_err(|_| {
-            PagedbError::corruption(crate::errors::CorruptionDetail::HeaderUnverifiable)
-        })?);
+        let source_mk_epoch = u64::from_le_bytes(
+            bytes[4..12]
+                .try_into()
+                .map_err(|_| PagedbError::catalog_row_invalid("rekey.source_mk_epoch"))?,
+        );
+        let target_mk_epoch = u64::from_le_bytes(
+            bytes[12..20]
+                .try_into()
+                .map_err(|_| PagedbError::catalog_row_invalid("rekey.target_mk_epoch"))?,
+        );
         if target_mk_epoch == 0 || target_mk_epoch <= source_mk_epoch {
-            return Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
-            ));
+            return Err(PagedbError::catalog_row_invalid("rekey.epoch_ordering"));
         }
         let same_kek = match bytes[2] {
             0 => false,
             1 => true,
             _ => {
-                return Err(PagedbError::corruption(
-                    crate::errors::CorruptionDetail::HeaderUnverifiable,
-                ));
+                return Err(PagedbError::catalog_row_invalid("rekey.same_kek"));
             }
         };
         crate::crypto::CipherId::from_byte(bytes[20])?;
@@ -352,8 +347,8 @@ impl Catalog {
             || bytes[0] != 1
             || bytes[2..4].iter().any(|byte| *byte != 0)
         {
-            return Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
+            return Err(PagedbError::catalog_row_invalid(
+                "rekey.segment_progress.framing",
             ));
         }
         let mut replacement_segment_id = [0u8; 16];
@@ -385,9 +380,7 @@ impl Catalog {
     /// Decode a counter value from an 8-byte little-endian slice.
     pub fn decode_counter(bytes: &[u8]) -> Result<u64> {
         if bytes.len() != 8 {
-            return Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
-            ));
+            return Err(PagedbError::catalog_row_invalid("counter.value"));
         }
         let mut b = [0u8; 8];
         b.copy_from_slice(bytes);
@@ -420,9 +413,7 @@ impl Catalog {
 
     pub fn decode_realm_quotas(bytes: &[u8]) -> Result<RealmQuotas> {
         if bytes.len() != REALM_QUOTAS_LEN {
-            return Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
-            ));
+            return Err(PagedbError::catalog_row_invalid("realm_quotas.length"));
         }
         let mask = bytes[0];
         let read = |off: usize| -> u64 {
@@ -490,9 +481,7 @@ impl Catalog {
 
     pub fn decode_segment_meta(bytes: &[u8]) -> Result<SegmentMeta> {
         if bytes.len() != SEGMENT_META_LEN {
-            return Err(PagedbError::corruption(
-                crate::errors::CorruptionDetail::HeaderUnverifiable,
-            ));
+            return Err(PagedbError::catalog_row_invalid("segment_meta.length"));
         }
         let segment_id = {
             let mut b = [0u8; 16];
@@ -547,9 +536,7 @@ impl Catalog {
             0 => Evictable::Authoritative,
             1 => Evictable::Replaceable,
             _ => {
-                return Err(PagedbError::corruption(
-                    crate::errors::CorruptionDetail::HeaderUnverifiable,
-                ));
+                return Err(PagedbError::catalog_row_invalid("segment_meta.evictable"));
             }
         };
         Ok(SegmentMeta {