sochdb_storage/

zero_copy_safety.rs

// SPDX-License-Identifier: AGPL-3.0-or-later
// SochDB - LLM-Optimized Embedded Database
// Copyright (C) 2026 Sushanth Reddy Vanagala (https://github.com/sushanthpy)
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.

//! Zero-Copy Safety with Validation Layer (Task 5)
//!
//! Implements defense-in-depth validation for memory-mapped files to prevent crashes
//! from corrupted, truncated, or tampered files.
//!
//! ## Safety Model
//!
//! Defense-in-Depth Validation:
//!
//! Layer 1: Pre-mmap File Validation
//!   - Check file size: size ≥ HEADER_SIZE + MIN_ENTRIES × EDGE_SIZE + FOOTER_SIZE
//!   - Read & verify header magic and version
//!   - Read & verify footer checksum
//!   - Sample validation: K = ceiling(ln(1/δ) / ε) random edges
//!
//! Layer 2: Bounded Access Wrappers
//!   - Validated constructors with bounds checking
//!   - Type-safe API prevents misuse at compile-time
//!   - All offset dereferences bounds-checked
//!
//! Layer 3: Runtime Mmap Protection
//!   - ValidatedMmap wrapper for all accesses
//!   - Graceful handling of SIGBUS from truncated files
//!
//! ## Probabilistic Sampling
//!
//! Instead of O(N) full validation, sample K random edges:
//!   K = ceiling(ln(1/δ) / ε)
//! Where:
//!   δ = false negative rate (e.g., 0.01 = 1% miss rate)
//!   ε = corruption fraction (e.g., 0.01 = 1% bad edges)
//!
//! Example: δ = 0.01, ε = 0.01 → K = 461 samples
//! Time: O(K) = O(log(1/δ) / ε) independent of file size

use std::collections::HashSet;
use std::fs::File;
use std::io::{Read, Seek, SeekFrom};
use std::marker::PhantomData;
use std::ops::Range;
use std::path::Path;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};

use byteorder::{ByteOrder, LittleEndian};

// ============================================================================
// Constants
// ============================================================================

/// SochDB magic number for SSTable files
pub const SOCHDB_MAGIC: u64 = 0x544F4F4E44420001; // "SOCHDB" + version 1

/// Edge magic number (within each edge record)
pub const EDGE_MAGIC: u32 = 0xED6E0001;

/// Standard edge size in bytes
pub const EDGE_SIZE: usize = 128;

/// Header size (magic + version + metadata)
pub const HEADER_SIZE: usize = 64;

/// Footer size (checksum + stats + index offset)
pub const FOOTER_SIZE: usize = 144;

/// Minimum valid file size
pub const MIN_FILE_SIZE: u64 = (HEADER_SIZE + EDGE_SIZE + FOOTER_SIZE) as u64;

/// Maximum reasonable file size (10 GB)
pub const MAX_FILE_SIZE: u64 = 10 * 1024 * 1024 * 1024;

/// Supported format versions
pub const SUPPORTED_VERSIONS: &[u32] = &[1, 2];

// ============================================================================
// Validation Errors
// ============================================================================

/// Validation error types with detailed context
#[derive(Debug, Clone)]
pub enum ValidationError {
    /// File is smaller than minimum valid size
    FileTooSmall { actual: u64, minimum: u64 },
    /// File is larger than maximum supported size
    FileTooLarge { actual: u64, maximum: u64 },
    /// Invalid magic number at file header
    BadMagic { expected: u64, actual: u64 },
    /// Unsupported format version
    UnsupportedVersion { version: u32, supported: Vec<u32> },
    /// Footer checksum does not match
    ChecksumMismatch {
        expected: [u8; 32],
        actual: [u8; 32],
    },
    /// Edge at given index is corrupted
    CorruptedEdge { index: usize, reason: String },
    /// Offset points outside valid data region
    InvalidOffset { offset: u64, max: u64 },
    /// Length would exceed data region
    InvalidLength { offset: u64, length: u64, max: u64 },
    /// Alignment violation
    AlignmentViolation {
        offset: u64,
        required_alignment: usize,
    },
    /// Access to unmapped or invalid region
    OutOfBounds {
        offset: usize,
        length: usize,
        region_size: usize,
    },
    /// I/O error during validation
    IoError(String),
    /// File was truncated after mmap
    TruncatedFile { expected: u64, actual: u64 },
}

impl std::fmt::Display for ValidationError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::FileTooSmall { actual, minimum } => {
                write!(f, "File too small: {} bytes (minimum: {})", actual, minimum)
            }
            Self::FileTooLarge { actual, maximum } => {
                write!(f, "File too large: {} bytes (maximum: {})", actual, maximum)
            }
            Self::BadMagic { expected, actual } => {
                write!(f, "Bad magic: {:#x} (expected {:#x})", actual, expected)
            }
            Self::UnsupportedVersion { version, supported } => {
                write!(
                    f,
                    "Unsupported version: {} (supported: {:?})",
                    version, supported
                )
            }
            Self::ChecksumMismatch { expected, actual } => {
                write!(
                    f,
                    "Checksum mismatch: {} vs {}",
                    hex::encode(expected),
                    hex::encode(actual)
                )
            }
            Self::CorruptedEdge { index, reason } => {
                write!(f, "Corrupted edge at index {}: {}", index, reason)
            }
            Self::InvalidOffset { offset, max } => {
                write!(f, "Invalid offset: {} (max: {})", offset, max)
            }
            Self::InvalidLength {
                offset,
                length,
                max,
            } => {
                write!(
                    f,
                    "Invalid length: {} at offset {} (max: {})",
                    length, offset, max
                )
            }
            Self::AlignmentViolation {
                offset,
                required_alignment,
            } => {
                write!(
                    f,
                    "Alignment violation at {}: required {} byte alignment",
                    offset, required_alignment
                )
            }
            Self::OutOfBounds {
                offset,
                length,
                region_size,
            } => {
                write!(
                    f,
                    "Out of bounds: [{}..{}] in region of size {}",
                    offset,
                    offset + length,
                    region_size
                )
            }
            Self::IoError(e) => write!(f, "I/O error: {}", e),
            Self::TruncatedFile { expected, actual } => {
                write!(
                    f,
                    "File truncated: expected {} bytes, got {}",
                    expected, actual
                )
            }
        }
    }
}

impl std::error::Error for ValidationError {}

impl From<std::io::Error> for ValidationError {
    fn from(e: std::io::Error) -> Self {
        ValidationError::IoError(e.to_string())
    }
}

// ============================================================================
// Validation Metrics
// ============================================================================

/// Metrics for validation operations
#[derive(Debug, Default)]
pub struct ValidationMetrics {
    /// Total files validated
    pub files_validated: AtomicU64,
    /// Validation failures
    pub validation_failures: AtomicU64,
    /// Edges sampled for validation
    pub edges_sampled: AtomicU64,
    /// Corrupted edges detected
    pub corrupted_edges_detected: AtomicU64,
    /// Bounds check violations
    pub bounds_violations: AtomicU64,
    /// Total validation time (microseconds)
    pub validation_time_us: AtomicU64,
}

impl ValidationMetrics {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn record_validation(&self, success: bool, duration_us: u64) {
        self.files_validated.fetch_add(1, Ordering::Relaxed);
        if !success {
            self.validation_failures.fetch_add(1, Ordering::Relaxed);
        }
        self.validation_time_us
            .fetch_add(duration_us, Ordering::Relaxed);
    }

    pub fn record_sample(&self, corrupted: bool) {
        self.edges_sampled.fetch_add(1, Ordering::Relaxed);
        if corrupted {
            self.corrupted_edges_detected
                .fetch_add(1, Ordering::Relaxed);
        }
    }

    pub fn record_bounds_violation(&self) {
        self.bounds_violations.fetch_add(1, Ordering::Relaxed);
    }
}

// ============================================================================
// Layer 1: Pre-Mmap File Validation
// ============================================================================

/// Configuration for pre-mmap validation
#[derive(Debug, Clone)]
pub struct ValidationConfig {
    /// Perform full file checksum validation
    pub full_checksum: bool,
    /// Number of random edge samples (0 = no sampling)
    pub sample_count: usize,
    /// Maximum acceptable file size
    pub max_file_size: u64,
    /// Check alignment constraints
    pub check_alignment: bool,
    /// Required alignment for edge data
    pub required_alignment: usize,
}

impl Default for ValidationConfig {
    fn default() -> Self {
        Self {
            full_checksum: false,
            sample_count: 100, // Default: sample 100 edges
            max_file_size: MAX_FILE_SIZE,
            check_alignment: true,
            required_alignment: 8,
        }
    }
}

impl ValidationConfig {
    /// High-security config with full validation
    pub fn high_security() -> Self {
        Self {
            full_checksum: true,
            sample_count: 500,
            max_file_size: MAX_FILE_SIZE,
            check_alignment: true,
            required_alignment: 8,
        }
    }

    /// Fast validation for hot path
    pub fn fast() -> Self {
        Self {
            full_checksum: false,
            sample_count: 0,
            max_file_size: MAX_FILE_SIZE,
            check_alignment: false,
            required_alignment: 1,
        }
    }

    /// Calculate optimal sample count for given parameters
    ///
    /// K = ceiling(ln(1/δ) / ε)
    ///
    /// - delta: false negative rate (probability of missing corruption)
    /// - epsilon: minimum corruption fraction to detect
    pub fn optimal_sample_count(delta: f64, epsilon: f64) -> usize {
        ((1.0 / delta).ln() / epsilon).ceil() as usize
    }
}

/// Pre-mmap file validator
pub struct FileValidator {
    config: ValidationConfig,
    metrics: Arc<ValidationMetrics>,
}

impl FileValidator {
    pub fn new(config: ValidationConfig) -> Self {
        Self {
            config,
            metrics: Arc::new(ValidationMetrics::new()),
        }
    }

    pub fn with_metrics(config: ValidationConfig, metrics: Arc<ValidationMetrics>) -> Self {
        Self { config, metrics }
    }

    pub fn metrics(&self) -> &Arc<ValidationMetrics> {
        &self.metrics
    }

    /// Validate file before memory mapping
    ///
    /// Steps:
    /// 1. Check file size constraints
    /// 2. Read and verify header magic/version
    /// 3. Read and verify footer checksum (optional)
    /// 4. Sample random edges for corruption (optional)
    pub fn validate_before_mmap(
        &self,
        path: &Path,
    ) -> std::result::Result<FileMetadata, ValidationError> {
        let start = std::time::Instant::now();

        let result = self.validate_impl(path);

        let duration_us = start.elapsed().as_micros() as u64;
        self.metrics.record_validation(result.is_ok(), duration_us);

        result
    }

    fn validate_impl(&self, path: &Path) -> std::result::Result<FileMetadata, ValidationError> {
        let mut file = File::open(path)?;
        let file_size = file.metadata()?.len();

        // Step 1: Size constraints
        if file_size < MIN_FILE_SIZE {
            return Err(ValidationError::FileTooSmall {
                actual: file_size,
                minimum: MIN_FILE_SIZE,
            });
        }

        if file_size > self.config.max_file_size {
            return Err(ValidationError::FileTooLarge {
                actual: file_size,
                maximum: self.config.max_file_size,
            });
        }

        // Step 2: Read and verify header
        file.seek(SeekFrom::Start(0))?;
        let mut header = [0u8; HEADER_SIZE];
        file.read_exact(&mut header)?;

        let magic = LittleEndian::read_u64(&header[0..8]);
        if magic != SOCHDB_MAGIC {
            return Err(ValidationError::BadMagic {
                expected: SOCHDB_MAGIC,
                actual: magic,
            });
        }

        let version = LittleEndian::read_u32(&header[8..12]);
        if !SUPPORTED_VERSIONS.contains(&version) {
            return Err(ValidationError::UnsupportedVersion {
                version,
                supported: SUPPORTED_VERSIONS.to_vec(),
            });
        }

        let num_edges = LittleEndian::read_u64(&header[16..24]);
        let data_offset = HEADER_SIZE as u64;
        let data_length = num_edges * EDGE_SIZE as u64;

        // Step 3: Read and verify footer
        file.seek(SeekFrom::End(-(FOOTER_SIZE as i64)))?;
        let mut footer = [0u8; FOOTER_SIZE];
        file.read_exact(&mut footer)?;

        // Optional: Full checksum verification
        if self.config.full_checksum {
            let expected_checksum: [u8; 32] = footer[0..32].try_into().unwrap();
            let actual_checksum =
                self.compute_checksum(&mut file, file_size - FOOTER_SIZE as u64)?;

            if expected_checksum != actual_checksum {
                return Err(ValidationError::ChecksumMismatch {
                    expected: expected_checksum,
                    actual: actual_checksum,
                });
            }
        }

        // Step 4: Sample random edges for corruption detection
        if self.config.sample_count > 0 && num_edges > 0 {
            self.validate_edge_samples(&mut file, data_offset, num_edges)?;
        }

        Ok(FileMetadata {
            file_size,
            version,
            num_edges,
            data_offset,
            data_length,
        })
    }

    fn compute_checksum(
        &self,
        file: &mut File,
        length: u64,
    ) -> std::result::Result<[u8; 32], ValidationError> {
        file.seek(SeekFrom::Start(0))?;

        let mut hasher = blake3::Hasher::new();
        let mut buffer = vec![0u8; 64 * 1024];
        let mut remaining = length;

        while remaining > 0 {
            let to_read = remaining.min(buffer.len() as u64) as usize;
            file.read_exact(&mut buffer[..to_read])?;
            hasher.update(&buffer[..to_read]);
            remaining -= to_read as u64;
        }

        Ok(*hasher.finalize().as_bytes())
    }

    fn validate_edge_samples(
        &self,
        file: &mut File,
        data_offset: u64,
        num_edges: u64,
    ) -> std::result::Result<(), ValidationError> {
        // Use a simple deterministic pseudo-random sampling based on hashing
        // This avoids adding rand dependency while still providing good coverage
        let sample_count = self.config.sample_count.min(num_edges as usize);
        let mut sampled_indices = HashSet::new();

        // Generate sample indices using a simple hash-based PRNG
        let mut seed = 0x12345678u64;
        let prime = 0x9E3779B97F4A7C15u64; // Golden ratio based prime

        while sampled_indices.len() < sample_count {
            seed = seed.wrapping_mul(prime).wrapping_add(1);
            let idx = (seed % num_edges) as usize;
            sampled_indices.insert(idx);
        }

        let mut edge_buffer = [0u8; EDGE_SIZE];

        for idx in sampled_indices {
            let edge_offset = data_offset + (idx as u64 * EDGE_SIZE as u64);
            file.seek(SeekFrom::Start(edge_offset))?;
            file.read_exact(&mut edge_buffer)?;

            let corrupted = !self.validate_edge(&edge_buffer, idx);
            self.metrics.record_sample(corrupted);

            if corrupted {
                return Err(ValidationError::CorruptedEdge {
                    index: idx,
                    reason: "Edge validation failed".to_string(),
                });
            }
        }

        Ok(())
    }

    fn validate_edge(&self, edge_bytes: &[u8; EDGE_SIZE], _index: usize) -> bool {
        // Check edge magic number
        let edge_magic = LittleEndian::read_u32(&edge_bytes[0..4]);
        if edge_magic != EDGE_MAGIC {
            return false;
        }

        // Check edge CRC (last 4 bytes)
        let expected_crc = LittleEndian::read_u32(&edge_bytes[EDGE_SIZE - 4..]);
        let actual_crc = crc32fast::hash(&edge_bytes[..EDGE_SIZE - 4]);

        expected_crc == actual_crc
    }
}

/// Metadata extracted during validation
#[derive(Debug, Clone)]
pub struct FileMetadata {
    pub file_size: u64,
    pub version: u32,
    pub num_edges: u64,
    pub data_offset: u64,
    pub data_length: u64,
}

// ============================================================================
// Layer 2: Bounded Access Wrappers
// ============================================================================

/// Type-safe, bounds-checked edge reference
///
/// Instead of raw transmute, uses validated constructor with bounds check.
pub struct EdgeRef<'a> {
    bytes: &'a [u8; EDGE_SIZE],
    _marker: PhantomData<&'a ()>,
}

impl<'a> EdgeRef<'a> {
    /// Create a new EdgeRef with bounds and validity checking
    ///
    /// Returns Err if:
    /// - offset + EDGE_SIZE > data.len()
    /// - Edge magic is invalid
    /// - Edge CRC does not match
    pub fn new_checked(
        data: &'a [u8],
        offset: usize,
    ) -> std::result::Result<Self, ValidationError> {
        // Bounds check
        if offset + EDGE_SIZE > data.len() {
            return Err(ValidationError::OutOfBounds {
                offset,
                length: EDGE_SIZE,
                region_size: data.len(),
            });
        }

        let slice = &data[offset..offset + EDGE_SIZE];
        let bytes: &[u8; EDGE_SIZE] =
            slice
                .try_into()
                .map_err(|_| ValidationError::InvalidLength {
                    offset: offset as u64,
                    length: EDGE_SIZE as u64,
                    max: data.len() as u64,
                })?;

        // Verify edge magic
        let magic = LittleEndian::read_u32(&bytes[0..4]);
        if magic != EDGE_MAGIC {
            return Err(ValidationError::CorruptedEdge {
                index: offset / EDGE_SIZE,
                reason: format!("Bad edge magic: {:#x}", magic),
            });
        }

        Ok(Self {
            bytes,
            _marker: PhantomData,
        })
    }

    /// Create EdgeRef without validation (unsafe fast path)
    ///
    /// # Safety
    /// Caller must ensure:
    /// - offset + EDGE_SIZE <= data.len()
    /// - Edge data is valid
    pub unsafe fn new_unchecked(data: &'a [u8], offset: usize) -> Self {
        let bytes: &[u8; EDGE_SIZE] = unsafe {
            data[offset..offset + EDGE_SIZE]
                .try_into()
                .unwrap_unchecked()
        };
        Self {
            bytes,
            _marker: PhantomData,
        }
    }

    /// Get raw bytes
    pub fn as_bytes(&self) -> &[u8; EDGE_SIZE] {
        self.bytes
    }

    /// Get source vertex ID (with bounds check)
    pub fn source_id(&self) -> u64 {
        LittleEndian::read_u64(&self.bytes[4..12])
    }

    /// Get target vertex ID (with bounds check)
    pub fn target_id(&self) -> u64 {
        LittleEndian::read_u64(&self.bytes[12..20])
    }

    /// Get edge weight (with bounds check)
    pub fn weight(&self) -> f64 {
        LittleEndian::read_f64(&self.bytes[20..28])
    }

    /// Get edge type (with bounds check)
    pub fn edge_type(&self) -> u32 {
        LittleEndian::read_u32(&self.bytes[28..32])
    }

    /// Get timestamp (with bounds check)
    pub fn timestamp(&self) -> u64 {
        LittleEndian::read_u64(&self.bytes[32..40])
    }

    /// Get payload bytes with bounds validation
    ///
    /// Payload is stored at variable offset within the edge
    pub fn payload_bytes(&self) -> std::result::Result<&'a [u8], ValidationError> {
        let payload_offset = LittleEndian::read_u32(&self.bytes[40..44]) as usize;
        let payload_length = LittleEndian::read_u32(&self.bytes[44..48]) as usize;

        // Bounds check within edge
        if payload_offset + payload_length > EDGE_SIZE - 4 {
            // -4 for CRC
            return Err(ValidationError::InvalidOffset {
                offset: payload_offset as u64,
                max: (EDGE_SIZE - 4) as u64,
            });
        }

        Ok(&self.bytes[payload_offset..payload_offset + payload_length])
    }

    /// Verify edge CRC
    pub fn verify_crc(&self) -> bool {
        let expected_crc = LittleEndian::read_u32(&self.bytes[EDGE_SIZE - 4..]);
        let actual_crc = crc32fast::hash(&self.bytes[..EDGE_SIZE - 4]);
        expected_crc == actual_crc
    }
}

// ============================================================================
// Layer 3: ValidatedMmap Wrapper
// ============================================================================

/// Validated memory-mapped region with bounds checking
///
/// All accesses are bounds-checked to prevent undefined behavior
/// from corrupted or truncated files.
pub struct ValidatedMmap {
    /// Underlying mmap (via memmap2 or similar)
    data: Vec<u8>, // Using Vec for safety; in production use memmap2::Mmap
    /// File metadata from validation
    metadata: FileMetadata,
    /// Whether file has been truncated
    is_valid: AtomicBool,
    /// Access metrics
    metrics: Arc<ValidationMetrics>,
}

impl ValidatedMmap {
    /// Create a new ValidatedMmap with full validation
    pub fn open(
        path: &Path,
        config: ValidationConfig,
    ) -> std::result::Result<Self, ValidationError> {
        let validator = FileValidator::new(config);
        let metadata = validator.validate_before_mmap(path)?;

        // Read entire file (in production, use mmap)
        let mut file = File::open(path)?;
        let mut data = Vec::with_capacity(metadata.file_size as usize);
        file.read_to_end(&mut data)?;

        Ok(Self {
            data,
            metadata,
            is_valid: AtomicBool::new(true),
            metrics: validator.metrics,
        })
    }

    /// Get file metadata
    pub fn metadata(&self) -> &FileMetadata {
        &self.metadata
    }

    /// Check if mmap is still valid
    pub fn is_valid(&self) -> bool {
        self.is_valid.load(Ordering::Acquire)
    }

    /// Get a validated edge reference
    pub fn get_edge(&self, index: usize) -> std::result::Result<EdgeRef<'_>, ValidationError> {
        if !self.is_valid() {
            return Err(ValidationError::TruncatedFile {
                expected: self.metadata.file_size,
                actual: self.data.len() as u64,
            });
        }

        if index >= self.metadata.num_edges as usize {
            self.metrics.record_bounds_violation();
            return Err(ValidationError::OutOfBounds {
                offset: index * EDGE_SIZE + self.metadata.data_offset as usize,
                length: EDGE_SIZE,
                region_size: self.data.len(),
            });
        }

        let offset = self.metadata.data_offset as usize + index * EDGE_SIZE;
        EdgeRef::new_checked(&self.data, offset)
    }

    /// Get a slice of the data with bounds checking
    pub fn slice(&self, range: Range<usize>) -> std::result::Result<&[u8], ValidationError> {
        if !self.is_valid() {
            return Err(ValidationError::TruncatedFile {
                expected: self.metadata.file_size,
                actual: self.data.len() as u64,
            });
        }

        if range.end > self.data.len() {
            self.metrics.record_bounds_violation();
            return Err(ValidationError::OutOfBounds {
                offset: range.start,
                length: range.end - range.start,
                region_size: self.data.len(),
            });
        }

        Ok(&self.data[range])
    }

    /// Iterate over all edges with validation
    pub fn iter_edges(&self) -> ValidatedEdgeIterator<'_> {
        ValidatedEdgeIterator {
            mmap: self,
            current_index: 0,
        }
    }

    /// Get number of edges
    pub fn num_edges(&self) -> usize {
        self.metadata.num_edges as usize
    }

    /// Mark mmap as invalid (e.g., after detecting truncation)
    pub fn invalidate(&self) {
        self.is_valid.store(false, Ordering::Release);
    }

    /// Verify integrity of all edges
    pub fn verify_all(&self) -> std::result::Result<usize, ValidationError> {
        let mut valid_count = 0;
        for i in 0..self.metadata.num_edges as usize {
            let edge = self.get_edge(i)?;
            if edge.verify_crc() {
                valid_count += 1;
            }
        }
        Ok(valid_count)
    }
}

/// Iterator over validated edges
pub struct ValidatedEdgeIterator<'a> {
    mmap: &'a ValidatedMmap,
    current_index: usize,
}

impl<'a> Iterator for ValidatedEdgeIterator<'a> {
    type Item = std::result::Result<EdgeRef<'a>, ValidationError>;

    fn next(&mut self) -> Option<Self::Item> {
        if self.current_index >= self.mmap.num_edges() {
            return None;
        }

        let result = self.mmap.get_edge(self.current_index);
        self.current_index += 1;
        Some(result)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.mmap.num_edges() - self.current_index;
        (remaining, Some(remaining))
    }
}

impl<'a> ExactSizeIterator for ValidatedEdgeIterator<'a> {}

// ============================================================================
// Offset Validation Helpers
// ============================================================================

/// Validates that an offset and length are within bounds
#[inline]
pub fn validate_offset_length(
    offset: u64,
    length: u64,
    max: u64,
) -> std::result::Result<(), ValidationError> {
    if offset > max {
        return Err(ValidationError::InvalidOffset { offset, max });
    }
    if offset + length > max {
        return Err(ValidationError::InvalidLength {
            offset,
            length,
            max,
        });
    }
    Ok(())
}

/// Validates alignment of an offset
#[inline]
pub fn validate_alignment(
    offset: u64,
    alignment: usize,
) -> std::result::Result<(), ValidationError> {
    if !(offset as usize).is_multiple_of(alignment) {
        return Err(ValidationError::AlignmentViolation {
            offset,
            required_alignment: alignment,
        });
    }
    Ok(())
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Write;
    use tempfile::NamedTempFile;

    fn create_valid_test_file() -> NamedTempFile {
        let mut file = NamedTempFile::new().unwrap();

        // Write header
        let mut header = [0u8; HEADER_SIZE];
        LittleEndian::write_u64(&mut header[0..8], SOCHDB_MAGIC);
        LittleEndian::write_u32(&mut header[8..12], 1); // version
        LittleEndian::write_u64(&mut header[16..24], 2); // num_edges
        file.write_all(&header).unwrap();

        // Write 2 valid edges
        for i in 0..2u64 {
            let mut edge = [0u8; EDGE_SIZE];
            LittleEndian::write_u32(&mut edge[0..4], EDGE_MAGIC);
            LittleEndian::write_u64(&mut edge[4..12], i); // source
            LittleEndian::write_u64(&mut edge[12..20], i + 1); // target

            // Compute and write CRC
            let crc = crc32fast::hash(&edge[..EDGE_SIZE - 4]);
            LittleEndian::write_u32(&mut edge[EDGE_SIZE - 4..], crc);

            file.write_all(&edge).unwrap();
        }

        // Write footer
        let footer = [0u8; FOOTER_SIZE];
        file.write_all(&footer).unwrap();

        file.flush().unwrap();
        file
    }

    #[test]
    fn test_file_too_small() {
        let mut file = NamedTempFile::new().unwrap();
        file.write_all(&[0u8; 100]).unwrap();
        file.flush().unwrap();

        let validator = FileValidator::new(ValidationConfig::default());
        let result = validator.validate_before_mmap(file.path());

        assert!(matches!(result, Err(ValidationError::FileTooSmall { .. })));
    }

    #[test]
    fn test_bad_magic() {
        let mut file = NamedTempFile::new().unwrap();

        // Write header with wrong magic
        let mut header = [0u8; HEADER_SIZE];
        LittleEndian::write_u64(&mut header[0..8], 0xDEADBEEF);
        file.write_all(&header).unwrap();

        // Pad to minimum size
        file.write_all(&vec![0u8; (MIN_FILE_SIZE - HEADER_SIZE as u64) as usize])
            .unwrap();
        file.flush().unwrap();

        let validator = FileValidator::new(ValidationConfig::fast());
        let result = validator.validate_before_mmap(file.path());

        assert!(matches!(result, Err(ValidationError::BadMagic { .. })));
    }

    #[test]
    fn test_valid_file() {
        let file = create_valid_test_file();

        let validator = FileValidator::new(ValidationConfig::fast());
        let result = validator.validate_before_mmap(file.path());

        assert!(result.is_ok());
        let metadata = result.unwrap();
        assert_eq!(metadata.version, 1);
        assert_eq!(metadata.num_edges, 2);
    }

    #[test]
    fn test_edge_ref_bounds_check() {
        let file = create_valid_test_file();
        let config = ValidationConfig::fast();
        let mmap = ValidatedMmap::open(file.path(), config).unwrap();

        // Valid access
        let edge0 = mmap.get_edge(0);
        assert!(edge0.is_ok());

        // Out of bounds
        let edge_invalid = mmap.get_edge(100);
        assert!(matches!(
            edge_invalid,
            Err(ValidationError::OutOfBounds { .. })
        ));
    }

    #[test]
    fn test_edge_ref_crc_verification() {
        let file = create_valid_test_file();
        let config = ValidationConfig::fast();
        let mmap = ValidatedMmap::open(file.path(), config).unwrap();

        let edge = mmap.get_edge(0).unwrap();
        assert!(edge.verify_crc());
    }

    #[test]
    fn test_validated_iterator() {
        let file = create_valid_test_file();
        let config = ValidationConfig::fast();
        let mmap = ValidatedMmap::open(file.path(), config).unwrap();

        let edges: Vec<_> = mmap.iter_edges().collect();
        assert_eq!(edges.len(), 2);
        assert!(edges.iter().all(|e| e.is_ok()));
    }

    #[test]
    fn test_optimal_sample_count() {
        // K = ceiling(ln(1/δ) / ε)
        // For δ = 0.01, ε = 0.01: K = ceiling(ln(100) / 0.01) ≈ 461
        let k = ValidationConfig::optimal_sample_count(0.01, 0.01);
        assert!((460..=470).contains(&k));
    }
}