refactor(segment): collapse footer format v1/v2 into a single version

Every segment has carried an encrypted extent index since the format
gained one, so the v1/no-index and v2/indexed footer layouts no longer
describe a real distinction. Fold both into one FORMAT_VERSION with a
fixed field layout, drop the version-conditional branches from the
footer encoder/decoder and metadata validator, and let index_page_count
== 0 stand for "no extents" without a separate version tag.

Author: farhan-syah

src/pager/format/page_kind.rs

@@ -22,9 +22,10 @@ pub enum PageKind {
     /// before an `apply_incremental` header swap to record the segment
     /// promotions and tombstones that must be completed after the swap.
     ApplyJournal = 0x08,
-    /// v2 overflow root page. Carries a `refcount: u32` in its body header
-    /// before the `next` pointer. Chain pages (not the root) continue to use
-    /// `PageKind::Overflow`. This crate always writes the count as 1 —
+    /// First page of an overflow chain. Carries a `refcount: u32` in its body
+    /// header before the `next` pointer, which is what distinguishes it from
+    /// the chain's later pages — those use `PageKind::Overflow`. This crate
+    /// always writes the count as 1 —
     /// snapshot lifetime comes from commit-tagged page reclamation — but the
     /// release path still honours a larger count so a root produced elsewhere
     /// decodes correctly.

src/pager/format/segment_footer/decode.rs

@@ -4,8 +4,8 @@ use crate::{RealmId, Result};
 
 use super::auth::{constant_time_eq, footer_aad, mac_hk};
 use super::fields::{
-    FOOTER_CLEARTEXT_END_V1, FOOTER_CLEARTEXT_END_V2, FOOTER_FIELDS_END_V1, FOOTER_FIELDS_END_V2,
-    MAGIC, MANIFEST_TAG_LEN, SegmentFooterFields, max_manifest_len, max_manifest_len_v2,
+    FOOTER_CLEARTEXT_END, FOOTER_FIELDS_END, FORMAT_VERSION, MAGIC, MANIFEST_TAG_LEN,
+    SegmentFooterFields, max_manifest_len,
 };
 
 pub fn decode_segment_footer(
@@ -17,47 +17,27 @@ pub fn decode_segment_footer(
     let parsed = parse_cleartext(bytes, page_size)?;
     authenticate_cleartext(bytes, hk, &parsed)?;
     let (fields, ciphertext_end, tag_end) = assemble_fields(bytes, &parsed, cipher)?;
-    let manifest = authenticate_manifest(
-        bytes,
-        cipher,
-        &fields,
-        parsed.cleartext_end,
-        ciphertext_end,
-        tag_end,
-    )?;
+    let manifest = authenticate_manifest(bytes, cipher, &fields, ciphertext_end, tag_end)?;
     Ok((fields, manifest))
 }
 
 struct ParsedFooter {
-    fields_end: usize,
-    cleartext_end: usize,
-    max_manifest: usize,
     manifest_offset: u32,
     manifest_len: usize,
     fields: SegmentFooterFields,
 }
 
 fn parse_cleartext(bytes: &[u8], page_size: usize) -> Result<ParsedFooter> {
-    if bytes.len() != page_size || page_size < FOOTER_CLEARTEXT_END_V1 + MANIFEST_TAG_LEN {
+    if bytes.len() != page_size || page_size < FOOTER_CLEARTEXT_END + MANIFEST_TAG_LEN {
         return Err(PagedbError::Unsupported);
     }
     if bytes[..8] != MAGIC {
         return Err(PagedbError::footer_framing_invalid("magic"));
     }
     let format_version = u16_le(&bytes[8..10]);
-    let (fields_end, cleartext_end, max_manifest) = match format_version {
-        1 => (
-            FOOTER_FIELDS_END_V1,
-            FOOTER_CLEARTEXT_END_V1,
-            max_manifest_len(page_size),
-        ),
-        2 if page_size >= FOOTER_CLEARTEXT_END_V2 + MANIFEST_TAG_LEN => (
-            FOOTER_FIELDS_END_V2,
-            FOOTER_CLEARTEXT_END_V2,
-            max_manifest_len_v2(page_size),
-        ),
-        _ => return Err(PagedbError::Unsupported),
-    };
+    if format_version != FORMAT_VERSION {
+        return Err(PagedbError::footer_framing_invalid("format_version"));
+    }
     let mut offset = 10;
     let cipher_id = bytes[offset];
     offset += 1;
@@ -80,26 +60,10 @@ fn parse_cleartext(bytes: &[u8], page_size: usize) -> Result<ParsedFooter> {
     let manifest_len = usize::try_from(u32_le(&bytes[offset..offset + 4]))
         .map_err(|_| PagedbError::Unsupported)?;
     offset += 4;
-    let (index_start_page, index_page_count) = if format_version == 2 {
-        (
-            u64_le(&bytes[offset..offset + 8]),
-            u32_le(&bytes[offset + 8..offset + 12]),
-        )
-    } else {
-        (0, 0)
-    };
-    debug_assert_eq!(
-        if format_version == 2 {
-            offset + 12
-        } else {
-            offset
-        },
-        fields_end
-    );
+    let index_start_page = u64_le(&bytes[offset..offset + 8]);
+    let index_page_count = u32_le(&bytes[offset + 8..offset + 12]);
+    debug_assert_eq!(offset + 12, FOOTER_FIELDS_END);
     Ok(ParsedFooter {
-        fields_end,
-        cleartext_end,
-        max_manifest,
         manifest_offset,
         manifest_len,
         fields: SegmentFooterFields {
@@ -123,13 +87,13 @@ fn authenticate_cleartext(
     hk: &crate::crypto::keys::DerivedKey,
     parsed: &ParsedFooter,
 ) -> Result<()> {
-    let mac = mac_hk(hk, &bytes[..parsed.fields_end])?;
-    let valid_mac = constant_time_eq(&mac, &bytes[parsed.fields_end..parsed.cleartext_end]);
+    let mac = mac_hk(hk, &bytes[..FOOTER_FIELDS_END])?;
+    let valid_mac = constant_time_eq(&mac, &bytes[FOOTER_FIELDS_END..FOOTER_CLEARTEXT_END]);
     let expected_offset =
-        u32::try_from(parsed.cleartext_end).map_err(|_| PagedbError::Unsupported)?;
+        u32::try_from(FOOTER_CLEARTEXT_END).map_err(|_| PagedbError::Unsupported)?;
     if !valid_mac
         || parsed.manifest_offset != expected_offset
-        || parsed.manifest_len > parsed.max_manifest
+        || parsed.manifest_len > max_manifest_len(bytes.len())
     {
         return Err(PagedbError::footer_framing_invalid(
             "manifest_offset_or_length",
@@ -152,8 +116,7 @@ fn assemble_fields(
             },
         ));
     }
-    let ciphertext_end = parsed
-        .cleartext_end
+    let ciphertext_end = FOOTER_CLEARTEXT_END
         .checked_add(parsed.manifest_len)
         .ok_or_else(|| PagedbError::arithmetic_overflow("footer manifest end"))?;
     let tag_end = ciphertext_end
@@ -169,7 +132,6 @@ fn authenticate_manifest(
     bytes: &[u8],
     cipher: &Cipher,
     fields: &SegmentFooterFields,
-    cleartext_end: usize,
     ciphertext_end: usize,
     tag_end: usize,
 ) -> Result<Vec<u8>> {
@@ -181,7 +143,7 @@ fn authenticate_manifest(
     let mut file_id = [0u8; 6];
     file_id.copy_from_slice(&fields.segment_id[..6]);
     let nonce = Nonce::from_parts(file_id, nonce_counter);
-    let mut manifest = bytes[cleartext_end..ciphertext_end].to_vec();
+    let mut manifest = bytes[FOOTER_CLEARTEXT_END..ciphertext_end].to_vec();
     let mut tag = [0u8; MANIFEST_TAG_LEN];
     tag.copy_from_slice(&bytes[ciphertext_end..tag_end]);
     cipher

src/pager/format/segment_footer/encode.rs

@@ -4,9 +4,8 @@ use crate::errors::PagedbError;
 
 use super::auth::{footer_aad, mac_hk};
 use super::fields::{
-    FOOTER_CLEARTEXT_END_V1, FOOTER_CLEARTEXT_END_V2, FOOTER_FIELDS_END_V1, FOOTER_FIELDS_END_V2,
-    FOOTER_HEADER_MAC_LEN, MANIFEST_TAG_LEN, SegmentFooterFields, max_manifest_len,
-    max_manifest_len_v2,
+    FOOTER_CLEARTEXT_END, FOOTER_FIELDS_END, FOOTER_HEADER_MAC_LEN, FORMAT_VERSION,
+    MANIFEST_TAG_LEN, SegmentFooterFields, max_manifest_len,
 };
 
 pub fn encode_segment_footer(
@@ -16,27 +15,21 @@ pub fn encode_segment_footer(
     cipher: &Cipher,
     page_size: usize,
 ) -> Result<Vec<u8>> {
-    let (fields_end, cleartext_end) = match fields.format_version {
-        1 => (FOOTER_FIELDS_END_V1, FOOTER_CLEARTEXT_END_V1),
-        2 => (FOOTER_FIELDS_END_V2, FOOTER_CLEARTEXT_END_V2),
-        _ => return Err(PagedbError::Unsupported),
-    };
-    if page_size < cleartext_end + MANIFEST_TAG_LEN {
+    if fields.format_version != FORMAT_VERSION {
         return Err(PagedbError::Unsupported);
     }
-    let max_manifest = if fields.format_version == 1 {
-        max_manifest_len(page_size)
-    } else {
-        max_manifest_len_v2(page_size)
-    };
-    if manifest.len() > max_manifest {
+    if page_size < FOOTER_CLEARTEXT_END + MANIFEST_TAG_LEN {
+        return Err(PagedbError::Unsupported);
+    }
+    if manifest.len() > max_manifest_len(page_size) {
         return Err(PagedbError::ManifestTooLarge);
     }
     if cipher.id().as_byte() != fields.cipher_id {
         return Err(PagedbError::Unsupported);
     }
 
-    let manifest_offset = u32::try_from(cleartext_end).map_err(|_| PagedbError::Unsupported)?;
+    let manifest_offset =
+        u32::try_from(FOOTER_CLEARTEXT_END).map_err(|_| PagedbError::Unsupported)?;
     let manifest_len = u32::try_from(manifest.len()).map_err(|_| PagedbError::ManifestTooLarge)?;
     let mut out = vec![0u8; page_size];
     let mut offset = 0usize;
@@ -64,17 +57,15 @@ pub fn encode_segment_footer(
     offset += 4;
     out[offset..offset + 4].copy_from_slice(&manifest_len.to_le_bytes());
     offset += 4;
-    if fields.format_version == 2 {
-        out[offset..offset + 8].copy_from_slice(&fields.index_start_page.to_le_bytes());
-        offset += 8;
-        out[offset..offset + 4].copy_from_slice(&fields.index_page_count.to_le_bytes());
-        offset += 4;
-    }
-    debug_assert_eq!(offset, fields_end);
+    out[offset..offset + 8].copy_from_slice(&fields.index_start_page.to_le_bytes());
+    offset += 8;
+    out[offset..offset + 4].copy_from_slice(&fields.index_page_count.to_le_bytes());
+    offset += 4;
+    debug_assert_eq!(offset, FOOTER_FIELDS_END);
     let mac = mac_hk(hk, &out[..offset])?;
     out[offset..offset + FOOTER_HEADER_MAC_LEN].copy_from_slice(&mac);
     offset += FOOTER_HEADER_MAC_LEN;
-    debug_assert_eq!(offset, cleartext_end);
+    debug_assert_eq!(offset, FOOTER_CLEARTEXT_END);
 
     let nonce_counter = fields
         .final_counter
@@ -84,14 +75,14 @@ pub fn encode_segment_footer(
     let mut file_id = [0u8; 6];
     file_id.copy_from_slice(&fields.segment_id[..6]);
     let nonce = Nonce::from_parts(file_id, nonce_counter);
-    let manifest_end = cleartext_end
+    let manifest_end = FOOTER_CLEARTEXT_END
         .checked_add(manifest.len())
         .ok_or_else(|| PagedbError::arithmetic_overflow("footer manifest end"))?;
-    out[cleartext_end..manifest_end].copy_from_slice(manifest);
+    out[FOOTER_CLEARTEXT_END..manifest_end].copy_from_slice(manifest);
     let tag = cipher.encrypt(
         &nonce,
         &footer_aad(fields),
-        &mut out[cleartext_end..manifest_end],
+        &mut out[FOOTER_CLEARTEXT_END..manifest_end],
     )?;
     let tag_end = manifest_end
         .checked_add(MANIFEST_TAG_LEN)

src/pager/format/segment_footer/fields.rs

@@ -1,18 +1,18 @@
 use crate::RealmId;
 
 pub const MAGIC: [u8; 8] = *b"PAGESEAL";
-pub const FOOTER_FIELDS_END_V1: usize = 99;
-pub const FOOTER_FIELDS_END_V2: usize = FOOTER_FIELDS_END_V1 + 12;
+
+/// The only `format_version` this decoder accepts. The field is persisted so a
+/// later layout can be introduced without ambiguity; any other value is a
+/// footer this build cannot interpret and is rejected as corruption.
+pub const FORMAT_VERSION: u16 = 1;
+
+/// End of the MAC-covered cleartext field block.
+pub const FOOTER_FIELDS_END: usize = 111;
 pub const FOOTER_HEADER_MAC_LEN: usize = 16;
-pub const FOOTER_CLEARTEXT_END_V1: usize = FOOTER_FIELDS_END_V1 + FOOTER_HEADER_MAC_LEN;
-pub const FOOTER_CLEARTEXT_END_V2: usize = FOOTER_FIELDS_END_V2 + FOOTER_HEADER_MAC_LEN;
-/// Unversioned aliases for the v1 boundaries. Encode and decode always select
-/// a boundary from the footer's own `format_version`, so only the tamper tests
-/// — which forge a v1 footer and flip the byte at each boundary — name these.
-#[cfg(test)]
-pub const FOOTER_FIELDS_END: usize = FOOTER_FIELDS_END_V1;
-#[cfg(test)]
-pub const FOOTER_CLEARTEXT_END: usize = FOOTER_CLEARTEXT_END_V1;
+/// End of the cleartext prefix — fields plus their MAC. The encrypted manifest
+/// starts here.
+pub const FOOTER_CLEARTEXT_END: usize = FOOTER_FIELDS_END + FOOTER_HEADER_MAC_LEN;
 pub const MANIFEST_TAG_LEN: usize = 16;
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -32,10 +32,5 @@ pub struct SegmentFooterFields {
 
 #[must_use]
 pub const fn max_manifest_len(page_size: usize) -> usize {
-    page_size - FOOTER_CLEARTEXT_END_V1 - MANIFEST_TAG_LEN
-}
-
-#[must_use]
-pub const fn max_manifest_len_v2(page_size: usize) -> usize {
-    page_size - FOOTER_CLEARTEXT_END_V2 - MANIFEST_TAG_LEN
+    page_size - FOOTER_CLEARTEXT_END - MANIFEST_TAG_LEN
 }

src/pager/format/segment_footer/mod.rs

@@ -7,7 +7,7 @@ mod fields;
 
 pub use decode::decode_segment_footer;
 pub use encode::encode_segment_footer;
-pub use fields::{SegmentFooterFields, max_manifest_len, max_manifest_len_v2};
+pub use fields::{FORMAT_VERSION, SegmentFooterFields, max_manifest_len};
 // Layout boundaries the footer tests assert against directly.
 #[cfg(test)]
 pub use fields::{FOOTER_CLEARTEXT_END, FOOTER_FIELDS_END};

src/pager/format/segment_footer/tests.rs

@@ -2,11 +2,11 @@ use crate::RealmId;
 use crate::crypto::Cipher;
 use crate::crypto::kdf::{derive_dek, derive_hk, derive_mk};
 use crate::crypto::nonce::Nonce;
-use crate::errors::PagedbError;
+use crate::errors::{CorruptionDetail, PagedbError};
 
 use super::{
-    FOOTER_CLEARTEXT_END, FOOTER_FIELDS_END, SegmentFooterFields, decode_segment_footer,
-    encode_segment_footer, max_manifest_len,
+    FOOTER_CLEARTEXT_END, FOOTER_FIELDS_END, FORMAT_VERSION, SegmentFooterFields,
+    decode_segment_footer, encode_segment_footer, max_manifest_len,
 };
 
 const PAGE_SIZE: usize = 4096;
@@ -20,7 +20,7 @@ fn keys() -> (crate::crypto::keys::DerivedKey, Cipher) {
 
 fn fields() -> SegmentFooterFields {
     SegmentFooterFields {
-        format_version: 1,
+        format_version: FORMAT_VERSION,
         cipher_id: 1,
         segment_id: [9; 16],
         parent_file_id: [1; 16],
@@ -73,6 +73,39 @@ fn rejects_footer_nonce_beyond_u48_counter_space() {
     assert!(encode_segment_footer(&exhausted, b"manifest", &header, &cipher, PAGE_SIZE).is_ok());
 }
 
+#[test]
+fn rejects_footer_whose_declared_format_version_is_not_the_accepted_one() {
+    let (header, cipher) = keys();
+    let encoded =
+        encode_segment_footer(&fields(), b"manifest", &header, &cipher, PAGE_SIZE).unwrap();
+    for declared in [FORMAT_VERSION - 1, FORMAT_VERSION + 1, u16::MAX] {
+        let mut forged = encoded.clone();
+        forged[8..10].copy_from_slice(&declared.to_le_bytes());
+        assert!(
+            matches!(
+                decode_segment_footer(&forged, &header, &cipher, PAGE_SIZE),
+                Err(PagedbError::Corruption(
+                    CorruptionDetail::FooterFramingInvalid {
+                        field: "format_version"
+                    }
+                ))
+            ),
+            "format_version={declared} must be rejected as unreadable framing"
+        );
+    }
+}
+
+#[test]
+fn refuses_to_encode_a_footer_under_an_unaccepted_format_version() {
+    let (header, cipher) = keys();
+    let mut unknown = fields();
+    unknown.format_version = FORMAT_VERSION + 1;
+    assert!(matches!(
+        encode_segment_footer(&unknown, b"manifest", &header, &cipher, PAGE_SIZE),
+        Err(PagedbError::Unsupported)
+    ));
+}
+
 #[test]
 fn rejects_header_mac_and_manifest_tampering() {
     let (header, cipher) = keys();