foxhunt/WAVE_D_DATABASE_QUICK_REFERENCE.md

Wave D Database Schema - Quick Reference

Last Updated: 2025-10-17 Migration: 045_wave_d_regime_tracking.sql Status: ✅ Production-Ready (13/13 tests passing)

---

🗄️ Database Tables

1. regime_states

Purpose: Current regime classification per symbol

Key Columns:

• symbol TEXT - Trading symbol (e.g., "ES.FUT")
• event_timestamp TIMESTAMPTZ - Classification timestamp
• regime TEXT - Regime type (Normal, Trending, Ranging, Volatile, Crisis, Illiquid, Momentum)
• confidence DOUBLE PRECISION - Classification confidence (0.0-1.0)
• cusum_s_plus, cusum_s_minus - CUSUM statistics (Agent D13)
• adx, plus_di, minus_di - ADX indicators (Agent D14)
• stability, entropy - Regime stability (Agent D15)

Unique Constraint: (symbol, event_timestamp)

2. regime_transitions

Purpose: Track regime changes

Key Columns:

• symbol TEXT - Trading symbol
• event_timestamp TIMESTAMPTZ - Transition timestamp
• from_regime TEXT - Source regime
• to_regime TEXT - Destination regime
• duration_bars INTEGER - Duration in previous regime
• transition_probability DOUBLE PRECISION - Transition probability (Agent D15)
• adx_at_transition, cusum_alert_triggered - Transition context

Constraint: from_regime != to_regime

3. adaptive_strategy_metrics

Purpose: Adaptive strategy performance per regime

Key Columns:

• symbol TEXT - Trading symbol
• event_timestamp TIMESTAMPTZ - Metric timestamp
• regime TEXT - Associated regime
• position_multiplier DOUBLE PRECISION - Position size adjustment (0.2-2.0x)
• stop_loss_multiplier DOUBLE PRECISION - Stop-loss adjustment (1.0-5.0x)
• regime_sharpe DOUBLE PRECISION - Regime-conditioned Sharpe
• risk_budget_utilization DOUBLE PRECISION - Risk usage (0.0-1.0)
• total_trades, winning_trades, total_pnl - Performance tracking

Unique Constraint: (symbol, event_timestamp, regime)

---

🔧 Database Functions

1. get_latest_regime(p_symbol TEXT)

Retrieve current regime for a symbol.

SELECT * FROM get_latest_regime('ES.FUT');

Returns: regime, confidence, event_timestamp, cusum_s_plus, cusum_s_minus, adx, stability

2. get_regime_transition_matrix(p_symbol TEXT, p_window_hours INTEGER)

Calculate transition probabilities.

SELECT * FROM get_regime_transition_matrix('ES.FUT', 168);

Returns: from_regime, to_regime, transition_count, transition_probability

3. get_regime_performance(p_symbol TEXT, p_window_hours INTEGER)

Get regime-specific performance.

SELECT * FROM get_regime_performance('ES.FUT', 24);

Returns: regime, total_trades, win_rate, avg_sharpe, avg_position_multiplier, avg_stop_loss_multiplier, total_pnl, avg_risk_utilization

---

💻 Rust API

DatabasePool Methods

use common::database::DatabasePool;

let pool = DatabasePool::new(config).await?;

// 1. Get latest regime
let regime = pool.get_latest_regime("ES.FUT").await?;
println!("Regime: {}, Confidence: {:.2}%", regime.regime, regime.confidence * 100.0);

// 2. Insert regime state
pool.insert_regime_state(
    "ES.FUT",
    "Trending",
    0.88,
    chrono::Utc::now(),
    Some(3.5),   // cusum_s_plus
    Some(-0.5),  // cusum_s_minus
    Some(52.0),  // adx
    Some(0.85),  // stability
).await?;

// 3. Track regime transition
pool.insert_regime_transition(
    "ES.FUT",
    "Normal",
    "Trending",
    chrono::Utc::now(),
    Some(120),   // duration_bars
    Some(0.42),  // transition_probability
    Some(52.0),  // adx_at_transition
    true,        // cusum_alert_triggered
).await?;

// 4. Update adaptive metrics
pool.upsert_adaptive_strategy_metrics(
    "ES.FUT",
    "Trending",
    chrono::Utc::now(),
    1.5,         // position_multiplier
    2.5,         // stop_loss_multiplier
    Some(2.1),   // regime_sharpe
    Some(0.80),  // risk_budget_utilization
    15,          // total_trades
    12,          // winning_trades
    25000,       // total_pnl
).await?;

// 5. Query regime performance
let performance = pool.get_regime_performance(Some("ES.FUT"), 24).await?;
for regime_perf in performance {
    println!("Regime: {:?}, Sharpe: {:.2}", regime_perf.regime, regime_perf.avg_sharpe.unwrap_or(0.0));
}

---

📊 Integration with Wave D Agents

Agent	Table/Function	Fields Used
D13 (CUSUM)	regime_states	cusum_s_plus, cusum_s_minus, cusum_alert_count
D13 (CUSUM)	regime_transitions	cusum_alert_triggered
D14 (ADX)	regime_states	adx, plus_di, minus_di
D14 (ADX)	regime_transitions	adx_at_transition
D15 (Transitions)	regime_states	stability, entropy
D15 (Transitions)	regime_transitions	transition_probability
D15 (Transitions)	get_regime_transition_matrix()	Matrix calculation
D16 (Adaptive)	adaptive_strategy_metrics	All fields
D16 (Adaptive)	get_regime_performance()	Performance aggregation

---

⚙️ Configuration

Database Connection (common crate)

use common::database::{DatabasePool, LocalDatabaseConfig, PoolConfig, PerformanceConfig};

let config = LocalDatabaseConfig {
    url: "postgresql://foxhunt:foxhunt_dev_password@localhost:5432/foxhunt".to_string(),
    pool: PoolConfig {
        max_connections: 50,
        min_connections: 10,
        connect_timeout_ms: 100,
        acquire_timeout_ms: 50,
        max_lifetime_seconds: 3600,
        idle_timeout_seconds: 300,
    },
    performance: PerformanceConfig {
        query_timeout_micros: 800,  // <1ms for HFT
        enable_prewarming: true,
        enable_prepared_statements: true,
        enable_slow_query_logging: true,
        slow_query_threshold_micros: 1000,
    },
};

let pool = DatabasePool::new(config).await?;

---

🧪 Testing

Run All Tests

SQLX_OFFLINE=false cargo test -p common --test wave_d_regime_tracking_tests --features database -- --test-threads=1

Run Specific Test

SQLX_OFFLINE=false cargo test -p common --test wave_d_regime_tracking_tests test_insert_regime_state --features database

Expected Output

running 13 tests
test test_adaptive_strategy_metrics_constraints ... ok
test test_concurrent_regime_updates ... ok
test test_end_to_end_regime_workflow ... ok
test test_get_latest_regime ... ok
test test_get_regime_performance ... ok
test test_get_regime_transition_matrix_function ... ok
test test_insert_regime_state ... ok
test test_insert_regime_transition ... ok
test test_multiple_regime_transitions ... ok
test test_regime_state_constraints ... ok
test test_regime_transition_invalid_same_regime ... ok
test test_upsert_adaptive_strategy_metrics ... ok
test test_upsert_regime_state ... ok

test result: ok. 13 passed; 0 failed

---

🚀 Performance

Query Performance (Targets)

Operation	Target	Notes
get_latest_regime()	<1ms	Single-row with index
insert_regime_state()	<5ms	UPSERT with unique constraint
get_regime_transition_matrix()	<50ms	Aggregation over window
get_regime_performance()	<50ms	Multi-regime aggregation

Index Coverage

• ✅ regime_states(symbol, event_timestamp DESC) - Latest regime lookups
• ✅ regime_transitions(symbol, from_regime, to_regime) - Transition queries
• ✅ adaptive_strategy_metrics(symbol, event_timestamp DESC) - Performance tracking

---

📖 Schema Diagram

┌─────────────────────────┐
│   regime_states         │
├─────────────────────────┤
│ • symbol                │
│ • event_timestamp       │
│ • regime                │
│ • confidence            │
│ • cusum_s_plus/minus    │ ← Agent D13
│ • adx/plus_di/minus_di  │ ← Agent D14
│ • stability/entropy     │ ← Agent D15
└─────────────────────────┘
           │
           │ 1:N (same symbol)
           ▼
┌─────────────────────────┐
│  regime_transitions     │
├─────────────────────────┤
│ • symbol                │
│ • event_timestamp       │
│ • from_regime           │
│ • to_regime             │
│ • duration_bars         │
│ • transition_prob       │ ← Agent D15
│ • adx_at_transition     │
│ • cusum_alert_triggered │
└─────────────────────────┘

┌─────────────────────────┐
│ adaptive_strategy       │
│        _metrics         │
├─────────────────────────┤
│ • symbol                │
│ • event_timestamp       │
│ • regime                │
│ • position_multiplier   │ ← Agent D16
│ • stop_loss_multiplier  │ ← Agent D16
│ • regime_sharpe         │ ← Agent D16
│ • risk_budget_util      │ ← Agent D16
│ • total_trades/pnl      │
└─────────────────────────┘

---

🔗 Related Documentation

• Full Report: AGENT_D34_DATABASE_SCHEMA_REPORT.md
• Migration File: migrations/045_wave_d_regime_tracking.sql
• Database Module: common/src/database.rs
• Test Suite: common/tests/wave_d_regime_tracking_tests.rs
• Wave D Overview: CLAUDE.md (Section: Wave D)

---

Quick Reference v1.0 | Agent D34 | 2025-10-17