sochdb_storage/

lscs.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/>.

//! Log-Structured Column Store (LSCS)
//!
//! A columnar variant of LSM trees optimized for TOON workloads.
//!
//! ## Key Innovations
//!
//! 1. **Column-oriented memtable**: Groups data by column for sequential writes
//! 2. **Column-aware compaction**: Only compacts changed columns (5× less write amplification)
//! 3. **Schema-aware compression**: Uses column type for optimal encoding
//!
//! ## Write Amplification Analysis
//!
//! Traditional LSM: WA = T × (T-1) / 2  where T = size ratio (typically 10)
//! LSCS: WA = T × (T-1) / 2 × (C_hot / C_total)
//!
//! If only 20% of columns change frequently: **5× less write amplification**
//!
//! ## Column-Aware Compaction Model
//!
//! Standard LSM Write Amplification:
//!    WA = (T/(T-1)) × Σᵢ₌₀ᵏ (1/Tⁱ) ≈ (T/(T-1)) × log_T(N/M)
//!
//! Column-Aware WA:
//!    Let C = {c₁, c₂, ..., c_K} be columns
//!    Hot columns: H = {cⱼ | temp(cⱼ) > θ} where θ = 0.1
//!    WA_col = (|H|/|C|) × WA = f × WA
//!
//!    Example: If 2 out of 10 columns hot: f = 0.2, 5x reduction
//!
//! ## Architecture
//!
//! ```text
//! ┌────────────────┐
//! │ MemTable       │
//! │ [col1][col2]...│ ← Columns in memory
//! └───────┬────────┘
//!         │ flush
//!         ▼
//! ┌────────────────────────────┐
//! │ Column Group L0            │
//! │ ┌─────┐┌─────┐┌─────┐     │
//! │ │col1 ││col2 ││col3 │     │
//! │ └─────┘└─────┘└─────┘     │
//! └────────────────────────────┘
//! ```

use parking_lot::RwLock;
use serde::{Deserialize, Serialize};
use sochdb_core::{Result, SochDBError};
use std::collections::{BTreeMap, HashMap, HashSet};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};

use crate::txn_wal::TxnWal;

// ============================================================================
// Column Temperature Tracking (Task 3)
// ============================================================================

/// Temperature tracking for a single column using Exponential Moving Average.
///
/// Temperature is computed as: temp_new = α × temp_current + (1-α) × temp_old
/// where α = 0.1 (decay factor) and temp_current = updates_in_window / total_updates
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ColumnTemperature {
    /// Column name
    pub name: String,
    /// Current temperature (0.0 = cold, 1.0 = hot)
    pub temperature: f64,
    /// Updates in current window
    pub window_updates: u64,
    /// Total updates since last decay
    pub total_updates: u64,
    /// Last update timestamp (micros)
    pub last_update_us: u64,
}

impl ColumnTemperature {
    /// Create a new temperature tracker for a column
    pub fn new(name: String) -> Self {
        Self {
            name,
            temperature: 0.0,
            window_updates: 0,
            total_updates: 0,
            last_update_us: 0,
        }
    }

    /// Record an update to this column
    pub fn record_update(&mut self) {
        self.window_updates += 1;
        self.total_updates += 1;
        self.last_update_us = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_micros() as u64;
    }

    /// Update temperature using EMA when window completes
    ///
    /// α = 0.1 (decay factor)
    /// temp_new = α × temp_current + (1-α) × temp_old
    pub fn update_ema(&mut self, total_window_updates: u64) {
        const ALPHA: f64 = 0.1;

        let temp_current = if total_window_updates > 0 {
            self.window_updates as f64 / total_window_updates as f64
        } else {
            0.0
        };

        self.temperature = ALPHA * temp_current + (1.0 - ALPHA) * self.temperature;
        self.window_updates = 0;
    }

    /// Check if column is "hot" (above threshold)
    pub fn is_hot(&self, threshold: f64) -> bool {
        self.temperature > threshold
    }
}

/// Column temperature tracker for all columns in a table
#[derive(Debug)]
pub struct ColumnTemperatureTracker {
    /// Per-column temperature (column name -> temperature)
    columns: RwLock<HashMap<String, ColumnTemperature>>,
    /// Window size for temperature updates
    window_size: u64,
    /// Current window update count
    window_updates: AtomicU64,
    /// Hot threshold — stored as AtomicU64 bit pattern for lock-free updates
    hot_threshold: AtomicU64,
}

impl ColumnTemperatureTracker {
    /// Create a new temperature tracker
    pub fn new(column_names: &[String], window_size: u64) -> Self {
        let mut columns = HashMap::new();
        for name in column_names {
            columns.insert(name.clone(), ColumnTemperature::new(name.clone()));
        }
        Self {
            columns: RwLock::new(columns),
            window_size,
            window_updates: AtomicU64::new(0),
            hot_threshold: AtomicU64::new(0.1_f64.to_bits()),
        }
    }

    /// Read the current hot threshold (lock-free)
    fn threshold(&self) -> f64 {
        f64::from_bits(self.hot_threshold.load(Ordering::Relaxed))
    }

    /// Record an update to specific columns
    pub fn record_updates(&self, column_names: &[&str]) {
        let mut cols = self.columns.write();
        for name in column_names {
            if let Some(temp) = cols.get_mut(*name) {
                temp.record_update();
            }
        }

        let total = self.window_updates.fetch_add(1, Ordering::SeqCst) + 1;

        // Check if window is complete
        if total >= self.window_size {
            self.update_all_ema(&mut cols, total);
            self.window_updates.store(0, Ordering::SeqCst);
        }
    }

    fn update_all_ema(&self, cols: &mut HashMap<String, ColumnTemperature>, total: u64) {
        for temp in cols.values_mut() {
            temp.update_ema(total);
        }
    }

    /// Get hot columns (above threshold)
    pub fn get_hot_columns(&self) -> HashSet<String> {
        let threshold = self.threshold();
        let cols = self.columns.read();
        cols.values()
            .filter(|t| t.is_hot(threshold))
            .map(|t| t.name.clone())
            .collect()
    }

    /// Get cold columns (at or below threshold)
    pub fn get_cold_columns(&self) -> HashSet<String> {
        let threshold = self.threshold();
        let cols = self.columns.read();
        cols.values()
            .filter(|t| !t.is_hot(threshold))
            .map(|t| t.name.clone())
            .collect()
    }

    /// Get all temperatures for reporting
    pub fn get_all_temperatures(&self) -> Vec<ColumnTemperature> {
        self.columns.read().values().cloned().collect()
    }

    /// Set hot threshold (lock-free via atomic u64 bit pattern)
    ///
    /// Threshold ∈ [0.0, 1.0]. Columns with temperature > threshold are "hot" and
    /// participate in compaction merges. Lower threshold = more columns treated as hot.
    pub fn set_hot_threshold(&self, threshold: f64) {
        let clamped = threshold.clamp(0.0, 1.0);
        self.hot_threshold
            .store(clamped.to_bits(), Ordering::Relaxed);
    }
}

// ============================================================================
// Column Stripe References (Task 3)
// ============================================================================

/// Reference to a column stripe stored at a specific level
///
/// Allows columns to be stored at different levels independently,
/// enabling selective compaction of hot columns while cold columns
/// remain at lower levels.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ColumnStripeRef {
    /// Level where stripe is stored
    pub level: u32,
    /// Segment ID within level
    pub segment_id: u64,
    /// Column name
    pub column_name: String,
    /// Offset within segment file
    pub offset: u64,
    /// Length in bytes
    pub length: u64,
    /// Row count in stripe
    pub row_count: u64,
    /// Compression type
    pub compression: u8,
}

impl ColumnStripeRef {
    /// Create a new stripe reference
    pub fn new(
        level: u32,
        segment_id: u64,
        column_name: String,
        offset: u64,
        length: u64,
        row_count: u64,
    ) -> Self {
        Self {
            level,
            segment_id,
            column_name,
            offset,
            length,
            row_count,
            compression: 0,
        }
    }

    /// Create a reference pointing to a new location after compaction
    pub fn relocate(&self, new_level: u32, new_segment_id: u64, new_offset: u64) -> Self {
        Self {
            level: new_level,
            segment_id: new_segment_id,
            column_name: self.column_name.clone(),
            offset: new_offset,
            length: self.length,
            row_count: self.row_count,
            compression: self.compression,
        }
    }
}

/// Segment descriptor with column stripe references
///
/// Instead of storing all column data inline, the segment stores
/// references to column stripes which may be at different levels.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SegmentDescriptor {
    /// Segment ID
    pub id: u64,
    /// Level
    pub level: u32,
    /// Column stripe references (column name -> stripe ref)
    pub col_refs: HashMap<String, ColumnStripeRef>,
    /// Min row ID in segment
    pub min_row_id: RowId,
    /// Max row ID in segment
    pub max_row_id: RowId,
    /// Row count
    pub row_count: u64,
    /// Min timestamp
    pub min_timestamp: u64,
    /// Max timestamp
    pub max_timestamp: u64,
    /// Is tombstone (deleted after compaction)
    pub is_tombstone: bool,
}

/// Column ID type
pub type ColumnId = u32;

/// Row ID type (globally unique within table)
pub type RowId = u64;

/// Column data type for storage
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum ColumnType {
    Bool = 0,
    Int64 = 1,
    UInt64 = 2,
    Float64 = 3,
    Text = 4,
    Binary = 5,
    Timestamp = 6,
}

impl ColumnType {
    /// Fixed size in bytes, or None for variable-length
    pub fn fixed_size(&self) -> Option<usize> {
        match self {
            ColumnType::Bool => Some(1),
            ColumnType::Int64
            | ColumnType::UInt64
            | ColumnType::Float64
            | ColumnType::Timestamp => Some(8),
            ColumnType::Text | ColumnType::Binary => None,
        }
    }

    /// From byte
    pub fn from_byte(b: u8) -> Option<Self> {
        match b {
            0 => Some(ColumnType::Bool),
            1 => Some(ColumnType::Int64),
            2 => Some(ColumnType::UInt64),
            3 => Some(ColumnType::Float64),
            4 => Some(ColumnType::Text),
            5 => Some(ColumnType::Binary),
            6 => Some(ColumnType::Timestamp),
            _ => None,
        }
    }
}

/// Schema for a table in LSCS
#[derive(Debug, Clone)]
pub struct TableSchema {
    /// Table name
    pub name: String,
    /// Column definitions
    pub columns: Vec<ColumnDef>,
}

impl TableSchema {
    pub fn new(name: String, columns: Vec<ColumnDef>) -> Self {
        Self { name, columns }
    }

    /// Add MVCC columns (__txn_start, __txn_end) if not present
    pub fn with_mvcc(mut self) -> Self {
        if !self.columns.iter().any(|c| c.name == "__txn_start") {
            self.columns.push(ColumnDef {
                name: "__txn_start".to_string(),
                col_type: ColumnType::UInt64,
                nullable: false,
            });
        }
        if !self.columns.iter().any(|c| c.name == "__txn_end") {
            self.columns.push(ColumnDef {
                name: "__txn_end".to_string(),
                col_type: ColumnType::UInt64,
                nullable: false, // 0 or MAX for active/infinity
            });
        }
        self
    }
}

/// Column definition
#[derive(Debug, Clone)]
pub struct ColumnDef {
    /// Column name
    pub name: String,
    /// Column type
    pub col_type: ColumnType,
    /// Is nullable
    pub nullable: bool,
}

/// In-memory column buffer with O(1) random access
#[derive(Debug)]
struct ColumnBuffer {
    /// Column type
    col_type: ColumnType,
    /// Data bytes
    data: Vec<u8>,
    /// Null bitmap (bit per row, 1 = non-null)
    nulls: Vec<u8>,
    /// Offsets for variable-length types
    offsets: Option<Vec<u32>>,
    /// Row count
    row_count: u64,
}

impl ColumnBuffer {
    fn new(col_type: ColumnType) -> Self {
        Self {
            col_type,
            data: Vec::new(),
            nulls: Vec::new(),
            offsets: if col_type.fixed_size().is_none() {
                Some(vec![0]) // Initial offset
            } else {
                None
            },
            row_count: 0,
        }
    }

    /// Append a value (bytes)
    fn append(&mut self, value: Option<&[u8]>) {
        // Update null bitmap
        let bit_idx = self.row_count as usize;
        let byte_idx = bit_idx / 8;
        let bit_offset = bit_idx % 8;

        while self.nulls.len() <= byte_idx {
            self.nulls.push(0);
        }

        if let Some(data) = value {
            // Set non-null bit
            self.nulls[byte_idx] |= 1 << bit_offset;

            // Append data
            self.data.extend_from_slice(data);

            // Update offsets for variable-length
            if let Some(offsets) = &mut self.offsets {
                offsets.push(self.data.len() as u32);
            }
        } else if let Some(offsets) = &mut self.offsets {
            // Null value - repeat last offset
            let last = *offsets.last().unwrap();
            offsets.push(last);
        }

        self.row_count += 1;
    }

    /// Check if value at row_idx is null
    fn is_null(&self, row_idx: u64) -> bool {
        if row_idx >= self.row_count {
            return true; // Out of bounds treated as null
        }
        let byte_idx = (row_idx / 8) as usize;
        let bit_offset = (row_idx % 8) as u8;

        if byte_idx >= self.nulls.len() {
            return true;
        }

        (self.nulls[byte_idx] & (1 << bit_offset)) == 0
    }

    /// Get value at row_idx
    /// Returns None if null, Some(bytes) if non-null
    fn get(&self, row_idx: u64) -> Option<Vec<u8>> {
        if row_idx >= self.row_count || self.is_null(row_idx) {
            return None;
        }

        if let Some(fixed_size) = self.col_type.fixed_size() {
            // Fixed-size column: O(1) access
            let start = (row_idx as usize) * fixed_size;
            let end = start + fixed_size;
            if end <= self.data.len() {
                Some(self.data[start..end].to_vec())
            } else {
                None
            }
        } else {
            // Variable-length column: use offsets
            if let Some(offsets) = &self.offsets {
                let start = offsets[row_idx as usize] as usize;
                let end = offsets[(row_idx + 1) as usize] as usize;
                if end <= self.data.len() {
                    Some(self.data[start..end].to_vec())
                } else {
                    None
                }
            } else {
                None
            }
        }
    }

    /// Memory usage in bytes
    fn memory_bytes(&self) -> usize {
        self.data.len() + self.nulls.len() + self.offsets.as_ref().map(|o| o.len() * 4).unwrap_or(0)
    }
}

/// Columnar memtable with skip-list-like concurrent access
#[derive(Debug)]
pub struct ColumnarMemtable {
    /// Table schema
    schema: TableSchema,
    /// Column buffers (one per column)
    columns: Vec<RwLock<ColumnBuffer>>,
    /// Row ID to row index mapping (skip-list for O(log N) lookup)
    row_ids: RwLock<BTreeMap<RowId, u64>>,
    /// Reverse mapping: row index -> row ID (for range scans)
    row_idx_to_id: RwLock<Vec<RowId>>,
    /// Next row index
    next_row_idx: AtomicU64,
    /// Total bytes written
    bytes_written: AtomicU64,
    /// Memtable size limit
    size_limit: usize,
}

impl ColumnarMemtable {
    /// Create a new columnar memtable
    pub fn new(schema: TableSchema, size_limit: usize) -> Self {
        let columns = schema
            .columns
            .iter()
            .map(|def| RwLock::new(ColumnBuffer::new(def.col_type)))
            .collect();

        Self {
            schema,
            columns,
            row_ids: RwLock::new(BTreeMap::new()),
            row_idx_to_id: RwLock::new(Vec::new()),
            next_row_idx: AtomicU64::new(0),
            bytes_written: AtomicU64::new(0),
            size_limit,
        }
    }

    /// Insert a row
    ///
    /// `values` must have the same length as schema columns
    pub fn insert(&self, row_id: RowId, values: &[Option<&[u8]>]) -> Result<()> {
        if values.len() != self.schema.columns.len() {
            return Err(SochDBError::InvalidData(format!(
                "Expected {} columns, got {}",
                self.schema.columns.len(),
                values.len()
            )));
        }

        let row_idx = self.next_row_idx.fetch_add(1, Ordering::SeqCst);

        // Insert into each column
        let mut bytes = 0usize;
        for (i, value) in values.iter().enumerate() {
            let mut col = self.columns[i].write();
            if let Some(data) = value {
                bytes += data.len();
            }
            col.append(*value);
        }

        // Update row ID mapping (forward and reverse)
        {
            let mut ids = self.row_ids.write();
            ids.insert(row_id, row_idx);
        }
        {
            let mut idx_to_id = self.row_idx_to_id.write();
            // Ensure vector is large enough
            while idx_to_id.len() <= row_idx as usize {
                idx_to_id.push(0); // placeholder
            }
            idx_to_id[row_idx as usize] = row_id;
        }

        self.bytes_written
            .fetch_add(bytes as u64, Ordering::Relaxed);

        Ok(())
    }

    /// Get a row by row ID (O(log N) lookup via BTreeMap)
    /// Returns all column values for the row
    pub fn get(&self, row_id: RowId) -> Option<Vec<Option<Vec<u8>>>> {
        // Look up row index from row ID
        let row_ids = self.row_ids.read();
        let row_idx = *row_ids.get(&row_id)?;
        drop(row_ids);

        // Read all columns for this row
        let mut values = Vec::with_capacity(self.columns.len());
        for col in &self.columns {
            let col_buf = col.read();
            values.push(col_buf.get(row_idx));
        }

        Some(values)
    }

    /// Get specific columns for a row by row ID
    pub fn get_columns(
        &self,
        row_id: RowId,
        col_indices: &[usize],
    ) -> Option<Vec<Option<Vec<u8>>>> {
        // Look up row index from row ID
        let row_ids = self.row_ids.read();
        let row_idx = *row_ids.get(&row_id)?;
        drop(row_ids);

        // Read only requested columns
        let mut values = Vec::with_capacity(col_indices.len());
        for &col_idx in col_indices {
            if col_idx < self.columns.len() {
                let col_buf = self.columns[col_idx].read();
                values.push(col_buf.get(row_idx));
            } else {
                values.push(None);
            }
        }

        Some(values)
    }

    /// Scan a range of row IDs, returning all matching rows
    pub fn scan_range(&self, start: RowId, end: RowId) -> Vec<(RowId, Vec<Option<Vec<u8>>>)> {
        let row_ids = self.row_ids.read();
        let mut results = Vec::new();

        for (&row_id, &row_idx) in row_ids.range(start..=end) {
            let mut values = Vec::with_capacity(self.columns.len());
            for col in &self.columns {
                let col_buf = col.read();
                values.push(col_buf.get(row_idx));
            }
            results.push((row_id, values));
        }

        results
    }

    /// Check if memtable is full
    pub fn is_full(&self) -> bool {
        self.bytes_written.load(Ordering::Relaxed) as usize >= self.size_limit
    }

    /// Get row count
    pub fn row_count(&self) -> u64 {
        self.next_row_idx.load(Ordering::SeqCst)
    }

    /// Get memory usage
    pub fn memory_bytes(&self) -> usize {
        self.columns.iter().map(|c| c.read().memory_bytes()).sum()
    }

    /// Get schema
    pub fn schema(&self) -> &TableSchema {
        &self.schema
    }
}

use sochdb_core::learned_index::LearnedSparseIndex;

/// Metadata for a stored column
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ColumnIndex {
    /// Offset in the file
    pub offset: u64,
    /// Length in bytes
    pub length: u64,
    /// Compression type (0 = None for now)
    pub compression: u8,
}

/// Column group stored on disk
#[derive(Debug)]
#[allow(dead_code)]
pub struct ColumnGroup {
    /// Path to the monolithic .sst file
    path: PathBuf,
    /// Table schema
    schema: TableSchema,
    /// Level in LSM tree (0 = L0)
    level: u32,
    /// Sequence number
    sequence: u64,
    /// Row count
    row_count: u64,
    /// Min timestamp
    min_timestamp: u64,
    /// Max timestamp
    max_timestamp: u64,
    /// Column offsets loaded from footer
    column_offsets: BTreeMap<String, ColumnIndex>,
    /// Learned Sparse Index for RowId lookup
    lsi: Option<LearnedSparseIndex>,
}

impl ColumnGroup {
    /// Magic bytes for SSTable file (TOON + version 1)
    const MAGIC: [u8; 4] = [b'T', b'O', b'O', b'N'];
    const VERSION: u32 = 1;

    /// Create metadata for a column group
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        path: PathBuf,
        schema: TableSchema,
        level: u32,
        sequence: u64,
        row_count: u64,
        min_timestamp: u64,
        max_timestamp: u64,
        column_offsets: BTreeMap<String, ColumnIndex>,
        lsi: Option<LearnedSparseIndex>,
    ) -> Self {
        Self {
            path,
            schema,
            level,
            sequence,
            row_count,
            min_timestamp,
            max_timestamp,
            column_offsets,
            lsi,
        }
    }

    /// Write memtable to disk as a single SSTable file
    pub fn from_memtable(
        base_path: &Path,
        memtable: &ColumnarMemtable,
        level: u32,
        sequence: u64,
    ) -> Result<Self> {
        use byteorder::{LittleEndian, WriteBytesExt};
        use std::fs::File;
        use std::io::{BufWriter, Seek, Write};

        // Create monolithic file: L{level}_seq{sequence}.sst
        let file_name = format!("L{}_seq{}.sst", level, sequence);
        let file_path = base_path.join(&file_name);
        let file = File::create(&file_path)?;
        let mut writer = BufWriter::new(file);

        // Write Header
        writer.write_all(&Self::MAGIC)?;
        writer.write_u32::<LittleEndian>(Self::VERSION)?;

        let mut column_offsets = BTreeMap::new();
        let mut min_ts = u64::MAX;
        let mut max_ts = 0u64;

        // Write each column sequentially
        for (i, col_lock) in memtable.columns.iter().enumerate() {
            let col = col_lock.read();
            let col_def = &memtable.schema.columns[i];

            // Extract min/max timestamps from __txn_start column
            if col_def.name == "__txn_start" && col.col_type == ColumnType::UInt64 {
                // Parse u64 timestamps from the column data
                let mut offset = 0;
                let row_count = col.row_count as usize;
                for row_idx in 0..row_count {
                    // Check if not null
                    let byte_idx = row_idx / 8;
                    let bit_idx = row_idx % 8;
                    let is_null =
                        byte_idx < col.nulls.len() && (col.nulls[byte_idx] & (1 << bit_idx)) != 0;

                    if !is_null && offset + 8 <= col.data.len() {
                        let ts = u64::from_le_bytes(
                            col.data[offset..offset + 8].try_into().unwrap_or([0u8; 8]),
                        );
                        min_ts = min_ts.min(ts);
                        max_ts = max_ts.max(ts);
                    }
                    offset += 8;
                }
            }

            let start_offset = writer.stream_position()?;

            // Column Header within the block
            writer.write_u8(col.col_type as u8)?;
            writer.write_u64::<LittleEndian>(col.row_count)?;

            // Null bitmap
            writer.write_u32::<LittleEndian>(col.nulls.len() as u32)?;
            writer.write_all(&col.nulls)?;

            // Offsets (if variable-length)
            if let Some(offsets) = &col.offsets {
                writer.write_u32::<LittleEndian>(offsets.len() as u32)?;
                for &off in offsets {
                    writer.write_u32::<LittleEndian>(off)?;
                }
            }

            // Data
            writer.write_u32::<LittleEndian>(col.data.len() as u32)?;
            writer.write_all(&col.data)?;

            let end_offset = writer.stream_position()?;

            column_offsets.insert(
                col_def.name.clone(),
                ColumnIndex {
                    offset: start_offset,
                    length: end_offset - start_offset,
                    compression: 0, // No compression yet
                },
            );
        }

        // Build Learned Sparse Index on RowIds
        let row_ids = memtable.row_ids.read();
        let keys: Vec<u64> = row_ids.keys().cloned().collect();
        let lsi = LearnedSparseIndex::build(&keys);

        // Write Footer (Index + LSI)
        let footer_start = writer.stream_position()?;

        // Serialize Column Offsets
        let offsets_bytes = bincode::serialize(&column_offsets)
            .map_err(|e| SochDBError::Serialization(e.to_string()))?;
        writer.write_u64::<LittleEndian>(offsets_bytes.len() as u64)?;
        writer.write_all(&offsets_bytes)?;

        // Serialize LSI
        let lsi_bytes =
            bincode::serialize(&lsi).map_err(|e| SochDBError::Serialization(e.to_string()))?;
        writer.write_u64::<LittleEndian>(lsi_bytes.len() as u64)?;
        writer.write_all(&lsi_bytes)?;

        // Write Footer Offset and Magic at the very end
        writer.write_u64::<LittleEndian>(footer_start)?;
        writer.write_all(&Self::MAGIC)?;

        writer.flush()?;

        // Fallback: use current time if no timestamps were found in data
        if min_ts == u64::MAX || max_ts == 0 {
            let now = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_micros() as u64;
            min_ts = now;
            max_ts = now;
        }

        Ok(Self {
            path: file_path,
            schema: memtable.schema.clone(),
            level,
            sequence,
            row_count: memtable.row_count(),
            min_timestamp: min_ts,
            max_timestamp: max_ts,
            column_offsets,
            lsi: Some(lsi),
        })
    }

    /// Open a ColumnGroup from an existing SST file
    pub fn open(path: PathBuf, schema: TableSchema, level: u32, sequence: u64) -> Result<Self> {
        use byteorder::{LittleEndian, ReadBytesExt};
        use std::fs::File;
        use std::io::{Read, Seek, SeekFrom};

        let mut file = File::open(&path)?;
        let file_len = file.metadata()?.len();

        if file_len < 12 {
            // Magic (4) + FooterOffset (8)
            return Err(SochDBError::Corruption("File too short".to_string()));
        }

        // Read Footer Offset
        file.seek(SeekFrom::End(-12))?;
        let footer_offset = file.read_u64::<LittleEndian>()?;
        let mut magic = [0u8; 4];
        file.read_exact(&mut magic)?;

        if magic != Self::MAGIC {
            return Err(SochDBError::Corruption("Invalid magic bytes".to_string()));
        }

        // Read Footer
        file.seek(SeekFrom::Start(footer_offset))?;

        // Read Column Offsets
        let offsets_len = file.read_u64::<LittleEndian>()?;
        let mut offsets_bytes = vec![0u8; offsets_len as usize];
        file.read_exact(&mut offsets_bytes)?;
        let column_offsets: BTreeMap<String, ColumnIndex> = bincode::deserialize(&offsets_bytes)
            .map_err(|e| SochDBError::Serialization(e.to_string()))?;

        // Read LSI
        let lsi_len = file.read_u64::<LittleEndian>()?;
        let mut lsi_bytes = vec![0u8; lsi_len as usize];
        file.read_exact(&mut lsi_bytes)?;
        let lsi: LearnedSparseIndex = bincode::deserialize(&lsi_bytes)
            .map_err(|e| SochDBError::Serialization(e.to_string()))?;

        Ok(Self {
            path,
            schema,
            level,
            sequence,
            row_count: 0, // Needs to be fixed by storing in footer
            min_timestamp: 0,
            max_timestamp: 0,
            column_offsets,
            lsi: Some(lsi),
        })
    }

    /// Get path to the SST file
    pub fn file_path(&self) -> &Path {
        &self.path
    }

    /// Get offset info for a column
    pub fn column_index(&self, col_name: &str) -> Option<&ColumnIndex> {
        self.column_offsets.get(col_name)
    }

    /// Get level
    pub fn level(&self) -> u32 {
        self.level
    }

    /// Get row count
    pub fn row_count(&self) -> u64 {
        self.row_count
    }
}

// ============================================================================
// Compaction Statistics (Task 3)
// ============================================================================

/// Statistics for column-aware compaction
#[derive(Debug, Clone, Default)]
pub struct CompactionStats {
    /// Total compactions performed
    pub compactions_total: u64,
    /// L0 to L1 compactions
    pub l0_compactions: u64,
    /// Total bytes read during compaction
    pub bytes_read: u64,
    /// Total bytes written during compaction
    pub bytes_written: u64,
    /// Hot column compactions (only hot columns merged)
    pub hot_column_compactions: u64,
    /// Cold column references preserved (not rewritten)
    pub cold_column_refs_preserved: u64,
    /// Estimated write amplification reduction
    pub estimated_wa_reduction: f64,
    /// Last compaction duration (micros)
    pub last_compaction_duration_us: u64,
}

impl CompactionStats {
    /// Calculate write amplification factor
    pub fn write_amplification(&self) -> f64 {
        if self.bytes_read == 0 {
            1.0
        } else {
            self.bytes_written as f64 / self.bytes_read as f64
        }
    }
}

/// Statistics from WAL recovery
#[derive(Debug, Clone, Default)]
pub struct LscsRecoveryStats {
    /// Number of transactions successfully replayed
    pub transactions_recovered: usize,
    /// Number of rows restored to memtable
    pub rows_recovered: usize,
    /// Maximum row ID found (used to set next_row_id)
    pub max_row_id: u64,
}

/// LSCS configuration
#[derive(Debug, Clone)]
pub struct LscsConfig {
    /// Memtable size limit in bytes
    pub memtable_size: usize,
    /// Number of levels
    pub num_levels: usize,
    /// Size ratio between levels
    pub level_ratio: usize,
    /// Maximum L0 column groups before compaction
    pub l0_compaction_threshold: usize,
    /// Hot column temperature threshold (0.0-1.0)
    pub hot_threshold: f64,
    /// Temperature window size (number of updates)
    pub temperature_window_size: u64,
}

impl Default for LscsConfig {
    fn default() -> Self {
        Self {
            memtable_size: 64 * 1024 * 1024, // 64 MB
            num_levels: 7,
            level_ratio: 10,
            l0_compaction_threshold: 4,
            hot_threshold: 0.1,            // 10% threshold for "hot" column
            temperature_window_size: 1000, // 1000 updates per window
        }
    }
}

/// Log-Structured Column Store
pub struct Lscs {
    /// Configuration
    config: LscsConfig,
    /// Base path for storage
    path: PathBuf,
    /// Table schema
    schema: TableSchema,
    /// Write-ahead log
    wal: Arc<TxnWal>,
    /// Active memtable
    active_memtable: RwLock<ColumnarMemtable>,
    /// Immutable memtables pending flush
    immutable_memtables: RwLock<Vec<ColumnarMemtable>>,
    /// Column groups by level
    column_groups: RwLock<Vec<Vec<ColumnGroup>>>,
    /// Segment descriptors with column stripe references (Task 3)
    segment_descriptors: RwLock<HashMap<u64, SegmentDescriptor>>,
    /// Column temperature tracker (Task 3)
    temperature_tracker: Arc<ColumnTemperatureTracker>,
    /// Next sequence number
    next_sequence: AtomicU64,
    /// Next row ID
    next_row_id: AtomicU64,
    /// Compaction statistics (Task 3)
    compaction_stats: RwLock<CompactionStats>,
}

impl Lscs {
    /// Create a new LSCS instance
    pub fn new(path: PathBuf, schema: TableSchema, config: LscsConfig) -> Result<Self> {
        std::fs::create_dir_all(&path)?;

        let wal_path = path.join("wal.log");
        let wal = Arc::new(TxnWal::new(&wal_path)?);

        let active_memtable = ColumnarMemtable::new(schema.clone(), config.memtable_size);

        let mut column_groups = Vec::with_capacity(config.num_levels);
        for _ in 0..config.num_levels {
            column_groups.push(Vec::new());
        }

        // Create temperature tracker for all columns (Task 3)
        let column_names: Vec<String> = schema.columns.iter().map(|c| c.name.clone()).collect();
        let temperature_tracker = Arc::new(ColumnTemperatureTracker::new(
            &column_names,
            config.temperature_window_size,
        ));

        Ok(Self {
            config,
            path,
            schema,
            wal,
            active_memtable: RwLock::new(active_memtable),
            immutable_memtables: RwLock::new(Vec::new()),
            column_groups: RwLock::new(column_groups),
            segment_descriptors: RwLock::new(HashMap::new()),
            temperature_tracker,
            next_sequence: AtomicU64::new(0),
            next_row_id: AtomicU64::new(1),
            compaction_stats: RwLock::new(CompactionStats::default()),
        })
    }

    /// Open an existing LSCS instance and recover from WAL
    ///
    /// This is the production entrypoint that ensures durability:
    /// 1. Opens the existing storage directory
    /// 2. Replays committed transactions from WAL into memtable
    /// 3. Updates next_row_id to prevent ID conflicts
    ///
    /// ## Crash Recovery Guarantees
    ///
    /// - Only committed transactions are replayed (atomicity)
    /// - All committed data is restored (durability)
    /// - Uncommitted transactions are discarded (consistency)
    pub fn open(path: PathBuf, schema: TableSchema, config: LscsConfig) -> Result<Self> {
        let lscs = Self::new(path, schema, config)?;
        let stats = lscs.recover()?;

        if stats.rows_recovered > 0 {
            eprintln!(
                "LSCS Recovery: restored {} rows from {} transactions",
                stats.rows_recovered, stats.transactions_recovered
            );
        }

        Ok(lscs)
    }

    /// Perform crash recovery by replaying committed WAL entries
    ///
    /// Returns statistics about recovered data.
    pub fn recover(&self) -> Result<LscsRecoveryStats> {
        let (writes, txn_count) = self.wal.replay_for_recovery()?;

        if writes.is_empty() {
            return Ok(LscsRecoveryStats::default());
        }

        let mut max_row_id: u64 = 0;
        let mut rows_recovered = 0usize;

        // Apply committed writes to memtable
        for (key, value) in &writes {
            // Key is row_id as little-endian u64
            if key.len() >= 8 {
                let row_id = u64::from_le_bytes(key[..8].try_into().unwrap_or([0; 8]));
                if row_id > max_row_id {
                    max_row_id = row_id;
                }

                // Deserialize row and insert into memtable
                if let Ok(row_values) = Self::deserialize_row(value) {
                    let value_refs: Vec<Option<&[u8]>> =
                        row_values.iter().map(|v| v.as_deref()).collect();

                    let memtable = self.active_memtable.read();
                    if memtable.insert(row_id, &value_refs).is_ok() {
                        rows_recovered += 1;
                    }
                }
            }
        }

        // Update next_row_id to prevent conflicts
        if max_row_id > 0 {
            self.next_row_id.store(max_row_id + 1, Ordering::SeqCst);
        }

        Ok(LscsRecoveryStats {
            transactions_recovered: txn_count,
            rows_recovered,
            max_row_id,
        })
    }

    /// Write a clean shutdown marker
    ///
    /// Call this during graceful shutdown to indicate all data was flushed.
    /// On next open, if this marker exists, recovery can be optimized.
    pub fn mark_clean_shutdown(&self) -> Result<()> {
        // First ensure all data is synced
        self.fsync()?;

        // Write clean shutdown marker
        let marker_path = self.path.join(".clean_shutdown");
        std::fs::write(&marker_path, b"clean")?;

        // Optionally truncate WAL after checkpoint
        // (conservative: we leave WAL intact for extra safety)

        Ok(())
    }

    /// Insert a row
    pub fn insert(&self, values: &[Option<&[u8]>]) -> Result<RowId> {
        let row_id = self.next_row_id.fetch_add(1, Ordering::SeqCst);

        // Write to WAL first
        let txn_id = self.wal.begin_transaction()?;

        // Serialize values for WAL
        let key = row_id.to_le_bytes().to_vec();
        let value = self.serialize_row(values)?;
        self.wal.write(txn_id, key, value)?;
        self.wal.commit_transaction(txn_id)?;

        // Insert into memtable
        let memtable = self.active_memtable.read();
        memtable.insert(row_id, values)?;

        // Check if memtable is full
        if memtable.is_full() {
            drop(memtable);
            self.rotate_memtable()?;
        }

        Ok(row_id)
    }

    /// Mark a row as deleted by setting __txn_end to the given transaction timestamp
    ///
    /// In MVCC, deletion doesn't remove the row immediately - instead we mark
    /// it with an end timestamp so it becomes invisible to newer transactions.
    ///
    /// ## Durability
    ///
    /// This operation is fully WAL-logged with proper transaction boundaries:
    /// - TxnBegin record
    /// - Data record with the updated row
    /// - TxnCommit record with fsync
    ///
    /// On crash recovery, only committed deletions will be replayed.
    pub fn mark_deleted(&self, row_id: RowId, _caller_txn_id: u64, txn_end: u64) -> Result<()> {
        // Find the __txn_end column index
        let txn_end_idx = self
            .schema
            .columns
            .iter()
            .position(|c| c.name == "__txn_end")
            .ok_or_else(|| {
                SochDBError::InvalidData("Schema missing __txn_end column for MVCC".to_string())
            })?;

        // Get current row values
        let current = self
            .get(row_id)?
            .ok_or_else(|| SochDBError::NotFound(format!("Row {} not found", row_id)))?;

        // Build new row with updated __txn_end
        let mut new_values: Vec<Option<Vec<u8>>> = current;
        new_values[txn_end_idx] = Some(txn_end.to_le_bytes().to_vec());

        // Convert to references for insert
        let value_refs: Vec<Option<&[u8]>> = new_values.iter().map(|v| v.as_deref()).collect();

        // Write to WAL with proper transaction boundaries for durability
        // Begin a new WAL transaction (allocates txn_id and writes TxnBegin)
        let wal_txn_id = self.wal.begin_transaction()?;

        // Write the data record
        let row_data = self.serialize_row(&value_refs)?;
        self.wal
            .write(wal_txn_id, row_id.to_le_bytes().to_vec(), row_data)?;

        // Commit with fsync for durability guarantee
        self.wal.commit_transaction(wal_txn_id)?;

        // Update memtable (only after WAL commit succeeds)
        let memtable = self.active_memtable.read();
        memtable.insert(row_id, &value_refs)?;

        Ok(())
    }

    /// Serialize a row for WAL storage
    fn serialize_row(&self, values: &[Option<&[u8]>]) -> Result<Vec<u8>> {
        use byteorder::{LittleEndian, WriteBytesExt};

        let mut buf = Vec::new();
        buf.write_u32::<LittleEndian>(values.len() as u32)?;

        for value in values {
            match value {
                Some(data) => {
                    buf.write_u8(1)?; // non-null
                    buf.write_u32::<LittleEndian>(data.len() as u32)?;
                    buf.extend_from_slice(data);
                }
                None => {
                    buf.write_u8(0)?; // null
                }
            }
        }

        Ok(buf)
    }

    /// Deserialize a row from WAL storage
    #[allow(dead_code)]
    fn deserialize_row(data: &[u8]) -> Result<Vec<Option<Vec<u8>>>> {
        use byteorder::{LittleEndian, ReadBytesExt};
        use std::io::Cursor;

        let mut cursor = Cursor::new(data);
        let num_cols = cursor.read_u32::<LittleEndian>()? as usize;
        let mut values = Vec::with_capacity(num_cols);

        for _ in 0..num_cols {
            let is_non_null = cursor.read_u8()? == 1;
            if is_non_null {
                let len = cursor.read_u32::<LittleEndian>()? as usize;
                let pos = cursor.position() as usize;
                let value = data[pos..pos + len].to_vec();
                cursor.set_position((pos + len) as u64);
                values.push(Some(value));
            } else {
                values.push(None);
            }
        }

        Ok(values)
    }

    /// Get a row by row ID
    ///
    /// Search order: memtable -> immutable memtables -> SSTables
    /// Uses learned sparse index for O(1) expected time on SSTables
    pub fn get(&self, row_id: RowId) -> Result<Option<Vec<Option<Vec<u8>>>>> {
        // 1. Check active memtable (O(log N))
        {
            let memtable = self.active_memtable.read();
            if let Some(values) = memtable.get(row_id) {
                return Ok(Some(values));
            }
        }

        // 2. Check immutable memtables (O(log N) per table)
        {
            let immutable = self.immutable_memtables.read();
            for memtable in immutable.iter().rev() {
                if let Some(values) = memtable.get(row_id) {
                    return Ok(Some(values));
                }
            }
        }

        // 3. Check SSTables using learned sparse index
        // For each level, use LSI for O(1) expected lookup
        {
            use sochdb_core::learned_index::LookupResult;
            let groups = self.column_groups.read();
            for level in &*groups {
                for group in level.iter().rev() {
                    if let Some(lsi) = &group.lsi {
                        // Use learned index for O(1) lookup
                        let lookup = lsi.lookup(row_id);
                        match lookup {
                            LookupResult::Exact(_) | LookupResult::Range { .. } => {
                                // Key might be in this SSTable, read to confirm
                                if let Some(row) = self.read_row_from_sstable(group, row_id)? {
                                    return Ok(Some(row));
                                }
                            }
                            LookupResult::NotFound => {
                                // Key definitely not in this SSTable
                                continue;
                            }
                        }
                    }
                }
            }
        }

        Ok(None)
    }

    /// Read a single row from an SSTable file
    fn read_row_from_sstable(
        &self,
        group: &ColumnGroup,
        row_id: RowId,
    ) -> Result<Option<Vec<Option<Vec<u8>>>>> {
        use byteorder::{LittleEndian, ReadBytesExt};
        use std::fs::File;
        use std::io::{BufReader, Read, Seek, SeekFrom};

        let file = File::open(group.file_path())?;
        let mut reader = BufReader::new(file);

        let mut values = Vec::new();

        // Read each column's data for this row
        for (col_name, col_idx) in &group.column_offsets {
            reader.seek(SeekFrom::Start(col_idx.offset))?;

            // Read column header
            let col_type = reader.read_u8()?;
            let row_count = reader.read_u64::<LittleEndian>()?;

            if row_id >= row_count {
                values.push(None);
                continue;
            }

            // Read null bitmap
            let nulls_len = reader.read_u32::<LittleEndian>()? as usize;
            let mut nulls = vec![0u8; nulls_len];
            reader.read_exact(&mut nulls)?;

            // Check if this row is null
            let byte_idx = (row_id / 8) as usize;
            let bit_offset = (row_id % 8) as u8;
            let is_null = byte_idx >= nulls.len() || (nulls[byte_idx] & (1 << bit_offset)) == 0;

            if is_null {
                values.push(None);
                continue;
            }

            // Read value based on column type
            let col_type = ColumnType::from_byte(col_type).unwrap_or(ColumnType::Binary);
            if let Some(fixed_size) = col_type.fixed_size() {
                // Skip nulls bitmap, then seek to row
                let offsets_section = reader.stream_position()?;
                let data_len = reader.read_u32::<LittleEndian>()? as usize;
                let _ = data_len;

                // Calculate offset for this row
                let row_offset = (row_id as usize) * fixed_size;
                reader.seek(SeekFrom::Start(offsets_section + 4 + row_offset as u64))?;

                let mut value = vec![0u8; fixed_size];
                reader.read_exact(&mut value)?;
                values.push(Some(value));
            } else {
                // Variable-length: read offsets array
                let offsets_count = reader.read_u32::<LittleEndian>()? as usize;
                let mut offsets = vec![0u32; offsets_count];
                for offset in offsets.iter_mut().take(offsets_count) {
                    *offset = reader.read_u32::<LittleEndian>()?;
                }

                if (row_id as usize + 1) >= offsets.len() {
                    values.push(None);
                    continue;
                }

                let start = offsets[row_id as usize] as usize;
                let end = offsets[(row_id + 1) as usize] as usize;

                // Read data section
                let data_len = reader.read_u32::<LittleEndian>()? as usize;
                let data_start = reader.stream_position()?;

                if end <= data_len {
                    reader.seek(SeekFrom::Start(data_start + start as u64))?;
                    let mut value = vec![0u8; end - start];
                    reader.read_exact(&mut value)?;
                    values.push(Some(value));
                } else {
                    values.push(None);
                }
            }
            let _ = col_name; // silence unused warning
        }

        if values.is_empty() {
            Ok(None)
        } else {
            Ok(Some(values))
        }
    }

    /// Fsync - ensure all data is durably persisted to disk
    ///
    /// This is the key durability guarantee:
    /// 1. Flush WAL to disk with fsync
    /// 2. If memtable is large, flush to SSTable
    ///
    /// After fsync returns, all prior writes are guaranteed durable.
    pub fn fsync(&self) -> Result<()> {
        // 1. Sync WAL (critical for durability)
        self.wal.sync()?;

        // 2. Optionally flush memtable if it's getting large
        let memtable = self.active_memtable.read();
        let should_flush = memtable.memory_bytes() > self.config.memtable_size / 2;
        drop(memtable);

        if should_flush {
            // Rotate and flush in background
            self.rotate_memtable()?;
            self.flush()?;
        }

        Ok(())
    }

    /// Rotate memtable (switch to new one, add old to immutable list)
    fn rotate_memtable(&self) -> Result<()> {
        let new_memtable = ColumnarMemtable::new(self.schema.clone(), self.config.memtable_size);

        let old_memtable = {
            let mut active = self.active_memtable.write();
            std::mem::replace(&mut *active, new_memtable)
        };

        let mut immutable = self.immutable_memtables.write();
        immutable.push(old_memtable);

        // Trigger background flush if we have pending immutable memtables
        if immutable.len() >= 2 {
            // Flush synchronously if too many pending
            drop(immutable); // Release lock before flushing
            self.flush()?;
        }

        Ok(())
    }

    /// Flush immutable memtables to disk
    pub fn flush(&self) -> Result<()> {
        let memtables = {
            let mut immutable = self.immutable_memtables.write();
            std::mem::take(&mut *immutable)
        };

        for memtable in memtables {
            let sequence = self.next_sequence.fetch_add(1, Ordering::SeqCst);
            let column_group = ColumnGroup::from_memtable(&self.path, &memtable, 0, sequence)?;

            let mut groups = self.column_groups.write();
            groups[0].push(column_group);
        }

        // Check if L0 compaction needed
        let groups = self.column_groups.read();
        if groups[0].len() >= self.config.l0_compaction_threshold {
            drop(groups);
            self.compact_l0()?;
        }

        Ok(())
    }

    /// Compact L0 column groups using column-aware compaction (Task 3)
    ///
    /// Algorithm:
    /// 1. Query `temperature_tracker` for hot/cold column sets
    /// 2. Drain all L0 `ColumnGroup` segments
    /// 3. Hot columns: read stripes, merge-sort by row_id, write to L1
    /// 4. Cold columns: create `ColumnStripeRef` pointing to existing L0 data (zero I/O)
    /// 5. Create `SegmentDescriptor` at L1 with mixed references
    ///
    /// Write amplification: WA_col = (|H| / |C|) × WA_lsm
    /// With 20% hot columns: WA_col = 0.2 × WA_lsm ≈ 5× reduction.
    fn compact_l0(&self) -> Result<()> {
        let start_time = std::time::Instant::now();

        // Get hot and cold columns
        let hot_columns = self.temperature_tracker.get_hot_columns();
        let cold_columns = self.temperature_tracker.get_cold_columns();

        let total_columns = self.schema.columns.len();
        let hot_fraction = if total_columns > 0 {
            hot_columns.len() as f64 / total_columns as f64
        } else {
            1.0
        };

        // Get L0 segments to compact
        let l0_segments: Vec<ColumnGroup> = {
            let mut groups = self.column_groups.write();
            std::mem::take(&mut groups[0])
        };

        if l0_segments.is_empty() {
            return Ok(());
        }

        let mut bytes_read = 0u64;
        let mut bytes_written = 0u64;
        let mut cold_refs_preserved = 0u64;

        let sequence = self.next_sequence.fetch_add(1, Ordering::SeqCst);

        // ---- Hot column selective merge ----
        // Only hot columns are read and rewritten. Cost = O(|H| × N × log N).
        let merged_path = self.path.join(format!("L1_seq{}.sst", sequence));
        let segment_refs: Vec<&ColumnGroup> = l0_segments.iter().collect();

        let hot_col_refs = if !hot_columns.is_empty() {
            let refs =
                self.selective_merge_hot_columns(&segment_refs, &hot_columns, &merged_path)?;
            // Tally I/O for merged hot columns
            for (_col, stripe) in &refs {
                bytes_written += stripe.length;
            }
            refs
        } else {
            HashMap::new()
        };

        // ---- Cold column reference promotion (zero I/O) ----
        // Cold columns keep their existing L0 stripe addresses.
        let mut col_refs = hot_col_refs;
        let mut total_row_count = 0u64;
        let min_row_id = u64::MAX;
        let max_row_id = 0u64;

        for segment in &l0_segments {
            bytes_read += segment.row_count * 100; // Estimate per-row overhead
            total_row_count += segment.row_count;

            // Count hot-column bytes read from this segment
            for col_name in &hot_columns {
                if let Some(col_idx) = segment.column_offsets.get(col_name) {
                    bytes_read += col_idx.length;
                }
            }

            // Promote cold column stripe references — no data movement
            for col_name in &cold_columns {
                if let Some(col_idx) = segment.column_offsets.get(col_name) {
                    let stripe_ref = ColumnStripeRef::new(
                        segment.level,
                        segment.sequence,
                        col_name.clone(),
                        col_idx.offset,
                        col_idx.length,
                        segment.row_count,
                    );
                    col_refs.insert(col_name.clone(), stripe_ref);
                    cold_refs_preserved += 1;
                }
            }
        }

        // Create segment descriptor for the merged segment
        let segment_desc = SegmentDescriptor {
            id: sequence,
            level: 1,
            col_refs,
            min_row_id,
            max_row_id,
            row_count: total_row_count,
            min_timestamp: 0,
            max_timestamp: std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_micros() as u64,
            is_tombstone: false,
        };

        // Store segment descriptor
        {
            let mut descriptors = self.segment_descriptors.write();
            descriptors.insert(sequence, segment_desc);
        }

        // Update compaction stats
        {
            let mut stats = self.compaction_stats.write();
            stats.compactions_total += 1;
            stats.l0_compactions += 1;
            stats.bytes_read += bytes_read;
            stats.bytes_written += bytes_written;
            stats.cold_column_refs_preserved += cold_refs_preserved;
            stats.hot_column_compactions += 1;
            stats.estimated_wa_reduction = 1.0 / hot_fraction.max(0.01);
            stats.last_compaction_duration_us = start_time.elapsed().as_micros() as u64;
        }

        // Clean up old L0 segments (mark as tombstones)
        // The segment files remain for cold column references until no longer needed
        for segment in l0_segments {
            let _ = segment; // Drop the in-memory metadata
        }

        Ok(())
    }

    /// Perform selective merge of hot columns across segments
    ///
    /// Algorithm:
    ///   Input: L0 segments S₀ = {s₁, s₂, ..., s_n}, hot columns H
    ///   
    ///   1. For each column cⱼ ∈ H:
    ///      merged[cⱼ] = merge_column_stripes(S₀[cⱼ])
    ///   
    ///   2. Write merged hot columns to new segment
    ///   
    ///   Time: O(|H| × N × log(N)) where N = rows
    fn selective_merge_hot_columns(
        &self,
        segments: &[&ColumnGroup],
        hot_columns: &HashSet<String>,
        output_path: &Path,
    ) -> Result<HashMap<String, ColumnStripeRef>> {
        use byteorder::{LittleEndian, WriteBytesExt};
        use std::fs::File;
        use std::io::{BufWriter, Seek, Write};

        let mut result = HashMap::new();

        // Create output file
        let file = File::create(output_path)?;
        let mut writer = BufWriter::new(file);

        // Write header
        writer.write_all(&ColumnGroup::MAGIC)?;
        writer.write_u32::<LittleEndian>(ColumnGroup::VERSION)?;

        let sequence = self.next_sequence.load(Ordering::SeqCst);

        // Merge each hot column
        for col_name in hot_columns {
            let start_offset = writer.stream_position()?;

            // Collect column data from all segments
            let mut merged_data = Vec::new();
            let mut row_count = 0u64;

            for segment in segments {
                if let Some(_col_idx) = segment.column_offsets.get(col_name) {
                    // Read column data from segment
                    // In production, this would do proper merge-sort
                    merged_data.extend_from_slice(&[0u8; 0]); // Placeholder
                    row_count += segment.row_count;
                }
            }

            // Write merged column
            // In production, this would write proper column format
            writer.write_u64::<LittleEndian>(row_count)?;
            writer.write_all(&merged_data)?;

            let end_offset = writer.stream_position()?;

            // Create stripe reference
            let stripe_ref = ColumnStripeRef::new(
                1, // L1
                sequence,
                col_name.clone(),
                start_offset,
                end_offset - start_offset,
                row_count,
            );
            result.insert(col_name.clone(), stripe_ref);
        }

        writer.flush()?;
        Ok(result)
    }

    /// Read specific column stripes for a query (Task 3)
    ///
    /// Only reads the requested columns, reducing I/O by (1 - k/K)
    /// where k = requested columns, K = total columns
    pub fn scan_columns(
        &self,
        column_names: &[&str],
        row_range: Option<(RowId, RowId)>,
    ) -> Result<Vec<Vec<u8>>> {
        let mut results = Vec::new();

        // Look up stripe references for requested columns
        let descriptors = self.segment_descriptors.read();

        for (_seg_id, descriptor) in descriptors.iter() {
            // Check row range overlap if specified
            if let Some((min, max)) = row_range
                && (descriptor.max_row_id < min || descriptor.min_row_id > max)
            {
                continue;
            }

            // Read only requested columns
            for col_name in column_names {
                if let Some(stripe_ref) = descriptor.col_refs.get(*col_name) {
                    // Read stripe data
                    let data = self.read_column_stripe(stripe_ref)?;
                    results.push(data);
                }
            }
        }

        Ok(results)
    }

    /// Read a single column stripe from disk
    fn read_column_stripe(&self, stripe_ref: &ColumnStripeRef) -> Result<Vec<u8>> {
        use std::fs::File;
        use std::io::{Read, Seek, SeekFrom};

        // Construct file path from level and segment_id
        let file_path = self.path.join(format!(
            "L{}_seq{}.sst",
            stripe_ref.level, stripe_ref.segment_id
        ));

        let mut file = File::open(&file_path)?;
        file.seek(SeekFrom::Start(stripe_ref.offset))?;

        let mut data = vec![0u8; stripe_ref.length as usize];
        file.read_exact(&mut data)?;

        Ok(data)
    }

    /// Get compaction statistics
    pub fn compaction_stats(&self) -> CompactionStats {
        self.compaction_stats.read().clone()
    }

    /// Trigger manual compaction
    ///
    /// This compacts L0 segments into L1 using the temperature-aware strategy
    pub fn compact(&self) -> Result<()> {
        self.compact_l0()
    }

    /// Get column temperatures for monitoring
    pub fn column_temperatures(&self) -> Vec<ColumnTemperature> {
        self.temperature_tracker.get_all_temperatures()
    }

    /// Scan a range of row IDs
    ///
    /// Returns all rows in the range [start, end] from all sources
    /// (memtable, immutable memtables, SSTables)
    #[allow(clippy::type_complexity)]
    pub fn scan_range(
        &self,
        start: RowId,
        end: RowId,
    ) -> Result<Vec<(RowId, Vec<Option<Vec<u8>>>)>> {
        let mut results = Vec::new();
        let mut seen = std::collections::HashSet::new();

        // 1. Scan active memtable
        {
            let memtable = self.active_memtable.read();
            for (row_id, values) in memtable.scan_range(start, end) {
                if seen.insert(row_id) {
                    results.push((row_id, values));
                }
            }
        }

        // 2. Scan immutable memtables
        {
            let immutable = self.immutable_memtables.read();
            for memtable in immutable.iter().rev() {
                for (row_id, values) in memtable.scan_range(start, end) {
                    if seen.insert(row_id) {
                        results.push((row_id, values));
                    }
                }
            }
        }

        // 3. Scan SSTables (would need to iterate over all, using index)
        // For now, focus on memtable access; SSTable scan is more complex

        // Sort by row_id
        results.sort_by_key(|(id, _)| *id);

        Ok(results)
    }

    /// Scan specific columns for a range of row IDs (columnar optimization)
    ///
    /// This achieves 80% I/O reduction when reading 20% of columns
    #[allow(clippy::type_complexity)]
    pub fn scan_columns_range(
        &self,
        start: RowId,
        end: RowId,
        col_indices: &[usize],
    ) -> Result<Vec<(RowId, Vec<Option<Vec<u8>>>)>> {
        let mut results = Vec::new();
        let mut seen = std::collections::HashSet::new();

        // 1. Scan active memtable
        {
            let memtable = self.active_memtable.read();
            let row_ids = memtable.row_ids.read();

            for (&row_id, _) in row_ids.range(start..=end) {
                if seen.insert(row_id)
                    && let Some(values) = memtable.get_columns(row_id, col_indices)
                {
                    results.push((row_id, values));
                }
            }
        }

        // 2. Scan immutable memtables
        {
            let immutable = self.immutable_memtables.read();
            for memtable in immutable.iter().rev() {
                let row_ids = memtable.row_ids.read();
                for (&row_id, _) in row_ids.range(start..=end) {
                    if seen.insert(row_id)
                        && let Some(values) = memtable.get_columns(row_id, col_indices)
                    {
                        results.push((row_id, values));
                    }
                }
            }
        }

        // Sort by row_id
        results.sort_by_key(|(id, _)| *id);

        Ok(results)
    }

    /// Get statistics
    pub fn stats(&self) -> LscsStats {
        let active = self.active_memtable.read();
        let immutable = self.immutable_memtables.read();
        let groups = self.column_groups.read();

        let mut level_sizes = vec![0u64; self.config.num_levels];
        let mut disk_bytes = 0u64;

        for (i, level) in groups.iter().enumerate() {
            for group in level {
                level_sizes[i] += group.row_count;
                // Calculate disk bytes from SST file sizes
                if let Ok(metadata) = std::fs::metadata(&group.path) {
                    disk_bytes += metadata.len();
                }
            }
        }

        LscsStats {
            active_memtable_bytes: active.memory_bytes(),
            immutable_memtables: immutable.len(),
            level_row_counts: level_sizes,
            next_row_id: self.next_row_id.load(Ordering::SeqCst),
            disk_bytes,
        }
    }

    /// Get WAL reference
    pub fn wal(&self) -> &Arc<TxnWal> {
        &self.wal
    }
}

/// LSCS statistics
#[derive(Debug, Clone)]
pub struct LscsStats {
    /// Active memtable memory usage
    pub active_memtable_bytes: usize,
    /// Number of immutable memtables pending flush
    pub immutable_memtables: usize,
    /// Row count per level
    pub level_row_counts: Vec<u64>,
    /// Next row ID to be assigned
    pub next_row_id: u64,
    /// Total disk bytes used by SST files
    pub disk_bytes: u64,
}

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

    fn test_schema() -> TableSchema {
        TableSchema {
            name: "users".to_string(),
            columns: vec![
                ColumnDef {
                    name: "id".to_string(),
                    col_type: ColumnType::UInt64,
                    nullable: false,
                },
                ColumnDef {
                    name: "name".to_string(),
                    col_type: ColumnType::Text,
                    nullable: false,
                },
                ColumnDef {
                    name: "score".to_string(),
                    col_type: ColumnType::Float64,
                    nullable: true,
                },
            ],
        }
    }

    #[test]
    fn test_columnar_memtable_insert() {
        let schema = test_schema();
        let memtable = ColumnarMemtable::new(schema, 1024 * 1024);

        let id: u64 = 1;
        let name = "Alice";
        let score: f64 = 95.5;

        memtable
            .insert(
                1,
                &[
                    Some(&id.to_le_bytes()),
                    Some(name.as_bytes()),
                    Some(&score.to_le_bytes()),
                ],
            )
            .unwrap();

        assert_eq!(memtable.row_count(), 1);
    }

    #[test]
    fn test_columnar_memtable_with_nulls() {
        let schema = test_schema();
        let memtable = ColumnarMemtable::new(schema, 1024 * 1024);

        let id: u64 = 1;
        let name = "Bob";

        // Score is null
        memtable
            .insert(1, &[Some(&id.to_le_bytes()), Some(name.as_bytes()), None])
            .unwrap();

        assert_eq!(memtable.row_count(), 1);
    }

    #[test]
    fn test_lscs_basic() {
        let dir = tempdir().unwrap();
        let schema = test_schema();
        let config = LscsConfig {
            memtable_size: 1024,
            ..Default::default()
        };

        let lscs = Lscs::new(dir.path().to_path_buf(), schema, config).unwrap();

        let id: u64 = 1;
        let name = "Charlie";
        let score: f64 = 87.2;

        let row_id = lscs
            .insert(&[
                Some(&id.to_le_bytes()),
                Some(name.as_bytes()),
                Some(&score.to_le_bytes()),
            ])
            .unwrap();

        assert_eq!(row_id, 1);

        let stats = lscs.stats();
        assert!(stats.active_memtable_bytes > 0);
    }

    #[test]
    fn test_column_group_write() {
        let dir = tempfile::tempdir().unwrap();
        let schema = TableSchema::new(
            "users".to_string(),
            vec![
                ColumnDef {
                    name: "id".to_string(),
                    col_type: ColumnType::UInt64,
                    nullable: false,
                },
                ColumnDef {
                    name: "name".to_string(),
                    col_type: ColumnType::Text,
                    nullable: false,
                },
                ColumnDef {
                    name: "score".to_string(),
                    col_type: ColumnType::Float64,
                    nullable: true,
                },
            ],
        )
        .with_mvcc(); // Add MVCC columns

        let memtable = ColumnarMemtable::new(schema.clone(), 1024 * 1024);

        // Add rows using the public insert API
        // Row 1: Active
        memtable
            .insert(
                1,
                &[
                    Some(&1u64.to_le_bytes()),    // id
                    Some(b"Alice"),               // name
                    Some(&95.5f64.to_le_bytes()), // score
                    Some(&100u64.to_le_bytes()),  // __txn_start
                    Some(&0u64.to_le_bytes()),    // __txn_end
                ],
            )
            .unwrap();

        // Row 2: Deleted
        memtable
            .insert(
                2,
                &[
                    Some(&2u64.to_le_bytes()),    // id
                    Some(b"Bob"),                 // name
                    Some(&87.2f64.to_le_bytes()), // score
                    Some(&100u64.to_le_bytes()),  // __txn_start
                    Some(&200u64.to_le_bytes()),  // __txn_end (deleted at 200)
                ],
            )
            .unwrap();

        let cg = ColumnGroup::from_memtable(dir.path(), &memtable, 0, 1).unwrap();
        let file_path = cg.file_path();
        assert!(file_path.exists());
        assert!(file_path.extension().unwrap() == "sst");

        // Verify we can open it back
        let cg_opened = ColumnGroup::open(file_path.to_path_buf(), schema, 0, 1).unwrap();
        assert_eq!(cg_opened.column_offsets.len(), 5); // 3 user + 2 mvcc

        // Verify LSI is present
        assert!(cg_opened.lsi.is_some());
        let lsi = cg_opened.lsi.as_ref().unwrap();
        assert!(lsi.stats().num_keys > 0);
    }

    #[test]
    fn test_memtable_get() {
        let schema = test_schema();
        let memtable = ColumnarMemtable::new(schema, 1024 * 1024);

        // Insert some rows
        let id1: u64 = 1;
        let name1 = "Alice";
        let score1: f64 = 95.5;
        memtable
            .insert(
                1,
                &[
                    Some(&id1.to_le_bytes()),
                    Some(name1.as_bytes()),
                    Some(&score1.to_le_bytes()),
                ],
            )
            .unwrap();

        let id2: u64 = 2;
        let name2 = "Bob";
        memtable
            .insert(
                2,
                &[
                    Some(&id2.to_le_bytes()),
                    Some(name2.as_bytes()),
                    None, // null score
                ],
            )
            .unwrap();

        // Test get by row ID
        let row1 = memtable.get(1).unwrap();
        assert_eq!(row1.len(), 3);
        assert_eq!(
            u64::from_le_bytes(row1[0].as_ref().unwrap()[..].try_into().unwrap()),
            1
        );
        assert_eq!(
            std::str::from_utf8(row1[1].as_ref().unwrap()).unwrap(),
            "Alice"
        );

        let row2 = memtable.get(2).unwrap();
        assert!(row2[2].is_none()); // null score

        // Test get non-existent row
        assert!(memtable.get(999).is_none());
    }

    #[test]
    fn test_memtable_scan_range() {
        let schema = test_schema();
        let memtable = ColumnarMemtable::new(schema, 1024 * 1024);

        // Insert rows with different row IDs
        for i in 1..=10 {
            memtable
                .insert(
                    i,
                    &[
                        Some(&i.to_le_bytes()),
                        Some(format!("User{}", i).as_bytes()),
                        Some(&((i as f64) * 10.0).to_le_bytes()),
                    ],
                )
                .unwrap();
        }

        // Scan range [3, 7]
        let results = memtable.scan_range(3, 7);
        assert_eq!(results.len(), 5);

        // Verify row IDs are in range
        for (row_id, _) in &results {
            assert!(*row_id >= 3 && *row_id <= 7);
        }
    }

    #[test]
    fn test_lscs_get() {
        let dir = tempdir().unwrap();
        let schema = test_schema();
        let config = LscsConfig {
            memtable_size: 64 * 1024 * 1024,
            ..Default::default()
        };

        let lscs = Lscs::new(dir.path().to_path_buf(), schema, config).unwrap();

        // Insert a row
        let id: u64 = 42;
        let name = "TestUser";
        let score: f64 = 99.9;

        let row_id = lscs
            .insert(&[
                Some(&id.to_le_bytes()),
                Some(name.as_bytes()),
                Some(&score.to_le_bytes()),
            ])
            .unwrap();

        // Get the row back
        let result = lscs.get(row_id).unwrap();
        assert!(result.is_some());

        let values = result.unwrap();
        assert_eq!(
            u64::from_le_bytes(values[0].as_ref().unwrap()[..].try_into().unwrap()),
            42
        );
        assert_eq!(
            std::str::from_utf8(values[1].as_ref().unwrap()).unwrap(),
            "TestUser"
        );
    }

    #[test]
    fn test_lscs_fsync() {
        let dir = tempdir().unwrap();
        let schema = test_schema();
        let config = LscsConfig::default();

        let lscs = Lscs::new(dir.path().to_path_buf(), schema, config).unwrap();

        // Insert some data
        for i in 1..=5 {
            lscs.insert(&[
                Some(&(i as u64).to_le_bytes()),
                Some(format!("User{}", i).as_bytes()),
                Some(&((i as f64) * 10.0).to_le_bytes()),
            ])
            .unwrap();
        }

        // Fsync should not panic
        lscs.fsync().unwrap();

        // Data should still be accessible after fsync
        let result = lscs.get(1).unwrap();
        assert!(result.is_some());
    }

    #[test]
    fn test_temperature_tracker_set_threshold() {
        let cols = vec!["a".to_string(), "b".to_string(), "c".to_string()];
        let tracker = ColumnTemperatureTracker::new(&cols, 10);

        // Default threshold is 0.1
        assert!((tracker.threshold() - 0.1).abs() < f64::EPSILON);

        // set_hot_threshold is no longer a no-op
        tracker.set_hot_threshold(0.5);
        assert!((tracker.threshold() - 0.5).abs() < f64::EPSILON);

        // Clamps to [0, 1]
        tracker.set_hot_threshold(2.0);
        assert!((tracker.threshold() - 1.0).abs() < f64::EPSILON);

        tracker.set_hot_threshold(-0.5);
        assert!((tracker.threshold() - 0.0).abs() < f64::EPSILON);
    }

    #[test]
    fn test_column_temperature_hot_cold_classification() {
        let cols = vec!["hot_col".to_string(), "cold_col".to_string()];
        let tracker = ColumnTemperatureTracker::new(&cols, 2);

        // Lower threshold so that EMA(0.1) > 0.05 qualifies as hot
        tracker.set_hot_threshold(0.05);

        // Update only "hot_col" — triggers EMA after window_size=2 updates
        tracker.record_updates(&["hot_col"]);
        tracker.record_updates(&["hot_col"]);

        let hot = tracker.get_hot_columns();
        let cold = tracker.get_cold_columns();

        // hot_col should be hot (temp = 0.1 × (2/2) + 0.9 × 0 = 0.1 > 0.05)
        assert!(
            hot.contains("hot_col"),
            "hot_col should be classified as hot"
        );
        // cold_col was never updated, temperature=0.0
        assert!(
            cold.contains("cold_col"),
            "cold_col should be classified as cold"
        );
    }
}