interstellar 0.2.0

//! On-disk record formats for memory-mapped storage.
//!
//! This module defines the fixed-size record structures used in the mmap file format.

// =============================================================================
// File Format Constants
// =============================================================================

/// Magic number identifying Interstellar database files ("GRML" in ASCII)
pub const MAGIC: u32 = 0x47524D4C;

/// Current file format version (V2)
pub const VERSION: u32 = 2;

/// Minimum version this library can read
pub const MIN_READABLE_VERSION: u32 = 1;

/// Size of the file header in bytes (V2)
pub const HEADER_SIZE: usize = 192;

/// Size of the V1 file header in bytes (for backward compatibility)
pub const HEADER_SIZE_V1: usize = 136;

/// Endianness indicator: little-endian
pub const ENDIAN_LITTLE: u8 = 1;

/// Endianness indicator: big-endian
pub const ENDIAN_BIG: u8 = 2;

/// Default page size in bytes
pub const DEFAULT_PAGE_SIZE: u32 = 4096;

/// Size of a node record in bytes
pub const NODE_RECORD_SIZE: usize = 48;

/// Size of an edge record in bytes
pub const EDGE_RECORD_SIZE: usize = 56;

// =============================================================================
// FileHeaderV1 (Legacy - for backward compatibility)
// =============================================================================

/// V1 File header at offset 0 (136 bytes total)
///
/// This is the legacy header format. New databases use V2.
/// This struct is kept for reading existing V1 databases.
///
/// # Layout
///
/// ```text
/// Offset | Size | Field
/// -------|------|-------------------
/// 0      | 4    | magic
/// 4      | 4    | version
/// 8      | 8    | node_count
/// 16     | 8    | node_capacity
/// 24     | 8    | edge_count
/// 32     | 8    | edge_capacity
/// 40     | 8    | string_table_offset
/// 48     | 8    | string_table_end
/// 56     | 8    | property_arena_offset
/// 64     | 8    | arena_next_offset
/// 72     | 8    | free_node_head
/// 80     | 8    | free_edge_head
/// 88     | 8    | next_node_id
/// 96     | 8    | next_edge_id
/// 104    | 8    | schema_offset
/// 112    | 8    | schema_size
/// 120    | 4    | schema_version
/// 124    | 12   | _schema_reserved
/// ```
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct FileHeaderV1 {
    /// Magic number (must be 0x47524D4C "GRML")
    pub magic: u32,

    /// File format version (1)
    pub version: u32,

    /// Number of active (non-deleted) nodes
    pub node_count: u64,

    /// Total allocated slots in node table
    pub node_capacity: u64,

    /// Number of active (non-deleted) edges
    pub edge_count: u64,

    /// Total allocated slots in edge table
    pub edge_capacity: u64,

    /// Byte offset to start of string table
    pub string_table_offset: u64,

    /// Byte offset to end of string table data (exclusive)
    pub string_table_end: u64,

    /// Byte offset to start of property arena
    pub property_arena_offset: u64,

    /// Current write position in property arena (for appending new properties)
    pub arena_next_offset: u64,

    /// First free node slot ID (u64::MAX if empty)
    pub free_node_head: u64,

    /// First free edge slot ID (u64::MAX if empty)
    pub free_edge_head: u64,

    /// Next node ID to allocate (high-water mark for iteration)
    pub next_node_id: u64,

    /// Next edge ID to allocate (high-water mark for iteration)
    pub next_edge_id: u64,

    /// Byte offset to schema region (0 = no schema)
    pub schema_offset: u64,

    /// Size of schema data in bytes
    pub schema_size: u64,

    /// Schema format version for compatibility checking
    pub schema_version: u32,

    /// Reserved for future schema-related fields
    pub _schema_reserved: [u8; 12],
}

impl FileHeaderV1 {
    /// Read V1 header from bytes
    ///
    /// # Safety
    ///
    /// This uses `read_unaligned` because the struct is `#[repr(C, packed)]`,
    /// which means fields may not be naturally aligned.
    pub fn from_bytes(bytes: &[u8]) -> Self {
        assert!(
            bytes.len() >= HEADER_SIZE_V1,
            "Buffer too small for FileHeaderV1"
        );

        unsafe {
            let ptr = bytes.as_ptr() as *const FileHeaderV1;
            ptr.read_unaligned()
        }
    }

    /// Write V1 header to bytes
    ///
    /// # Safety
    ///
    /// This creates a byte slice from the packed struct.
    pub fn to_bytes(&self) -> [u8; HEADER_SIZE_V1] {
        unsafe {
            let ptr = self as *const FileHeaderV1 as *const u8;
            let slice = std::slice::from_raw_parts(ptr, HEADER_SIZE_V1);
            let mut result = [0u8; HEADER_SIZE_V1];
            result.copy_from_slice(slice);
            result
        }
    }
}

// =============================================================================
// FileHeader (V2 - Current Version)
// =============================================================================

/// File header at offset 0 (192 bytes total)
///
/// The V2 header contains enhanced metadata including page size, feature flags,
/// endianness declaration, and a CRC32 checksum for integrity verification.
///
/// # Layout
///
/// ```text
/// Offset | Size | Field                  | Description
/// -------|------|------------------------|------------------------------------------
/// 0      | 4    | magic                  | Magic number 0x47524D4C ("GRML")
/// 4      | 4    | version                | File format version (2)
/// 8      | 4    | min_reader_version     | Minimum library version that can read this file
/// 12     | 4    | page_size              | Page size in bytes (default 4096)
/// 16     | 4    | flags                  | Feature flags bitfield
/// 20     | 1    | endianness             | Byte order indicator (1 = little, 2 = big)
/// 21     | 3    | _padding1              | Alignment padding
/// 24     | 8    | node_count             | Number of active (non-deleted) nodes
/// 32     | 8    | node_capacity          | Total allocated slots in node table
/// 40     | 8    | edge_count             | Number of active (non-deleted) edges
/// 48     | 8    | edge_capacity          | Total allocated slots in edge table
/// 56     | 8    | string_table_offset    | Byte offset to start of string table
/// 64     | 8    | string_table_end       | Byte offset to end of string table data
/// 72     | 8    | property_arena_offset  | Byte offset to start of property arena
/// 80     | 8    | arena_next_offset      | Current write position in property arena
/// 88     | 8    | free_node_head         | First free node slot (u64::MAX if empty)
/// 96     | 8    | free_edge_head         | First free edge slot (u64::MAX if empty)
/// 104    | 8    | next_node_id           | Next node ID to allocate
/// 112    | 8    | next_edge_id           | Next edge ID to allocate
/// 120    | 8    | schema_offset          | Byte offset to schema region (0 = none)
/// 128    | 8    | schema_size            | Size of schema data in bytes
/// 136    | 4    | schema_version         | Schema format version
/// 140    | 12   | _schema_reserved       | Reserved for future schema fields
/// 152    | 4    | header_crc32           | CRC32 of bytes 0-151 (header excluding this field)
/// 156    | 36   | _reserved              | Reserved for future use (zero-filled)
/// ```
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct FileHeader {
    // Identity (12 bytes)
    /// Magic number (must be 0x47524D4C "GRML")
    pub magic: u32,

    /// File format version
    pub version: u32,

    /// Minimum library version required to read this file
    pub min_reader_version: u32,

    // Configuration (8 bytes)
    /// Page size in bytes
    pub page_size: u32,

    /// Feature flags bitfield
    pub flags: u32,

    // Endianness (4 bytes with padding)
    /// Byte order: 1 = little-endian, 2 = big-endian
    pub endianness: u8,

    /// Alignment padding (must be zero)
    pub _padding1: [u8; 3],

    // Counts (32 bytes)
    /// Number of active (non-deleted) nodes
    pub node_count: u64,

    /// Total allocated slots in node table
    pub node_capacity: u64,

    /// Number of active (non-deleted) edges
    pub edge_count: u64,

    /// Total allocated slots in edge table
    pub edge_capacity: u64,

    // Offsets (64 bytes)
    /// Byte offset to start of string table
    pub string_table_offset: u64,

    /// Byte offset to end of string table data
    pub string_table_end: u64,

    /// Byte offset to start of property arena
    pub property_arena_offset: u64,

    /// Current write position in property arena
    pub arena_next_offset: u64,

    /// First free node slot ID (u64::MAX if empty)
    pub free_node_head: u64,

    /// First free edge slot ID (u64::MAX if empty)
    pub free_edge_head: u64,

    /// Next node ID to allocate
    pub next_node_id: u64,

    /// Next edge ID to allocate
    pub next_edge_id: u64,

    // Schema (32 bytes)
    /// Byte offset to schema region (0 = no schema)
    pub schema_offset: u64,

    /// Size of schema data in bytes
    pub schema_size: u64,

    /// Schema format version
    pub schema_version: u32,

    /// Reserved for future schema fields
    pub _schema_reserved: [u8; 12],

    // Integrity (4 bytes)
    /// CRC32 of bytes 0-151
    pub header_crc32: u32,

    // Reserved (36 bytes)
    /// Reserved for future use (must be zero)
    pub _reserved: [u8; 36],
}

impl FileHeader {
    /// Create a new header with default values
    pub fn new() -> Self {
        let mut header = Self {
            magic: MAGIC,
            version: VERSION,
            min_reader_version: VERSION,
            page_size: DEFAULT_PAGE_SIZE,
            flags: 0,
            endianness: ENDIAN_LITTLE,
            _padding1: [0u8; 3],
            node_count: 0,
            node_capacity: 0,
            edge_count: 0,
            edge_capacity: 0,
            string_table_offset: 0,
            string_table_end: 0,
            property_arena_offset: 0,
            arena_next_offset: 0,
            free_node_head: u64::MAX,
            free_edge_head: u64::MAX,
            next_node_id: 0,
            next_edge_id: 0,
            schema_offset: 0,
            schema_size: 0,
            schema_version: 0,
            _schema_reserved: [0u8; 12],
            header_crc32: 0,
            _reserved: [0u8; 36],
        };
        // Compute and set the CRC
        header.header_crc32 = header.compute_crc32();
        header
    }

    /// Convert from a V1 header, synthesizing missing V2 fields with defaults
    pub fn from_v1(v1: &FileHeaderV1) -> Self {
        // Don't compute CRC for V1-sourced headers since we skip CRC validation for V1
        Self {
            magic: v1.magic,
            version: 1, // Keep original version for tracking
            min_reader_version: 1,
            page_size: DEFAULT_PAGE_SIZE,
            flags: 0,
            endianness: ENDIAN_LITTLE,
            _padding1: [0u8; 3],
            node_count: v1.node_count,
            node_capacity: v1.node_capacity,
            edge_count: v1.edge_count,
            edge_capacity: v1.edge_capacity,
            string_table_offset: v1.string_table_offset,
            string_table_end: v1.string_table_end,
            property_arena_offset: v1.property_arena_offset,
            arena_next_offset: v1.arena_next_offset,
            free_node_head: v1.free_node_head,
            free_edge_head: v1.free_edge_head,
            next_node_id: v1.next_node_id,
            next_edge_id: v1.next_edge_id,
            schema_offset: v1.schema_offset,
            schema_size: v1.schema_size,
            schema_version: v1.schema_version,
            _schema_reserved: v1._schema_reserved,
            header_crc32: 0, // V1 files don't have CRC, skip validation
            _reserved: [0u8; 36],
        }
    }

    /// Read header from bytes (handles both V1 and V2)
    ///
    /// # Safety
    ///
    /// This uses `read_unaligned` because the struct is `#[repr(C, packed)]`,
    /// which means fields may not be naturally aligned.
    pub fn from_bytes(bytes: &[u8]) -> Self {
        assert!(
            bytes.len() >= HEADER_SIZE,
            "Buffer too small for FileHeader"
        );

        unsafe {
            let ptr = bytes.as_ptr() as *const FileHeader;
            ptr.read_unaligned()
        }
    }

    /// Write header to bytes
    ///
    /// # Safety
    ///
    /// This creates a byte slice from the packed struct. Since the struct
    /// is `#[repr(C, packed)]`, we can safely interpret it as bytes.
    pub fn to_bytes(&self) -> [u8; HEADER_SIZE] {
        unsafe {
            let ptr = self as *const FileHeader as *const u8;
            let slice = std::slice::from_raw_parts(ptr, HEADER_SIZE);
            let mut result = [0u8; HEADER_SIZE];
            result.copy_from_slice(slice);
            result
        }
    }

    /// Compute the CRC32 of the header (bytes 0-151, excluding header_crc32 and _reserved)
    pub fn compute_crc32(&self) -> u32 {
        let bytes = self.to_bytes();
        // CRC covers bytes 0-151 (excludes header_crc32 at 152 and _reserved at 156)
        let crc_range = &bytes[0..152];

        let mut hasher = crc32fast::Hasher::new();
        hasher.update(crc_range);
        hasher.finalize()
    }

    /// Update the header's CRC32 field to match its current contents
    pub fn update_crc32(&mut self) {
        self.header_crc32 = self.compute_crc32();
    }

    /// Validate the header's CRC32 (for V2+ headers only)
    ///
    /// Returns `true` if the CRC is valid or if this is a V1 header (no CRC).
    pub fn validate_crc32(&self) -> bool {
        // V1 headers don't have CRC validation
        if self.version < 2 {
            return true;
        }
        self.header_crc32 == self.compute_crc32()
    }

    // =========================================================================
    // Query Storage Metadata Helpers
    // =========================================================================
    //
    // The _reserved field (36 bytes at offset 156) is used to store query
    // storage metadata without changing the struct layout:
    //
    // Offset 0-7:   query_store_offset (u64) - Byte offset to query region start
    // Offset 8-15:  query_store_end (u64)    - Byte offset to query data end
    // Offset 16-19: query_count (u32)        - Number of active queries
    // Offset 20-23: next_query_id (u32)      - Next query ID to allocate
    // Offset 24-35: Reserved for future use (12 bytes, must be zero)

    /// Get the byte offset to the query region start.
    ///
    /// Returns 0 if no query region has been allocated.
    #[inline]
    pub fn query_store_offset(&self) -> u64 {
        u64::from_le_bytes(self._reserved[0..8].try_into().unwrap())
    }

    /// Set the byte offset to the query region start.
    #[inline]
    pub fn set_query_store_offset(&mut self, offset: u64) {
        self._reserved[0..8].copy_from_slice(&offset.to_le_bytes());
    }

    /// Get the byte offset to the query data end (exclusive).
    ///
    /// This is the current write position in the query region.
    #[inline]
    pub fn query_store_end(&self) -> u64 {
        u64::from_le_bytes(self._reserved[8..16].try_into().unwrap())
    }

    /// Set the byte offset to the query data end.
    #[inline]
    pub fn set_query_store_end(&mut self, end: u64) {
        self._reserved[8..16].copy_from_slice(&end.to_le_bytes());
    }

    /// Get the number of active (non-deleted) queries.
    #[inline]
    pub fn query_count(&self) -> u32 {
        u32::from_le_bytes(self._reserved[16..20].try_into().unwrap())
    }

    /// Set the number of active (non-deleted) queries.
    #[inline]
    pub fn set_query_count(&mut self, count: u32) {
        self._reserved[16..20].copy_from_slice(&count.to_le_bytes());
    }

    /// Get the next query ID to allocate.
    ///
    /// Query IDs are never reused, even after deletion.
    #[inline]
    pub fn next_query_id(&self) -> u32 {
        u32::from_le_bytes(self._reserved[20..24].try_into().unwrap())
    }

    /// Set the next query ID to allocate.
    #[inline]
    pub fn set_next_query_id(&mut self, id: u32) {
        self._reserved[20..24].copy_from_slice(&id.to_le_bytes());
    }

    /// Check if the query region has been initialized.
    ///
    /// Returns true if query_store_offset is non-zero.
    #[inline]
    pub fn has_query_region(&self) -> bool {
        self.query_store_offset() != 0
    }
}

impl Default for FileHeader {
    fn default() -> Self {
        Self::new()
    }
}

// =============================================================================
// NodeRecord
// =============================================================================

/// Node (vertex) flag: marks a deleted node
pub const NODE_FLAG_DELETED: u32 = 0x0001;

/// Node (vertex) flag: has property indexes (reserved for future use)
pub const NODE_FLAG_INDEXED: u32 = 0x0002;

/// On-disk vertex record (48 bytes)
///
/// Fixed-size record for each vertex in the graph. Uses linked lists to track
/// adjacency (outgoing and incoming edges).
///
/// # Layout
///
/// ```text
/// Offset | Size | Field
/// -------|------|-------------
/// 0      | 8    | id
/// 8      | 4    | label_id
/// 12     | 4    | flags
/// 16     | 8    | first_out_edge
/// 24     | 8    | first_in_edge
/// 32     | 8    | prop_head
/// 40     | 8    | (padding to 48)
/// ```
///
/// # Fields
///
/// - **id**: Vertex ID (0-based index in node table)
/// - **label_id**: String table ID for the vertex label
/// - **flags**: Status flags (deleted, indexed, etc.)
/// - **first_out_edge**: First outgoing edge ID (u64::MAX if none)
/// - **first_in_edge**: First incoming edge ID (u64::MAX if none)
/// - **prop_head**: Property list head offset in arena (u64::MAX if none)
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct NodeRecord {
    /// Vertex ID (0-based)
    pub id: u64,

    /// String table ID for label
    pub label_id: u32,

    /// Status flags (NODE_FLAG_*)
    pub flags: u32,

    /// First outgoing edge ID (u64::MAX if none)
    pub first_out_edge: u64,

    /// First incoming edge ID (u64::MAX if none)
    pub first_in_edge: u64,

    /// Property list head offset (u64::MAX if none)
    pub prop_head: u64,

    /// Padding to reach 48 bytes
    _padding: u64,
}

impl NodeRecord {
    /// Create a new node record
    pub fn new(id: u64, label_id: u32) -> Self {
        Self {
            id,
            label_id,
            flags: 0,
            first_out_edge: u64::MAX,
            first_in_edge: u64::MAX,
            prop_head: u64::MAX,
            _padding: 0,
        }
    }

    /// Check if this node is deleted
    pub fn is_deleted(&self) -> bool {
        self.flags & NODE_FLAG_DELETED != 0
    }

    /// Mark this node as deleted
    pub fn mark_deleted(&mut self) {
        self.flags |= NODE_FLAG_DELETED;
    }

    /// Read node record from bytes
    ///
    /// # Safety
    ///
    /// Uses `read_unaligned` because the struct is `#[repr(C, packed)]`.
    pub fn from_bytes(bytes: &[u8]) -> Self {
        assert!(
            bytes.len() >= NODE_RECORD_SIZE,
            "Buffer too small for NodeRecord"
        );

        unsafe {
            let ptr = bytes.as_ptr() as *const NodeRecord;
            ptr.read_unaligned()
        }
    }

    /// Write node record to bytes
    ///
    /// # Safety
    ///
    /// Creates a byte slice from the packed struct.
    pub fn to_bytes(&self) -> [u8; NODE_RECORD_SIZE] {
        unsafe {
            let ptr = self as *const NodeRecord as *const u8;
            let slice = std::slice::from_raw_parts(ptr, NODE_RECORD_SIZE);
            let mut result = [0u8; NODE_RECORD_SIZE];
            result.copy_from_slice(slice);
            result
        }
    }
}

// =============================================================================
// EdgeRecord
// =============================================================================

/// Edge flag: marks a deleted edge
pub const EDGE_FLAG_DELETED: u32 = 0x0001;

/// On-disk edge record (56 bytes)
///
/// Fixed-size record for each edge in the graph. Includes linked-list pointers
/// for efficient adjacency list traversal.
///
/// # Layout
///
/// ```text
/// Offset | Size | Field
/// -------|------|-------------
/// 0      | 8    | id
/// 8      | 4    | label_id
/// 12     | 4    | flags (stores edge flags)
/// 16     | 8    | src
/// 24     | 8    | dst
/// 32     | 8    | next_out
/// 40     | 8    | next_in
/// 48     | 8    | prop_head
/// ```
///
/// # Fields
///
/// - **id**: Edge ID (0-based index in edge table)
/// - **label_id**: String table ID for the edge label
/// - **flags**: Status flags (deleted, etc.)
/// - **src**: Source vertex ID
/// - **dst**: Destination vertex ID
/// - **next_out**: Next outgoing edge from src (u64::MAX if last)
/// - **next_in**: Next incoming edge to dst (u64::MAX if last)
/// - **prop_head**: Property list head offset in arena (u64::MAX if none)
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct EdgeRecord {
    /// Edge ID (0-based)
    pub id: u64,

    /// String table ID for label
    pub label_id: u32,

    /// Status flags (EDGE_FLAG_*)
    pub flags: u32,

    /// Source vertex ID
    pub src: u64,

    /// Destination vertex ID
    pub dst: u64,

    /// Next outgoing edge from src (u64::MAX if last)
    pub next_out: u64,

    /// Next incoming edge to dst (u64::MAX if last)
    pub next_in: u64,

    /// Property list head offset (u64::MAX if none)
    pub prop_head: u64,
}

impl EdgeRecord {
    /// Create a new edge record
    pub fn new(id: u64, label_id: u32, src: u64, dst: u64) -> Self {
        Self {
            id,
            label_id,
            flags: 0,
            src,
            dst,
            next_out: u64::MAX,
            next_in: u64::MAX,
            prop_head: u64::MAX,
        }
    }

    /// Check if this edge is deleted
    pub fn is_deleted(&self) -> bool {
        self.flags & EDGE_FLAG_DELETED != 0
    }

    /// Mark this edge as deleted
    pub fn mark_deleted(&mut self) {
        self.flags |= EDGE_FLAG_DELETED;
    }

    /// Read edge record from bytes
    ///
    /// # Safety
    ///
    /// Uses `read_unaligned` because the struct is `#[repr(C, packed)]`.
    pub fn from_bytes(bytes: &[u8]) -> Self {
        assert!(
            bytes.len() >= EDGE_RECORD_SIZE,
            "Buffer too small for EdgeRecord"
        );

        unsafe {
            let ptr = bytes.as_ptr() as *const EdgeRecord;
            ptr.read_unaligned()
        }
    }

    /// Write edge record to bytes
    ///
    /// # Safety
    ///
    /// Creates a byte slice from the packed struct.
    pub fn to_bytes(&self) -> [u8; EDGE_RECORD_SIZE] {
        unsafe {
            let ptr = self as *const EdgeRecord as *const u8;
            let slice = std::slice::from_raw_parts(ptr, EDGE_RECORD_SIZE);
            let mut result = [0u8; EDGE_RECORD_SIZE];
            result.copy_from_slice(slice);
            result
        }
    }
}

// =============================================================================
// Property Arena Structures
// =============================================================================

/// Size of the property entry header in bytes
pub const PROPERTY_ENTRY_HEADER_SIZE: usize = 17;

/// Property entry in the arena (variable length)
///
/// Properties are stored in a linked list in the property arena. Each entry
/// contains a key (string table ID), value type, value data, and a pointer
/// to the next property in the list.
///
/// # Layout
///
/// ```text
/// Offset | Size | Field
/// -------|------|-------------
/// 0      | 4    | key_id
/// 4      | 1    | value_type
/// 5      | 4    | value_len
/// 9      | 8    | next
/// 17     | N    | value_data (variable length)
/// ```
///
/// # Fields
///
/// - **key_id**: String table ID for the property key
/// - **value_type**: Value discriminant (from Value::discriminant())
/// - **value_len**: Length of serialized value in bytes
/// - **next**: Offset to next property entry (u64::MAX if last)
/// - **value_data**: Serialized value data (follows header, not in struct)
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct PropertyEntry {
    /// String table ID for property key
    pub key_id: u32,

    /// Value type discriminant
    pub value_type: u8,

    /// Length of serialized value
    pub value_len: u32,

    /// Next property in list (u64::MAX if last)
    pub next: u64,
}

impl PropertyEntry {
    /// Create a new property entry
    pub fn new(key_id: u32, value_type: u8, value_len: u32, next: u64) -> Self {
        Self {
            key_id,
            value_type,
            value_len,
            next,
        }
    }

    /// Read property entry from bytes
    ///
    /// # Safety
    ///
    /// Uses `read_unaligned` because the struct is `#[repr(C, packed)]`.
    pub fn from_bytes(bytes: &[u8]) -> Self {
        assert!(
            bytes.len() >= PROPERTY_ENTRY_HEADER_SIZE,
            "Buffer too small for PropertyEntry"
        );

        unsafe {
            let ptr = bytes.as_ptr() as *const PropertyEntry;
            ptr.read_unaligned()
        }
    }

    /// Write property entry to bytes
    ///
    /// # Safety
    ///
    /// Creates a byte slice from the packed struct.
    pub fn to_bytes(&self) -> [u8; PROPERTY_ENTRY_HEADER_SIZE] {
        unsafe {
            let ptr = self as *const PropertyEntry as *const u8;
            let slice = std::slice::from_raw_parts(ptr, PROPERTY_ENTRY_HEADER_SIZE);
            let mut result = [0u8; PROPERTY_ENTRY_HEADER_SIZE];
            result.copy_from_slice(slice);
            result
        }
    }
}

// =============================================================================
// String Table Structures
// =============================================================================

/// Size of the string entry header in bytes
pub const STRING_ENTRY_HEADER_SIZE: usize = 8;

/// String table entry
///
/// String table entries store interned strings (labels and property keys).
/// Each entry contains an ID, length, and the UTF-8 bytes of the string.
///
/// # Layout
///
/// ```text
/// Offset | Size | Field
/// -------|------|-------------
/// 0      | 4    | id
/// 4      | 4    | len
/// 8      | N    | string bytes (variable length, UTF-8)
/// ```
///
/// # Fields
///
/// - **id**: String ID (unique identifier)
/// - **len**: String length in bytes
/// - **string bytes**: UTF-8 encoded string data (follows header, not in struct)
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct StringEntry {
    /// String ID
    pub id: u32,

    /// String length in bytes
    pub len: u32,
}

impl StringEntry {
    /// Create a new string entry
    pub fn new(id: u32, len: u32) -> Self {
        Self { id, len }
    }

    /// Read string entry from bytes
    ///
    /// # Safety
    ///
    /// Uses `read_unaligned` because the struct is `#[repr(C, packed)]`.
    pub fn from_bytes(bytes: &[u8]) -> Self {
        assert!(
            bytes.len() >= STRING_ENTRY_HEADER_SIZE,
            "Buffer too small for StringEntry"
        );

        unsafe {
            let ptr = bytes.as_ptr() as *const StringEntry;
            ptr.read_unaligned()
        }
    }

    /// Write string entry to bytes
    ///
    /// # Safety
    ///
    /// Creates a byte slice from the packed struct.
    pub fn to_bytes(&self) -> [u8; STRING_ENTRY_HEADER_SIZE] {
        unsafe {
            let ptr = self as *const StringEntry as *const u8;
            let slice = std::slice::from_raw_parts(ptr, STRING_ENTRY_HEADER_SIZE);
            let mut result = [0u8; STRING_ENTRY_HEADER_SIZE];
            result.copy_from_slice(slice);
            result
        }
    }
}

// =============================================================================
// Query Storage Structures
// =============================================================================

/// Magic number identifying query region ("QRYS" in ASCII)
pub const QUERY_REGION_MAGIC: u32 = 0x51525953;

/// Query region format version
pub const QUERY_REGION_VERSION: u32 = 1;

/// Size of the query region header in bytes
pub const QUERY_REGION_HEADER_SIZE: usize = 16;

/// Size of the query record header in bytes (fixed portion)
pub const QUERY_RECORD_HEADER_SIZE: usize = 36;

/// Size of the parameter entry header in bytes
pub const PARAMETER_ENTRY_HEADER_SIZE: usize = 4;

/// Query flag: marks a deleted query
pub const QUERY_FLAG_DELETED: u16 = 0x0001;

/// Query type mask (bits 1-2)
pub const QUERY_TYPE_MASK: u16 = 0x0006;

/// Query type shift (to extract type from flags)
pub const QUERY_TYPE_SHIFT: u16 = 1;

/// Query type: Gremlin (value 1, stored as bits 1-2 = 0b01)
pub const QUERY_TYPE_GREMLIN: u16 = 1;

/// Query type: GQL (value 2, stored as bits 1-2 = 0b10)
pub const QUERY_TYPE_GQL: u16 = 2;

/// Query region header (16 bytes)
///
/// This header is placed at the start of the query storage region.
///
/// # Layout
///
/// ```text
/// Offset | Size | Field
/// -------|------|-------------------
/// 0      | 4    | magic
/// 4      | 4    | version
/// 8      | 8    | first_query
/// ```
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct QueryRegionHeader {
    /// Magic number (must be 0x51525953 "QRYS")
    pub magic: u32,

    /// Query region format version
    pub version: u32,

    /// Offset to first query record (u64::MAX if empty)
    pub first_query: u64,
}

impl QueryRegionHeader {
    /// Create a new empty query region header
    pub fn new() -> Self {
        Self {
            magic: QUERY_REGION_MAGIC,
            version: QUERY_REGION_VERSION,
            first_query: u64::MAX,
        }
    }

    /// Read query region header from bytes
    ///
    /// # Safety
    ///
    /// Uses `read_unaligned` because the struct is `#[repr(C, packed)]`.
    pub fn from_bytes(bytes: &[u8]) -> Self {
        assert!(
            bytes.len() >= QUERY_REGION_HEADER_SIZE,
            "Buffer too small for QueryRegionHeader"
        );

        unsafe {
            let ptr = bytes.as_ptr() as *const QueryRegionHeader;
            ptr.read_unaligned()
        }
    }

    /// Write query region header to bytes
    ///
    /// # Safety
    ///
    /// Creates a byte slice from the packed struct.
    pub fn to_bytes(&self) -> [u8; QUERY_REGION_HEADER_SIZE] {
        unsafe {
            let ptr = self as *const QueryRegionHeader as *const u8;
            let slice = std::slice::from_raw_parts(ptr, QUERY_REGION_HEADER_SIZE);
            let mut result = [0u8; QUERY_REGION_HEADER_SIZE];
            result.copy_from_slice(slice);
            result
        }
    }

    /// Check if the magic number is valid
    pub fn is_valid(&self) -> bool {
        self.magic == QUERY_REGION_MAGIC
    }
}

impl Default for QueryRegionHeader {
    fn default() -> Self {
        Self::new()
    }
}

/// Query record header (36 bytes fixed + variable data)
///
/// Queries are stored as variable-length records in a dedicated region.
/// The header contains metadata, and variable data follows immediately after.
///
/// # Layout
///
/// ```text
/// Offset | Size | Field
/// -------|------|-------------------
/// 0      | 4    | id
/// 4      | 2    | flags
/// 6      | 2    | param_count
/// 8      | 2    | name_len
/// 10     | 2    | description_len
/// 12     | 4    | query_len
/// 16     | 4    | record_size
/// 20     | 8    | next
/// 28     | 8    | prev
/// ```
///
/// # Variable data layout (immediately follows header)
///
/// ```text
/// Offset              | Size              | Content
/// --------------------|-------------------|------------------
/// 0                   | name_len          | Query name (UTF-8)
/// name_len            | description_len   | Description (UTF-8)
/// name_len+desc_len   | query_len         | Query text (UTF-8)
/// ...                 | param_count * N   | Parameter entries
/// ```
///
/// # Flags
///
/// - bit 0: deleted flag
/// - bits 1-2: query type (0=reserved, 1=gremlin, 2=gql)
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct QueryRecord {
    /// Query ID (unique, never reused)
    pub id: u32,

    /// Flags bitfield
    pub flags: u16,

    /// Number of parameters
    pub param_count: u16,

    /// Length of name string (UTF-8 bytes)
    pub name_len: u16,

    /// Length of description string (UTF-8 bytes)
    pub description_len: u16,

    /// Length of query text (UTF-8 bytes)
    pub query_len: u32,

    /// Total record size including header and all variable data
    pub record_size: u32,

    /// Offset to next record (u64::MAX if last)
    pub next: u64,

    /// Offset to previous record (u64::MAX if first)
    pub prev: u64,
}

impl QueryRecord {
    /// Create a new query record
    pub fn new(
        id: u32,
        query_type: u16,
        param_count: u16,
        name_len: u16,
        description_len: u16,
        query_len: u32,
        record_size: u32,
    ) -> Self {
        let flags = (query_type << QUERY_TYPE_SHIFT) & QUERY_TYPE_MASK;
        Self {
            id,
            flags,
            param_count,
            name_len,
            description_len,
            query_len,
            record_size,
            next: u64::MAX,
            prev: u64::MAX,
        }
    }

    /// Check if this query is deleted
    pub fn is_deleted(&self) -> bool {
        self.flags & QUERY_FLAG_DELETED != 0
    }

    /// Mark this query as deleted
    pub fn mark_deleted(&mut self) {
        self.flags |= QUERY_FLAG_DELETED;
    }

    /// Get the query type (1 = Gremlin, 2 = GQL)
    pub fn query_type(&self) -> u16 {
        (self.flags & QUERY_TYPE_MASK) >> QUERY_TYPE_SHIFT
    }

    /// Read query record from bytes
    ///
    /// # Safety
    ///
    /// Uses `read_unaligned` because the struct is `#[repr(C, packed)]`.
    pub fn from_bytes(bytes: &[u8]) -> Self {
        assert!(
            bytes.len() >= QUERY_RECORD_HEADER_SIZE,
            "Buffer too small for QueryRecord"
        );

        unsafe {
            let ptr = bytes.as_ptr() as *const QueryRecord;
            ptr.read_unaligned()
        }
    }

    /// Write query record to bytes
    ///
    /// # Safety
    ///
    /// Creates a byte slice from the packed struct.
    pub fn to_bytes(&self) -> [u8; QUERY_RECORD_HEADER_SIZE] {
        unsafe {
            let ptr = self as *const QueryRecord as *const u8;
            let slice = std::slice::from_raw_parts(ptr, QUERY_RECORD_HEADER_SIZE);
            let mut result = [0u8; QUERY_RECORD_HEADER_SIZE];
            result.copy_from_slice(slice);
            result
        }
    }
}

/// Parameter entry header (4 bytes + variable name)
///
/// Each parameter is stored with its name and inferred type.
///
/// # Layout
///
/// ```text
/// Offset | Size | Field
/// -------|------|-------------------
/// 0      | 2    | name_len
/// 2      | 1    | value_type
/// 3      | 1    | _reserved
/// 4      | N    | name bytes (UTF-8)
/// ```
///
/// # Value Types
///
/// - 0x00 = Null
/// - 0x01 = Bool
/// - 0x02 = Int
/// - 0x03 = Float
/// - 0x04 = String
/// - 0x05 = List
/// - 0x06 = Map
/// - 0x07 = Vertex
/// - 0x08 = Edge
/// - 0xFF = Any (unknown/unconstrained)
#[repr(C, packed)]
#[derive(Copy, Clone, Debug)]
pub struct ParameterEntry {
    /// Parameter name length
    pub name_len: u16,

    /// Expected value type (Value discriminant, 0xFF = any)
    pub value_type: u8,

    /// Reserved for future use (alignment)
    pub _reserved: u8,
}

/// Value type discriminant for "any" type (unconstrained)
pub const PARAMETER_TYPE_ANY: u8 = 0xFF;

impl ParameterEntry {
    /// Create a new parameter entry
    pub fn new(name_len: u16, value_type: u8) -> Self {
        Self {
            name_len,
            value_type,
            _reserved: 0,
        }
    }

    /// Create a new parameter entry with "any" type
    pub fn new_any(name_len: u16) -> Self {
        Self::new(name_len, PARAMETER_TYPE_ANY)
    }

    /// Read parameter entry from bytes
    ///
    /// # Safety
    ///
    /// Uses `read_unaligned` because the struct is `#[repr(C, packed)]`.
    pub fn from_bytes(bytes: &[u8]) -> Self {
        assert!(
            bytes.len() >= PARAMETER_ENTRY_HEADER_SIZE,
            "Buffer too small for ParameterEntry"
        );

        unsafe {
            let ptr = bytes.as_ptr() as *const ParameterEntry;
            ptr.read_unaligned()
        }
    }

    /// Write parameter entry to bytes
    ///
    /// # Safety
    ///
    /// Creates a byte slice from the packed struct.
    pub fn to_bytes(&self) -> [u8; PARAMETER_ENTRY_HEADER_SIZE] {
        unsafe {
            let ptr = self as *const ParameterEntry as *const u8;
            let slice = std::slice::from_raw_parts(ptr, PARAMETER_ENTRY_HEADER_SIZE);
            let mut result = [0u8; PARAMETER_ENTRY_HEADER_SIZE];
            result.copy_from_slice(slice);
            result
        }
    }

    /// Total size of this parameter entry including the name
    pub fn total_size(&self) -> usize {
        PARAMETER_ENTRY_HEADER_SIZE + self.name_len as usize
    }
}

// =============================================================================
// Tests
// =============================================================================

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

    // =========================================================================
    // FileHeaderV1 Tests (Legacy)
    // =========================================================================

    #[test]
    fn test_file_header_v1_size() {
        // FileHeaderV1 must be exactly 136 bytes
        assert_eq!(
            std::mem::size_of::<FileHeaderV1>(),
            HEADER_SIZE_V1,
            "FileHeaderV1 size must be exactly 136 bytes"
        );
    }

    #[test]
    fn test_file_header_v1_alignment() {
        // Verify the packed struct has expected layout
        // magic and version are u32 (4 bytes each) = 8 bytes
        // 14 u64 fields (14 × 8 bytes) = 112 bytes
        // 1 u32 field (schema_version) = 4 bytes
        // 1 [u8; 12] field (_schema_reserved) = 12 bytes
        // Total: 8 + 112 + 4 + 12 = 136 bytes

        assert_eq!(
            std::mem::size_of::<FileHeaderV1>(),
            4 + 4 + (14 * 8) + 4 + 12,
            "FileHeaderV1 fields should sum to 136 bytes"
        );
    }

    // =========================================================================
    // FileHeader (V2) Tests
    // =========================================================================

    #[test]
    fn test_file_header_size() {
        // FileHeader (V2) must be exactly 192 bytes
        assert_eq!(
            std::mem::size_of::<FileHeader>(),
            HEADER_SIZE,
            "FileHeader size must be exactly 192 bytes"
        );
    }

    #[test]
    fn test_file_header_alignment() {
        // Verify the packed V2 struct has expected layout
        // Identity: magic(4) + version(4) + min_reader_version(4) = 12 bytes
        // Configuration: page_size(4) + flags(4) = 8 bytes
        // Endianness: endianness(1) + _padding1(3) = 4 bytes
        // Counts: node_count(8) + node_capacity(8) + edge_count(8) + edge_capacity(8) = 32 bytes
        // Offsets: 8 * 8 = 64 bytes
        // Schema: schema_offset(8) + schema_size(8) + schema_version(4) + _schema_reserved(12) = 32 bytes
        // Integrity: header_crc32(4) = 4 bytes
        // Reserved: _reserved(36) = 36 bytes
        // Total: 12 + 8 + 4 + 32 + 64 + 32 + 4 + 36 = 192 bytes

        assert_eq!(
            std::mem::size_of::<FileHeader>(),
            12 + 8 + 4 + 32 + 64 + 32 + 4 + 36,
            "FileHeader fields should sum to 192 bytes"
        );
    }

    #[test]
    fn test_file_header_default_values() {
        let header = FileHeader::new();

        // Copy fields to avoid unaligned reference errors
        let magic = header.magic;
        let version = header.version;
        let min_reader_version = header.min_reader_version;
        let page_size = header.page_size;
        let flags = header.flags;
        let endianness = header.endianness;
        let node_count = header.node_count;
        let node_capacity = header.node_capacity;
        let edge_count = header.edge_count;
        let edge_capacity = header.edge_capacity;
        let string_table_offset = header.string_table_offset;
        let string_table_end = header.string_table_end;
        let property_arena_offset = header.property_arena_offset;
        let arena_next_offset = header.arena_next_offset;
        let free_node_head = header.free_node_head;
        let free_edge_head = header.free_edge_head;
        let next_node_id = header.next_node_id;
        let next_edge_id = header.next_edge_id;
        let schema_offset = header.schema_offset;
        let schema_size = header.schema_size;
        let schema_version = header.schema_version;

        assert_eq!(magic, MAGIC);
        assert_eq!(version, VERSION);
        assert_eq!(min_reader_version, VERSION);
        assert_eq!(page_size, DEFAULT_PAGE_SIZE);
        assert_eq!(flags, 0);
        assert_eq!(endianness, ENDIAN_LITTLE);
        assert_eq!(node_count, 0);
        assert_eq!(node_capacity, 0);
        assert_eq!(edge_count, 0);
        assert_eq!(edge_capacity, 0);
        assert_eq!(string_table_offset, 0);
        assert_eq!(string_table_end, 0);
        assert_eq!(property_arena_offset, 0);
        assert_eq!(arena_next_offset, 0);
        assert_eq!(free_node_head, u64::MAX);
        assert_eq!(free_edge_head, u64::MAX);
        assert_eq!(next_node_id, 0);
        assert_eq!(next_edge_id, 0);
        assert_eq!(schema_offset, 0);
        assert_eq!(schema_size, 0);
        assert_eq!(schema_version, 0);
    }

    #[test]
    fn test_file_header_roundtrip() {
        // Create a header with some values
        let mut header = FileHeader::new();
        header.node_count = 100;
        header.node_capacity = 1000;
        header.edge_count = 500;
        header.edge_capacity = 5000;
        header.string_table_offset = 123456;
        header.string_table_end = 124000;
        header.property_arena_offset = 789012;
        header.arena_next_offset = 800000;
        header.free_node_head = 42;
        header.free_edge_head = 99;
        header.next_node_id = 150;
        header.next_edge_id = 600;
        header.schema_offset = 900000;
        header.schema_size = 2048;
        header.schema_version = 1;
        header.update_crc32();

        // Copy original values
        let orig_magic = header.magic;
        let orig_version = header.version;
        let orig_min_reader_version = header.min_reader_version;
        let orig_page_size = header.page_size;
        let orig_flags = header.flags;
        let orig_endianness = header.endianness;
        let orig_node_count = header.node_count;
        let orig_node_capacity = header.node_capacity;
        let orig_edge_count = header.edge_count;
        let orig_edge_capacity = header.edge_capacity;
        let orig_string_table_offset = header.string_table_offset;
        let orig_string_table_end = header.string_table_end;
        let orig_property_arena_offset = header.property_arena_offset;
        let orig_arena_next_offset = header.arena_next_offset;
        let orig_free_node_head = header.free_node_head;
        let orig_free_edge_head = header.free_edge_head;
        let orig_next_node_id = header.next_node_id;
        let orig_next_edge_id = header.next_edge_id;
        let orig_schema_offset = header.schema_offset;
        let orig_schema_size = header.schema_size;
        let orig_schema_version = header.schema_version;

        // Convert to bytes
        let bytes = header.to_bytes();

        // Verify size
        assert_eq!(bytes.len(), HEADER_SIZE);

        // Convert back from bytes
        let recovered = FileHeader::from_bytes(&bytes);

        // Copy recovered values to avoid unaligned reference errors
        let rec_magic = recovered.magic;
        let rec_version = recovered.version;
        let rec_min_reader_version = recovered.min_reader_version;
        let rec_page_size = recovered.page_size;
        let rec_flags = recovered.flags;
        let rec_endianness = recovered.endianness;
        let rec_node_count = recovered.node_count;
        let rec_node_capacity = recovered.node_capacity;
        let rec_edge_count = recovered.edge_count;
        let rec_edge_capacity = recovered.edge_capacity;
        let rec_string_table_offset = recovered.string_table_offset;
        let rec_string_table_end = recovered.string_table_end;
        let rec_property_arena_offset = recovered.property_arena_offset;
        let rec_arena_next_offset = recovered.arena_next_offset;
        let rec_free_node_head = recovered.free_node_head;
        let rec_free_edge_head = recovered.free_edge_head;
        let rec_next_node_id = recovered.next_node_id;
        let rec_next_edge_id = recovered.next_edge_id;
        let rec_schema_offset = recovered.schema_offset;
        let rec_schema_size = recovered.schema_size;
        let rec_schema_version = recovered.schema_version;

        // Verify all fields match
        assert_eq!(rec_magic, orig_magic);
        assert_eq!(rec_version, orig_version);
        assert_eq!(rec_min_reader_version, orig_min_reader_version);
        assert_eq!(rec_page_size, orig_page_size);
        assert_eq!(rec_flags, orig_flags);
        assert_eq!(rec_endianness, orig_endianness);
        assert_eq!(rec_node_count, orig_node_count);
        assert_eq!(rec_node_capacity, orig_node_capacity);
        assert_eq!(rec_edge_count, orig_edge_count);
        assert_eq!(rec_edge_capacity, orig_edge_capacity);
        assert_eq!(rec_string_table_offset, orig_string_table_offset);
        assert_eq!(rec_string_table_end, orig_string_table_end);
        assert_eq!(rec_property_arena_offset, orig_property_arena_offset);
        assert_eq!(rec_arena_next_offset, orig_arena_next_offset);
        assert_eq!(rec_free_node_head, orig_free_node_head);
        assert_eq!(rec_free_edge_head, orig_free_edge_head);
        assert_eq!(rec_next_node_id, orig_next_node_id);
        assert_eq!(rec_next_edge_id, orig_next_edge_id);
        assert_eq!(rec_schema_offset, orig_schema_offset);
        assert_eq!(rec_schema_size, orig_schema_size);
        assert_eq!(rec_schema_version, orig_schema_version);
    }

    #[test]
    fn test_file_header_transmute_safety() {
        let header = FileHeader::new();
        let bytes = header.to_bytes();

        // This should not panic
        let _ = FileHeader::from_bytes(&bytes);

        // Verify magic number is at correct offset (0)
        let magic_bytes: [u8; 4] = [bytes[0], bytes[1], bytes[2], bytes[3]];
        let magic = u32::from_le_bytes(magic_bytes);
        assert_eq!(magic, MAGIC);

        // Verify version is at correct offset (4)
        let version_bytes: [u8; 4] = [bytes[4], bytes[5], bytes[6], bytes[7]];
        let version = u32::from_le_bytes(version_bytes);
        assert_eq!(version, VERSION);
    }

    #[test]
    fn test_file_header_byte_order() {
        // Verify fields are stored in little-endian format
        let mut header = FileHeader::new();
        header.node_count = 0x0102030405060708u64;
        header.update_crc32();

        let bytes = header.to_bytes();

        // node_count starts at offset 24 in V2 (after identity, config, and endianness blocks)
        let node_count_bytes: [u8; 8] = [
            bytes[24], bytes[25], bytes[26], bytes[27], bytes[28], bytes[29], bytes[30], bytes[31],
        ];

        // Should be little-endian
        assert_eq!(node_count_bytes[0], 0x08);
        assert_eq!(node_count_bytes[7], 0x01);
    }

    #[test]
    fn test_constants() {
        assert_eq!(MAGIC, 0x47524D4C); // "GRML"
        assert_eq!(VERSION, 2);
        assert_eq!(MIN_READABLE_VERSION, 1);
        assert_eq!(HEADER_SIZE, 192);
        assert_eq!(HEADER_SIZE_V1, 136);
        assert_eq!(NODE_RECORD_SIZE, 48);
        assert_eq!(EDGE_RECORD_SIZE, 56);
        assert_eq!(DEFAULT_PAGE_SIZE, 4096);
        assert_eq!(ENDIAN_LITTLE, 1);
        assert_eq!(ENDIAN_BIG, 2);
    }

    // =========================================================================
    // V1 to V2 Conversion Tests
    // =========================================================================

    #[test]
    fn test_file_header_from_v1() {
        // Create a V1 header
        let v1 = FileHeaderV1 {
            magic: MAGIC,
            version: 1,
            node_count: 100,
            node_capacity: 1000,
            edge_count: 50,
            edge_capacity: 500,
            string_table_offset: 10000,
            string_table_end: 12000,
            property_arena_offset: 5000,
            arena_next_offset: 6000,
            free_node_head: 42,
            free_edge_head: 99,
            next_node_id: 101,
            next_edge_id: 51,
            schema_offset: 0,
            schema_size: 0,
            schema_version: 0,
            _schema_reserved: [0u8; 12],
        };

        // Copy V1 fields to local variables to avoid packed struct reference issues
        let v1_magic = v1.magic;
        let v1_node_count = v1.node_count;
        let v1_node_capacity = v1.node_capacity;
        let v1_edge_count = v1.edge_count;
        let v1_edge_capacity = v1.edge_capacity;
        let v1_string_table_offset = v1.string_table_offset;
        let v1_string_table_end = v1.string_table_end;
        let v1_property_arena_offset = v1.property_arena_offset;
        let v1_arena_next_offset = v1.arena_next_offset;
        let v1_free_node_head = v1.free_node_head;
        let v1_free_edge_head = v1.free_edge_head;
        let v1_next_node_id = v1.next_node_id;
        let v1_next_edge_id = v1.next_edge_id;

        // Convert to V2
        let v2 = FileHeader::from_v1(&v1);

        // Copy V2 fields to local variables
        let v2_magic = v2.magic;
        let v2_version = v2.version;
        let v2_node_count = v2.node_count;
        let v2_node_capacity = v2.node_capacity;
        let v2_edge_count = v2.edge_count;
        let v2_edge_capacity = v2.edge_capacity;
        let v2_string_table_offset = v2.string_table_offset;
        let v2_string_table_end = v2.string_table_end;
        let v2_property_arena_offset = v2.property_arena_offset;
        let v2_arena_next_offset = v2.arena_next_offset;
        let v2_free_node_head = v2.free_node_head;
        let v2_free_edge_head = v2.free_edge_head;
        let v2_next_node_id = v2.next_node_id;
        let v2_next_edge_id = v2.next_edge_id;
        let v2_min_reader_version = v2.min_reader_version;
        let v2_page_size = v2.page_size;
        let v2_flags = v2.flags;
        let v2_endianness = v2.endianness;

        // Verify V1 fields are preserved
        assert_eq!(v2_magic, v1_magic);
        assert_eq!(v2_version, 1); // Keeps original version
        assert_eq!(v2_node_count, v1_node_count);
        assert_eq!(v2_node_capacity, v1_node_capacity);
        assert_eq!(v2_edge_count, v1_edge_count);
        assert_eq!(v2_edge_capacity, v1_edge_capacity);
        assert_eq!(v2_string_table_offset, v1_string_table_offset);
        assert_eq!(v2_string_table_end, v1_string_table_end);
        assert_eq!(v2_property_arena_offset, v1_property_arena_offset);
        assert_eq!(v2_arena_next_offset, v1_arena_next_offset);
        assert_eq!(v2_free_node_head, v1_free_node_head);
        assert_eq!(v2_free_edge_head, v1_free_edge_head);
        assert_eq!(v2_next_node_id, v1_next_node_id);
        assert_eq!(v2_next_edge_id, v1_next_edge_id);

        // Verify V2 defaults are applied
        assert_eq!(v2_min_reader_version, 1);
        assert_eq!(v2_page_size, DEFAULT_PAGE_SIZE);
        assert_eq!(v2_flags, 0);
        assert_eq!(v2_endianness, ENDIAN_LITTLE);
    }

    // =========================================================================
    // CRC32 Tests
    // =========================================================================

    #[test]
    fn test_file_header_crc32_validation() {
        let header = FileHeader::new();

        // New headers should have valid CRC
        assert!(header.validate_crc32());
    }

    #[test]
    fn test_file_header_crc32_detects_corruption() {
        let mut header = FileHeader::new();

        // Corrupt a field
        header.node_count = 12345;

        // CRC should now be invalid (unless we update it)
        assert!(!header.validate_crc32());

        // After updating CRC, it should be valid again
        header.update_crc32();
        assert!(header.validate_crc32());
    }

    #[test]
    fn test_file_header_crc32_roundtrip() {
        let mut header = FileHeader::new();
        header.node_count = 100;
        header.edge_count = 200;
        header.update_crc32();

        // Serialize and deserialize
        let bytes = header.to_bytes();
        let recovered = FileHeader::from_bytes(&bytes);

        // CRC should still be valid
        assert!(recovered.validate_crc32());
    }

    #[test]
    fn test_file_header_v1_skips_crc_validation() {
        // V1-sourced headers should skip CRC validation
        let v1 = FileHeaderV1 {
            magic: MAGIC,
            version: 1,
            node_count: 0,
            node_capacity: 0,
            edge_count: 0,
            edge_capacity: 0,
            string_table_offset: 0,
            string_table_end: 0,
            property_arena_offset: 0,
            arena_next_offset: 0,
            free_node_head: u64::MAX,
            free_edge_head: u64::MAX,
            next_node_id: 0,
            next_edge_id: 0,
            schema_offset: 0,
            schema_size: 0,
            schema_version: 0,
            _schema_reserved: [0u8; 12],
        };

        let v2 = FileHeader::from_v1(&v1);

        // V1-converted headers have version=1 so CRC validation is skipped
        assert!(v2.validate_crc32());
    }

    // =========================================================================
    // NodeRecord Tests
    // =========================================================================

    #[test]
    fn test_node_record_size() {
        // NodeRecord must be exactly 48 bytes
        assert_eq!(
            std::mem::size_of::<NodeRecord>(),
            NODE_RECORD_SIZE,
            "NodeRecord size must be exactly 48 bytes"
        );
    }

    #[test]
    fn test_node_record_alignment() {
        // Verify packed struct layout
        // id: u64 (8 bytes)
        // label_id: u32 (4 bytes)
        // flags: u32 (4 bytes)
        // first_out_edge: u64 (8 bytes)
        // first_in_edge: u64 (8 bytes)
        // prop_head: u64 (8 bytes)
        // _padding: u64 (8 bytes)
        // Total: 8 + 4 + 4 + 8 + 8 + 8 + 8 = 48 bytes

        assert_eq!(
            std::mem::size_of::<NodeRecord>(),
            8 + 4 + 4 + 8 + 8 + 8 + 8,
            "NodeRecord fields should sum to 48 bytes"
        );
    }

    #[test]
    fn test_node_record_new() {
        let record = NodeRecord::new(42, 7);

        // Copy values to avoid unaligned reference errors
        let id = record.id;
        let label_id = record.label_id;
        let flags = record.flags;
        let first_out_edge = record.first_out_edge;
        let first_in_edge = record.first_in_edge;
        let prop_head = record.prop_head;

        assert_eq!(id, 42);
        assert_eq!(label_id, 7);
        assert_eq!(flags, 0);
        assert_eq!(first_out_edge, u64::MAX);
        assert_eq!(first_in_edge, u64::MAX);
        assert_eq!(prop_head, u64::MAX);
        assert!(!record.is_deleted());
    }

    #[test]
    fn test_node_record_deleted_flag() {
        let mut record = NodeRecord::new(0, 0);

        assert!(!record.is_deleted());

        record.mark_deleted();
        assert!(record.is_deleted());

        // Verify flag is set correctly
        let flags = record.flags;
        assert_eq!(flags & NODE_FLAG_DELETED, NODE_FLAG_DELETED);
    }

    #[test]
    fn test_node_record_roundtrip() {
        let mut record = NodeRecord::new(123, 456);
        record.flags = 0x0003; // Set some flags
        record.first_out_edge = 789;
        record.first_in_edge = 101112;
        record.prop_head = 131415;

        // Copy original values
        let orig_id = record.id;
        let orig_label_id = record.label_id;
        let orig_flags = record.flags;
        let orig_first_out_edge = record.first_out_edge;
        let orig_first_in_edge = record.first_in_edge;
        let orig_prop_head = record.prop_head;

        // Convert to bytes
        let bytes = record.to_bytes();
        assert_eq!(bytes.len(), NODE_RECORD_SIZE);

        // Convert back from bytes
        let recovered = NodeRecord::from_bytes(&bytes);

        // Copy recovered values
        let rec_id = recovered.id;
        let rec_label_id = recovered.label_id;
        let rec_flags = recovered.flags;
        let rec_first_out_edge = recovered.first_out_edge;
        let rec_first_in_edge = recovered.first_in_edge;
        let rec_prop_head = recovered.prop_head;

        // Verify all fields match
        assert_eq!(rec_id, orig_id);
        assert_eq!(rec_label_id, orig_label_id);
        assert_eq!(rec_flags, orig_flags);
        assert_eq!(rec_first_out_edge, orig_first_out_edge);
        assert_eq!(rec_first_in_edge, orig_first_in_edge);
        assert_eq!(rec_prop_head, orig_prop_head);
    }

    #[test]
    fn test_node_record_byte_order() {
        // Verify fields are stored in little-endian format
        let record = NodeRecord::new(0x0102030405060708u64, 0x090A0B0Cu32);

        let bytes = record.to_bytes();

        // id starts at offset 0
        let id_bytes: [u8; 8] = [
            bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7],
        ];
        assert_eq!(id_bytes[0], 0x08); // Little-endian: LSB first
        assert_eq!(id_bytes[7], 0x01);

        // label_id starts at offset 8
        let label_id_bytes: [u8; 4] = [bytes[8], bytes[9], bytes[10], bytes[11]];
        assert_eq!(label_id_bytes[0], 0x0C); // Little-endian: LSB first
        assert_eq!(label_id_bytes[3], 0x09);
    }

    #[test]
    fn test_node_record_no_unexpected_padding() {
        // Verify there's no unexpected padding in the struct
        // We explicitly include _padding field to reach 48 bytes

        let record = NodeRecord::new(0, 0);
        let bytes = record.to_bytes();

        // All 48 bytes should be defined (no random padding)
        assert_eq!(bytes.len(), 48);
    }

    // =========================================================================
    // EdgeRecord Tests
    // =========================================================================

    #[test]
    fn test_edge_record_size() {
        // EdgeRecord must be exactly 56 bytes
        assert_eq!(
            std::mem::size_of::<EdgeRecord>(),
            EDGE_RECORD_SIZE,
            "EdgeRecord size must be exactly 56 bytes"
        );
    }

    #[test]
    fn test_edge_record_alignment() {
        // Verify packed struct layout
        // id: u64 (8 bytes)
        // label_id: u32 (4 bytes)
        // flags: u32 (4 bytes)
        // src: u64 (8 bytes)
        // dst: u64 (8 bytes)
        // next_out: u64 (8 bytes)
        // next_in: u64 (8 bytes)
        // prop_head: u64 (8 bytes)
        // Total: 8 + 4 + 4 + 8 + 8 + 8 + 8 + 8 = 56 bytes

        assert_eq!(
            std::mem::size_of::<EdgeRecord>(),
            8 + 4 + 4 + 8 + 8 + 8 + 8 + 8,
            "EdgeRecord fields should sum to 56 bytes"
        );
    }

    #[test]
    fn test_edge_record_new() {
        let record = EdgeRecord::new(42, 7, 100, 200);

        // Copy values to avoid unaligned reference errors
        let id = record.id;
        let label_id = record.label_id;
        let flags = record.flags;
        let src = record.src;
        let dst = record.dst;
        let next_out = record.next_out;
        let next_in = record.next_in;
        let prop_head = record.prop_head;

        assert_eq!(id, 42);
        assert_eq!(label_id, 7);
        assert_eq!(flags, 0);
        assert_eq!(src, 100);
        assert_eq!(dst, 200);
        assert_eq!(next_out, u64::MAX);
        assert_eq!(next_in, u64::MAX);
        assert_eq!(prop_head, u64::MAX);
        assert!(!record.is_deleted());
    }

    #[test]
    fn test_edge_record_deleted_flag() {
        let mut record = EdgeRecord::new(0, 0, 0, 0);

        assert!(!record.is_deleted());

        record.mark_deleted();
        assert!(record.is_deleted());

        // Verify flag is set correctly
        let flags = record.flags;
        assert_eq!(flags & EDGE_FLAG_DELETED, EDGE_FLAG_DELETED);
    }

    #[test]
    fn test_edge_record_roundtrip() {
        let mut record = EdgeRecord::new(123, 456, 789, 101112);
        record.flags = 0x0001; // Set deleted flag
        record.next_out = 131415;
        record.next_in = 161718;
        record.prop_head = 192021;

        // Copy original values
        let orig_id = record.id;
        let orig_label_id = record.label_id;
        let orig_flags = record.flags;
        let orig_src = record.src;
        let orig_dst = record.dst;
        let orig_next_out = record.next_out;
        let orig_next_in = record.next_in;
        let orig_prop_head = record.prop_head;

        // Convert to bytes
        let bytes = record.to_bytes();
        assert_eq!(bytes.len(), EDGE_RECORD_SIZE);

        // Convert back from bytes
        let recovered = EdgeRecord::from_bytes(&bytes);

        // Copy recovered values
        let rec_id = recovered.id;
        let rec_label_id = recovered.label_id;
        let rec_flags = recovered.flags;
        let rec_src = recovered.src;
        let rec_dst = recovered.dst;
        let rec_next_out = recovered.next_out;
        let rec_next_in = recovered.next_in;
        let rec_prop_head = recovered.prop_head;

        // Verify all fields match
        assert_eq!(rec_id, orig_id);
        assert_eq!(rec_label_id, orig_label_id);
        assert_eq!(rec_flags, orig_flags);
        assert_eq!(rec_src, orig_src);
        assert_eq!(rec_dst, orig_dst);
        assert_eq!(rec_next_out, orig_next_out);
        assert_eq!(rec_next_in, orig_next_in);
        assert_eq!(rec_prop_head, orig_prop_head);
        assert!(recovered.is_deleted());
    }

    #[test]
    fn test_edge_record_byte_order() {
        // Verify fields are stored in little-endian format
        let record = EdgeRecord::new(
            0x0102030405060708u64,
            0x090A0B0Cu32,
            0x0D0E0F1011121314u64,
            0x1516171819202122u64,
        );

        let bytes = record.to_bytes();

        // id starts at offset 0
        let id_bytes: [u8; 8] = [
            bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7],
        ];
        assert_eq!(id_bytes[0], 0x08); // Little-endian: LSB first
        assert_eq!(id_bytes[7], 0x01);

        // label_id starts at offset 8
        let label_id_bytes: [u8; 4] = [bytes[8], bytes[9], bytes[10], bytes[11]];
        assert_eq!(label_id_bytes[0], 0x0C); // Little-endian: LSB first
        assert_eq!(label_id_bytes[3], 0x09);

        // src starts at offset 16
        let src_bytes: [u8; 8] = [
            bytes[16], bytes[17], bytes[18], bytes[19], bytes[20], bytes[21], bytes[22], bytes[23],
        ];
        assert_eq!(src_bytes[0], 0x14); // Little-endian: LSB first
        assert_eq!(src_bytes[7], 0x0D);
    }

    #[test]
    fn test_edge_record_no_unexpected_padding() {
        // Verify there's no unexpected padding in the struct
        let record = EdgeRecord::new(0, 0, 0, 0);
        let bytes = record.to_bytes();

        // All 56 bytes should be defined (no random padding)
        assert_eq!(bytes.len(), 56);
    }

    #[test]
    fn test_edge_record_linked_list_pointers() {
        // Test that next_out and next_in can be used for linked lists
        let mut edge1 = EdgeRecord::new(0, 0, 10, 20);
        let mut edge2 = EdgeRecord::new(1, 0, 10, 30);
        let mut edge3 = EdgeRecord::new(2, 0, 10, 40);

        // Build linked list: edge1 -> edge2 -> edge3 -> MAX
        edge1.next_out = 1; // Points to edge2
        edge2.next_out = 2; // Points to edge3
        edge3.next_out = u64::MAX; // End of list

        // Verify chain (copy values to avoid unaligned reference)
        let next_out_1 = edge1.next_out;
        let next_out_2 = edge2.next_out;
        let next_out_3 = edge3.next_out;

        assert_eq!(next_out_1, 1);
        assert_eq!(next_out_2, 2);
        assert_eq!(next_out_3, u64::MAX);

        // Verify this survives serialization
        let bytes1 = edge1.to_bytes();
        let recovered1 = EdgeRecord::from_bytes(&bytes1);
        let recovered_next_out = recovered1.next_out;
        assert_eq!(recovered_next_out, 1);
    }

    #[test]
    fn test_flag_constants() {
        // Verify flag constants are non-overlapping
        assert_eq!(NODE_FLAG_DELETED, 0x0001);
        assert_eq!(NODE_FLAG_INDEXED, 0x0002);
        assert_eq!(EDGE_FLAG_DELETED, 0x0001);

        // Verify flags can be combined
        let combined = NODE_FLAG_DELETED | NODE_FLAG_INDEXED;
        assert_eq!(combined, 0x0003);
        assert_ne!(combined & NODE_FLAG_DELETED, 0);
        assert_ne!(combined & NODE_FLAG_INDEXED, 0);
    }

    // =========================================================================
    // PropertyEntry Tests
    // =========================================================================

    #[test]
    fn test_property_entry_size() {
        // PropertyEntry header must be exactly 17 bytes
        assert_eq!(
            std::mem::size_of::<PropertyEntry>(),
            PROPERTY_ENTRY_HEADER_SIZE,
            "PropertyEntry size must be exactly 17 bytes"
        );
    }

    #[test]
    fn test_property_entry_alignment() {
        // Verify packed struct layout
        // key_id: u32 (4 bytes)
        // value_type: u8 (1 byte)
        // value_len: u32 (4 bytes)
        // next: u64 (8 bytes)
        // Total: 4 + 1 + 4 + 8 = 17 bytes

        assert_eq!(
            std::mem::size_of::<PropertyEntry>(),
            4 + 1 + 4 + 8,
            "PropertyEntry fields should sum to 17 bytes"
        );
    }

    #[test]
    fn test_property_entry_new() {
        let entry = PropertyEntry::new(42, 5, 128, 1024);

        // Copy values to avoid unaligned reference errors
        let key_id = entry.key_id;
        let value_type = entry.value_type;
        let value_len = entry.value_len;
        let next = entry.next;

        assert_eq!(key_id, 42);
        assert_eq!(value_type, 5);
        assert_eq!(value_len, 128);
        assert_eq!(next, 1024);
    }

    #[test]
    fn test_property_entry_roundtrip() {
        let entry = PropertyEntry::new(123, 7, 256, 4096);

        // Copy original values
        let orig_key_id = entry.key_id;
        let orig_value_type = entry.value_type;
        let orig_value_len = entry.value_len;
        let orig_next = entry.next;

        // Convert to bytes
        let bytes = entry.to_bytes();
        assert_eq!(bytes.len(), PROPERTY_ENTRY_HEADER_SIZE);

        // Convert back from bytes
        let recovered = PropertyEntry::from_bytes(&bytes);

        // Copy recovered values
        let rec_key_id = recovered.key_id;
        let rec_value_type = recovered.value_type;
        let rec_value_len = recovered.value_len;
        let rec_next = recovered.next;

        // Verify all fields match
        assert_eq!(rec_key_id, orig_key_id);
        assert_eq!(rec_value_type, orig_value_type);
        assert_eq!(rec_value_len, orig_value_len);
        assert_eq!(rec_next, orig_next);
    }

    #[test]
    fn test_property_entry_byte_order() {
        // Verify fields are stored in little-endian format
        let entry = PropertyEntry::new(0x01020304u32, 0xAAu8, 0x05060708u32, 0x090A0B0C0D0E0F10u64);

        let bytes = entry.to_bytes();

        // key_id starts at offset 0
        let key_id_bytes: [u8; 4] = [bytes[0], bytes[1], bytes[2], bytes[3]];
        assert_eq!(key_id_bytes[0], 0x04); // Little-endian: LSB first
        assert_eq!(key_id_bytes[3], 0x01);

        // value_type at offset 4
        assert_eq!(bytes[4], 0xAA);

        // value_len starts at offset 5
        let value_len_bytes: [u8; 4] = [bytes[5], bytes[6], bytes[7], bytes[8]];
        assert_eq!(value_len_bytes[0], 0x08); // Little-endian: LSB first
        assert_eq!(value_len_bytes[3], 0x05);

        // next starts at offset 9
        let next_bytes: [u8; 8] = [
            bytes[9], bytes[10], bytes[11], bytes[12], bytes[13], bytes[14], bytes[15], bytes[16],
        ];
        assert_eq!(next_bytes[0], 0x10); // Little-endian: LSB first
        assert_eq!(next_bytes[7], 0x09);
    }

    #[test]
    fn test_property_entry_end_of_list() {
        // Test that u64::MAX is correctly used as end-of-list marker
        let entry = PropertyEntry::new(1, 2, 3, u64::MAX);

        let bytes = entry.to_bytes();
        let recovered = PropertyEntry::from_bytes(&bytes);

        let next = recovered.next;
        assert_eq!(next, u64::MAX, "End-of-list marker should be u64::MAX");
    }

    #[test]
    fn test_property_entry_no_unexpected_padding() {
        // Verify there's no unexpected padding in the struct
        let entry = PropertyEntry::new(0, 0, 0, 0);
        let bytes = entry.to_bytes();

        // All 17 bytes should be defined
        assert_eq!(bytes.len(), 17);
    }

    // =========================================================================
    // StringEntry Tests
    // =========================================================================

    #[test]
    fn test_string_entry_size() {
        // StringEntry header must be exactly 8 bytes
        assert_eq!(
            std::mem::size_of::<StringEntry>(),
            STRING_ENTRY_HEADER_SIZE,
            "StringEntry size must be exactly 8 bytes"
        );
    }

    #[test]
    fn test_string_entry_alignment() {
        // Verify packed struct layout
        // id: u32 (4 bytes)
        // len: u32 (4 bytes)
        // Total: 4 + 4 = 8 bytes

        assert_eq!(
            std::mem::size_of::<StringEntry>(),
            4 + 4,
            "StringEntry fields should sum to 8 bytes"
        );
    }

    #[test]
    fn test_string_entry_new() {
        let entry = StringEntry::new(42, 128);

        // Copy values to avoid unaligned reference errors
        let id = entry.id;
        let len = entry.len;

        assert_eq!(id, 42);
        assert_eq!(len, 128);
    }

    #[test]
    fn test_string_entry_roundtrip() {
        let entry = StringEntry::new(123, 456);

        // Copy original values
        let orig_id = entry.id;
        let orig_len = entry.len;

        // Convert to bytes
        let bytes = entry.to_bytes();
        assert_eq!(bytes.len(), STRING_ENTRY_HEADER_SIZE);

        // Convert back from bytes
        let recovered = StringEntry::from_bytes(&bytes);

        // Copy recovered values
        let rec_id = recovered.id;
        let rec_len = recovered.len;

        // Verify all fields match
        assert_eq!(rec_id, orig_id);
        assert_eq!(rec_len, orig_len);
    }

    #[test]
    fn test_string_entry_byte_order() {
        // Verify fields are stored in little-endian format
        let entry = StringEntry::new(0x01020304u32, 0x05060708u32);

        let bytes = entry.to_bytes();

        // id starts at offset 0
        let id_bytes: [u8; 4] = [bytes[0], bytes[1], bytes[2], bytes[3]];
        assert_eq!(id_bytes[0], 0x04); // Little-endian: LSB first
        assert_eq!(id_bytes[3], 0x01);

        // len starts at offset 4
        let len_bytes: [u8; 4] = [bytes[4], bytes[5], bytes[6], bytes[7]];
        assert_eq!(len_bytes[0], 0x08); // Little-endian: LSB first
        assert_eq!(len_bytes[3], 0x05);
    }

    #[test]
    fn test_string_entry_zero_length() {
        // Test that zero-length strings are handled correctly
        let entry = StringEntry::new(1, 0);

        let bytes = entry.to_bytes();
        let recovered = StringEntry::from_bytes(&bytes);

        let len = recovered.len;
        assert_eq!(len, 0, "Zero-length string should be valid");
    }

    #[test]
    fn test_string_entry_large_length() {
        // Test that large string lengths are handled correctly
        let entry = StringEntry::new(1, u32::MAX);

        let bytes = entry.to_bytes();
        let recovered = StringEntry::from_bytes(&bytes);

        let len = recovered.len;
        assert_eq!(len, u32::MAX, "Large string length should be preserved");
    }

    #[test]
    fn test_string_entry_no_unexpected_padding() {
        // Verify there's no unexpected padding in the struct
        let entry = StringEntry::new(0, 0);
        let bytes = entry.to_bytes();

        // All 8 bytes should be defined
        assert_eq!(bytes.len(), 8);
    }

    // =========================================================================
    // Cross-Structure Tests
    // =========================================================================

    #[test]
    fn test_all_record_sizes() {
        // Verify all record sizes match their constants
        assert_eq!(std::mem::size_of::<FileHeader>(), HEADER_SIZE);
        assert_eq!(std::mem::size_of::<FileHeaderV1>(), HEADER_SIZE_V1);
        assert_eq!(std::mem::size_of::<NodeRecord>(), NODE_RECORD_SIZE);
        assert_eq!(std::mem::size_of::<EdgeRecord>(), EDGE_RECORD_SIZE);
        assert_eq!(
            std::mem::size_of::<PropertyEntry>(),
            PROPERTY_ENTRY_HEADER_SIZE
        );
        assert_eq!(std::mem::size_of::<StringEntry>(), STRING_ENTRY_HEADER_SIZE);
    }

    #[test]
    fn test_constant_values() {
        // Verify all constant values are as specified
        assert_eq!(MAGIC, 0x47524D4C);
        assert_eq!(VERSION, 2);
        assert_eq!(MIN_READABLE_VERSION, 1);
        assert_eq!(HEADER_SIZE, 192);
        assert_eq!(HEADER_SIZE_V1, 136);
        assert_eq!(NODE_RECORD_SIZE, 48);
        assert_eq!(EDGE_RECORD_SIZE, 56);
        assert_eq!(PROPERTY_ENTRY_HEADER_SIZE, 17);
        assert_eq!(STRING_ENTRY_HEADER_SIZE, 8);
        assert_eq!(DEFAULT_PAGE_SIZE, 4096);
        assert_eq!(ENDIAN_LITTLE, 1);
        assert_eq!(ENDIAN_BIG, 2);
    }

    // =========================================================================
    // QueryRegionHeader Tests
    // =========================================================================

    #[test]
    fn test_query_region_header_size() {
        assert_eq!(
            std::mem::size_of::<QueryRegionHeader>(),
            QUERY_REGION_HEADER_SIZE,
            "QueryRegionHeader size must be exactly 16 bytes"
        );
    }

    #[test]
    fn test_query_region_header_alignment() {
        // Verify packed struct layout
        // magic: u32 (4 bytes)
        // version: u32 (4 bytes)
        // first_query: u64 (8 bytes)
        // Total: 4 + 4 + 8 = 16 bytes
        assert_eq!(
            std::mem::size_of::<QueryRegionHeader>(),
            4 + 4 + 8,
            "QueryRegionHeader fields should sum to 16 bytes"
        );
    }

    #[test]
    fn test_query_region_header_new() {
        let header = QueryRegionHeader::new();

        let magic = header.magic;
        let version = header.version;
        let first_query = header.first_query;

        assert_eq!(magic, QUERY_REGION_MAGIC);
        assert_eq!(version, QUERY_REGION_VERSION);
        assert_eq!(first_query, u64::MAX);
        assert!(header.is_valid());
    }

    #[test]
    fn test_query_region_header_roundtrip() {
        let mut header = QueryRegionHeader::new();
        header.first_query = 1024;

        let orig_magic = header.magic;
        let orig_version = header.version;
        let orig_first_query = header.first_query;

        let bytes = header.to_bytes();
        assert_eq!(bytes.len(), QUERY_REGION_HEADER_SIZE);

        let recovered = QueryRegionHeader::from_bytes(&bytes);

        let rec_magic = recovered.magic;
        let rec_version = recovered.version;
        let rec_first_query = recovered.first_query;

        assert_eq!(rec_magic, orig_magic);
        assert_eq!(rec_version, orig_version);
        assert_eq!(rec_first_query, orig_first_query);
    }

    #[test]
    fn test_query_region_header_invalid_magic() {
        let mut header = QueryRegionHeader::new();
        header.magic = 0x12345678;
        assert!(!header.is_valid());
    }

    // =========================================================================
    // QueryRecord Tests
    // =========================================================================

    #[test]
    fn test_query_record_size() {
        assert_eq!(
            std::mem::size_of::<QueryRecord>(),
            QUERY_RECORD_HEADER_SIZE,
            "QueryRecord size must be exactly 36 bytes"
        );
    }

    #[test]
    fn test_query_record_alignment() {
        // Verify packed struct layout
        // id: u32 (4 bytes)
        // flags: u16 (2 bytes)
        // param_count: u16 (2 bytes)
        // name_len: u16 (2 bytes)
        // description_len: u16 (2 bytes)
        // query_len: u32 (4 bytes)
        // record_size: u32 (4 bytes)
        // next: u64 (8 bytes)
        // prev: u64 (8 bytes)
        // Total: 4 + 2 + 2 + 2 + 2 + 4 + 4 + 8 + 8 = 36 bytes
        assert_eq!(
            std::mem::size_of::<QueryRecord>(),
            4 + 2 + 2 + 2 + 2 + 4 + 4 + 8 + 8,
            "QueryRecord fields should sum to 36 bytes"
        );
    }

    #[test]
    fn test_query_record_new() {
        let record = QueryRecord::new(
            42,                 // id
            QUERY_TYPE_GREMLIN, // query_type
            2,                  // param_count
            10,                 // name_len
            50,                 // description_len
            100,                // query_len
            200,                // record_size
        );

        let id = record.id;
        let param_count = record.param_count;
        let name_len = record.name_len;
        let description_len = record.description_len;
        let query_len = record.query_len;
        let record_size = record.record_size;
        let next = record.next;
        let prev = record.prev;

        assert_eq!(id, 42);
        assert_eq!(record.query_type(), QUERY_TYPE_GREMLIN);
        assert_eq!(param_count, 2);
        assert_eq!(name_len, 10);
        assert_eq!(description_len, 50);
        assert_eq!(query_len, 100);
        assert_eq!(record_size, 200);
        assert_eq!(next, u64::MAX);
        assert_eq!(prev, u64::MAX);
        assert!(!record.is_deleted());
    }

    #[test]
    fn test_query_record_query_types() {
        let gremlin = QueryRecord::new(1, QUERY_TYPE_GREMLIN, 0, 0, 0, 0, 0);
        let gql = QueryRecord::new(2, QUERY_TYPE_GQL, 0, 0, 0, 0, 0);

        assert_eq!(gremlin.query_type(), QUERY_TYPE_GREMLIN);
        assert_eq!(gql.query_type(), QUERY_TYPE_GQL);
    }

    #[test]
    fn test_query_record_deleted_flag() {
        let mut record = QueryRecord::new(1, QUERY_TYPE_GREMLIN, 0, 0, 0, 0, 0);

        assert!(!record.is_deleted());

        record.mark_deleted();
        assert!(record.is_deleted());

        // Query type should be preserved after marking deleted
        assert_eq!(record.query_type(), QUERY_TYPE_GREMLIN);
    }

    #[test]
    fn test_query_record_roundtrip() {
        let mut record = QueryRecord::new(123, QUERY_TYPE_GQL, 3, 20, 100, 500, 700);
        record.next = 1000;
        record.prev = 500;

        let orig_id = record.id;
        let orig_flags = record.flags;
        let orig_param_count = record.param_count;
        let orig_name_len = record.name_len;
        let orig_description_len = record.description_len;
        let orig_query_len = record.query_len;
        let orig_record_size = record.record_size;
        let orig_next = record.next;
        let orig_prev = record.prev;

        let bytes = record.to_bytes();
        assert_eq!(bytes.len(), QUERY_RECORD_HEADER_SIZE);

        let recovered = QueryRecord::from_bytes(&bytes);

        let rec_id = recovered.id;
        let rec_flags = recovered.flags;
        let rec_param_count = recovered.param_count;
        let rec_name_len = recovered.name_len;
        let rec_description_len = recovered.description_len;
        let rec_query_len = recovered.query_len;
        let rec_record_size = recovered.record_size;
        let rec_next = recovered.next;
        let rec_prev = recovered.prev;

        assert_eq!(rec_id, orig_id);
        assert_eq!(rec_flags, orig_flags);
        assert_eq!(rec_param_count, orig_param_count);
        assert_eq!(rec_name_len, orig_name_len);
        assert_eq!(rec_description_len, orig_description_len);
        assert_eq!(rec_query_len, orig_query_len);
        assert_eq!(rec_record_size, orig_record_size);
        assert_eq!(rec_next, orig_next);
        assert_eq!(rec_prev, orig_prev);
    }

    #[test]
    fn test_query_record_byte_order() {
        let record = QueryRecord::new(
            0x01020304u32,
            QUERY_TYPE_GREMLIN,
            0x0506u16,
            0x0708u16,
            0x090Au16,
            0x0B0C0D0Eu32,
            0x0F101112u32,
        );

        let bytes = record.to_bytes();

        // id starts at offset 0
        let id_bytes: [u8; 4] = [bytes[0], bytes[1], bytes[2], bytes[3]];
        assert_eq!(id_bytes[0], 0x04); // Little-endian: LSB first
        assert_eq!(id_bytes[3], 0x01);
    }

    // =========================================================================
    // ParameterEntry Tests
    // =========================================================================

    #[test]
    fn test_parameter_entry_size() {
        assert_eq!(
            std::mem::size_of::<ParameterEntry>(),
            PARAMETER_ENTRY_HEADER_SIZE,
            "ParameterEntry size must be exactly 4 bytes"
        );
    }

    #[test]
    fn test_parameter_entry_alignment() {
        // Verify packed struct layout
        // name_len: u16 (2 bytes)
        // value_type: u8 (1 byte)
        // _reserved: u8 (1 byte)
        // Total: 2 + 1 + 1 = 4 bytes
        assert_eq!(
            std::mem::size_of::<ParameterEntry>(),
            2 + 1 + 1,
            "ParameterEntry fields should sum to 4 bytes"
        );
    }

    #[test]
    fn test_parameter_entry_new() {
        let entry = ParameterEntry::new(10, 0x02); // 0x02 = Int type

        let name_len = entry.name_len;
        let value_type = entry.value_type;
        let reserved = entry._reserved;

        assert_eq!(name_len, 10);
        assert_eq!(value_type, 0x02);
        assert_eq!(reserved, 0);
    }

    #[test]
    fn test_parameter_entry_new_any() {
        let entry = ParameterEntry::new_any(15);

        let name_len = entry.name_len;
        let value_type = entry.value_type;

        assert_eq!(name_len, 15);
        assert_eq!(value_type, PARAMETER_TYPE_ANY);
    }

    #[test]
    fn test_parameter_entry_roundtrip() {
        let entry = ParameterEntry::new(25, 0x04); // 0x04 = String type

        let orig_name_len = entry.name_len;
        let orig_value_type = entry.value_type;

        let bytes = entry.to_bytes();
        assert_eq!(bytes.len(), PARAMETER_ENTRY_HEADER_SIZE);

        let recovered = ParameterEntry::from_bytes(&bytes);

        let rec_name_len = recovered.name_len;
        let rec_value_type = recovered.value_type;

        assert_eq!(rec_name_len, orig_name_len);
        assert_eq!(rec_value_type, orig_value_type);
    }

    #[test]
    fn test_parameter_entry_total_size() {
        let entry = ParameterEntry::new(20, 0x02);
        assert_eq!(entry.total_size(), PARAMETER_ENTRY_HEADER_SIZE + 20);
    }

    #[test]
    fn test_parameter_entry_byte_order() {
        let entry = ParameterEntry::new(0x0102u16, 0xAB);

        let bytes = entry.to_bytes();

        // name_len starts at offset 0
        let name_len_bytes: [u8; 2] = [bytes[0], bytes[1]];
        assert_eq!(name_len_bytes[0], 0x02); // Little-endian: LSB first
        assert_eq!(name_len_bytes[1], 0x01);

        // value_type at offset 2
        assert_eq!(bytes[2], 0xAB);

        // _reserved at offset 3
        assert_eq!(bytes[3], 0x00);
    }

    // =========================================================================
    // Query Storage Constants Tests
    // =========================================================================

    #[test]
    fn test_query_storage_constants() {
        assert_eq!(QUERY_REGION_MAGIC, 0x51525953);
        assert_eq!(QUERY_REGION_VERSION, 1);
        assert_eq!(QUERY_REGION_HEADER_SIZE, 16);
        assert_eq!(QUERY_RECORD_HEADER_SIZE, 36);
        assert_eq!(PARAMETER_ENTRY_HEADER_SIZE, 4);
        assert_eq!(QUERY_FLAG_DELETED, 0x0001);
        assert_eq!(QUERY_TYPE_MASK, 0x0006);
        assert_eq!(QUERY_TYPE_SHIFT, 1);
        assert_eq!(QUERY_TYPE_GREMLIN, 1);
        assert_eq!(QUERY_TYPE_GQL, 2);
        assert_eq!(PARAMETER_TYPE_ANY, 0xFF);
    }

    // =========================================================================
    // FileHeader Query Metadata Helper Tests
    // =========================================================================

    #[test]
    fn test_file_header_query_metadata_default() {
        let header = FileHeader::new();

        // New headers should have no query region
        assert!(!header.has_query_region());
        assert_eq!(header.query_store_offset(), 0);
        assert_eq!(header.query_store_end(), 0);
        assert_eq!(header.query_count(), 0);
        assert_eq!(header.next_query_id(), 0);
    }

    #[test]
    fn test_file_header_query_metadata_setters() {
        let mut header = FileHeader::new();

        // Set query metadata
        header.set_query_store_offset(1000);
        header.set_query_store_end(2000);
        header.set_query_count(5);
        header.set_next_query_id(10);

        // Verify values
        assert!(header.has_query_region());
        assert_eq!(header.query_store_offset(), 1000);
        assert_eq!(header.query_store_end(), 2000);
        assert_eq!(header.query_count(), 5);
        assert_eq!(header.next_query_id(), 10);
    }

    #[test]
    fn test_file_header_query_metadata_roundtrip() {
        let mut header = FileHeader::new();

        // Set various query metadata values
        header.set_query_store_offset(0x123456789ABCDEF0);
        header.set_query_store_end(0xFEDCBA9876543210);
        header.set_query_count(0x12345678);
        header.set_next_query_id(0x87654321);
        header.update_crc32();

        // Serialize and deserialize
        let bytes = header.to_bytes();
        let recovered = FileHeader::from_bytes(&bytes);

        // Verify query metadata survives roundtrip
        assert_eq!(recovered.query_store_offset(), 0x123456789ABCDEF0);
        assert_eq!(recovered.query_store_end(), 0xFEDCBA9876543210);
        assert_eq!(recovered.query_count(), 0x12345678);
        assert_eq!(recovered.next_query_id(), 0x87654321);
        assert!(recovered.has_query_region());
    }

    #[test]
    fn test_file_header_query_metadata_crc_after_change() {
        let mut header = FileHeader::new();

        // Initially valid CRC
        assert!(header.validate_crc32());

        // Modify query metadata (changes _reserved bytes)
        header.set_query_store_offset(1000);

        // CRC should now be invalid (reserved bytes are not included in CRC)
        // Actually, the CRC covers bytes 0-151, and _reserved starts at 156
        // So CRC should still be valid since _reserved isn't in the CRC range
        assert!(header.validate_crc32());
    }

    #[test]
    fn test_file_header_query_metadata_byte_layout() {
        let mut header = FileHeader::new();

        // Set known values to verify byte layout
        header.set_query_store_offset(0x0807060504030201);
        header.set_query_store_end(0x100F0E0D0C0B0A09);
        header.set_query_count(0x14131211);
        header.set_next_query_id(0x18171615);

        let bytes = header.to_bytes();

        // _reserved starts at offset 156
        // query_store_offset at _reserved[0..8]
        assert_eq!(bytes[156], 0x01); // LSB
        assert_eq!(bytes[163], 0x08); // MSB

        // query_store_end at _reserved[8..16]
        assert_eq!(bytes[164], 0x09); // LSB
        assert_eq!(bytes[171], 0x10); // MSB

        // query_count at _reserved[16..20]
        assert_eq!(bytes[172], 0x11); // LSB
        assert_eq!(bytes[175], 0x14); // MSB

        // next_query_id at _reserved[20..24]
        assert_eq!(bytes[176], 0x15); // LSB
        assert_eq!(bytes[179], 0x18); // MSB
    }

    #[test]
    fn test_file_header_has_query_region() {
        let mut header = FileHeader::new();

        // No query region initially
        assert!(!header.has_query_region());

        // Setting offset to non-zero indicates query region exists
        header.set_query_store_offset(1);
        assert!(header.has_query_region());

        // Setting back to zero
        header.set_query_store_offset(0);
        assert!(!header.has_query_region());
    }
}