hypercall/vol_oracle/

factory.rs

use std::collections::{BTreeSet, HashMap, HashSet};
use std::sync::Arc;
use std::time::Duration;

use anyhow::{Context, Result};
use tokio::task::JoinHandle;
use tracing::{error, info, warn};

use crate::shared::shutdown::Shutdown;
use crate::shared::task_group::TaskGroup;
use catalog_manager::{
    BlockScholesProviderConfig, CatalogConfig, DeribitProviderConfig, DeriveProviderConfig,
    PolygonProviderConfig, PolymarketProviderConfig, RealizedVolProviderConfig,
    StickyMoneynessProviderConfig, VolOracleProviderConfig,
};
use hypercall_vol_oracle::FixedTestRiskVolOracle;
use hypercall_vol_oracle::PollingVolOracle as _;
use hypercall_vol_oracle::RoutedVolOracle;
use hypercall_vol_oracle::SharedVolOracle;
use hypercall_vol_oracle::{BlockScholesVolOracle, BlockScholesVolOracleConfig};
use hypercall_vol_oracle::{DeribitVolOracle, DeribitVolOracleConfig};
use hypercall_vol_oracle::{DeriveVolOracle, DeriveVolOracleConfig};
use hypercall_vol_oracle::{
    PlatformSpotPrices, PolygonUnderlyingConfig, PolygonVolOracle, PolygonVolOracleConfig,
};
use hypercall_vol_oracle::{PolymarketVolOracle, PolymarketVolOracleConfig};
use hypercall_vol_oracle::{RealizedVolOracle, RealizedVolOracleConfig};
use hypercall_vol_oracle::{StickyMoneynessVolOracle, StickyMoneynessVolOracleConfig};

/// Builds the runtime volatility router from the market catalog.
pub struct VolOracleFactory;

/// Result of building the vol oracle, including handles for dynamic updates.
pub struct VolOracleFactoryOutput {
    pub oracle: SharedVolOracle,
    /// Shared map for injecting platform spot prices into the Polygon oracle.
    /// Update this map to enable dynamic strike scaling.
    pub polygon_platform_spots: PlatformSpotPrices,
}

impl VolOracleFactory {
    pub async fn build(
        catalog_config: &CatalogConfig,
        task_group: &mut TaskGroup,
        shutdown: &Shutdown,
    ) -> Result<VolOracleFactoryOutput> {
        let routes = catalog_config.vol_oracles.routes.clone();
        let polygon_platform_spots: PlatformSpotPrices =
            Arc::new(std::sync::RwLock::new(HashMap::new()));
        let routed_underlyings = routed_underlyings_by_provider(catalog_config);
        // Flatten every route into a set of unique provider names so we
        // build each provider instance exactly once regardless of how
        // many routes reference it.
        let mut used_provider_names = routes
            .values()
            .flat_map(|chain| chain.iter().cloned())
            .collect::<HashSet<_>>();
        expand_source_providers(catalog_config, &mut used_provider_names);
        let mut used_provider_names = used_provider_names.into_iter().collect::<Vec<_>>();
        used_provider_names.sort();
        let mut providers = HashMap::new();

        for provider_name in used_provider_names
            .iter()
            .filter(|name| {
                !matches!(
                    catalog_config
                        .vol_oracles
                        .providers
                        .get(*name)
                        .expect("catalog validation must guarantee provider existence"),
                    VolOracleProviderConfig::StickyMoneyness(_)
                )
            })
            .cloned()
            .collect::<Vec<_>>()
        {
            let provider_config = catalog_config
                .vol_oracles
                .providers
                .get(&provider_name)
                .expect("catalog validation must guarantee provider existence");
            let assigned_underlyings = routed_underlyings
                .get(&provider_name)
                .cloned()
                .unwrap_or_default();

            let provider = match provider_config {
                VolOracleProviderConfig::BlockScholes(config) => {
                    let block_scholes_config =
                        build_block_scholes_config(config, &assigned_underlyings).await?;
                    let oracle = Arc::new(BlockScholesVolOracle::new(block_scholes_config));
                    let handle = oracle.clone().start_polling();
                    spawn_provider_task(task_group, shutdown, "BlockScholesVolOracle", handle);
                    info!(
                        "Started Block Scholes vol oracle provider {} for {:?}",
                        provider_name, assigned_underlyings
                    );
                    let provider: SharedVolOracle = oracle;
                    provider
                }
                VolOracleProviderConfig::Deribit(config) => {
                    let deribit_config = build_deribit_config(config, &assigned_underlyings);
                    let oracle = Arc::new(DeribitVolOracle::new(deribit_config));
                    let handle = oracle.clone().start_polling();
                    spawn_provider_task(task_group, shutdown, "DeribitVolOracle", handle);
                    info!(
                        "Started Deribit vol oracle provider {} for {:?}",
                        provider_name, assigned_underlyings
                    );
                    let provider: SharedVolOracle = oracle;
                    provider
                }
                VolOracleProviderConfig::Derive(config) => {
                    let derive_config = build_derive_config(config, &assigned_underlyings);
                    let oracle = Arc::new(DeriveVolOracle::new(derive_config));
                    let handle = oracle.clone().start_polling();
                    spawn_provider_task(task_group, shutdown, "DeriveVolOracle", handle);
                    info!(
                        "Started Derive vol oracle provider {} for {:?}",
                        provider_name, assigned_underlyings
                    );
                    let provider: SharedVolOracle = oracle;
                    provider
                }
                VolOracleProviderConfig::Polygon(config) => {
                    let polygon_config = build_polygon_config(config, &assigned_underlyings);
                    let oracle = Arc::new(PolygonVolOracle::new(
                        polygon_config,
                        polygon_platform_spots.clone(),
                    ));
                    let handle = oracle.clone().start_polling();
                    spawn_provider_task(task_group, shutdown, "PolygonVolOracle", handle);
                    info!(
                        "Started Polygon vol oracle provider {} for {:?}",
                        provider_name, assigned_underlyings
                    );
                    let provider: SharedVolOracle = oracle;
                    provider
                }
                VolOracleProviderConfig::StickyMoneyness(_) => {
                    unreachable!("sticky moneyness providers are built after their sources")
                }
                VolOracleProviderConfig::Fixed(config) => {
                    let provider: SharedVolOracle = Arc::new(
                        FixedTestRiskVolOracle::with_underlyings(config.iv, assigned_underlyings),
                    );
                    info!("Configured fixed vol oracle provider {}", provider_name);
                    provider
                }
                VolOracleProviderConfig::Polymarket(config) => {
                    let polymarket_config = build_polymarket_config(config, &assigned_underlyings);
                    let oracle = Arc::new(PolymarketVolOracle::new(polymarket_config));
                    let handle = oracle.clone().start_polling();
                    spawn_provider_task(task_group, shutdown, "PolymarketVolOracle", handle);
                    info!(
                        "Started Polymarket vol oracle provider {} for {:?}",
                        provider_name, assigned_underlyings
                    );
                    let provider: SharedVolOracle = oracle;
                    provider
                }
                VolOracleProviderConfig::RealizedVol(config) => {
                    let realized_config = build_realized_vol_config(config, &assigned_underlyings);
                    let oracle = Arc::new(RealizedVolOracle::new(realized_config));
                    let handle = oracle.clone().start_polling();
                    spawn_provider_task(task_group, shutdown, "RealizedVolOracle", handle);
                    info!(
                        "Configured realized-vol oracle provider {} for {:?}",
                        provider_name, assigned_underlyings
                    );
                    let provider: SharedVolOracle = oracle;
                    provider
                }
                VolOracleProviderConfig::Databento(config) => {
                    // v1 supports a single underlying per Databento provider.
                    // The catalog validator (tested in cycle 12) should reject
                    // multi-underlying configs, but we defend here too.
                    if assigned_underlyings.len() != 1 {
                        anyhow::bail!(
                            "Databento provider {} must serve exactly one \
                             underlying (got {:?}) — v2 item to support more",
                            provider_name,
                            assigned_underlyings
                        );
                    }
                    let underlying_name = assigned_underlyings[0].clone();
                    let underlying_config =
                        config.underlyings.get(&underlying_name).ok_or_else(|| {
                            anyhow::anyhow!(
                                "Databento provider {} missing per-underlying \
                                 config for {}",
                                provider_name,
                                underlying_name
                            )
                        })?;

                    // v1 only supports GC futures + OG options (CME Globex
                    // gold). The orchestrator run loop in
                    // `databento_oracle.rs` gates on `root == "GC"` and the
                    // option parser scopes to the OG chain, so a catalog
                    // that asks for a different pair would silently build a
                    // surface from the wrong contract or stay Disconnected
                    // forever. Refuse to build the provider in that case
                    // rather than deferring the failure to runtime.
                    if underlying_config.futures_root != "GC"
                        || underlying_config.options_root != "OG"
                    {
                        anyhow::bail!(
                            "Databento provider {} for {} currently only \
                             supports futures_root=\"GC\" + options_root=\"OG\" \
                             (CME Globex gold). Got futures_root=\"{}\", \
                             options_root=\"{}\". Add explicit plumbing to \
                             `DatabentoVolOracleConfig` and the orchestrator \
                             before configuring a non-gold route.",
                            provider_name,
                            underlying_name,
                            underlying_config.futures_root,
                            underlying_config.options_root,
                        );
                    }

                    let oracle = Arc::new(
                        hypercall_vol_oracle::databento_oracle::DatabentoVolOracle::new(
                            hypercall_vol_oracle::databento_oracle::DatabentoVolOracleConfig {
                                underlying: underlying_name.clone(),
                                risk_free_rate: underlying_config.risk_free_rate,
                                strike_scale: underlying_config.strike_scale,
                                staleness_threshold: Duration::from_millis(config.staleness_ms),
                            },
                        ),
                    );

                    // Spawn the live Databento feed task. The helper
                    // connects to databento::LiveClient, subscribes to
                    // GC.FUT + OG.OPT with definition + mbp-1 schemas,
                    // and drives the oracle's run loop forever. If the
                    // connection fails (e.g. missing api_key) the task
                    // logs and exits; the oracle stays unready and the
                    // RoutedVolOracle's get_iv call will return
                    // UnhealthyProvider for GOLD.
                    hypercall_vol_oracle::databento_oracle::spawn_databento_live_feed_task(
                        oracle.clone(),
                        config.api_key.clone(),
                        config.dataset.clone(),
                    );
                    info!(
                        provider = %provider_name,
                        underlying = %underlying_name,
                        dataset = %config.dataset,
                        "Databento vol oracle live feed task spawned"
                    );

                    let provider: SharedVolOracle = oracle;
                    provider
                }
            };

            providers.insert(provider_name, provider);
        }

        for provider_name in used_provider_names
            .iter()
            .filter(|name| {
                matches!(
                    catalog_config
                        .vol_oracles
                        .providers
                        .get(*name)
                        .expect("catalog validation must guarantee provider existence"),
                    VolOracleProviderConfig::StickyMoneyness(_)
                )
            })
            .cloned()
            .collect::<Vec<_>>()
        {
            let VolOracleProviderConfig::StickyMoneyness(config) = catalog_config
                .vol_oracles
                .providers
                .get(&provider_name)
                .expect("catalog validation must guarantee provider existence")
            else {
                unreachable!("filtered to sticky moneyness providers");
            };
            let assigned_underlyings = routed_underlyings
                .get(&provider_name)
                .cloned()
                .unwrap_or_default();
            let source = providers
                .get(&config.source_provider)
                .cloned()
                .ok_or_else(|| {
                    anyhow::anyhow!(
                        "Sticky moneyness provider {} source_provider {} was not built",
                        provider_name,
                        config.source_provider
                    )
                })?;
            if !source.supports_surface_snapshots() {
                anyhow::bail!(
                    "Sticky moneyness provider {} source_provider {} does not support surface snapshots",
                    provider_name,
                    config.source_provider
                );
            }

            let provider: SharedVolOracle = Arc::new(StickyMoneynessVolOracle::new(
                source,
                polygon_platform_spots.clone(),
                build_sticky_moneyness_config(config, &assigned_underlyings),
            ));
            info!(
                "Configured sticky moneyness vol oracle provider {} for {:?} from {}",
                provider_name, assigned_underlyings, config.source_provider
            );
            providers.insert(provider_name, provider);
        }

        Ok(VolOracleFactoryOutput {
            oracle: Arc::new(RoutedVolOracle::new(providers, routes)),
            polygon_platform_spots,
        })
    }
}

fn routed_underlyings_by_provider(catalog_config: &CatalogConfig) -> HashMap<String, Vec<String>> {
    let mut routed = HashMap::<String, Vec<String>>::new();

    // Each route provider, plus source providers used by composite models,
    // needs to know which underlyings it serves so per-underlying config
    // lookups succeed.
    for (underlying, chain) in &catalog_config.vol_oracles.routes {
        for provider_name in chain {
            routed
                .entry(provider_name.clone())
                .or_default()
                .push(underlying.clone());

            if let Some(VolOracleProviderConfig::StickyMoneyness(config)) =
                catalog_config.vol_oracles.providers.get(provider_name)
            {
                routed
                    .entry(config.source_provider.clone())
                    .or_default()
                    .push(underlying.clone());
            }
        }
    }

    for underlyings in routed.values_mut() {
        underlyings.sort();
        underlyings.dedup();
    }

    routed
}

fn expand_source_providers(
    catalog_config: &CatalogConfig,
    used_provider_names: &mut HashSet<String>,
) {
    loop {
        let before = used_provider_names.len();
        for provider_name in used_provider_names.clone() {
            if let Some(VolOracleProviderConfig::StickyMoneyness(config)) =
                catalog_config.vol_oracles.providers.get(&provider_name)
            {
                used_provider_names.insert(config.source_provider.clone());
            }
        }
        if used_provider_names.len() == before {
            break;
        }
    }
}

async fn build_block_scholes_config(
    provider_config: &BlockScholesProviderConfig,
    assigned_underlyings: &[String],
) -> Result<BlockScholesVolOracleConfig> {
    // Fetch Deribit's actual term structure so we subscribe to expiries that
    // Block Scholes recognizes. Hypercall's own expiry schedule (daily/weekly/
    // monthly) doesn't match Deribit's listed expiries, causing BS to reject
    // subscriptions. The vol surface interpolation layer bridges the gap.
    let expiries = fetch_deribit_expiries(assigned_underlyings).await?;

    if expiries.is_empty() {
        warn!(
            "No Deribit expiries found for Block Scholes underlyings {:?} — \
             oracle will start with no subscriptions and remain unready.",
            assigned_underlyings
        );
    } else {
        info!(
            "Fetched {} Deribit expiries for Block Scholes subscription: {:?}",
            expiries.len(),
            expiries
        );
    }

    Ok(BlockScholesVolOracleConfig {
        ws_url: provider_config.ws_url.clone(),
        api_key: provider_config.api_key.clone(),
        api_secret: provider_config.api_secret.clone(),
        symbols: assigned_underlyings.to_vec(),
        strikes: HashMap::new(), // Not needed — we use delta.iv, not strike.iv
        expiries,
        reconnect_delay_ms: provider_config.reconnect_delay_ms,
        max_reconnect_attempts: provider_config.max_reconnect_attempts,
        heartbeat_interval_ms: provider_config.heartbeat_interval_ms,
        cache_ttl_ms: provider_config.staleness_ms,
    })
}

/// Deribit instruments API response.
#[derive(Debug, serde::Deserialize)]
struct DeribitInstrumentsResponse {
    result: Vec<DeribitInstrument>,
}

#[derive(Debug, serde::Deserialize)]
struct DeribitInstrument {
    /// Expiry timestamp in milliseconds
    expiration_timestamp: i64,
}

/// Fetch the current Deribit option term structure for the given underlyings.
///
/// Returns a sorted, deduplicated list of expiry timestamps in ISO 8601 format
/// (e.g., "2026-04-11T08:00:00Z") that Block Scholes will accept.
async fn fetch_deribit_expiries(underlyings: &[String]) -> Result<Vec<String>> {
    let client = reqwest::Client::builder()
        .timeout(Duration::from_secs(10))
        .build()
        .context("failed to build HTTP client for Deribit")?;

    let mut all_expiry_ts: BTreeSet<i64> = BTreeSet::new();

    for underlying in underlyings {
        let url = format!(
            "https://www.deribit.com/api/v2/public/get_instruments?currency={}&kind=option&expired=false",
            underlying
        );

        match client.get(&url).send().await {
            Ok(resp) => match resp.json::<DeribitInstrumentsResponse>().await {
                Ok(data) => {
                    let count = data.result.len();
                    for instrument in data.result {
                        // Deribit timestamps are in milliseconds
                        all_expiry_ts.insert(instrument.expiration_timestamp / 1000);
                    }
                    info!(
                        "Fetched {} {} instruments from Deribit ({} unique expiries so far)",
                        count,
                        underlying,
                        all_expiry_ts.len()
                    );
                }
                Err(e) => {
                    warn!(
                        "Failed to parse Deribit instruments response for {}: {}",
                        underlying, e
                    );
                }
            },
            Err(e) => {
                warn!(
                    "Failed to fetch Deribit instruments for {}: {}",
                    underlying, e
                );
            }
        }
    }

    let expiries: Vec<String> = all_expiry_ts
        .into_iter()
        .filter_map(|ts| {
            let dt = chrono::DateTime::from_timestamp(ts, 0);
            if dt.is_none() {
                warn!("Skipping invalid Deribit expiry timestamp: {}", ts);
            }
            dt.map(|d| d.format("%Y-%m-%dT%H:%M:%SZ").to_string())
        })
        .collect();

    Ok(expiries)
}

fn build_deribit_config(
    provider_config: &DeribitProviderConfig,
    assigned_underlyings: &[String],
) -> DeribitVolOracleConfig {
    DeribitVolOracleConfig {
        base_url: provider_config.base_url.clone(),
        poll_interval: Duration::from_millis(provider_config.refresh_interval_ms),
        staleness_threshold: Duration::from_millis(provider_config.staleness_ms),
        symbols: assigned_underlyings.to_vec(),
    }
}

fn build_derive_config(
    provider_config: &DeriveProviderConfig,
    assigned_underlyings: &[String],
) -> DeriveVolOracleConfig {
    DeriveVolOracleConfig {
        base_url: provider_config.base_url.clone(),
        poll_interval: Duration::from_millis(provider_config.refresh_interval_ms),
        staleness_threshold: Duration::from_millis(provider_config.staleness_ms),
        symbols: assigned_underlyings.to_vec(),
    }
}

fn build_polygon_config(
    provider_config: &PolygonProviderConfig,
    assigned_underlyings: &[String],
) -> PolygonVolOracleConfig {
    let configured_underlyings = assigned_underlyings
        .iter()
        .map(|underlying| {
            let config = provider_config
                .underlyings
                .get(underlying)
                .unwrap_or_else(|| {
                    panic!(
                        "catalog validation must guarantee Polygon settings for routed underlying {}",
                        underlying
                    )
                });

            (
                underlying.clone(),
                PolygonUnderlyingConfig {
                    ticker: config.ticker.clone(),
                    strike_scale: config.strike_scale,
                    require_live_strike_scale: config.require_live_strike_scale,
                },
            )
        })
        .collect();

    PolygonVolOracleConfig {
        api_key: provider_config.api_key.clone(),
        base_url: provider_config.base_url.clone(),
        poll_interval: Duration::from_millis(provider_config.refresh_interval_ms),
        staleness_threshold: Duration::from_millis(provider_config.staleness_ms),
        underlyings: configured_underlyings,
    }
}

fn build_polymarket_config(
    provider_config: &PolymarketProviderConfig,
    assigned_underlyings: &[String],
) -> PolymarketVolOracleConfig {
    PolymarketVolOracleConfig {
        event_slug: provider_config.event_slug.clone(),
        shares_outstanding: provider_config.shares_outstanding,
        reference_tte_days: provider_config.reference_tte_days,
        poll_interval: Duration::from_millis(provider_config.refresh_interval_ms),
        staleness_threshold: Duration::from_millis(provider_config.staleness_ms),
        symbols: assigned_underlyings.to_vec(),
    }
}

fn build_realized_vol_config(
    provider_config: &RealizedVolProviderConfig,
    assigned_underlyings: &[String],
) -> RealizedVolOracleConfig {
    RealizedVolOracleConfig {
        info_url: provider_config.info_url.clone(),
        candle_coin: provider_config.candle_coin.clone(),
        lookback_days: provider_config.lookback_days,
        min_samples: provider_config.min_samples,
        annualization_days: provider_config.annualization_days,
        floor_iv: provider_config.floor_iv,
        cap_iv: provider_config.cap_iv,
        multiplier: provider_config.multiplier,
        poll_interval: Duration::from_millis(provider_config.refresh_interval_ms),
        staleness_threshold: Duration::from_millis(provider_config.staleness_ms),
        strike_min: provider_config.strike_min,
        strike_max: provider_config.strike_max,
        strike_step: provider_config.strike_step,
        symbols: assigned_underlyings.to_vec(),
    }
}

fn build_sticky_moneyness_config(
    provider_config: &StickyMoneynessProviderConfig,
    assigned_underlyings: &[String],
) -> StickyMoneynessVolOracleConfig {
    StickyMoneynessVolOracleConfig {
        underlyings: assigned_underlyings.to_vec(),
        max_snapshot_age: Duration::from_millis(provider_config.max_snapshot_age_ms),
        event_jump: provider_config.event_jump,
        min_tte_years: provider_config.min_tte_years,
    }
}

fn spawn_provider_task(
    task_group: &mut TaskGroup,
    shutdown: &Shutdown,
    task_name: &'static str,
    handle: JoinHandle<()>,
) {
    let mut shutdown_rx = shutdown.subscribe();
    task_group.spawn(task_name, async move {
        let mut handle = handle;
        tokio::select! {
            result = &mut handle => {
                if let Err(err) = result {
                    error!("{} task panicked: {:?}", task_name, err);
                }
            }
            _ = shutdown_rx.recv() => {
                handle.abort();
                let _ = handle.await;
            }
        }
        Ok(())
    });
}

#[cfg(test)]
mod tests {
    use super::*;
    use catalog_manager::{
        DeribitRegionStepsConfig, FixedVolOracleProviderConfig, HyperliquidAssetConfig,
        PerpCollateralConfig, StablecoinCollateralConfig, StrikeSelectionConfig,
    };
    use catalog_manager::{
        ExpiryConfig, ExpiryScheduleConfig, ExtensionPolicyConfig, ObservabilityConfig,
        UnderlyingConfig, VolOracleCatalogConfig,
    };

    fn base_catalog() -> CatalogConfig {
        CatalogConfig {
            version: 1,
            expiry: ExpiryConfig {
                expiry_time_utc: "08:00".to_string(),
                schedule: ExpiryScheduleConfig {
                    daily_count: 2,
                    weekly_count: 4,
                    monthly_count: 3,
                    weekdays_only: false,
                },
            },
            underlyings: HashMap::from([
                (
                    "BTC".to_string(),
                    UnderlyingConfig {
                        vol_source: "deribit".to_string(),
                        hl_symbol: None,
                        trading_mode: hypercall_types::TradingModes::ORDERBOOK,
                        max_expiry_code: None,
                        expiry_time_utc: None,
                        schedule: None,
                    },
                ),
                (
                    "ETH".to_string(),
                    UnderlyingConfig {
                        vol_source: "deribit".to_string(),
                        hl_symbol: None,
                        trading_mode: hypercall_types::TradingModes::ORDERBOOK,
                        max_expiry_code: None,
                        expiry_time_utc: None,
                        schedule: None,
                    },
                ),
            ]),
            collateral: HashMap::from([
                (
                    "BTC_PERP".to_string(),
                    HyperliquidAssetConfig::Perp(PerpCollateralConfig {
                        asset_id: 0,
                        underlying: "BTC".to_string(),
                    }),
                ),
                (
                    "ETH_PERP".to_string(),
                    HyperliquidAssetConfig::Perp(PerpCollateralConfig {
                        asset_id: 1,
                        underlying: "ETH".to_string(),
                    }),
                ),
                (
                    "USDC".to_string(),
                    HyperliquidAssetConfig::Stablecoin(StablecoinCollateralConfig { token_id: 0 }),
                ),
            ]),
            strike_selection: StrikeSelectionConfig {
                deribit_table_assets: vec![
                    "BTC".to_string(),
                    "ETH".to_string(),
                    "SOL".to_string(),
                    "AVAX".to_string(),
                    "XRP".to_string(),
                    "TRX".to_string(),
                ],
                deribit_region_steps: DeribitRegionStepsConfig {
                    atm: 3,
                    outer: 4,
                    wings: 3,
                },
                occ_fallback_side_count: 8,
            },
            extension_policy: ExtensionPolicyConfig {
                enabled: true,
                ensure_min_strikes_per_side: 5,
                ensure_atm_within_pct: 0.05,
                cooldown_secs: 3600,
                max_total_strikes_per_expiry: 40,
                min_spot_move_pct: 0.05,
            },
            observability: ObservabilityConfig::default(),
            vol_oracles: VolOracleCatalogConfig {
                providers: HashMap::from([
                    (
                        "btc_fixed".to_string(),
                        VolOracleProviderConfig::Fixed(FixedVolOracleProviderConfig { iv: 0.55 }),
                    ),
                    (
                        "eth_fixed".to_string(),
                        VolOracleProviderConfig::Fixed(FixedVolOracleProviderConfig { iv: 0.91 }),
                    ),
                ]),
                routes: HashMap::from([
                    ("BTC".to_string(), vec!["btc_fixed".to_string()]),
                    ("ETH".to_string(), vec!["eth_fixed".to_string()]),
                ]),
            },
        }
    }

    #[tokio::test]
    async fn factory_routes_underlyings_to_named_providers() {
        let catalog = base_catalog();
        let mut task_group = TaskGroup::new();
        let shutdown = Shutdown::new();

        let output = VolOracleFactory::build(&catalog, &mut task_group, &shutdown)
            .await
            .expect("factory should build fixed providers");

        assert_eq!(
            output
                .oracle
                .get_iv("BTC", 100_000.0, 1_800_000_000)
                .unwrap(),
            0.55
        );
        assert_eq!(
            output.oracle.get_iv("ETH", 4_000.0, 1_800_000_000).unwrap(),
            0.91
        );
        assert!(matches!(
            output.oracle.get_iv("US500", 600.0, 1_800_000_000),
            Err(hypercall_vol_oracle::VolLookupError::UnsupportedUnderlying { .. })
        ));
        assert_eq!(task_group.len(), 0);
    }

    #[tokio::test]
    async fn factory_builds_sticky_moneyness_provider_from_snapshot_source() {
        let mut catalog = base_catalog();
        catalog.underlyings.clear();
        catalog.underlyings.insert(
            "US500".to_string(),
            UnderlyingConfig {
                vol_source: "none".to_string(),
                hl_symbol: Some("km:US500".to_string()),
                trading_mode: hypercall_types::TradingModes::RFQ,
                max_expiry_code: None,
                expiry_time_utc: None,
                schedule: None,
            },
        );
        catalog.underlyings.insert(
            "USOIL".to_string(),
            UnderlyingConfig {
                vol_source: "none".to_string(),
                hl_symbol: Some("km:USOIL".to_string()),
                trading_mode: hypercall_types::TradingModes::RFQ,
                max_expiry_code: None,
                expiry_time_utc: None,
                schedule: None,
            },
        );
        catalog.collateral = HashMap::from([(
            "USDC".to_string(),
            HyperliquidAssetConfig::Stablecoin(StablecoinCollateralConfig { token_id: 0 }),
        )]);
        catalog.vol_oracles = VolOracleCatalogConfig {
            providers: HashMap::from([
                (
                    "polygon_main".to_string(),
                    VolOracleProviderConfig::Polygon(PolygonProviderConfig {
                        api_key: "test-polygon-key".to_string(),
                        base_url: "http://127.0.0.1:9".to_string(),
                        refresh_interval_ms: 60_000,
                        staleness_ms: 180_000,
                        underlyings: HashMap::from([
                            (
                                "US500".to_string(),
                                catalog_manager::PolygonProviderUnderlyingConfig {
                                    ticker: "SPY".to_string(),
                                    strike_scale: 1.0,
                                    require_live_strike_scale: true,
                                },
                            ),
                            (
                                "USOIL".to_string(),
                                catalog_manager::PolygonProviderUnderlyingConfig {
                                    ticker: "USO".to_string(),
                                    strike_scale: 1.0,
                                    require_live_strike_scale: true,
                                },
                            ),
                        ]),
                    }),
                ),
                (
                    "polygon_session_model".to_string(),
                    VolOracleProviderConfig::StickyMoneyness(StickyMoneynessProviderConfig {
                        source_provider: "polygon_main".to_string(),
                        max_snapshot_age_ms: 259_200_000,
                        event_jump: 0.03,
                        min_tte_years: 1.0 / 365.25,
                    }),
                ),
            ]),
            routes: HashMap::from([
                (
                    "US500".to_string(),
                    vec!["polygon_session_model".to_string()],
                ),
                (
                    "USOIL".to_string(),
                    vec!["polygon_session_model".to_string()],
                ),
            ]),
        };
        catalog
            .validate()
            .expect("synthetic sticky moneyness catalog should validate");

        let mut task_group = TaskGroup::new();
        let shutdown = Shutdown::new();
        let output = VolOracleFactory::build(&catalog, &mut task_group, &shutdown)
            .await
            .expect("factory should build polygon plus sticky moneyness provider");

        let statuses = output.oracle.statuses();
        for underlying in ["US500", "USOIL"] {
            assert!(statuses.iter().any(|status| {
                status.underlying == underlying
                    && status.provider == hypercall_vol_oracle::VolProviderKind::Polygon
            }));
            assert!(statuses.iter().any(|status| {
                status.underlying == underlying
                    && status.provider == hypercall_vol_oracle::VolProviderKind::StickyMoneyness
            }));
        }

        task_group
            .shutdown_and_join(&shutdown, Duration::from_secs(1))
            .await
            .expect("polygon polling task should shut down");
    }

    /// Cycle 13 e2e: catalog with a Databento provider + route → factory
    /// builds a `SharedVolOracle` without spawning a real feed → `get_iv`
    /// returns `UnhealthyProvider` because no GC BBO has arrived.
    ///
    /// This test exists because cycle 11 covers the oracle directly but
    /// doesn't exercise the catalog-parse-and-wire path, and cycle 12
    /// covers the config parse but doesn't exercise the factory. A full
    /// green-field catalog → queryable oracle walk catches wiring bugs
    /// (missing match arms, bad defaults, mismatched provider names)
    /// that unit tests at either end can miss.
    #[tokio::test]
    async fn factory_builds_databento_oracle_and_reports_unhealthy_without_feed() {
        use catalog_manager::{DatabentoProviderConfig, DatabentoProviderUnderlyingConfig};

        let mut catalog = base_catalog();

        // Swap the default BTC/ETH Fixed routes for a single GOLD→databento route.
        // `base_catalog()` seeds collateral entries that reference BTC/ETH as their
        // underlyings; since we're about to drop those, also drop the matching
        // collateral rows (the validator rejects collateral that points at an
        // underlying not in the catalog — "Collateral perp ETH_PERP references
        // unknown underlying ETH"). Keep only USDC (stablecoin, no underlying
        // reference) so the "at least one stablecoin collateral" rule is still met.
        catalog.collateral.retain(|name, _| name == "USDC");
        catalog.underlyings.clear();
        catalog.underlyings.insert(
            "GOLD".to_string(),
            UnderlyingConfig {
                // The per-underlying `vol_source` field is a legacy hint
                // used by older catalog code paths — route-based catalogs
                // use the vol_oracles.routes map instead. `"none"` is the
                // pre-existing convention for GOLD since its real IV
                // comes from the routed provider below.
                vol_source: "none".to_string(),
                hl_symbol: Some("km:GOLD".to_string()),
                trading_mode: hypercall_types::TradingModes::RFQ,
                max_expiry_code: None,
                expiry_time_utc: None,
                schedule: None,
            },
        );
        catalog.collateral = HashMap::from([(
            "USDC".to_string(),
            HyperliquidAssetConfig::Stablecoin(StablecoinCollateralConfig { token_id: 0 }),
        )]);

        catalog.vol_oracles = VolOracleCatalogConfig {
            providers: HashMap::from([(
                "databento_main".to_string(),
                VolOracleProviderConfig::Databento(DatabentoProviderConfig {
                    api_key: "test-key".to_string(),
                    dataset: "GLBX.MDP3".to_string(),
                    staleness_ms: 120_000,
                    underlyings: HashMap::from([(
                        "GOLD".to_string(),
                        DatabentoProviderUnderlyingConfig {
                            futures_root: "GC".to_string(),
                            options_root: "OG".to_string(),
                            strike_scale: 1.0,
                            risk_free_rate: 0.05,
                        },
                    )]),
                }),
            )]),
            routes: HashMap::from([("GOLD".to_string(), vec!["databento_main".to_string()])]),
        };

        catalog
            .validate()
            .expect("synthetic GOLD/databento catalog should validate");

        let mut task_group = TaskGroup::new();
        let shutdown = Shutdown::new();
        let oracle = VolOracleFactory::build(&catalog, &mut task_group, &shutdown)
            .await
            .expect("factory should build a databento oracle");

        // The factory spawns a detached tokio task for the Databento
        // live feed via tokio::spawn (not the TaskGroup). task_group
        // stays at 0 for this provider because the feed task is
        // intentionally outside the structured task group — the
        // connection can fail at any time and a supervisor-level
        // restart is a v2 item.
        assert_eq!(
            task_group.len(),
            0,
            "databento provider spawns its live feed task outside the TaskGroup"
        );

        // get_iv on the routed provider should bubble UnhealthyProvider
        // from DatabentoVolOracle's "no forward received yet" path.
        let err = oracle
            .oracle
            .get_iv("GOLD", 4700.0, 1_800_000_000)
            .expect_err("no data means unhealthy");
        assert!(
            matches!(
                err,
                hypercall_vol_oracle::VolLookupError::UnhealthyProvider {
                    ref provider,
                    ..
                }
                if matches!(provider, hypercall_vol_oracle::VolProviderKind::Databento)
            ),
            "expected UnhealthyProvider(Databento), got {err:?}"
        );

        // statuses() should report the single databento underlying.
        let statuses = oracle.oracle.statuses();
        let gold = statuses
            .iter()
            .find(|s| s.underlying == "GOLD")
            .expect("GOLD should be reported");
        assert_eq!(
            gold.provider,
            hypercall_vol_oracle::VolProviderKind::Databento
        );
        assert!(!gold.connected, "no feed → not connected");
        assert!(!gold.ready, "no feed → not ready");
        assert_eq!(gold.surface_points, 0);
    }

    #[tokio::test]
    #[ignore] // Requires network access to Deribit public API
    async fn fetch_deribit_expiries_returns_sorted_iso_dates() {
        let expiries = fetch_deribit_expiries(&["BTC".to_string()])
            .await
            .expect("Deribit public API should be reachable");

        assert!(!expiries.is_empty(), "Deribit must have active BTC options");

        // All should parse as valid ISO 8601 timestamps
        for exp in &expiries {
            chrono::DateTime::parse_from_rfc3339(exp)
                .unwrap_or_else(|e| panic!("Invalid ISO 8601 expiry '{}': {}", exp, e));
        }

        // Should be sorted
        let mut sorted = expiries.clone();
        sorted.sort();
        assert_eq!(expiries, sorted, "Expiries must be sorted ascending");

        // Deribit typically has 10+ unique expiries for BTC
        assert!(
            expiries.len() >= 5,
            "Expected at least 5 BTC expiries, got {}",
            expiries.len()
        );
    }
}