hyper_risk/

risk_defaults.rs

use serde::{Deserialize, Serialize};

use hyper_ta::Candle;
use hyper_ta::TechnicalIndicators;

// ---------------------------------------------------------------------------
// #215 — Per-category SL/TP Defaults
// ---------------------------------------------------------------------------

/// The type of stop-loss calculation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SlType {
    /// Stop is ATR-multiple based.
    Atr,
    /// Stop is a fixed percentage of entry price.
    Percent,
}

/// Per-category risk defaults for SL, TP, and trailing-stop parameters.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RiskDefaults {
    pub category: String,
    pub sl_type: SlType,
    /// Multiplier applied to ATR (or percentage value for `Percent` type).
    pub sl_mult: f64,
    /// Take-profit multiplier (ATR multiples or percentage).
    pub tp_mult: f64,
    /// Whether trailing stop is enabled for this category.
    pub trailing: bool,
    /// Trailing-stop ATR multiplier (only meaningful when `trailing == true`).
    pub trailing_mult: f64,
}

/// Look up the risk defaults for the given strategy category.
///
/// Unknown categories fall back to a conservative default
/// (ATR-based, SL 2.0, TP 3.0, no trailing).
pub fn get_risk_defaults(category: &str) -> RiskDefaults {
    match category {
        "trend_following" => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Atr,
            sl_mult: 2.0,
            tp_mult: 4.0,
            trailing: true,
            trailing_mult: 3.0,
        },
        "momentum" => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Atr,
            sl_mult: 1.5,
            tp_mult: 3.0,
            trailing: false,
            trailing_mult: 0.0,
        },
        "mean_reversion" => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Atr,
            sl_mult: 1.0,
            tp_mult: 1.5,
            trailing: false,
            trailing_mult: 0.0,
        },
        "volatility" => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Atr,
            sl_mult: 2.0,
            tp_mult: 3.5,
            trailing: false,
            trailing_mult: 0.0,
        },
        "stat_arb" => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Percent,
            sl_mult: 2.0,
            tp_mult: 3.0,
            trailing: false,
            trailing_mult: 0.0,
        },
        "onchain" => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Atr,
            sl_mult: 1.5,
            tp_mult: 2.5,
            trailing: false,
            trailing_mult: 0.0,
        },
        "factor" => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Atr,
            sl_mult: 1.5,
            tp_mult: 3.0,
            trailing: false,
            trailing_mult: 0.0,
        },
        "execution" => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Percent,
            sl_mult: 1.0,
            tp_mult: 2.0,
            trailing: false,
            trailing_mult: 0.0,
        },
        "snr" => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Atr,
            sl_mult: 1.5,
            tp_mult: 2.5,
            trailing: false,
            trailing_mult: 0.0,
        },
        "composite" => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Atr,
            sl_mult: 2.0,
            tp_mult: 4.0,
            trailing: true,
            trailing_mult: 3.0,
        },
        // Unknown category — conservative fallback
        _ => RiskDefaults {
            category: category.to_string(),
            sl_type: SlType::Atr,
            sl_mult: 2.0,
            tp_mult: 3.0,
            trailing: false,
            trailing_mult: 0.0,
        },
    }
}

// ---------------------------------------------------------------------------
// #216 — Dynamic Position Sizing
// ---------------------------------------------------------------------------

/// Return the base position percentage for the given strategy category.
///
/// Values are expressed as fractions (0.0–1.0).
pub fn base_position_pct(category: &str) -> f64 {
    match category {
        "trend_following" => 0.60,
        "mean_reversion" => 0.30,
        "momentum" => 0.50,
        "volatility" => 0.40,
        "stat_arb" => 0.20,
        "onchain" => 0.40,
        "factor" => 0.30,
        "execution" => 0.15,
        "snr" => 0.40,
        "composite" => 0.50,
        _ => 0.25, // conservative fallback
    }
}

/// Compute a suggested position size as a percentage of total capital.
///
/// `signal_strength` is expected in 0.0–1.0.
/// Returns a value in 0.0–1.0 (fraction of capital).
pub fn suggested_qty_pct(category: &str, signal_strength: f64) -> f64 {
    let base = base_position_pct(category);
    let clamped_strength = signal_strength.clamp(0.0, 1.0);
    base * clamped_strength
}

// ---------------------------------------------------------------------------
// #217 — Trailing Stop State Management
// ---------------------------------------------------------------------------

/// Direction of the trailing stop (tracks position side).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TrailingDirection {
    Long,
    Short,
}

/// State for a trailing stop attached to an open position.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TrailingStopState {
    pub highest_since_entry: f64,
    pub lowest_since_entry: f64,
    pub current_stop: f64,
    pub direction: TrailingDirection,
    pub active: bool,
}

impl TrailingStopState {
    /// Create a new trailing stop state at the given entry price.
    pub fn new(entry_price: f64, direction: TrailingDirection) -> Self {
        Self {
            highest_since_entry: entry_price,
            lowest_since_entry: entry_price,
            current_stop: 0.0, // will be set on first update
            direction,
            active: true,
        }
    }

    /// Update the trailing stop with the latest price and ATR.
    ///
    /// For longs:  track highest, stop = highest − multiplier × ATR
    /// For shorts: track lowest,  stop = lowest  + multiplier × ATR
    pub fn update(&mut self, current_price: f64, atr: f64, multiplier: f64) {
        if !self.active {
            return;
        }

        match self.direction {
            TrailingDirection::Long => {
                if current_price > self.highest_since_entry {
                    self.highest_since_entry = current_price;
                }
                let new_stop = self.highest_since_entry - multiplier * atr;
                // Only ratchet the stop upward
                if new_stop > self.current_stop {
                    self.current_stop = new_stop;
                }
            }
            TrailingDirection::Short => {
                if current_price < self.lowest_since_entry {
                    self.lowest_since_entry = current_price;
                }
                let new_stop = self.lowest_since_entry + multiplier * atr;
                // Only ratchet the stop downward (for shorts, lower stop = tighter)
                if self.current_stop == 0.0 || new_stop < self.current_stop {
                    self.current_stop = new_stop;
                }
            }
        }
    }

    /// Check whether the trailing stop has been triggered.
    pub fn is_triggered(&self, current_price: f64) -> bool {
        if !self.active || self.current_stop == 0.0 {
            return false;
        }

        match self.direction {
            TrailingDirection::Long => current_price <= self.current_stop,
            TrailingDirection::Short => current_price >= self.current_stop,
        }
    }
}

// ---------------------------------------------------------------------------
// #218 — ADX Regime Filter for Mean Reversion
// ---------------------------------------------------------------------------

/// Apply ADX-based filtering to a mean-reversion signal.
///
/// - ADX > 30  → suppress completely (return 0.0)
/// - ADX 25–30 → reduce by 50% (return strength × 0.5)
/// - ADX < 25  → pass through unchanged
/// - ADX unavailable (None) → pass through unchanged
pub fn apply_adx_filter(signal_strength: f64, adx: Option<f64>) -> f64 {
    match adx {
        Some(v) if v > 30.0 => 0.0,
        Some(v) if v >= 25.0 => signal_strength * 0.5,
        _ => signal_strength,
    }
}

// ---------------------------------------------------------------------------
// #219 — Volume Context Analysis
// ---------------------------------------------------------------------------

/// Classified volume context for the current market state.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum VolumeContext {
    /// High volume + with-trend price move: trend likely continues.
    TrendContinuation,
    /// Volume spike + counter-trend / reversal candle: exhaustion.
    ClimaxExhaustion,
    /// Volume spike + RSI extreme + reversal: reversal confirmed.
    ReversalConfirm,
    /// Very large volume spike + ADX breakout: regime changing.
    RegimeChange,
    /// No noteworthy volume pattern.
    Normal,
}

/// Analyse volume context using candles and technical indicators.
///
/// Classification logic (evaluated in priority order):
///
/// 1. `volume_zscore > 3.0` AND `adx > 25` AND ADX rising → `RegimeChange`
/// 2. `volume_zscore > 2.0` AND RSI extreme (>70 or <30) AND reversal candle → `ReversalConfirm`
/// 3. `volume_zscore > 2.0` AND counter-trend candle → `ClimaxExhaustion`
/// 4. `volume_zscore > 2.0` AND with-trend candle → `TrendContinuation`
/// 5. Otherwise → `Normal`
pub fn analyze_volume_context(
    candles: &[Candle],
    indicators: &TechnicalIndicators,
) -> VolumeContext {
    let vol_zscore = match indicators.volume_zscore_20 {
        Some(z) => z,
        None => return VolumeContext::Normal,
    };

    // Need at least 2 candles for trend/reversal detection
    if candles.len() < 2 {
        return VolumeContext::Normal;
    }

    let last = &candles[candles.len() - 1];
    let prev = &candles[candles.len() - 2];

    // Determine price direction of the latest candle
    let candle_bullish = last.close > last.open;
    let candle_bearish = last.close < last.open;

    // Simple trend proxy: previous close vs two bars ago close
    let trend_up = last.close > prev.close;

    // A "reversal candle" is one that moves against the prior trend
    let is_reversal = (trend_up && candle_bearish) || (!trend_up && candle_bullish);

    // With-trend: candle direction aligns with recent trend
    let is_with_trend = (trend_up && candle_bullish) || (!trend_up && candle_bearish);

    // 1. RegimeChange: very large spike + ADX breakout
    if vol_zscore > 3.0 {
        if let Some(adx) = indicators.adx_14 {
            if adx > 25.0 {
                return VolumeContext::RegimeChange;
            }
        }
    }

    // 2. ReversalConfirm: volume spike + RSI extreme + reversal candle
    if vol_zscore > 2.0 {
        if let Some(rsi) = indicators.rsi_14 {
            if (rsi > 70.0 || rsi < 30.0) && is_reversal {
                return VolumeContext::ReversalConfirm;
            }
        }
    }

    // 3. ClimaxExhaustion: volume spike + against-trend
    if vol_zscore > 2.0 && is_reversal {
        return VolumeContext::ClimaxExhaustion;
    }

    // 4. TrendContinuation: volume spike + with-trend
    if vol_zscore > 2.0 && is_with_trend {
        return VolumeContext::TrendContinuation;
    }

    VolumeContext::Normal
}

/// Return a strength modifier for a given volume context and strategy category.
///
/// Values > 1.0 amplify the signal; values < 1.0 dampen it.
pub fn volume_strength_modifier(context: &VolumeContext, category: &str) -> f64 {
    match context {
        VolumeContext::TrendContinuation => {
            match category {
                "trend_following" | "composite" => 1.3,
                "momentum" => 1.2,
                "mean_reversion" => 0.7, // continuation is bad for MR
                _ => 1.1,
            }
        }
        VolumeContext::ClimaxExhaustion => {
            match category {
                "trend_following" | "momentum" => 0.5, // exhaustion dampens trend signals
                "mean_reversion" => 1.3,               // exhaustion supports MR
                _ => 0.8,
            }
        }
        VolumeContext::ReversalConfirm => {
            match category {
                "mean_reversion" => 1.5, // strong confirmation for MR
                "trend_following" => 0.4,
                "momentum" => 0.5,
                _ => 1.0,
            }
        }
        VolumeContext::RegimeChange => {
            match category {
                "volatility" => 1.4,
                "trend_following" | "composite" => 1.2,
                "mean_reversion" | "stat_arb" => 0.3, // regime change is risky for MR/arb
                "execution" => 0.5,
                _ => 0.8,
            }
        }
        VolumeContext::Normal => 1.0,
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    // -----------------------------------------------------------------------
    // #215 — Risk Defaults
    // -----------------------------------------------------------------------

    #[test]
    fn test_risk_defaults_trend_following() {
        let d = get_risk_defaults("trend_following");
        assert_eq!(d.sl_type, SlType::Atr);
        assert_eq!(d.sl_mult, 2.0);
        assert_eq!(d.tp_mult, 4.0);
        assert!(d.trailing);
        assert_eq!(d.trailing_mult, 3.0);
    }

    #[test]
    fn test_risk_defaults_momentum() {
        let d = get_risk_defaults("momentum");
        assert_eq!(d.sl_type, SlType::Atr);
        assert_eq!(d.sl_mult, 1.5);
        assert_eq!(d.tp_mult, 3.0);
        assert!(!d.trailing);
    }

    #[test]
    fn test_risk_defaults_mean_reversion() {
        let d = get_risk_defaults("mean_reversion");
        assert_eq!(d.sl_type, SlType::Atr);
        assert_eq!(d.sl_mult, 1.0);
        assert_eq!(d.tp_mult, 1.5);
        assert!(!d.trailing);
    }

    #[test]
    fn test_risk_defaults_stat_arb_uses_percent() {
        let d = get_risk_defaults("stat_arb");
        assert_eq!(d.sl_type, SlType::Percent);
        assert_eq!(d.sl_mult, 2.0);
        assert_eq!(d.tp_mult, 3.0);
    }

    #[test]
    fn test_risk_defaults_execution_uses_percent() {
        let d = get_risk_defaults("execution");
        assert_eq!(d.sl_type, SlType::Percent);
        assert_eq!(d.sl_mult, 1.0);
        assert_eq!(d.tp_mult, 2.0);
    }

    #[test]
    fn test_risk_defaults_composite_has_trailing() {
        let d = get_risk_defaults("composite");
        assert!(d.trailing);
        assert_eq!(d.trailing_mult, 3.0);
    }

    #[test]
    fn test_risk_defaults_unknown_category_fallback() {
        let d = get_risk_defaults("unknown_strategy_xyz");
        assert_eq!(d.sl_type, SlType::Atr);
        assert_eq!(d.sl_mult, 2.0);
        assert_eq!(d.tp_mult, 3.0);
        assert!(!d.trailing);
        assert_eq!(d.category, "unknown_strategy_xyz");
    }

    #[test]
    fn test_risk_defaults_all_categories() {
        let categories = [
            "trend_following",
            "momentum",
            "mean_reversion",
            "volatility",
            "stat_arb",
            "onchain",
            "factor",
            "execution",
            "snr",
            "composite",
        ];
        for cat in &categories {
            let d = get_risk_defaults(cat);
            assert_eq!(d.category, *cat);
            assert!(d.sl_mult > 0.0);
            assert!(d.tp_mult > 0.0);
        }
    }

    #[test]
    fn test_risk_defaults_serialization_roundtrip() {
        let d = get_risk_defaults("trend_following");
        let json = serde_json::to_string(&d).unwrap();
        let parsed: RiskDefaults = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.sl_type, d.sl_type);
        assert_eq!(parsed.sl_mult, d.sl_mult);
        assert_eq!(parsed.trailing, d.trailing);
    }

    // -----------------------------------------------------------------------
    // #216 — Dynamic Position Sizing
    // -----------------------------------------------------------------------

    #[test]
    fn test_base_position_pct_known_categories() {
        assert_eq!(base_position_pct("trend_following"), 0.60);
        assert_eq!(base_position_pct("mean_reversion"), 0.30);
        assert_eq!(base_position_pct("momentum"), 0.50);
        assert_eq!(base_position_pct("execution"), 0.15);
    }

    #[test]
    fn test_base_position_pct_unknown_category() {
        assert_eq!(base_position_pct("unknown"), 0.25);
    }

    #[test]
    fn test_suggested_qty_pct_full_strength() {
        let pct = suggested_qty_pct("trend_following", 1.0);
        assert!((pct - 0.60).abs() < 1e-10);
    }

    #[test]
    fn test_suggested_qty_pct_half_strength() {
        let pct = suggested_qty_pct("trend_following", 0.5);
        assert!((pct - 0.30).abs() < 1e-10);
    }

    #[test]
    fn test_suggested_qty_pct_zero_strength() {
        let pct = suggested_qty_pct("momentum", 0.0);
        assert_eq!(pct, 0.0);
    }

    #[test]
    fn test_suggested_qty_pct_clamps_above_one() {
        let pct = suggested_qty_pct("momentum", 1.5);
        // Should clamp to 1.0, so base * 1.0 = 0.50
        assert!((pct - 0.50).abs() < 1e-10);
    }

    #[test]
    fn test_suggested_qty_pct_clamps_negative() {
        let pct = suggested_qty_pct("momentum", -0.3);
        assert_eq!(pct, 0.0);
    }

    // -----------------------------------------------------------------------
    // #217 — Trailing Stop State Management
    // -----------------------------------------------------------------------

    #[test]
    fn test_trailing_stop_new_long() {
        let ts = TrailingStopState::new(100.0, TrailingDirection::Long);
        assert_eq!(ts.highest_since_entry, 100.0);
        assert_eq!(ts.lowest_since_entry, 100.0);
        assert_eq!(ts.current_stop, 0.0);
        assert!(ts.active);
    }

    #[test]
    fn test_trailing_stop_long_update_raises_stop() {
        let mut ts = TrailingStopState::new(100.0, TrailingDirection::Long);
        // ATR = 2.0, multiplier = 3.0 → stop = 100 - 6 = 94
        ts.update(100.0, 2.0, 3.0);
        assert_eq!(ts.current_stop, 94.0);

        // Price rises to 110 → stop = 110 - 6 = 104
        ts.update(110.0, 2.0, 3.0);
        assert_eq!(ts.highest_since_entry, 110.0);
        assert_eq!(ts.current_stop, 104.0);

        // Price drops back to 105 → stop should NOT decrease
        ts.update(105.0, 2.0, 3.0);
        assert_eq!(ts.current_stop, 104.0);
    }

    #[test]
    fn test_trailing_stop_long_triggered() {
        let mut ts = TrailingStopState::new(100.0, TrailingDirection::Long);
        ts.update(100.0, 2.0, 3.0); // stop = 94
        assert!(!ts.is_triggered(95.0));
        assert!(ts.is_triggered(94.0));
        assert!(ts.is_triggered(90.0));
    }

    #[test]
    fn test_trailing_stop_short_update_lowers_stop() {
        let mut ts = TrailingStopState::new(100.0, TrailingDirection::Short);
        // ATR = 2.0, multiplier = 3.0 → stop = 100 + 6 = 106
        ts.update(100.0, 2.0, 3.0);
        assert_eq!(ts.current_stop, 106.0);

        // Price drops to 90 → stop = 90 + 6 = 96
        ts.update(90.0, 2.0, 3.0);
        assert_eq!(ts.lowest_since_entry, 90.0);
        assert_eq!(ts.current_stop, 96.0);

        // Price rises to 95 → stop should NOT increase (ratchet down only)
        ts.update(95.0, 2.0, 3.0);
        assert_eq!(ts.current_stop, 96.0);
    }

    #[test]
    fn test_trailing_stop_short_triggered() {
        let mut ts = TrailingStopState::new(100.0, TrailingDirection::Short);
        ts.update(100.0, 2.0, 3.0); // stop = 106
        assert!(!ts.is_triggered(105.0));
        assert!(ts.is_triggered(106.0));
        assert!(ts.is_triggered(110.0));
    }

    #[test]
    fn test_trailing_stop_inactive_does_not_update() {
        let mut ts = TrailingStopState::new(100.0, TrailingDirection::Long);
        ts.active = false;
        ts.update(200.0, 2.0, 3.0);
        assert_eq!(ts.current_stop, 0.0);
        assert_eq!(ts.highest_since_entry, 100.0);
    }

    #[test]
    fn test_trailing_stop_inactive_not_triggered() {
        let mut ts = TrailingStopState::new(100.0, TrailingDirection::Long);
        ts.update(100.0, 2.0, 3.0); // stop = 94
        ts.active = false;
        assert!(!ts.is_triggered(50.0));
    }

    #[test]
    fn test_trailing_stop_zero_stop_not_triggered() {
        let ts = TrailingStopState::new(100.0, TrailingDirection::Long);
        // current_stop is 0.0 (never updated)
        assert!(!ts.is_triggered(0.0));
    }

    #[test]
    fn test_trailing_stop_serialization_roundtrip() {
        let mut ts = TrailingStopState::new(100.0, TrailingDirection::Long);
        ts.update(105.0, 2.0, 3.0);
        let json = serde_json::to_string(&ts).unwrap();
        let parsed: TrailingStopState = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.highest_since_entry, 105.0);
        assert_eq!(parsed.current_stop, ts.current_stop);
        assert_eq!(parsed.direction, TrailingDirection::Long);
    }

    // -----------------------------------------------------------------------
    // #218 — ADX Regime Filter
    // -----------------------------------------------------------------------

    #[test]
    fn test_adx_filter_suppress_high_adx() {
        assert_eq!(apply_adx_filter(0.8, Some(35.0)), 0.0);
        assert_eq!(apply_adx_filter(1.0, Some(30.1)), 0.0);
    }

    #[test]
    fn test_adx_filter_reduce_medium_adx() {
        let result = apply_adx_filter(0.8, Some(27.0));
        assert!((result - 0.4).abs() < 1e-10);
    }

    #[test]
    fn test_adx_filter_boundary_25() {
        let result = apply_adx_filter(1.0, Some(25.0));
        assert!((result - 0.5).abs() < 1e-10);
    }

    #[test]
    fn test_adx_filter_boundary_30() {
        // ADX = 30.0 is >= 25.0 and not > 30.0, so it's in the 25-30 bucket
        let result = apply_adx_filter(1.0, Some(30.0));
        assert!((result - 0.5).abs() < 1e-10);
    }

    #[test]
    fn test_adx_filter_low_adx_passthrough() {
        assert_eq!(apply_adx_filter(0.8, Some(20.0)), 0.8);
        assert_eq!(apply_adx_filter(0.8, Some(24.9)), 0.8);
    }

    #[test]
    fn test_adx_filter_none_passthrough() {
        assert_eq!(apply_adx_filter(0.8, None), 0.8);
    }

    #[test]
    fn test_adx_filter_zero_strength() {
        assert_eq!(apply_adx_filter(0.0, Some(27.0)), 0.0);
    }

    // -----------------------------------------------------------------------
    // #219 — Volume Context Analysis
    // -----------------------------------------------------------------------

    fn make_candle(open: f64, close: f64, high: f64, low: f64, volume: f64) -> Candle {
        Candle {
            time: 0,
            open,
            high,
            low,
            close,
            volume,
        }
    }

    fn make_indicators(overrides: impl FnOnce(&mut TechnicalIndicators)) -> TechnicalIndicators {
        let mut ind = TechnicalIndicators::empty();
        overrides(&mut ind);
        ind
    }

    #[test]
    fn test_volume_context_normal_no_spike() {
        let candles = vec![
            make_candle(100.0, 101.0, 102.0, 99.0, 1000.0),
            make_candle(101.0, 102.0, 103.0, 100.0, 1100.0),
        ];
        let ind = make_indicators(|i| i.volume_zscore_20 = Some(0.5));
        assert_eq!(
            analyze_volume_context(&candles, &ind),
            VolumeContext::Normal
        );
    }

    #[test]
    fn test_volume_context_trend_continuation() {
        // Uptrend (close > prev close) + bullish candle + volume spike
        let candles = vec![
            make_candle(100.0, 101.0, 102.0, 99.0, 1000.0),
            make_candle(101.0, 105.0, 106.0, 100.0, 5000.0),
        ];
        let ind = make_indicators(|i| i.volume_zscore_20 = Some(2.5));
        assert_eq!(
            analyze_volume_context(&candles, &ind),
            VolumeContext::TrendContinuation
        );
    }

    #[test]
    fn test_volume_context_climax_exhaustion() {
        // Uptrend (close > prev close) but bearish candle (reversal) + volume spike
        // No RSI extreme → ClimaxExhaustion (not ReversalConfirm)
        let candles = vec![
            make_candle(100.0, 101.0, 102.0, 99.0, 1000.0),
            make_candle(105.0, 102.0, 106.0, 101.0, 5000.0), // bearish reversal
        ];
        let ind = make_indicators(|i| {
            i.volume_zscore_20 = Some(2.5);
            i.rsi_14 = Some(55.0); // not extreme
        });
        assert_eq!(
            analyze_volume_context(&candles, &ind),
            VolumeContext::ClimaxExhaustion
        );
    }

    #[test]
    fn test_volume_context_reversal_confirm() {
        // Uptrend + bearish candle + RSI overbought + volume spike
        let candles = vec![
            make_candle(100.0, 101.0, 102.0, 99.0, 1000.0),
            make_candle(105.0, 102.0, 106.0, 101.0, 5000.0), // bearish reversal
        ];
        let ind = make_indicators(|i| {
            i.volume_zscore_20 = Some(2.5);
            i.rsi_14 = Some(75.0); // overbought
        });
        assert_eq!(
            analyze_volume_context(&candles, &ind),
            VolumeContext::ReversalConfirm
        );
    }

    #[test]
    fn test_volume_context_regime_change() {
        let candles = vec![
            make_candle(100.0, 101.0, 102.0, 99.0, 1000.0),
            make_candle(101.0, 105.0, 106.0, 100.0, 10000.0),
        ];
        let ind = make_indicators(|i| {
            i.volume_zscore_20 = Some(3.5);
            i.adx_14 = Some(30.0); // > 25
        });
        assert_eq!(
            analyze_volume_context(&candles, &ind),
            VolumeContext::RegimeChange
        );
    }

    #[test]
    fn test_volume_context_no_zscore_returns_normal() {
        let candles = vec![
            make_candle(100.0, 101.0, 102.0, 99.0, 1000.0),
            make_candle(101.0, 105.0, 106.0, 100.0, 5000.0),
        ];
        let ind = TechnicalIndicators::empty();
        assert_eq!(
            analyze_volume_context(&candles, &ind),
            VolumeContext::Normal
        );
    }

    #[test]
    fn test_volume_context_insufficient_candles() {
        let candles = vec![make_candle(100.0, 101.0, 102.0, 99.0, 1000.0)];
        let ind = make_indicators(|i| i.volume_zscore_20 = Some(3.0));
        assert_eq!(
            analyze_volume_context(&candles, &ind),
            VolumeContext::Normal
        );
    }

    #[test]
    fn test_volume_context_empty_candles() {
        let candles: Vec<Candle> = vec![];
        let ind = make_indicators(|i| i.volume_zscore_20 = Some(3.0));
        assert_eq!(
            analyze_volume_context(&candles, &ind),
            VolumeContext::Normal
        );
    }

    #[test]
    fn test_volume_context_regime_change_low_adx_falls_through() {
        // zscore > 3 but ADX < 25 → should NOT be RegimeChange
        let candles = vec![
            make_candle(100.0, 101.0, 102.0, 99.0, 1000.0),
            make_candle(101.0, 105.0, 106.0, 100.0, 10000.0), // bullish, with-trend
        ];
        let ind = make_indicators(|i| {
            i.volume_zscore_20 = Some(3.5);
            i.adx_14 = Some(20.0); // < 25
        });
        // Falls through to TrendContinuation (with-trend + spike)
        assert_eq!(
            analyze_volume_context(&candles, &ind),
            VolumeContext::TrendContinuation
        );
    }

    // --- Volume Strength Modifier ---

    #[test]
    fn test_volume_modifier_normal_always_one() {
        assert_eq!(
            volume_strength_modifier(&VolumeContext::Normal, "trend_following"),
            1.0
        );
        assert_eq!(
            volume_strength_modifier(&VolumeContext::Normal, "mean_reversion"),
            1.0
        );
        assert_eq!(
            volume_strength_modifier(&VolumeContext::Normal, "unknown"),
            1.0
        );
    }

    #[test]
    fn test_volume_modifier_trend_continuation_amplifies_trend() {
        assert!(
            volume_strength_modifier(&VolumeContext::TrendContinuation, "trend_following") > 1.0
        );
        assert!(volume_strength_modifier(&VolumeContext::TrendContinuation, "momentum") > 1.0);
    }

    #[test]
    fn test_volume_modifier_trend_continuation_dampens_mr() {
        assert!(
            volume_strength_modifier(&VolumeContext::TrendContinuation, "mean_reversion") < 1.0
        );
    }

    #[test]
    fn test_volume_modifier_exhaustion_dampens_trend() {
        assert!(
            volume_strength_modifier(&VolumeContext::ClimaxExhaustion, "trend_following") < 1.0
        );
        assert!(volume_strength_modifier(&VolumeContext::ClimaxExhaustion, "momentum") < 1.0);
    }

    #[test]
    fn test_volume_modifier_exhaustion_amplifies_mr() {
        assert!(volume_strength_modifier(&VolumeContext::ClimaxExhaustion, "mean_reversion") > 1.0);
    }

    #[test]
    fn test_volume_modifier_reversal_confirm_amplifies_mr() {
        assert!(volume_strength_modifier(&VolumeContext::ReversalConfirm, "mean_reversion") > 1.0);
    }

    #[test]
    fn test_volume_modifier_reversal_confirm_dampens_trend() {
        assert!(volume_strength_modifier(&VolumeContext::ReversalConfirm, "trend_following") < 1.0);
    }

    #[test]
    fn test_volume_modifier_regime_change_dampens_mr_arb() {
        assert!(volume_strength_modifier(&VolumeContext::RegimeChange, "mean_reversion") < 1.0);
        assert!(volume_strength_modifier(&VolumeContext::RegimeChange, "stat_arb") < 1.0);
    }

    #[test]
    fn test_volume_modifier_regime_change_amplifies_volatility() {
        assert!(volume_strength_modifier(&VolumeContext::RegimeChange, "volatility") > 1.0);
    }

    #[test]
    fn test_volume_context_serialization_roundtrip() {
        let contexts = vec![
            VolumeContext::TrendContinuation,
            VolumeContext::ClimaxExhaustion,
            VolumeContext::ReversalConfirm,
            VolumeContext::RegimeChange,
            VolumeContext::Normal,
        ];
        for ctx in contexts {
            let json = serde_json::to_string(&ctx).unwrap();
            let parsed: VolumeContext = serde_json::from_str(&json).unwrap();
            assert_eq!(parsed, ctx);
        }
    }
}