oxirs_vec/

faiss_native_integration.rs

//! Native FAISS Integration — UNAVAILABLE under the Pure Rust policy
//!
//! This module's types describe what a native FAISS integration (via FFI
//! bindings to Facebook's C++ FAISS library) *would* look like, but no such
//! integration is actually wired up: the COOLJAPAN Pure Rust Policy forbids
//! adding new C/C++ FFI dependencies to this crate's default build, and no
//! `oxirs-vec-adapter-faiss` quarantine crate exists (unlike, e.g.,
//! `oxirs-vec-adapter-cuda` for CUDA).
//!
//! [`NativeFaissIndex::new`] therefore always returns an explicit error
//! instead of fabricating a working index behind fake numeric handles. Use
//! this crate's Pure Rust indexes instead (`HnswIndex`, `IvfIndex`,
//! `PQIndex`, ...), or the byte-compatible (import/export only, no live FFI)
//! [`crate::faiss_compatibility`] module.
//!
//! The struct/field definitions below are kept only so that a *future* real
//! `oxirs-vec-adapter-faiss` crate has a documented shape to implement
//! against; none of the "simulated" logic they describe (GPU context,
//! memory pool, benchmark numbers) executes in production.

use crate::{
    faiss_compatibility::FaissIndexMetadata,
    faiss_integration::{FaissConfig, FaissSearchParams, FaissStatistics},
    index::VectorIndex,
};
use anyhow::{Error as AnyhowError, Result};
use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex, RwLock};
use tracing::{debug, info, span, Level};

/// Native FAISS integration configuration
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NativeFaissConfig {
    /// FAISS library path
    pub faiss_lib_path: Option<PathBuf>,
    /// Enable native FAISS GPU support
    pub enable_gpu: bool,
    /// GPU device IDs for FAISS
    pub gpu_devices: Vec<i32>,
    /// Memory mapping threshold (bytes)
    pub mmap_threshold: usize,
    /// Enable FAISS optimization
    pub enable_optimization: bool,
    /// FAISS thread count (0 = auto)
    pub thread_count: usize,
    /// Enable FAISS logging
    pub enable_logging: bool,
    /// Native performance tuning
    pub performance_tuning: NativePerformanceTuning,
}

impl Default for NativeFaissConfig {
    fn default() -> Self {
        Self {
            faiss_lib_path: None,
            enable_gpu: false,
            gpu_devices: vec![0],
            mmap_threshold: 1024 * 1024 * 1024, // 1GB
            enable_optimization: true,
            thread_count: 0, // Auto-detect
            enable_logging: false,
            performance_tuning: NativePerformanceTuning::default(),
        }
    }
}

/// Native performance tuning configuration
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NativePerformanceTuning {
    /// Enable SIMD optimizations
    pub enable_simd: bool,
    /// Memory prefetch distance
    pub prefetch_distance: usize,
    /// Cache line size for optimization
    pub cache_line_size: usize,
    /// Batch size for operations
    pub batch_size: usize,
    /// Enable memory pooling
    pub enable_memory_pooling: bool,
    /// Pool size in MB
    pub memory_pool_size_mb: usize,
}

impl Default for NativePerformanceTuning {
    fn default() -> Self {
        Self {
            enable_simd: true,
            prefetch_distance: 64,
            cache_line_size: 64,
            batch_size: 1024,
            enable_memory_pooling: true,
            memory_pool_size_mb: 512,
        }
    }
}

/// Native FAISS index wrapper
pub struct NativeFaissIndex {
    /// Configuration
    config: NativeFaissConfig,
    /// FAISS index handle (simulated as usize for demo)
    index_handle: Arc<Mutex<Option<usize>>>,
    /// Index metadata
    metadata: Arc<RwLock<FaissIndexMetadata>>,
    /// Performance statistics
    stats: Arc<RwLock<NativeFaissStatistics>>,
    /// GPU context (if enabled)
    gpu_context: Arc<Mutex<Option<GpuContext>>>,
    /// Memory pool for optimization
    memory_pool: Arc<Mutex<MemoryPool>>,
}

/// Native FAISS statistics with detailed metrics
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct NativeFaissStatistics {
    /// Basic statistics
    pub basic_stats: FaissStatistics,
    /// Native FAISS specific metrics
    pub native_metrics: NativeMetrics,
    /// GPU performance metrics (if applicable)
    pub gpu_metrics: Option<GpuMetrics>,
    /// Memory efficiency metrics
    pub memory_metrics: MemoryMetrics,
    /// Performance comparison data
    pub comparison_data: ComparisonData,
}

/// Native FAISS specific metrics
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct NativeMetrics {
    /// FAISS library version
    pub faiss_version: String,
    /// Native search latency in nanoseconds
    pub native_search_latency_ns: u64,
    /// Index build time in milliseconds
    pub index_build_time_ms: u64,
    /// Native memory usage in bytes
    pub native_memory_usage: usize,
    /// SIMD utilization percentage
    pub simd_utilization: f32,
    /// Cache hit rate for operations
    pub cache_hit_rate: f32,
    /// Threading efficiency
    pub threading_efficiency: f32,
}

/// GPU performance metrics
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct GpuMetrics {
    /// GPU memory usage in bytes
    pub gpu_memory_usage: usize,
    /// GPU utilization percentage
    pub gpu_utilization: f32,
    /// GPU search speedup over CPU
    pub gpu_speedup: f32,
    /// GPU memory transfer time in microseconds
    pub memory_transfer_time_us: u64,
    /// GPU kernel execution time in microseconds
    pub kernel_execution_time_us: u64,
    /// Number of GPU devices used
    pub devices_used: usize,
}

/// Memory efficiency metrics
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct MemoryMetrics {
    /// Peak memory usage in bytes
    pub peak_memory_usage: usize,
    /// Memory fragmentation percentage
    pub fragmentation_percentage: f32,
    /// Memory pool efficiency
    pub pool_efficiency: f32,
    /// Page fault count
    pub page_faults: u64,
    /// Memory bandwidth utilization
    pub bandwidth_utilization: f32,
}

/// Performance comparison data
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ComparisonData {
    /// Oxirs-vec vs FAISS latency ratio
    pub latency_ratio: f32,
    /// Oxirs-vec vs FAISS memory ratio
    pub memory_ratio: f32,
    /// Oxirs-vec vs FAISS accuracy difference
    pub accuracy_difference: f32,
    /// Oxirs-vec vs FAISS throughput ratio
    pub throughput_ratio: f32,
    /// Detailed benchmark results
    pub benchmark_results: Vec<BenchmarkResult>,
}

/// Individual benchmark result
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BenchmarkResult {
    /// Benchmark name
    pub name: String,
    /// Dataset characteristics
    pub dataset: DatasetCharacteristics,
    /// Oxirs-vec performance
    pub oxirs_performance: PerformanceMetrics,
    /// FAISS performance
    pub faiss_performance: PerformanceMetrics,
    /// Winner (true = oxirs-vec, false = faiss)
    pub oxirs_wins: bool,
    /// Performance difference percentage
    pub performance_difference: f32,
}

/// Dataset characteristics for benchmarking
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DatasetCharacteristics {
    /// Number of vectors
    pub num_vectors: usize,
    /// Vector dimension
    pub dimension: usize,
    /// Data distribution type
    pub distribution: String,
    /// Intrinsic dimensionality
    pub intrinsic_dimension: f32,
    /// Clustering coefficient
    pub clustering_coefficient: f32,
}

/// Performance metrics for comparison
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PerformanceMetrics {
    /// Search latency in microseconds
    pub search_latency_us: f64,
    /// Index build time in seconds
    pub build_time_s: f64,
    /// Memory usage in MB
    pub memory_usage_mb: f64,
    /// Recall@10
    pub recall_at_10: f32,
    /// Queries per second
    pub qps: f64,
}

/// GPU context for FAISS GPU operations
#[derive(Debug)]
pub struct GpuContext {
    /// GPU device IDs
    pub device_ids: Vec<i32>,
    /// GPU memory allocated in bytes
    pub allocated_memory: usize,
    /// CUDA context handle (simulated)
    pub cuda_context: usize,
    /// GPU resource handles
    pub resources: Vec<GpuResource>,
}

/// GPU resource handle
#[derive(Debug)]
pub struct GpuResource {
    /// Resource ID
    pub id: usize,
    /// Resource type
    pub resource_type: String,
    /// Memory size in bytes
    pub memory_size: usize,
    /// Device ID
    pub device_id: i32,
}

/// Memory pool for efficient memory management
#[derive(Debug)]
pub struct MemoryPool {
    /// Pool blocks
    pub blocks: Vec<MemoryBlock>,
    /// Total size in bytes
    pub total_size: usize,
    /// Used size in bytes
    pub used_size: usize,
    /// Free blocks
    pub free_blocks: Vec<usize>,
    /// Allocation statistics
    pub allocation_stats: AllocationStats,
}

/// Memory block in the pool
#[derive(Debug)]
pub struct MemoryBlock {
    /// Block address (simulated)
    pub address: usize,
    /// Block size in bytes
    pub size: usize,
    /// Is block free
    pub is_free: bool,
    /// Allocation timestamp
    pub allocated_at: std::time::Instant,
}

/// Memory allocation statistics
#[derive(Debug, Default)]
pub struct AllocationStats {
    /// Total allocations
    pub total_allocations: usize,
    /// Total deallocations
    pub total_deallocations: usize,
    /// Peak memory usage
    pub peak_usage: usize,
    /// Average allocation size
    pub avg_allocation_size: usize,
    /// Fragmentation events
    pub fragmentation_events: usize,
}

impl NativeFaissIndex {
    /// Attempt to create a native FAISS index.
    ///
    /// This always fails: FAISS interop requires native FFI bindings that
    /// are unavailable under the COOLJAPAN Pure Rust Policy (no
    /// `oxirs-vec-adapter-faiss` quarantine crate exists to provide them).
    /// Use this crate's Pure Rust indexes (`HnswIndex`, `IvfIndex`,
    /// `PQIndex`, ...) instead. See the module-level docs for details.
    pub fn new(_config: NativeFaissConfig, _faiss_config: FaissConfig) -> Result<Self> {
        Err(AnyhowError::msg(
            "Native FAISS integration requires the (unavailable) native FAISS FFI adapter: \
             the COOLJAPAN Pure Rust Policy forbids new C/C++ FFI dependencies in oxirs-vec's \
             default build, and no `oxirs-vec-adapter-faiss` quarantine crate exists. Use the \
             crate's Pure Rust indexes (HnswIndex, IvfIndex, PQIndex, ...) instead.",
        ))
    }

    /// Add vectors to the native FAISS index with optimization
    pub fn add_vectors_optimized(&self, vectors: &[Vec<f32>], ids: &[String]) -> Result<()> {
        let span = span!(Level::DEBUG, "add_vectors_optimized");
        let _enter = span.enter();

        if vectors.len() != ids.len() {
            return Err(AnyhowError::msg("Vector and ID count mismatch"));
        }

        let start_time = std::time::Instant::now();

        // Process in batches for memory efficiency
        let batch_size = self.config.performance_tuning.batch_size;
        for chunk in vectors.chunks(batch_size).zip(ids.chunks(batch_size)) {
            let (vector_chunk, id_chunk) = chunk;
            self.add_vector_batch(vector_chunk, id_chunk)?;
        }

        // Update statistics
        {
            let mut stats = self
                .stats
                .write()
                .map_err(|_| AnyhowError::msg("Failed to acquire stats lock"))?;
            stats.native_metrics.index_build_time_ms += start_time.elapsed().as_millis() as u64;
            stats.basic_stats.total_vectors += vectors.len();
        }

        debug!(
            "Added {} vectors in batches of {}",
            vectors.len(),
            batch_size
        );
        Ok(())
    }

    /// Add a batch of vectors with memory pool optimization
    fn add_vector_batch(&self, vectors: &[Vec<f32>], _ids: &[String]) -> Result<()> {
        // Allocate from memory pool
        let memory_needed = vectors.len() * vectors[0].len() * std::mem::size_of::<f32>();
        let _memory_block = self.allocate_from_pool(memory_needed)?;

        // In a real implementation, this would:
        // 1. Convert vectors to FAISS format
        // 2. Call faiss_index_add() with optimized memory layout
        // 3. Update index statistics
        // 4. Handle GPU transfer if needed

        debug!("Added batch of {} vectors", vectors.len());
        Ok(())
    }

    /// Perform optimized search with native FAISS
    pub fn search_optimized(
        &self,
        query_vectors: &[Vec<f32>],
        k: usize,
        params: &FaissSearchParams,
    ) -> Result<Vec<Vec<(String, f32)>>> {
        let span = span!(Level::DEBUG, "search_optimized");
        let _enter = span.enter();

        let start_time = std::time::Instant::now();

        // Use GPU acceleration if available
        let results = if self.config.enable_gpu {
            self.search_gpu_accelerated(query_vectors, k, params)?
        } else {
            self.search_cpu_optimized(query_vectors, k, params)?
        };

        // Update performance statistics
        {
            let mut stats = self
                .stats
                .write()
                .map_err(|_| AnyhowError::msg("Failed to acquire stats lock"))?;
            let search_time_ns = start_time.elapsed().as_nanos() as u64;
            stats.native_metrics.native_search_latency_ns = search_time_ns;
            stats.basic_stats.total_searches += query_vectors.len();

            // Update average search time
            let search_time_us = search_time_ns as f64 / 1000.0;
            let total_searches = stats.basic_stats.total_searches as f64;
            stats.basic_stats.avg_search_time_us = (stats.basic_stats.avg_search_time_us
                * (total_searches - query_vectors.len() as f64)
                + search_time_us)
                / total_searches;
        }

        debug!(
            "Performed optimized search for {} queries in {:?}",
            query_vectors.len(),
            start_time.elapsed()
        );
        Ok(results)
    }

    /// GPU-accelerated search
    fn search_gpu_accelerated(
        &self,
        query_vectors: &[Vec<f32>],
        k: usize,
        _params: &FaissSearchParams,
    ) -> Result<Vec<Vec<(String, f32)>>> {
        let span = span!(Level::DEBUG, "search_gpu_accelerated");
        let _enter = span.enter();

        // In a real implementation, this would:
        // 1. Transfer query vectors to GPU memory
        // 2. Execute FAISS GPU search kernels
        // 3. Transfer results back to CPU
        // 4. Update GPU performance metrics

        let mut results = Vec::new();
        for _query in query_vectors {
            let mut query_results = Vec::new();
            for i in 0..k {
                query_results.push((format!("gpu_result_{i}"), 0.9 - (i as f32 * 0.1)));
            }
            results.push(query_results);
        }

        // Update GPU metrics
        {
            let mut stats = self
                .stats
                .write()
                .map_err(|_| AnyhowError::msg("Failed to acquire stats lock"))?;
            if let Some(ref mut gpu_metrics) = stats.gpu_metrics {
                gpu_metrics.gpu_utilization = 85.0;
                gpu_metrics.gpu_speedup = 3.2;
                gpu_metrics.kernel_execution_time_us = 250;
            }
        }

        debug!("GPU search completed for {} queries", query_vectors.len());
        Ok(results)
    }

    /// CPU-optimized search
    fn search_cpu_optimized(
        &self,
        query_vectors: &[Vec<f32>],
        k: usize,
        _params: &FaissSearchParams,
    ) -> Result<Vec<Vec<(String, f32)>>> {
        // In a real implementation, this would use FAISS CPU optimizations
        let mut results = Vec::new();
        for _query in query_vectors {
            let mut query_results = Vec::new();
            for i in 0..k {
                query_results.push((format!("cpu_result_{i}"), 0.95 - (i as f32 * 0.1)));
            }
            results.push(query_results);
        }

        debug!("CPU search completed for {} queries", query_vectors.len());
        Ok(results)
    }

    /// Allocate memory from pool
    fn allocate_from_pool(&self, size: usize) -> Result<usize> {
        let mut pool = self
            .memory_pool
            .lock()
            .map_err(|_| AnyhowError::msg("Failed to acquire memory pool lock"))?;

        pool.allocate(size)
    }

    /// Get comprehensive statistics
    pub fn get_native_statistics(&self) -> Result<NativeFaissStatistics> {
        let stats = self
            .stats
            .read()
            .map_err(|_| AnyhowError::msg("Failed to acquire stats lock"))?;
        Ok(stats.clone())
    }

    /// Optimize index for better performance
    pub fn optimize_index(&self) -> Result<()> {
        let span = span!(Level::INFO, "optimize_index");
        let _enter = span.enter();

        // In a real implementation, this would:
        // 1. Rebuild index with optimal parameters
        // 2. Reorganize memory layout
        // 3. Update quantization parameters
        // 4. Optimize GPU memory usage

        {
            let mut stats = self
                .stats
                .write()
                .map_err(|_| AnyhowError::msg("Failed to acquire stats lock"))?;
            stats.native_metrics.cache_hit_rate = 92.5;
            stats.native_metrics.simd_utilization = 88.0;
            stats.native_metrics.threading_efficiency = 85.0;
        }

        info!("Index optimization completed");
        Ok(())
    }

    /// Export index to native FAISS format
    pub fn export_to_native_faiss(&self, output_path: &Path) -> Result<()> {
        let span = span!(Level::INFO, "export_to_native_faiss");
        let _enter = span.enter();

        // Create output directory
        if let Some(parent) = output_path.parent() {
            std::fs::create_dir_all(parent)?;
        }

        // In a real implementation, this would:
        // 1. Use faiss_write_index() to save native format
        // 2. Include all optimization parameters
        // 3. Preserve GPU-specific data if applicable

        info!("Exported native FAISS index to: {:?}", output_path);
        Ok(())
    }

    /// Import index from native FAISS format
    pub fn import_from_native_faiss(&mut self, input_path: &Path) -> Result<()> {
        let span = span!(Level::INFO, "import_from_native_faiss");
        let _enter = span.enter();

        if !input_path.exists() {
            return Err(AnyhowError::msg(format!(
                "Input file does not exist: {input_path:?}"
            )));
        }

        // In a real implementation, this would:
        // 1. Use faiss_read_index() to load native format
        // 2. Restore optimization parameters
        // 3. Initialize GPU context if needed

        info!("Imported native FAISS index from: {:?}", input_path);
        Ok(())
    }
}

/// Memory pool implementation
impl MemoryPool {
    /// Create a new memory pool
    pub fn new(size: usize) -> Self {
        Self {
            blocks: Vec::new(),
            total_size: size,
            used_size: 0,
            free_blocks: Vec::new(),
            allocation_stats: AllocationStats::default(),
        }
    }

    /// Allocate memory from pool
    pub fn allocate(&mut self, size: usize) -> Result<usize> {
        if self.used_size + size > self.total_size {
            return Err(AnyhowError::msg("Memory pool exhausted"));
        }

        // Find suitable free block or create new one
        let block_id = if let Some(free_id) = self.find_free_block(size) {
            free_id
        } else {
            self.create_new_block(size)?
        };

        self.used_size += size;
        self.allocation_stats.total_allocations += 1;
        self.allocation_stats.avg_allocation_size = (self.allocation_stats.avg_allocation_size
            * (self.allocation_stats.total_allocations - 1)
            + size)
            / self.allocation_stats.total_allocations;

        if self.used_size > self.allocation_stats.peak_usage {
            self.allocation_stats.peak_usage = self.used_size;
        }

        Ok(block_id)
    }

    /// Find suitable free block
    fn find_free_block(&mut self, size: usize) -> Option<usize> {
        for &block_id in &self.free_blocks {
            if block_id < self.blocks.len()
                && self.blocks[block_id].size >= size
                && self.blocks[block_id].is_free
            {
                self.blocks[block_id].is_free = false;
                self.blocks[block_id].allocated_at = std::time::Instant::now();
                self.free_blocks.retain(|&id| id != block_id);
                return Some(block_id);
            }
        }
        None
    }

    /// Create new memory block
    fn create_new_block(&mut self, size: usize) -> Result<usize> {
        let block = MemoryBlock {
            address: self.blocks.len() * 1024, // Simulated address
            size,
            is_free: false,
            allocated_at: std::time::Instant::now(),
        };

        self.blocks.push(block);
        Ok(self.blocks.len() - 1)
    }

    /// Deallocate memory
    pub fn deallocate(&mut self, block_id: usize) -> Result<()> {
        if block_id >= self.blocks.len() {
            return Err(AnyhowError::msg("Invalid block ID"));
        }

        let block = &mut self.blocks[block_id];
        if block.is_free {
            return Err(AnyhowError::msg("Block already free"));
        }

        block.is_free = true;
        self.used_size -= block.size;
        self.free_blocks.push(block_id);
        self.allocation_stats.total_deallocations += 1;

        Ok(())
    }

    /// Get memory usage statistics
    pub fn get_usage_stats(&self) -> (usize, usize, f32) {
        let fragmentation = if self.total_size > 0 {
            (self.free_blocks.len() as f32 / self.blocks.len() as f32) * 100.0
        } else {
            0.0
        };

        (self.used_size, self.total_size, fragmentation)
    }
}

/// Performance comparison framework
pub struct FaissPerformanceComparison {
    /// Native FAISS index
    faiss_index: NativeFaissIndex,
    /// Oxirs-vec index for comparison
    oxirs_index: Box<dyn VectorIndex>,
    /// Benchmark datasets
    benchmark_datasets: Vec<BenchmarkDataset>,
    /// Comparison results
    results: Vec<ComparisonResult>,
}

/// Benchmark dataset
#[derive(Debug, Clone)]
pub struct BenchmarkDataset {
    /// Dataset name
    pub name: String,
    /// Vectors for indexing
    pub vectors: Vec<Vec<f32>>,
    /// Query vectors
    pub queries: Vec<Vec<f32>>,
    /// Ground truth results
    pub ground_truth: Vec<Vec<(usize, f32)>>,
    /// Dataset characteristics
    pub characteristics: DatasetCharacteristics,
}

/// Comparison result
#[derive(Debug, Clone, serde::Serialize)]
pub struct ComparisonResult {
    /// Dataset name
    pub dataset_name: String,
    /// FAISS performance
    pub faiss_performance: PerformanceMetrics,
    /// Oxirs performance
    pub oxirs_performance: PerformanceMetrics,
    /// Performance ratios
    pub ratios: PerformanceRatios,
    /// Statistical significance
    pub statistical_significance: StatisticalSignificance,
}

/// Performance ratios
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PerformanceRatios {
    /// Speed ratio (oxirs/faiss)
    pub speed_ratio: f64,
    /// Memory ratio (oxirs/faiss)
    pub memory_ratio: f64,
    /// Accuracy ratio (oxirs/faiss)
    pub accuracy_ratio: f64,
}

/// Statistical significance test results
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StatisticalSignificance {
    /// P-value for speed difference
    pub speed_p_value: f64,
    /// P-value for accuracy difference
    pub accuracy_p_value: f64,
    /// Confidence interval for speed (95%)
    pub speed_confidence_interval: (f64, f64),
    /// Effect size (Cohen's d)
    pub effect_size: f64,
}

impl FaissPerformanceComparison {
    /// Create new performance comparison framework
    pub fn new(faiss_index: NativeFaissIndex, oxirs_index: Box<dyn VectorIndex>) -> Self {
        Self {
            faiss_index,
            oxirs_index,
            benchmark_datasets: Vec::new(),
            results: Vec::new(),
        }
    }

    /// Add benchmark dataset
    pub fn add_benchmark_dataset(&mut self, dataset: BenchmarkDataset) {
        self.benchmark_datasets.push(dataset);
    }

    /// Run comprehensive performance comparison
    pub fn run_comprehensive_benchmark(&mut self) -> Result<Vec<ComparisonResult>> {
        let span = span!(Level::INFO, "run_comprehensive_benchmark");
        let _enter = span.enter();

        self.results.clear();

        let datasets = self.benchmark_datasets.clone();
        for dataset in &datasets {
            info!("Running benchmark on dataset: {}", dataset.name);
            let result = self.benchmark_single_dataset(dataset)?;
            self.results.push(result);
        }

        info!(
            "Completed comprehensive benchmark on {} datasets",
            self.benchmark_datasets.len()
        );
        Ok(self.results.clone())
    }

    /// Benchmark single dataset
    fn benchmark_single_dataset(&mut self, dataset: &BenchmarkDataset) -> Result<ComparisonResult> {
        // Benchmark FAISS performance
        let faiss_perf = self.benchmark_faiss_performance(dataset)?;

        // Benchmark Oxirs performance
        let oxirs_perf = self.benchmark_oxirs_performance(dataset)?;

        // Calculate ratios
        let ratios = PerformanceRatios {
            speed_ratio: oxirs_perf.search_latency_us / faiss_perf.search_latency_us,
            memory_ratio: oxirs_perf.memory_usage_mb / faiss_perf.memory_usage_mb,
            accuracy_ratio: (oxirs_perf.recall_at_10 as f64) / (faiss_perf.recall_at_10 as f64),
        };

        // Perform statistical significance testing
        let significance = self.test_statistical_significance(&faiss_perf, &oxirs_perf)?;

        Ok(ComparisonResult {
            dataset_name: dataset.name.clone(),
            faiss_performance: faiss_perf,
            oxirs_performance: oxirs_perf,
            ratios,
            statistical_significance: significance,
        })
    }

    /// Benchmark FAISS performance
    fn benchmark_faiss_performance(
        &self,
        _dataset: &BenchmarkDataset,
    ) -> Result<PerformanceMetrics> {
        let _start_time = std::time::Instant::now();

        // Simulate FAISS performance measurement
        let search_latency_us = 250.0; // Simulated
        let build_time_s = 5.0; // Simulated
        let memory_usage_mb = 512.0; // Simulated
        let recall_at_10 = 0.95; // Simulated
        let qps = 1000.0 / search_latency_us * 1_000_000.0; // Convert to QPS

        Ok(PerformanceMetrics {
            search_latency_us,
            build_time_s,
            memory_usage_mb,
            recall_at_10,
            qps,
        })
    }

    /// Benchmark Oxirs performance
    fn benchmark_oxirs_performance(
        &self,
        _dataset: &BenchmarkDataset,
    ) -> Result<PerformanceMetrics> {
        let _start_time = std::time::Instant::now();

        // Simulate Oxirs performance measurement
        let search_latency_us = 300.0; // Simulated (slightly slower)
        let build_time_s = 4.5; // Simulated (slightly faster build)
        let memory_usage_mb = 480.0; // Simulated (more memory efficient)
        let recall_at_10 = 0.93; // Simulated (slightly lower recall)
        let qps = 1000.0 / search_latency_us * 1_000_000.0;

        Ok(PerformanceMetrics {
            search_latency_us,
            build_time_s,
            memory_usage_mb,
            recall_at_10,
            qps,
        })
    }

    /// Test statistical significance
    fn test_statistical_significance(
        &self,
        faiss_perf: &PerformanceMetrics,
        oxirs_perf: &PerformanceMetrics,
    ) -> Result<StatisticalSignificance> {
        // Simplified statistical testing (in practice, would use proper statistical methods)
        let speed_diff = (oxirs_perf.search_latency_us - faiss_perf.search_latency_us).abs();
        let accuracy_diff = (oxirs_perf.recall_at_10 - faiss_perf.recall_at_10).abs();

        // Simulated statistical test results
        let speed_p_value = if speed_diff > 50.0 { 0.01 } else { 0.15 }; // Significant if diff > 50μs
        let accuracy_p_value = if accuracy_diff > 0.05 { 0.02 } else { 0.25 }; // Significant if diff > 5%

        let effect_size = speed_diff / 100.0; // Simplified Cohen's d calculation
        let speed_confidence_interval = (
            oxirs_perf.search_latency_us - 50.0,
            oxirs_perf.search_latency_us + 50.0,
        );

        Ok(StatisticalSignificance {
            speed_p_value,
            accuracy_p_value,
            speed_confidence_interval,
            effect_size,
        })
    }

    /// Generate comprehensive comparison report
    pub fn generate_comparison_report(&self) -> Result<String> {
        let mut report = String::new();

        report.push_str("# FAISS vs Oxirs-Vec Performance Comparison Report\n\n");
        report.push_str(&format!(
            "Generated: {}\n\n",
            chrono::Utc::now().to_rfc3339()
        ));

        // Summary statistics
        if !self.results.is_empty() {
            let avg_speed_ratio: f64 = self
                .results
                .iter()
                .map(|r| r.ratios.speed_ratio)
                .sum::<f64>()
                / self.results.len() as f64;
            let avg_memory_ratio: f64 = self
                .results
                .iter()
                .map(|r| r.ratios.memory_ratio)
                .sum::<f64>()
                / self.results.len() as f64;
            let avg_accuracy_ratio: f64 = self
                .results
                .iter()
                .map(|r| r.ratios.accuracy_ratio)
                .sum::<f64>()
                / self.results.len() as f64;

            report.push_str("## Summary\n\n");
            report.push_str(&format!(
                "- Average Speed Ratio (Oxirs/FAISS): {avg_speed_ratio:.2}\n"
            ));
            report.push_str(&format!(
                "- Average Memory Ratio (Oxirs/FAISS): {avg_memory_ratio:.2}\n"
            ));
            report.push_str(&format!(
                "- Average Accuracy Ratio (Oxirs/FAISS): {avg_accuracy_ratio:.2}\n\n"
            ));

            let oxirs_wins = self
                .results
                .iter()
                .filter(|r| r.ratios.speed_ratio < 1.0)
                .count();
            report.push_str(&format!(
                "- Oxirs wins in speed: {}/{} datasets\n",
                oxirs_wins,
                self.results.len()
            ));

            let memory_wins = self
                .results
                .iter()
                .filter(|r| r.ratios.memory_ratio < 1.0)
                .count();
            report.push_str(&format!(
                "- Oxirs wins in memory efficiency: {}/{} datasets\n\n",
                memory_wins,
                self.results.len()
            ));
        }

        // Detailed results
        report.push_str("## Detailed Results\n\n");
        for result in &self.results {
            report.push_str(&format!("### Dataset: {}\n\n", result.dataset_name));
            report.push_str("| Metric | FAISS | Oxirs | Ratio |\n");
            report.push_str("|--------|-------|-------|-------|\n");
            report.push_str(&format!(
                "| Search Latency (μs) | {:.1} | {:.1} | {:.2} |\n",
                result.faiss_performance.search_latency_us,
                result.oxirs_performance.search_latency_us,
                result.ratios.speed_ratio
            ));
            report.push_str(&format!(
                "| Memory Usage (MB) | {:.1} | {:.1} | {:.2} |\n",
                result.faiss_performance.memory_usage_mb,
                result.oxirs_performance.memory_usage_mb,
                result.ratios.memory_ratio
            ));
            report.push_str(&format!(
                "| Recall@10 | {:.3} | {:.3} | {:.2} |\n",
                result.faiss_performance.recall_at_10,
                result.oxirs_performance.recall_at_10,
                result.ratios.accuracy_ratio
            ));
            report.push_str(&format!(
                "| QPS | {:.1} | {:.1} | {:.2} |\n\n",
                result.faiss_performance.qps,
                result.oxirs_performance.qps,
                result.oxirs_performance.qps / result.faiss_performance.qps
            ));

            // Statistical significance
            report.push_str("**Statistical Significance:**\n");
            report.push_str(&format!(
                "- Speed difference p-value: {:.3}\n",
                result.statistical_significance.speed_p_value
            ));
            report.push_str(&format!(
                "- Accuracy difference p-value: {:.3}\n",
                result.statistical_significance.accuracy_p_value
            ));
            report.push_str(&format!(
                "- Effect size: {:.2}\n\n",
                result.statistical_significance.effect_size
            ));
        }

        Ok(report)
    }

    /// Export results to JSON
    pub fn export_results_json(&self) -> Result<String> {
        serde_json::to_string_pretty(&self.results)
            .map_err(|e| AnyhowError::new(e).context("Failed to serialize results to JSON"))
    }
}

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

    #[test]
    fn test_native_faiss_index_creation_fails_loudly() {
        // Regression test for the P1 finding: `NativeFaissIndex::new` used to
        // fabricate a "successful" index behind fake numeric handles
        // (cuda_context: 12345, index_handle: 98765). Native FAISS FFI is
        // unavailable under the Pure Rust Policy, so it must now fail with a
        // clear, honest error instead of pretending to succeed.
        let native_config = NativeFaissConfig::default();
        let faiss_config = FaissConfig::default();

        let result = NativeFaissIndex::new(native_config, faiss_config);
        let message = match result {
            Ok(_) => panic!("NativeFaissIndex::new must fail under the Pure Rust Policy"),
            Err(e) => e.to_string(),
        };
        assert!(
            message.contains("Pure Rust") || message.contains("unavailable"),
            "error message should honestly explain why native FAISS is unavailable, got: {message}"
        );
    }

    #[test]
    fn test_memory_pool_allocation() -> Result<()> {
        let mut pool = MemoryPool::new(1024);

        let block1 = pool.allocate(256)?;
        let block2 = pool.allocate(512)?;

        assert_ne!(block1, block2);
        assert_eq!(pool.used_size, 768);
        Ok(())
    }

    // NOTE: `FaissPerformanceComparison` requires a `NativeFaissIndex`, which
    // can no longer be constructed (see `test_native_faiss_index_creation_fails_loudly`
    // above) now that native FAISS FFI is honestly reported as unavailable
    // instead of simulated. There is therefore no way to exercise
    // `FaissPerformanceComparison` until a real `oxirs-vec-adapter-faiss`
    // crate exists to provide a genuine `NativeFaissIndex`.
}