opendeviationbar-core 13.78.0

//! Real market data loading for integration testing
//!
//! ## Service Level Objectives (SLOs)
//!
//! ### Availability SLO: 100% file accessibility
//! - Propagate filesystem errors (no fallbacks, no defaults)
//! - Fail fast on missing files with clear error messages
//! - Validation: File existence check before opening
//!
//! ### Correctness SLO: 100% data integrity
//! - Parse all records without data loss or silent failures
//! - Strict schema validation (reject malformed records)
//! - No default values on parse errors (fail-fast)
//! - Validation: Record count = file line count - 1 (header)
//!
//! ### Observability SLO: 100% error traceability
//! - All errors include file path and line number context
//! - Use thiserror for structured error messages
//! - No silent failures or swallowed errors
//!
//! ### Maintainability SLO: Off-the-shelf components only
//! - Use csv crate (de facto Rust standard for CSV parsing)
//! - Use serde for deserialization (no custom parsing)
//! - Zero custom string manipulation or parsing logic
//!
//! ## Data Source
//!
//! - BTCUSDT: `test_data/BTCUSDT/BTCUSDT_aggTrades_20250901.csv` (5,000 trades)
//! - ETHUSDT: `test_data/ETHUSDT/ETHUSDT_aggTrades_20250901.csv` (10,000 trades)
//!
//! ## CSV Format (Binance aggTrades)
//!
//! ```csv
//! a,p,q,f,l,T,m
//! 1,50014.00859087,0.12019569,1,1,1756710002083,False
//! ```
//!
//! Columns:
//! - a: Aggregate trade ID
//! - p: Price (decimal string)
//! - q: Quantity (decimal string)
//! - f: First trade ID
//! - l: Last trade ID
//! - T: Timestamp (milliseconds, integer)
//! - m: Is buyer maker ("True"/"False" string)

use crate::FixedPoint;
use crate::trade::Tick;
use std::path::Path;
use thiserror::Error;

/// Test data loader errors
#[derive(Debug, Error)]
pub enum LoaderError {
    /// File I/O error (propagate without modification)
    #[error("File I/O error for {path}: {source}")]
    Io {
        path: String,
        #[source]
        source: std::io::Error,
    },

    /// CSV parsing error (include line context)
    #[error("CSV parse error at line {line} in {path}: {source}")]
    CsvParse {
        path: String,
        line: usize,
        #[source]
        source: csv::Error,
    },

    /// Fixed-point conversion error
    #[error("Fixed-point conversion error at line {line} in {path}: {source}")]
    FixedPoint {
        path: String,
        line: usize,
        #[source]
        source: crate::fixed_point::FixedPointError,
    },

    /// Record count validation error
    #[error("Record count mismatch in {path}: expected {expected}, got {actual}")]
    CountMismatch {
        path: String,
        expected: usize,
        actual: usize,
    },
}

/// Binance aggTrades CSV record (Spot/Futures format)
///
/// Matches CSV columns: a,p,q,f,l,T,m
#[derive(Debug, serde::Deserialize)]
struct TickRecord {
    /// Aggregate trade ID
    a: i64,
    /// Price (decimal string)
    p: String,
    /// Quantity (decimal string)
    q: String,
    /// First trade ID
    f: i64,
    /// Last trade ID
    l: i64,
    /// Timestamp (milliseconds)
    #[serde(rename = "T")]
    timestamp_ms: i64,
    /// Is buyer maker ("True"/"False" string)
    m: String,
}

impl TickRecord {
    /// Convert CSV record to Tick
    ///
    /// SLO: Fail-fast on parse errors (no defaults, no fallbacks)
    fn into_tick(self) -> Result<Tick, crate::fixed_point::FixedPointError> {
        Ok(Tick {
            ref_id: self.a,
            price: FixedPoint::from_str(&self.p)?,
            volume: FixedPoint::from_str(&self.q)?,
            first_sub_id: self.f,
            last_sub_id: self.l,
            timestamp: self.timestamp_ms,
            is_buyer_maker: self.m == "True",
            is_best_match: None, // Spot data has no best_match field
            best_bid: None,
            best_ask: None,
        })
    }
}

/// Load BTCUSDT test data (5,000 trades from 2025-09-01)
///
/// SLO: Fail-fast on any error, 100% data integrity
///
/// Path resolution: Searches workspace root via CARGO_MANIFEST_DIR
pub fn load_btcusdt_test_data() -> Result<Vec<Tick>, LoaderError> {
    let path = workspace_test_data_path("BTCUSDT/BTCUSDT_aggTrades_20250901.csv");
    load_test_data(path, 5000)
}

/// Load ETHUSDT test data (10,000 trades from 2025-09-01)
///
/// SLO: Fail-fast on any error, 100% data integrity
///
/// Path resolution: Searches workspace root via CARGO_MANIFEST_DIR
pub fn load_ethusdt_test_data() -> Result<Vec<Tick>, LoaderError> {
    let path = workspace_test_data_path("ETHUSDT/ETHUSDT_aggTrades_20250901.csv");
    load_test_data(path, 10000)
}

/// Resolve test_data path from workspace root
///
/// Strategy: Navigate from CARGO_MANIFEST_DIR to workspace root
/// CARGO_MANIFEST_DIR = /path/to/opendeviationbar/crates/opendeviationbar-core
/// Workspace root = ../../ (2 levels up)
fn workspace_test_data_path(relative_path: &str) -> std::path::PathBuf {
    let manifest_dir = env!("CARGO_MANIFEST_DIR");
    let workspace_root = std::path::Path::new(manifest_dir)
        .parent() // crates/
        .unwrap()
        .parent() // workspace root
        .unwrap();

    workspace_root.join("test_data").join(relative_path)
}

/// Resolve tests/fixtures path from workspace root
/// Issue #96: Support real market data fixtures for statistical test accuracy
fn workspace_fixtures_path(relative_path: &str) -> std::path::PathBuf {
    let manifest_dir = env!("CARGO_MANIFEST_DIR");
    let workspace_root = std::path::Path::new(manifest_dir)
        .parent() // crates/
        .unwrap()
        .parent() // workspace root
        .unwrap();

    workspace_root
        .join("tests")
        .join("fixtures")
        .join(relative_path)
}

/// Binance aggTrades CSV record for headerless fixtures (8 columns)
///
/// Issue #96: Real 10K fixture has no header row + includes is_best_match column
/// Columns: agg_trade_id, price, quantity, first_trade_id, last_trade_id, timestamp, is_buyer_maker, is_best_match
#[derive(Debug, serde::Deserialize)]
struct TickRecordHeaderless {
    ref_id: i64,
    price: String,
    quantity: String,
    first_sub_id: i64,
    last_sub_id: i64,
    timestamp: i64,
    is_buyer_maker: String,
    is_best_match: String,
}

impl TickRecordHeaderless {
    fn into_tick(self) -> Result<Tick, crate::fixed_point::FixedPointError> {
        Ok(Tick {
            ref_id: self.ref_id,
            price: FixedPoint::from_str(&self.price)?,
            volume: FixedPoint::from_str(&self.quantity)?,
            first_sub_id: self.first_sub_id,
            last_sub_id: self.last_sub_id,
            timestamp: self.timestamp,
            is_buyer_maker: self.is_buyer_maker == "True",
            is_best_match: Some(self.is_best_match == "True"),
            best_bid: None,
            best_ask: None,
        })
    }
}

/// Load real BTCUSDT 10K trade fixture (10,001 trades from 2024-01-01)
///
/// Issue #96: Provides real market data with natural statistical properties
/// (timestamp clustering, volume skew, directional flow, aggregation density)
/// for tests that require non-degenerate microstructure.
///
/// Source: tests/fixtures/BTCUSDT-aggTrades-sample-10k.csv (headerless, 8 columns)
pub fn load_real_btcusdt_10k() -> Result<Vec<Tick>, LoaderError> {
    let path = workspace_fixtures_path("BTCUSDT-aggTrades-sample-10k.csv");
    load_headerless_data(path, 10001)
}

/// Load real ETHUSDT 10K trade fixture (10,001 aggTrades from Binance Vision spot,
/// day 2025-09-01) — mirror of [`load_real_btcusdt_10k`].
///
/// Source: tests/fixtures/ETHUSDT-aggTrades-sample-10k.csv (headerless, 8 columns,
/// µs timestamps). Committed in PR #607; regenerate via
/// `tests/fixtures/regenerate_aggtrades_samples.sh`.
/// sha256 = `b105e51f63e36be37de9560bd3fe62f64d69beee79de655391871b23da8a0932`.
pub fn load_real_ethusdt_10k() -> Result<Vec<Tick>, LoaderError> {
    let path = workspace_fixtures_path("ETHUSDT-aggTrades-sample-10k.csv");
    load_headerless_data(path, 10001)
}

/// Single-column bar-close fixture record (headerless CSV: one f64 close per line).
#[derive(Debug, serde::Deserialize)]
struct CloseRecord {
    close: f64,
}

#[derive(Debug, serde::Deserialize)]
struct CloseDurRecord {
    close: f64,
    duration_us: f64,
}

/// Load real BTCUSDT bar closes (10,000 closes sourced from ClickHouse).
///
/// Returns the bar-CLOSE series (one f64 per bar), the exact input consumed by
/// the bar-close-rolling features `compute_bar_petrosian_fd` /
/// `compute_bar_katz_fd`.
///
/// Fixture: `tests/fixtures/BTCUSDT-bars-close-sample-10k.csv`
/// (headerless, single column of f64 close prices).
///
/// Provenance — read-only `SELECT` against `opendeviationbar_cache.open_deviation_bars`
/// on bigblack (2026-05-29):
/// ```sql
/// SELECT close FROM opendeviationbar_cache.open_deviation_bars
/// WHERE symbol='BTCUSDT' AND threshold_decimal_bps=250
///   AND close_time_us >= toUnixTimestamp(toDateTime('2024-01-01 00:00:00'))*1000000
/// ORDER BY close_time_us ASC LIMIT 10000 FORMAT CSV
/// ```
/// sha256 = `08725310896db0a87559959c4c719854bb2654787b1e16700c1c5e427194cdad`.
/// Regenerate via `tests/fixtures/regenerate_bar_close_sample.sh`.
///
/// SLO: Fail-fast on any error, 100% data integrity (count-validated to 10,000).
pub fn load_real_btcusdt_bar_closes() -> Result<Vec<f64>, LoaderError> {
    let path = workspace_fixtures_path("BTCUSDT-bars-close-sample-10k.csv");
    load_close_series(path, 10000)
}

/// Load real ETHUSDT bar closes (10,000 closes sourced from ClickHouse).
///
/// The `>= 2-symbol` parity fixture for the bar-close feature oracle gate. ETH's
/// price scale (~2.3k–3.9k) is ~13–18× smaller than BTC's (~42k–67k), so a kernel
/// with a scale- or tick-coupled bug (absolute-magnitude assumptions, lost
/// precision on small increments) diverges on ETH even when it matches on BTC.
/// Every `bar_close` feature's `<=1e-9` oracle runs over BOTH symbols.
///
/// Fixture: `tests/fixtures/ETHUSDT-bars-close-sample-10k.csv`
/// (headerless, single column of f64 close prices).
///
/// Provenance — one-time read-only `SELECT` against
/// `opendeviationbar_cache.open_deviation_bars` on bigblack:
/// ```sql
/// SELECT close FROM opendeviationbar_cache.open_deviation_bars
/// WHERE symbol='ETHUSDT' AND threshold_decimal_bps=250
///   AND close_time_us >= toUnixTimestamp(toDateTime('2024-01-01 00:00:00'))*1000000
/// ORDER BY close_time_us ASC LIMIT 10000 FORMAT CSV
/// ```
/// sha256 = `09060aecc9bef0f5c4f523b3b83b00f0b1e327b123631f121f3db7437f8aa789`.
/// Regenerate via `tests/fixtures/regenerate_eth_bar_close_sample.sh`.
///
/// SLO: Fail-fast on any error, 100% data integrity (count-validated to 10,000).
pub fn load_real_ethusdt_bar_closes() -> Result<Vec<f64>, LoaderError> {
    let path = workspace_fixtures_path("ETHUSDT-bars-close-sample-10k.csv");
    load_close_series(path, 10000)
}

/// Load real BTCUSDT (close, duration_us) bar pairs (10,000 rows from ClickHouse).
///
/// The TWO-substrate fixture for `bar_hoeffding_phi_squared_midreturn_duration`
/// (batch-6 card 78): the first bar_close feature that consumes the bar DURATION
/// (`close_time − open_time`, integer µs — exact in f64) alongside the close.
///
/// Fixture: `tests/fixtures/BTCUSDT-bars-close-dur-sample-10k.csv`
/// (headerless, `close,duration_us` per row).
///
/// Provenance — read-only `SELECT` against `opendeviationbar_cache.open_deviation_bars`
/// on bigblack (2026-07-02):
/// ```sql
/// SELECT close, close_time_us - open_time_us AS duration_us
/// FROM opendeviationbar_cache.open_deviation_bars
/// WHERE symbol='BTCUSDT' AND threshold_decimal_bps=250
///   AND close_time_us >= toUnixTimestamp(toDateTime('2024-01-01 00:00:00'))*1000000
/// ORDER BY close_time_us ASC LIMIT 10000 FORMAT CSV
/// ```
/// sha256 = `26bfea6f887ea114b33f6595bb8bb287d1ddf32df2e73e1a550bd1c4e0985fdd`.
/// SELF-CONTAINED — deliberately NOT row-aligned with the 2026-05-29 close-only
/// fixture (the cache has since been legitimately repaired by kintsugi; the old
/// exact bar set is no longer reproducible). Regenerate via
/// `tests/fixtures/regenerate_bar_close_dur_samples.sh`.
///
/// SLO: Fail-fast on any error, 100% data integrity (count-validated to 10,000).
pub fn load_real_btcusdt_bar_close_durs() -> Result<(Vec<f64>, Vec<f64>), LoaderError> {
    let path = workspace_fixtures_path("BTCUSDT-bars-close-dur-sample-10k.csv");
    load_close_dur_series(path, 10000)
}

/// Load real ETHUSDT (close, duration_us) bar pairs (10,000 rows from ClickHouse).
///
/// The `>= 2-symbol` parity fixture for the card-78 Hoeffding Φ² oracle gate —
/// ETH's smaller price scale catches scale/tick-coupled bugs that match on BTC.
///
/// Fixture: `tests/fixtures/ETHUSDT-bars-close-dur-sample-10k.csv`
/// (headerless, `close,duration_us` per row); same pinned SELECT as the BTC
/// fixture with the symbol swapped, captured 2026-07-02.
/// sha256 = `1627ec312e5023547b106c000dbb005d5bdf2bdbbdc6211aadfa4ec70f024403`.
/// Regenerate via `tests/fixtures/regenerate_bar_close_dur_samples.sh`.
///
/// SLO: Fail-fast on any error, 100% data integrity (count-validated to 10,000).
pub fn load_real_ethusdt_bar_close_durs() -> Result<(Vec<f64>, Vec<f64>), LoaderError> {
    let path = workspace_fixtures_path("ETHUSDT-bars-close-dur-sample-10k.csv");
    load_close_dur_series(path, 10000)
}

/// Dependency-free SHA-256 (FIPS 180-4) for hermetic oracle / golden artifact
/// gates in the test suite — the single implementation shared by the `<=1e-9`
/// oracle tests (locked `ORACLE_SHA256`) and the robustness harness
/// (`GOLDEN_SHA256`). No new crate (nothing for cargo-deny/vet to vet); the loop
/// is hermetic. Returns the lowercase hex digest. Correctness is pinned by the
/// robustness harness's NIST known-vector test.
#[must_use]
pub fn sha256_hex(data: &[u8]) -> String {
    // FIPS 180-4 round constants + working registers use the canonical dense
    // notation; the readability lints do not apply to a standardized primitive.
    #[allow(clippy::unreadable_literal, clippy::many_single_char_names)]
    fn digest(data: &[u8]) -> [u8; 32] {
        const K: [u32; 64] = [
            0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4,
            0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe,
            0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f,
            0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
            0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc,
            0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
            0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116,
            0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
            0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
            0xc67178f2,
        ];
        let mut h: [u32; 8] = [
            0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab,
            0x5be0cd19,
        ];
        let bit_len = (data.len() as u64).wrapping_mul(8);
        let mut msg = data.to_vec();
        msg.push(0x80);
        while msg.len() % 64 != 56 {
            msg.push(0);
        }
        msg.extend_from_slice(&bit_len.to_be_bytes());
        for block in msg.chunks_exact(64) {
            let mut w = [0u32; 64];
            for (i, word) in block.chunks_exact(4).enumerate() {
                w[i] = u32::from_be_bytes([word[0], word[1], word[2], word[3]]);
            }
            for i in 16..64 {
                let s0 = w[i - 15].rotate_right(7) ^ w[i - 15].rotate_right(18) ^ (w[i - 15] >> 3);
                let s1 = w[i - 2].rotate_right(17) ^ w[i - 2].rotate_right(19) ^ (w[i - 2] >> 10);
                w[i] = w[i - 16]
                    .wrapping_add(s0)
                    .wrapping_add(w[i - 7])
                    .wrapping_add(s1);
            }
            let [mut a, mut b, mut c, mut d, mut e, mut f, mut g, mut hh] = h;
            for i in 0..64 {
                let big_s1 = e.rotate_right(6) ^ e.rotate_right(11) ^ e.rotate_right(25);
                let ch = (e & f) ^ ((!e) & g);
                let t1 = hh
                    .wrapping_add(big_s1)
                    .wrapping_add(ch)
                    .wrapping_add(K[i])
                    .wrapping_add(w[i]);
                let big_s0 = a.rotate_right(2) ^ a.rotate_right(13) ^ a.rotate_right(22);
                let maj = (a & b) ^ (a & c) ^ (b & c);
                let t2 = big_s0.wrapping_add(maj);
                hh = g;
                g = f;
                f = e;
                e = d.wrapping_add(t1);
                d = c;
                c = b;
                b = a;
                a = t1.wrapping_add(t2);
            }
            for (slot, v) in h.iter_mut().zip([a, b, c, d, e, f, g, hh]) {
                *slot = slot.wrapping_add(v);
            }
        }
        let mut out = [0u8; 32];
        for (i, word) in h.iter().enumerate() {
            out[i * 4..i * 4 + 4].copy_from_slice(&word.to_be_bytes());
        }
        out
    }

    const HEX: &[u8; 16] = b"0123456789abcdef";
    let mut s = String::with_capacity(64);
    for byte in digest(data) {
        s.push(HEX[(byte >> 4) as usize] as char);
        s.push(HEX[(byte & 0x0f) as usize] as char);
    }
    s
}

/// Generic headerless single-column close-series loader with record count validation.
fn load_close_series<P: AsRef<Path>>(
    path: P,
    expected_count: usize,
) -> Result<Vec<f64>, LoaderError> {
    let path_str = path.as_ref().to_string_lossy().to_string();

    let file = std::fs::File::open(&path).map_err(|e| LoaderError::Io {
        path: path_str.clone(),
        source: e,
    })?;

    let csv_buffer_size = (expected_count * 16).max(64 * 1024).min(2 * 1024 * 1024);

    let mut reader = csv::ReaderBuilder::new()
        .has_headers(false)
        .buffer_capacity(csv_buffer_size)
        .from_reader(file);

    let mut closes = Vec::with_capacity(expected_count);

    for (line, result) in (1..).zip(reader.deserialize()) {
        let record: CloseRecord = result.map_err(|e| LoaderError::CsvParse {
            path: path_str.clone(),
            line,
            source: e,
        })?;
        closes.push(record.close);
    }

    let actual_count = closes.len();
    if actual_count != expected_count {
        return Err(LoaderError::CountMismatch {
            path: path_str,
            expected: expected_count,
            actual: actual_count,
        });
    }

    Ok(closes)
}

/// Shared loader for the two-column `close,duration_us` fixtures (card 78).
/// Same fail-fast contract as [`load_close_series`]; returns the two aligned
/// series `(closes, durations_us)`.
fn load_close_dur_series<P: AsRef<Path>>(
    path: P,
    expected_count: usize,
) -> Result<(Vec<f64>, Vec<f64>), LoaderError> {
    let path_str = path.as_ref().to_string_lossy().to_string();

    let file = std::fs::File::open(&path).map_err(|e| LoaderError::Io {
        path: path_str.clone(),
        source: e,
    })?;

    let csv_buffer_size = (expected_count * 32).max(64 * 1024).min(2 * 1024 * 1024);

    let mut reader = csv::ReaderBuilder::new()
        .has_headers(false)
        .buffer_capacity(csv_buffer_size)
        .from_reader(file);

    let mut closes = Vec::with_capacity(expected_count);
    let mut durations = Vec::with_capacity(expected_count);

    for (line, result) in (1..).zip(reader.deserialize()) {
        let record: CloseDurRecord = result.map_err(|e| LoaderError::CsvParse {
            path: path_str.clone(),
            line,
            source: e,
        })?;
        closes.push(record.close);
        durations.push(record.duration_us);
    }

    let actual_count = closes.len();
    if actual_count != expected_count {
        return Err(LoaderError::CountMismatch {
            path: path_str,
            expected: expected_count,
            actual: actual_count,
        });
    }

    Ok((closes, durations))
}

/// Generic headerless CSV loader with record count validation
///
/// Issue #96: For fixture files without header rows (positional column mapping)
fn load_headerless_data<P: AsRef<Path>>(
    path: P,
    expected_count: usize,
) -> Result<Vec<Tick>, LoaderError> {
    let path_str = path.as_ref().to_string_lossy().to_string();

    let file = std::fs::File::open(&path).map_err(|e| LoaderError::Io {
        path: path_str.clone(),
        source: e,
    })?;

    let csv_buffer_size = (expected_count * 100).max(64 * 1024).min(2 * 1024 * 1024);

    let mut reader = csv::ReaderBuilder::new()
        .has_headers(false)
        .buffer_capacity(csv_buffer_size)
        .from_reader(file);

    let mut trades = Vec::with_capacity(expected_count);

    for (line, result) in (1..).zip(reader.deserialize()) {
        let record: TickRecordHeaderless = result.map_err(|e| LoaderError::CsvParse {
            path: path_str.clone(),
            line,
            source: e,
        })?;

        let trade = record.into_tick().map_err(|e| LoaderError::FixedPoint {
            path: path_str.clone(),
            line,
            source: e,
        })?;

        trades.push(trade);
    }

    let actual_count = trades.len();
    if actual_count != expected_count {
        return Err(LoaderError::CountMismatch {
            path: path_str,
            expected: expected_count,
            actual: actual_count,
        });
    }

    Ok(trades)
}

/// Generic CSV loader with record count validation
///
/// SLO Guarantees:
/// - Availability: Propagates I/O errors without fallbacks
/// - Correctness: Validates record count matches expected_count
/// - Observability: All errors include file path and line number
/// - Maintainability: Uses csv crate (no custom parsing)
fn load_test_data<P: AsRef<Path>>(
    path: P,
    expected_count: usize,
) -> Result<Vec<Tick>, LoaderError> {
    let path_str = path.as_ref().to_string_lossy().to_string();

    // SLO: Availability - Propagate I/O errors with context
    let file = std::fs::File::open(&path).map_err(|e| LoaderError::Io {
        path: path_str.clone(),
        source: e,
    })?;

    // Issue #96 Task #74: Pre-size CSV reader buffer based on record count (1-3% speedup)
    // Typical Tick record is ~50-80 bytes, so buffer = expected_count * 100 bytes
    // Minimum 64KB (default), maximum 2MB
    let csv_buffer_size = (expected_count * 100).max(64 * 1024).min(2 * 1024 * 1024);

    // SLO: Maintainability - Use csv crate (off-the-shelf)
    let mut reader = csv::ReaderBuilder::new()
        .has_headers(true)
        .buffer_capacity(csv_buffer_size)
        .from_reader(file);

    let mut trades = Vec::with_capacity(expected_count);
    // SLO: Correctness - Strict parsing, no silent failures
    // Line numbering starts at 2 (line 1 is the CSV header).
    for (line, result) in (2..).zip(reader.deserialize()) {
        let record: TickRecord = result.map_err(|e| LoaderError::CsvParse {
            path: path_str.clone(),
            line,
            source: e,
        })?;

        let trade = record.into_tick().map_err(|e| LoaderError::FixedPoint {
            path: path_str.clone(),
            line,
            source: e,
        })?;

        trades.push(trade);
    }

    // SLO: Correctness - Validate record count (detect truncation/corruption)
    let actual_count = trades.len();
    if actual_count != expected_count {
        return Err(LoaderError::CountMismatch {
            path: path_str,
            expected: expected_count,
            actual: actual_count,
        });
    }

    Ok(trades)
}

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

    #[test]
    fn test_load_btcusdt_data() {
        let trades = load_btcusdt_test_data().expect("Failed to load BTCUSDT test data");

        // SLO: Correctness - Validate record count
        assert_eq!(
            trades.len(),
            5000,
            "BTCUSDT should have exactly 5000 trades"
        );

        // SLO: Correctness - Validate first trade data integrity
        let first = &trades[0];
        assert_eq!(first.ref_id, 1);
        assert_eq!(first.price.to_string(), "50014.00859087");
        assert_eq!(first.volume.to_string(), "0.12019569");
        assert_eq!(first.first_sub_id, 1);
        assert_eq!(first.last_sub_id, 1);
        assert_eq!(first.timestamp, 1756710002083);
        assert!(!first.is_buyer_maker);
    }

    #[test]
    fn test_load_ethusdt_data() {
        let trades = load_ethusdt_test_data().expect("Failed to load ETHUSDT test data");

        // SLO: Correctness - Validate record count
        assert_eq!(
            trades.len(),
            10000,
            "ETHUSDT should have exactly 10000 trades"
        );

        // SLO: Correctness - All trades should have valid data
        for trade in &trades {
            assert!(trade.price.0 > 0, "Price must be positive");
            assert!(trade.volume.0 > 0, "Volume must be positive");
            assert!(trade.timestamp > 0, "Timestamp must be positive");
        }
    }

    #[test]
    fn test_temporal_integrity() {
        let trades = load_btcusdt_test_data().unwrap();

        // SLO: Correctness - Validate monotonic timestamps
        for i in 1..trades.len() {
            assert!(
                trades[i].timestamp >= trades[i - 1].timestamp,
                "Temporal integrity violation at trade {}: {} < {}",
                i,
                trades[i].timestamp,
                trades[i - 1].timestamp
            );
        }
    }
}