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.

```sql
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.

```sql
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.

```sql
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

```rust
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)

```rust
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

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

### Run Specific Test

```bash
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