hdf5_reader/

object_header.rs

//! HDF5 Object Header parser (v1 and v2).
//!
//! Object headers contain a collection of header messages that describe an
//! HDF5 object (group, dataset, committed datatype, etc.).  Two on-disk
//! formats exist:
//!
//! * **Version 1** (HDF5 < 1.8) — 16-byte fixed prefix, messages each have an
//!   8-byte envelope (type u16 + size u16 + flags u8 + reserved 3).
//! * **Version 2** (HDF5 >= 1.8) — begins with the `OHDR` signature, variable-
//!   length prefix, messages have a 4-or-6-byte envelope, and every chunk is
//!   checksummed with Jenkins lookup3.
//!
//! Continuation messages (type `0x0010`) cause the parser to follow an offset
//! to an additional chunk of messages (an `OCHK` block in v2, or a raw message
//! run in v1).

use crate::checksum::jenkins_lookup3;
use crate::error::{Error, Result};
use crate::io::Cursor;
use crate::messages::shared::SharedMessage;
use crate::messages::{parse_message, HdfMessage};

/// Magic signature for v2 object headers.
const OHDR_SIGNATURE: [u8; 4] = *b"OHDR";

/// Magic signature for v2 continuation chunks.
const OCHK_SIGNATURE: [u8; 4] = *b"OCHK";

/// Header continuation message type id.
const MSG_TYPE_CONTINUATION: u16 = 0x0010;

/// Nil (padding) message type id.
const MSG_TYPE_NIL: u16 = 0x0000;

/// Parsed object header with all its messages.
#[derive(Debug, Clone)]
pub struct ObjectHeader {
    /// Object header format version (1 or 2).
    pub version: u8,
    /// All parsed header messages, collected from every chunk.
    pub messages: Vec<HdfMessage>,
    /// Object reference count.
    pub reference_count: u32,
    /// Modification time in seconds since the UNIX epoch (v2 only, when the
    /// "times stored" flag is set).
    pub modification_time: Option<u32>,
}

impl ObjectHeader {
    /// Parse an object header at the given absolute file address.
    ///
    /// `data` is the entire file mapped into memory, `address` is the byte
    /// offset where the object header starts, and `offset_size` / `length_size`
    /// come from the superblock.
    pub fn parse_at(data: &[u8], address: u64, offset_size: u8, length_size: u8) -> Result<Self> {
        let mut cursor = Cursor::new(data);
        cursor.set_position(address);

        // Peek at the first four bytes to decide v1 vs v2.
        let sig = cursor.peek_bytes(4)?;
        if sig == OHDR_SIGNATURE {
            Self::parse_v2(&cursor, address, offset_size, length_size)
        } else {
            Self::parse_v1(&cursor, address, offset_size, length_size)
        }
    }

    /// Resolve shared messages by following references to other object headers.
    ///
    /// For `SharedInOhdr`, the referenced object header is parsed and the first
    /// matching message type is extracted. `SharedInSohm` returns an error (rare).
    pub fn resolve_shared_messages(
        &mut self,
        data: &[u8],
        offset_size: u8,
        length_size: u8,
    ) -> Result<()> {
        let old_messages = std::mem::take(&mut self.messages);
        let mut resolved = Vec::with_capacity(old_messages.len());
        for msg in old_messages {
            match msg {
                HdfMessage::Shared(SharedMessage::SharedInOhdr { address }) => {
                    match Self::parse_at(data, address, offset_size, length_size) {
                        Ok(target_header) => {
                            // Extract the actual message(s) from the target header.
                            // Typically there is exactly one "real" message (the
                            // committed datatype, fill value, etc.).
                            for target_msg in target_header.messages {
                                match target_msg {
                                    HdfMessage::Nil
                                    | HdfMessage::ObjectHeaderContinuation
                                    | HdfMessage::Shared(_) => continue,
                                    other => {
                                        resolved.push(other);
                                        break;
                                    }
                                }
                            }
                        }
                        Err(_) => {
                            // If we can't parse the target, keep the shared ref
                            resolved
                                .push(HdfMessage::Shared(SharedMessage::SharedInOhdr { address }));
                        }
                    }
                }
                HdfMessage::Shared(SharedMessage::SharedInSohm { .. }) => {
                    self.messages = resolved;
                    return Err(Error::Other(
                        "SOHM table lookup not yet supported — file uses shared object header messages".to_string(),
                    ));
                }
                other => resolved.push(other),
            }
        }
        self.messages = resolved;
        Ok(())
    }

    // ------------------------------------------------------------------
    // Version 1
    // ------------------------------------------------------------------

    /// Parse a version-1 object header.
    ///
    /// Layout (16 bytes total):
    /// ```text
    ///   version          u8    (must be 1)
    ///   reserved         u8
    ///   num_messages     u16
    ///   ref_count        u32
    ///   header_data_size u32   (byte count of the message run)
    ///   reserved         u32   (alignment padding)
    /// ```
    fn parse_v1(base: &Cursor<'_>, address: u64, offset_size: u8, length_size: u8) -> Result<Self> {
        let mut cursor = base.at_offset(address)?;

        let version = cursor.read_u8()?;
        if version != 1 {
            return Err(Error::UnsupportedObjectHeaderVersion(version));
        }

        let _reserved = cursor.read_u8()?;
        let num_messages = cursor.read_u16_le()?;
        let reference_count = cursor.read_u32_le()?;
        let header_data_size = cursor.read_u32_le()? as u64;
        let _reserved2 = cursor.read_u32_le()?; // alignment padding

        // Messages start right after the 16-byte prefix.
        let messages_start = cursor.position();
        let messages_end = messages_start + header_data_size;

        let mut messages: Vec<HdfMessage> = Vec::with_capacity(num_messages as usize);
        let mut continuations: Vec<(u64, u64)> = Vec::new();

        Self::read_v1_messages(
            base,
            messages_start,
            messages_end,
            offset_size,
            length_size,
            &mut messages,
            &mut continuations,
        )?;

        // Follow continuation messages.
        while let Some((cont_offset, cont_length)) = continuations.pop() {
            let cont_end = cont_offset + cont_length;
            Self::read_v1_messages(
                base,
                cont_offset,
                cont_end,
                offset_size,
                length_size,
                &mut messages,
                &mut continuations,
            )?;
        }

        Ok(ObjectHeader {
            version: 1,
            messages,
            reference_count,
            modification_time: None,
        })
    }

    /// Read v1 header messages from `start..end`, appending to `messages`.
    /// Any continuation messages encountered are pushed onto `continuations`
    /// for the caller to follow.
    fn read_v1_messages(
        base: &Cursor<'_>,
        start: u64,
        end: u64,
        offset_size: u8,
        length_size: u8,
        messages: &mut Vec<HdfMessage>,
        continuations: &mut Vec<(u64, u64)>,
    ) -> Result<()> {
        let mut cursor = base.at_offset(start)?;

        while cursor.position() + 8 <= end {
            let msg_type = cursor.read_u16_le()?;
            let msg_data_size = cursor.read_u16_le()? as usize;
            let msg_flags = cursor.read_u8()?;
            let _reserved = cursor.read_bytes(3)?; // 3 reserved bytes

            // Bounds-check the message data within this chunk.
            if cursor.position() + msg_data_size as u64 > end {
                return Err(Error::InvalidData(format!(
                    "v1 message data ({} bytes) extends past header chunk end",
                    msg_data_size
                )));
            }

            if msg_type == MSG_TYPE_NIL {
                // Nil / padding — skip the data bytes.
                cursor.skip(msg_data_size)?;
                messages.push(HdfMessage::Nil);
                continue;
            }

            let msg_data = cursor.read_bytes(msg_data_size)?;
            let is_shared = (msg_flags & 0x02) != 0;

            if is_shared {
                // Shared message — the stored bytes are a shared-message
                // reference, not the message payload itself.
                let shared_msg = crate::messages::shared::parse(
                    &mut Cursor::new(msg_data),
                    offset_size,
                    length_size,
                    msg_data_size,
                )?;
                messages.push(HdfMessage::Shared(shared_msg));
            } else if msg_type == MSG_TYPE_CONTINUATION {
                // Parse the continuation message to get offset + length, then
                // enqueue it for later processing.
                let cont = crate::messages::continuation::parse(
                    &mut Cursor::new(msg_data),
                    offset_size,
                    length_size,
                    msg_data_size,
                )?;
                continuations.push((cont.offset, cont.length));
                messages.push(HdfMessage::ObjectHeaderContinuation);
            } else {
                let parsed = parse_message(
                    msg_type,
                    msg_data.len(),
                    &mut Cursor::new(msg_data),
                    offset_size,
                    length_size,
                )?;
                messages.push(parsed);
            }
        }

        Ok(())
    }

    // ------------------------------------------------------------------
    // Version 2
    // ------------------------------------------------------------------

    /// Parse a version-2 object header.
    ///
    /// Layout:
    /// ```text
    ///   signature  4 bytes  ("OHDR")
    ///   version    u8       (must be 2)
    ///   flags      u8
    ///   [optional timestamps — 4 x u32 if bit 5 of flags]
    ///   [optional attr phase change — 2 x u16 if bit 4 of flags]
    ///   chunk0_size  1/2/4/8 bytes (encoded size depends on bits 0-1 of flags)
    ///   <messages for chunk 0>
    ///   checksum   u32      (Jenkins lookup3 from "OHDR" through last byte before checksum)
    /// ```
    fn parse_v2(base: &Cursor<'_>, address: u64, offset_size: u8, length_size: u8) -> Result<Self> {
        let mut cursor = base.at_offset(address)?;

        // ---- Fixed prefix ----
        let sig = cursor.read_bytes(4)?;
        if sig != OHDR_SIGNATURE {
            return Err(Error::InvalidObjectHeaderSignature);
        }
        let version = cursor.read_u8()?;
        if version != 2 {
            return Err(Error::UnsupportedObjectHeaderVersion(version));
        }
        let flags = cursor.read_u8()?;

        // Bit 5 — timestamps stored.
        let modification_time = if (flags & 0x20) != 0 {
            let _access_time = cursor.read_u32_le()?;
            let mod_time = cursor.read_u32_le()?;
            let _change_time = cursor.read_u32_le()?;
            let _birth_time = cursor.read_u32_le()?;
            Some(mod_time)
        } else {
            None
        };

        // Bit 4 — non-default attribute storage phase change values.
        if (flags & 0x10) != 0 {
            let _max_compact = cursor.read_u16_le()?;
            let _min_dense = cursor.read_u16_le()?;
        }

        // Chunk#0 size — width depends on bits 0-1 of flags.
        let size_field_width = 1usize << (flags & 0x03);
        let chunk0_data_size = cursor.read_uvar(size_field_width)?;

        // Bit 2 — attribute creation order tracked (affects per-message envelope).
        let creation_order_tracked = (flags & 0x04) != 0;

        // Messages for chunk 0 run from the current position for
        // `chunk0_data_size` bytes.  The last 4 bytes of that range are the
        // checksum.
        let messages_start = cursor.position();
        let chunk0_end = messages_start + chunk0_data_size;

        // The checksum covers everything from "OHDR" through the last byte
        // before the checksum field.
        let checksum_start = address as usize;
        let checksum_end = chunk0_end as usize; // the checksum itself sits at chunk0_end
        let stored_checksum = {
            let mut ck = base.at_offset(chunk0_end)?;
            ck.read_u32_le()?
        };
        let computed = jenkins_lookup3(&base.data()[checksum_start..checksum_end]);
        if computed != stored_checksum {
            return Err(Error::ChecksumMismatch {
                expected: stored_checksum,
                actual: computed,
            });
        }

        let mut messages: Vec<HdfMessage> = Vec::new();
        let mut continuations: Vec<(u64, u64)> = Vec::new();

        Self::read_v2_messages(
            base,
            messages_start,
            chunk0_end,
            offset_size,
            length_size,
            creation_order_tracked,
            &mut messages,
            &mut continuations,
        )?;

        // Follow continuation chunks.
        while let Some((cont_offset, cont_length)) = continuations.pop() {
            Self::read_v2_continuation_chunk(
                base,
                cont_offset,
                cont_length,
                offset_size,
                length_size,
                creation_order_tracked,
                &mut messages,
                &mut continuations,
            )?;
        }

        Ok(ObjectHeader {
            version: 2,
            messages,
            reference_count: 0, // v2 does not store a reference count in the header
            modification_time,
        })
    }

    /// Read v2 messages from `start..end`.
    #[allow(clippy::too_many_arguments)]
    fn read_v2_messages(
        base: &Cursor<'_>,
        start: u64,
        end: u64,
        offset_size: u8,
        length_size: u8,
        creation_order_tracked: bool,
        messages: &mut Vec<HdfMessage>,
        continuations: &mut Vec<(u64, u64)>,
    ) -> Result<()> {
        let mut cursor = base.at_offset(start)?;

        // Minimum envelope: type(1) + size(2) + flags(1) = 4 bytes, optionally
        // +2 for creation order.
        let min_envelope = if creation_order_tracked { 6 } else { 4 };

        while cursor.position() + min_envelope as u64 <= end {
            let msg_type = cursor.read_u8()? as u16;
            let msg_data_size = cursor.read_u16_le()? as usize;
            let msg_flags = cursor.read_u8()?;

            if creation_order_tracked {
                let _creation_order = cursor.read_u16_le()?;
            }

            if msg_type == MSG_TYPE_NIL {
                if msg_data_size == 0
                    && base.data()[cursor.position() as usize..end as usize]
                        .iter()
                        .all(|byte| *byte == 0)
                {
                    break;
                }
                cursor.skip(msg_data_size)?;
                messages.push(HdfMessage::Nil);
                continue;
            }

            if cursor.position() + msg_data_size as u64 > end {
                return Err(Error::InvalidData(format!(
                    "v2 message data ({} bytes) extends past chunk end",
                    msg_data_size
                )));
            }

            let msg_data = cursor.read_bytes(msg_data_size)?;
            let is_shared = (msg_flags & 0x02) != 0;

            if is_shared {
                let shared_msg = crate::messages::shared::parse(
                    &mut Cursor::new(msg_data),
                    offset_size,
                    length_size,
                    msg_data_size,
                )?;
                messages.push(HdfMessage::Shared(shared_msg));
            } else if msg_type == MSG_TYPE_CONTINUATION {
                let cont = crate::messages::continuation::parse(
                    &mut Cursor::new(msg_data),
                    offset_size,
                    length_size,
                    msg_data_size,
                )?;
                continuations.push((cont.offset, cont.length));
                messages.push(HdfMessage::ObjectHeaderContinuation);
            } else {
                let parsed = parse_message(
                    msg_type,
                    msg_data.len(),
                    &mut Cursor::new(msg_data),
                    offset_size,
                    length_size,
                )?;
                messages.push(parsed);
            }
        }

        Ok(())
    }

    /// Read and verify a v2 continuation chunk (`OCHK`).
    #[allow(clippy::too_many_arguments)]
    ///
    /// Layout:
    /// ```text
    ///   "OCHK"    4 bytes
    ///   messages  (cont_length - 4 - 4) bytes
    ///   checksum  u32
    /// ```
    fn read_v2_continuation_chunk(
        base: &Cursor<'_>,
        cont_offset: u64,
        cont_length: u64,
        offset_size: u8,
        length_size: u8,
        creation_order_tracked: bool,
        messages: &mut Vec<HdfMessage>,
        continuations: &mut Vec<(u64, u64)>,
    ) -> Result<()> {
        let mut cursor = base.at_offset(cont_offset)?;

        let sig = cursor.read_bytes(4)?;
        if sig != OCHK_SIGNATURE {
            return Err(Error::InvalidObjectHeaderSignature);
        }

        let chunk_end = cont_offset + cont_length;
        // The last 4 bytes of the chunk are the checksum.
        let messages_end = chunk_end - 4;
        let messages_start = cursor.position(); // right after "OCHK"

        // Verify checksum: covers "OCHK" through the byte before the checksum.
        let checksum_start = cont_offset as usize;
        let checksum_end = messages_end as usize;
        let stored_checksum = {
            let mut ck = base.at_offset(messages_end)?;
            ck.read_u32_le()?
        };
        let computed = jenkins_lookup3(&base.data()[checksum_start..checksum_end]);
        if computed != stored_checksum {
            return Err(Error::ChecksumMismatch {
                expected: stored_checksum,
                actual: computed,
            });
        }

        Self::read_v2_messages(
            base,
            messages_start,
            messages_end,
            offset_size,
            length_size,
            creation_order_tracked,
            messages,
            continuations,
        )
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::checksum::jenkins_lookup3;

    // ------------------------------------------------------------------
    // Helpers
    // ------------------------------------------------------------------

    /// Build a v1 object header containing the given pre-encoded messages.
    /// Each entry in `raw_messages` is `(type_id, flags, payload)`.
    fn build_v1_header(raw_messages: &[(u16, u8, &[u8])], ref_count: u32) -> Vec<u8> {
        // Compute total message data size.
        let data_size: usize = raw_messages
            .iter()
            .map(|(_, _, payload)| 8 + payload.len()) // 8-byte envelope per message
            .sum();

        let mut buf = Vec::new();
        // Version
        buf.push(1);
        // Reserved
        buf.push(0);
        // Number of messages
        buf.extend_from_slice(&(raw_messages.len() as u16).to_le_bytes());
        // Reference count
        buf.extend_from_slice(&ref_count.to_le_bytes());
        // Header data size
        buf.extend_from_slice(&(data_size as u32).to_le_bytes());
        // Reserved padding (4 bytes)
        buf.extend_from_slice(&[0u8; 4]);

        // Messages
        for (type_id, flags, payload) in raw_messages {
            buf.extend_from_slice(&type_id.to_le_bytes());
            buf.extend_from_slice(&(payload.len() as u16).to_le_bytes());
            buf.push(*flags);
            buf.extend_from_slice(&[0u8; 3]); // reserved
            buf.extend_from_slice(payload);
        }

        buf
    }

    /// Build a v2 OHDR chunk#0 with the given raw messages.
    /// `flags` controls the header flags byte.  Timestamps and phase-change
    /// values are added automatically when the corresponding flag bits are set.
    /// Each entry in `raw_messages` is `(type_id, flags, payload)`.
    /// Returns the complete OHDR block including the trailing checksum.
    fn build_v2_header(
        header_flags: u8,
        raw_messages: &[(u8, u8, &[u8])],
        timestamps: Option<[u32; 4]>,
        phase_change: Option<(u16, u16)>,
    ) -> Vec<u8> {
        let creation_order = (header_flags & 0x04) != 0;

        // Compute message data size.
        let envelope_size: usize = if creation_order { 6 } else { 4 };
        let msg_data_size: usize = raw_messages
            .iter()
            .map(|(_, _, payload)| envelope_size + payload.len())
            .sum();

        let mut buf = Vec::new();
        // Signature
        buf.extend_from_slice(&OHDR_SIGNATURE);
        // Version
        buf.push(2);
        // Flags
        buf.push(header_flags);

        // Timestamps (bit 5)
        if let Some(ts) = timestamps {
            for &t in &ts {
                buf.extend_from_slice(&t.to_le_bytes());
            }
        }

        // Phase change (bit 4)
        if let Some((max_compact, min_dense)) = phase_change {
            buf.extend_from_slice(&max_compact.to_le_bytes());
            buf.extend_from_slice(&min_dense.to_le_bytes());
        }

        // Chunk#0 size field — encode using the width dictated by bits 0-1.
        let size_width = 1usize << (header_flags & 0x03);
        match size_width {
            1 => buf.push(msg_data_size as u8),
            2 => buf.extend_from_slice(&(msg_data_size as u16).to_le_bytes()),
            4 => buf.extend_from_slice(&(msg_data_size as u32).to_le_bytes()),
            8 => buf.extend_from_slice(&(msg_data_size as u64).to_le_bytes()),
            _ => unreachable!(),
        }

        // Messages
        for (type_id, mflags, payload) in raw_messages {
            buf.push(*type_id);
            buf.extend_from_slice(&(payload.len() as u16).to_le_bytes());
            buf.push(*mflags);
            if creation_order {
                buf.extend_from_slice(&0u16.to_le_bytes());
            }
            buf.extend_from_slice(payload);
        }

        // Checksum — covers everything so far.
        let ck = jenkins_lookup3(&buf);
        buf.extend_from_slice(&ck.to_le_bytes());

        buf
    }

    /// Build a v2 OCHK continuation chunk containing the given raw messages.
    fn build_v2_ochk(raw_messages: &[(u8, u8, &[u8])], creation_order: bool) -> Vec<u8> {
        let mut buf = Vec::new();
        // Signature
        buf.extend_from_slice(&OCHK_SIGNATURE);

        // Messages
        for (type_id, mflags, payload) in raw_messages {
            buf.push(*type_id);
            buf.extend_from_slice(&(payload.len() as u16).to_le_bytes());
            buf.push(*mflags);
            if creation_order {
                buf.extend_from_slice(&0u16.to_le_bytes());
            }
            buf.extend_from_slice(payload);
        }

        // Checksum over everything before the checksum itself.
        let ck = jenkins_lookup3(&buf);
        buf.extend_from_slice(&ck.to_le_bytes());

        buf
    }

    // ------------------------------------------------------------------
    // Tests — Version 1
    // ------------------------------------------------------------------

    #[test]
    fn v1_empty_header() {
        let data = build_v1_header(&[], 1);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.version, 1);
        assert_eq!(hdr.reference_count, 1);
        assert!(hdr.messages.is_empty());
        assert!(hdr.modification_time.is_none());
    }

    #[test]
    fn v1_nil_message() {
        // A single nil message with 4 bytes of padding payload.
        let data = build_v1_header(&[(0x0000, 0, &[0u8; 4])], 1);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.messages.len(), 1);
        assert!(matches!(hdr.messages[0], HdfMessage::Nil));
    }

    #[test]
    fn v1_unknown_message() {
        // An unknown message type should be stored as HdfMessage::Unknown.
        let payload = [0xAA, 0xBB, 0xCC];
        let data = build_v1_header(&[(0x00FF, 0, &payload)], 2);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.reference_count, 2);
        assert_eq!(hdr.messages.len(), 1);
        match &hdr.messages[0] {
            HdfMessage::Unknown { type_id, data } => {
                assert_eq!(*type_id, 0x00FF);
                assert_eq!(data.as_slice(), &payload);
            }
            other => panic!("expected Unknown, got {:?}", other),
        }
    }

    #[test]
    fn v1_symbol_table_message() {
        // Type 0x0011 — symbol table message.
        // Payload: btree address (8 bytes) + heap address (8 bytes).
        let mut payload = Vec::new();
        payload.extend_from_slice(&0x1000u64.to_le_bytes());
        payload.extend_from_slice(&0x2000u64.to_le_bytes());

        let data = build_v1_header(&[(0x0011, 0, &payload)], 1);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.messages.len(), 1);
        match &hdr.messages[0] {
            HdfMessage::SymbolTable(st) => {
                assert_eq!(st.btree_address, 0x1000);
                assert_eq!(st.heap_address, 0x2000);
            }
            other => panic!("expected SymbolTable, got {:?}", other),
        }
    }

    #[test]
    fn v1_continuation_message() {
        // Build a continuation payload that points to a second chunk.
        // The second chunk contains one unknown message.
        let unknown_payload = [0xDD; 2];

        // Build the continuation target (a raw v1 message run, no header prefix).
        let mut cont_chunk = Vec::new();
        // message type 0x00FE
        cont_chunk.extend_from_slice(&0x00FEu16.to_le_bytes());
        // message data size
        cont_chunk.extend_from_slice(&(unknown_payload.len() as u16).to_le_bytes());
        // flags
        cont_chunk.push(0);
        // reserved
        cont_chunk.extend_from_slice(&[0u8; 3]);
        // payload
        cont_chunk.extend_from_slice(&unknown_payload);

        // We will place the continuation chunk after the main header.
        // First build the main header with a continuation message.
        let main_header_base_size = 16; // v1 prefix
                                        // The continuation message envelope = 8, payload = offset_size + length_size.
                                        // With offset_size=8, length_size=8, the continuation payload is 16 bytes.
        let cont_msg_envelope_size = 8 + 16; // 24
        let cont_chunk_offset = (main_header_base_size + cont_msg_envelope_size) as u64;

        let mut cont_payload = Vec::new();
        cont_payload.extend_from_slice(&cont_chunk_offset.to_le_bytes()); // offset
        cont_payload.extend_from_slice(&(cont_chunk.len() as u64).to_le_bytes()); // length

        let main_header = build_v1_header(&[(MSG_TYPE_CONTINUATION, 0, &cont_payload)], 1);

        // Concatenate main header + continuation chunk.
        let mut file_data = main_header;
        assert_eq!(file_data.len() as u64, cont_chunk_offset);
        file_data.extend_from_slice(&cont_chunk);

        let hdr = ObjectHeader::parse_at(&file_data, 0, 8, 8).unwrap();
        // Should have the continuation marker + the unknown message from the continuation chunk.
        assert_eq!(hdr.messages.len(), 2);
        assert!(matches!(
            hdr.messages[0],
            HdfMessage::ObjectHeaderContinuation
        ));
        match &hdr.messages[1] {
            HdfMessage::Unknown { type_id, data } => {
                assert_eq!(*type_id, 0x00FE);
                assert_eq!(data.as_slice(), &unknown_payload);
            }
            other => panic!("expected Unknown from continuation, got {:?}", other),
        }
    }

    #[test]
    fn v1_nonzero_address_offset() {
        // Place the header at a non-zero offset in the file.
        let prefix_pad = vec![0xFFu8; 64];
        let header = build_v1_header(&[(0x00AA, 0, &[0x01])], 3);

        let mut file_data = prefix_pad;
        file_data.extend_from_slice(&header);

        let hdr = ObjectHeader::parse_at(&file_data, 64, 8, 8).unwrap();
        assert_eq!(hdr.version, 1);
        assert_eq!(hdr.reference_count, 3);
        assert_eq!(hdr.messages.len(), 1);
    }

    #[test]
    fn v1_bad_version() {
        let mut data = build_v1_header(&[], 1);
        data[0] = 3; // corrupt version to 3
        let err = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap_err();
        assert!(matches!(err, Error::UnsupportedObjectHeaderVersion(3)));
    }

    // ------------------------------------------------------------------
    // Tests — Version 2
    // ------------------------------------------------------------------

    #[test]
    fn v2_empty_header() {
        // Flags=0 → 1-byte size field, no timestamps, no phase change, no creation order.
        let data = build_v2_header(0x00, &[], None, None);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.version, 2);
        assert!(hdr.messages.is_empty());
        assert!(hdr.modification_time.is_none());
    }

    #[test]
    fn v2_nil_message() {
        let data = build_v2_header(0x00, &[(0x00, 0, &[0u8; 3])], None, None);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.messages.len(), 1);
        assert!(matches!(hdr.messages[0], HdfMessage::Nil));
    }

    #[test]
    fn v2_unknown_message() {
        let payload = [0x11, 0x22];
        let data = build_v2_header(0x00, &[(0xFE, 0, &payload)], None, None);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.messages.len(), 1);
        match &hdr.messages[0] {
            HdfMessage::Unknown { type_id, data } => {
                assert_eq!(*type_id, 0x00FE);
                assert_eq!(data.as_slice(), &payload);
            }
            other => panic!("expected Unknown, got {:?}", other),
        }
    }

    #[test]
    fn v2_with_timestamps() {
        // Flags: bit 5 (timestamps) + bits 0-1 = 0 (1-byte size field).
        let flags = 0x20;
        let ts = [1000u32, 2000, 3000, 4000]; // access, modification, change, birth
        let data = build_v2_header(flags, &[], Some(ts), None);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.modification_time, Some(2000));
    }

    #[test]
    fn v2_with_phase_change() {
        // Flags: bit 4 (phase change) + bits 0-1 = 0.
        let flags = 0x10;
        let data = build_v2_header(flags, &[], None, Some((8, 6)));
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert!(hdr.messages.is_empty());
    }

    #[test]
    fn v2_with_creation_order() {
        // Flags: bit 2 (creation order tracked) + bits 0-1 = 0.
        let flags = 0x04;
        let payload = [0xAA];
        let data = build_v2_header(flags, &[(0xFE, 0, &payload)], None, None);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.messages.len(), 1);
        match &hdr.messages[0] {
            HdfMessage::Unknown { type_id, .. } => assert_eq!(*type_id, 0x00FE),
            other => panic!("expected Unknown, got {:?}", other),
        }
    }

    #[test]
    fn v2_2byte_size_field() {
        // bits 0-1 = 1 → 2-byte size field.
        let flags = 0x01;
        let payload = [0x42; 5];
        let data = build_v2_header(flags, &[(0xFE, 0, &payload)], None, None);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.messages.len(), 1);
    }

    #[test]
    fn v2_4byte_size_field() {
        // bits 0-1 = 2 → 4-byte size field.
        let flags = 0x02;
        let data = build_v2_header(flags, &[(0xFE, 0, &[0x01])], None, None);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.messages.len(), 1);
    }

    #[test]
    fn v2_8byte_size_field() {
        // bits 0-1 = 3 → 8-byte size field.
        let flags = 0x03;
        let data = build_v2_header(flags, &[(0xFE, 0, &[0x01])], None, None);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.messages.len(), 1);
    }

    #[test]
    fn v2_checksum_mismatch() {
        let mut data = build_v2_header(0x00, &[(0xFE, 0, &[0x01])], None, None);
        // Corrupt the last byte (part of checksum).
        let last = data.len() - 1;
        data[last] ^= 0xFF;
        let err = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap_err();
        assert!(matches!(err, Error::ChecksumMismatch { .. }));
    }

    #[test]
    fn v2_continuation_chunk() {
        // Build a continuation chunk (OCHK) that holds one unknown message.
        let unknown_payload = [0xCC; 3];
        let ochk = build_v2_ochk(&[(0xFD, 0, &unknown_payload)], false);

        // The continuation message payload is offset(8) + length(8) = 16 bytes.
        // We will compute the offset of the OCHK after building the main OHDR.
        // Strategy: build OHDR first with a placeholder, measure its size,
        // set the actual offset, then rebuild.

        // Placeholder continuation payload (will rewrite).
        let mut cont_payload = vec![0u8; 16];

        // Build OHDR with the continuation message.  The OHDR occupies:
        //   4 (sig) + 1 (ver) + 1 (flags) + 1 (size field, flags=0) + messages + 4 (checksum)
        // Message envelope: type(1) + size(2) + flags(1) = 4; payload = 16.
        // Total OHDR = 4 + 1 + 1 + 1 + 4 + 16 + 4 = 31 bytes.
        // The OCHK starts at byte 31.

        // We need the offset to be the byte where OCHK starts.
        // OHDR: sig(4) + ver(1) + flags(1) + size(1) + [envelope(4)+payload(16)] + checksum(4) = 31
        let ohdr_size = 4 + 1 + 1 + 1 + (4 + cont_payload.len()) + 4;
        let ochk_offset = ohdr_size as u64;

        // Rebuild continuation payload with correct offset.
        cont_payload.clear();
        cont_payload.extend_from_slice(&ochk_offset.to_le_bytes());
        cont_payload.extend_from_slice(&(ochk.len() as u64).to_le_bytes());

        let ohdr = build_v2_header(0x00, &[(0x10, 0, &cont_payload)], None, None);
        assert_eq!(ohdr.len(), ohdr_size);

        let mut file_data = ohdr;
        file_data.extend_from_slice(&ochk);

        let hdr = ObjectHeader::parse_at(&file_data, 0, 8, 8).unwrap();
        // Should have: continuation marker + unknown message from OCHK.
        assert_eq!(hdr.messages.len(), 2);
        assert!(matches!(
            hdr.messages[0],
            HdfMessage::ObjectHeaderContinuation
        ));
        match &hdr.messages[1] {
            HdfMessage::Unknown { type_id, data } => {
                assert_eq!(*type_id, 0x00FD);
                assert_eq!(data.as_slice(), &unknown_payload);
            }
            other => panic!("expected Unknown from OCHK, got {:?}", other),
        }
    }

    #[test]
    fn v2_ochk_checksum_mismatch() {
        let unknown_payload = [0xCC; 3];
        let mut ochk = build_v2_ochk(&[(0xFD, 0, &unknown_payload)], false);
        // Corrupt OCHK checksum.
        let last = ochk.len() - 1;
        ochk[last] ^= 0xFF;

        let ohdr_size = 4 + 1 + 1 + 1 + (4 + 16) + 4; // 31
        let ochk_offset = ohdr_size as u64;

        let mut cont_payload = Vec::new();
        cont_payload.extend_from_slice(&ochk_offset.to_le_bytes());
        cont_payload.extend_from_slice(&(ochk.len() as u64).to_le_bytes());

        let ohdr = build_v2_header(0x00, &[(0x10, 0, &cont_payload)], None, None);
        let mut file_data = ohdr;
        file_data.extend_from_slice(&ochk);

        let err = ObjectHeader::parse_at(&file_data, 0, 8, 8).unwrap_err();
        assert!(matches!(err, Error::ChecksumMismatch { .. }));
    }

    #[test]
    fn v2_multiple_messages() {
        // Two unknown messages in the same chunk.
        let p1 = [0x01, 0x02];
        let p2 = [0x03, 0x04, 0x05];
        let data = build_v2_header(0x00, &[(0xA0, 0, &p1), (0xA1, 0, &p2)], None, None);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.messages.len(), 2);
        match &hdr.messages[0] {
            HdfMessage::Unknown { type_id, .. } => assert_eq!(*type_id, 0x00A0),
            other => panic!("expected Unknown 0xA0, got {:?}", other),
        }
        match &hdr.messages[1] {
            HdfMessage::Unknown { type_id, .. } => assert_eq!(*type_id, 0x00A1),
            other => panic!("expected Unknown 0xA1, got {:?}", other),
        }
    }

    #[test]
    fn v2_zero_length_nil_before_more_messages() {
        let p1 = [0xAA];
        let p2 = [0xBB];
        let data = build_v2_header(
            0x04,
            &[(0xFE, 0, &p1), (0x00, 0, &[]), (0xFD, 0, &p2)],
            None,
            None,
        );
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.messages.len(), 3);
        assert!(matches!(hdr.messages[0], HdfMessage::Unknown { .. }));
        assert!(matches!(hdr.messages[1], HdfMessage::Nil));
        assert!(matches!(hdr.messages[2], HdfMessage::Unknown { .. }));
    }

    #[test]
    fn v2_nonzero_address() {
        // Place the OHDR at offset 128 in a larger buffer.
        let prefix_pad = vec![0u8; 128];
        let ohdr = build_v2_header(0x00, &[(0xFE, 0, &[0x42])], None, None);

        let mut file_data = prefix_pad;
        file_data.extend_from_slice(&ohdr);

        let hdr = ObjectHeader::parse_at(&file_data, 128, 8, 8).unwrap();
        assert_eq!(hdr.version, 2);
        assert_eq!(hdr.messages.len(), 1);
    }

    #[test]
    fn v2_all_flags_combined() {
        // Combine timestamps (0x20) + phase change (0x10) + creation order (0x04) + 2-byte size (0x01).
        let flags = 0x20 | 0x10 | 0x04 | 0x01;
        let ts = [100u32, 200, 300, 400];
        let payload = [0xBB];
        let data = build_v2_header(flags, &[(0xFE, 0, &payload)], Some(ts), Some((12, 8)));
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.version, 2);
        assert_eq!(hdr.modification_time, Some(200));
        assert_eq!(hdr.messages.len(), 1);
    }

    #[test]
    fn v1_multiple_messages() {
        // Two messages in a single v1 header.
        let p1 = [0xAA; 4];
        let p2 = [0xBB; 8];
        let data = build_v1_header(&[(0x00FF, 0, &p1), (0x00FE, 0, &p2)], 5);
        let hdr = ObjectHeader::parse_at(&data, 0, 8, 8).unwrap();
        assert_eq!(hdr.version, 1);
        assert_eq!(hdr.reference_count, 5);
        assert_eq!(hdr.messages.len(), 2);
    }

    #[test]
    fn v1_4byte_offsets() {
        // Verify correct operation with 4-byte offset/length sizes.
        // Symbol table message with 4-byte addresses.
        let mut payload = Vec::new();
        payload.extend_from_slice(&0x1000u32.to_le_bytes());
        payload.extend_from_slice(&0x2000u32.to_le_bytes());

        let data = build_v1_header(&[(0x0011, 0, &payload)], 1);
        let hdr = ObjectHeader::parse_at(&data, 0, 4, 4).unwrap();
        assert_eq!(hdr.messages.len(), 1);
        match &hdr.messages[0] {
            HdfMessage::SymbolTable(st) => {
                assert_eq!(st.btree_address, 0x1000);
                assert_eq!(st.heap_address, 0x2000);
            }
            other => panic!("expected SymbolTable, got {:?}", other),
        }
    }
}