foxhunt/WAVE2_INTEGRATION_STATUS.md

# Wave 2 Integration Coordinator - Status Report

**Agent**: Wave2-A5 (Integration and Testing Coordinator)
**Date**: 2025-11-11
**Status**: 🟡 **WAITING FOR WAVE 2 AGENTS TO START**

---

## Executive Summary

Wave 2 Agent A5 (Integration Coordinator) is **ready and monitoring** for the 4 parallel reward enhancement agents (A1-A4). Currently, **no Wave 2 agents have been launched yet**.

**Wave 1 Status**: ✅ **COMPLETE** (Factored Actions structural integration completed by Agent A5)

---

## Wave 2 Agent Dependencies

This integration agent depends on 4 parallel agents completing their work:

| Agent | Responsibility | Expected Outputs | Status |
|-------|---------------|------------------|--------|
| **Wave2-A1** | Transaction costs (bid-ask spread, market impact) | MarketData fields: `bid_ask_spread`, `market_depth` | ⏳ NOT STARTED |
| **Wave2-A2** | Slippage modeling (volatility, order book imbalance) | MarketData fields: `volatility`, `order_book_imbalance` | ⏳ NOT STARTED |
| **Wave2-A3** | Position risk metrics (VaR, Sharpe, drawdown) | Risk penalty calculation enhancements | ⏳ NOT STARTED |
| **Wave2-A4** | Reward normalization and shaping | Running statistics, z-score normalization | ⏳ NOT STARTED |

---

## Current Baseline State

### 1. MarketData Struct (ml/src/dqn/reward.rs, lines 66-76)

```rust
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct MarketData {
    /// Current bid price
    pub bid: Price,
    /// Current ask price
    pub ask: Price,
    /// Bid-ask spread
    pub spread: Price,
    /// Volume
    pub volume: Decimal,
}
```

**Current fields**: 4 (bid, ask, spread, volume)
**Expected after Wave 2**: 8 fields (+ bid_ask_spread, market_depth, volatility, order_book_imbalance)

### 2. calculate_reward() Signature

**3-action space** (lines 308-314):
```rust
pub fn calculate_reward(
    &mut self,
    action: TradingAction,
    current_state: &TradingState,
    next_state: &TradingState,
    recent_actions: &[TradingAction],
) -> Result<Decimal, MLError>
```

**45-action space (factored)** (lines 388-394):
```rust
pub fn calculate_reward(
    &mut self,
    action: FactoredAction,
    current_state: &TradingState,
    next_state: &TradingState,
    recent_actions: &[FactoredAction],
) -> Result<Decimal, MLError>
```

**Current signature**: `&mut self` (already supports running stats)
**Wave2-A4 compatibility**: ✅ No signature change needed

### 3. Reward Calculation Pipeline (3-action space, lines 323-368)

```rust
let base_reward = match action {
    TradingAction::Buy | TradingAction::Sell => {
        // 1. Calculate P&L-based reward
        let pnl_reward = self.calculate_pnl_reward(current_state, next_state)?;

        // 2. Calculate risk penalty
        let risk_penalty = self.calculate_risk_penalty(next_state);

        // 3. Calculate transaction cost penalty
        let cost_penalty = self.calculate_cost_penalty(current_state, next_state);

        self.config.pnl_weight * pnl_reward
            - self.config.risk_weight * risk_penalty
            - self.config.cost_weight * cost_penalty
    },
    TradingAction::Hold => {
        // Dynamic HOLD reward based on price movement
        self.calculate_hold_reward(current_state, next_state)?
    },
};

// 4. Calculate diversity bonus (entropy-based)
let entropy = calculate_entropy(recent_actions);
let diversity_bonus = if entropy < entropy_threshold {
    self.config.diversity_weight // -0.1 penalty
} else {
    Decimal::ZERO
};

let final_reward = base_reward + diversity_bonus;

// 5. Clamp reward to [-1, +1]
let clamped_reward = final_reward.clamp(Decimal::from(-1), Decimal::ONE);
```

**Missing components (to be added by Wave 2)**:
- ✅ Transaction costs calculated (but needs Wave2-A1 enhancements)
- ❌ Slippage modeling (Wave2-A2)
- ❌ Position risk metrics (Wave2-A3 - VaR, Sharpe, drawdown)
- ❌ Reward normalization/shaping (Wave2-A4 - z-score, running stats)

---

## Expected Integration Conflicts

### 1. MarketData Struct Merge

**Conflict**: Both Wave2-A1 and Wave2-A2 add fields to `MarketData`

**Resolution Strategy**:
- Merge all 4 new fields into single struct definition
- Update `Default` impl with realistic values
- Verify field names don't collide

**Expected final struct**:
```rust
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct MarketData {
    // Existing fields
    pub bid: Price,
    pub ask: Price,
    pub spread: Price,
    pub volume: Decimal,

    // Wave2-A1 additions
    pub bid_ask_spread: Price,  // Explicit spread for transaction cost calculation
    pub market_depth: Decimal,  // Order book depth for market impact

    // Wave2-A2 additions
    pub volatility: Decimal,     // Realized volatility for slippage modeling
    pub order_book_imbalance: Decimal,  // Buy/sell pressure for slippage adjustment
}
```

### 2. calculate_reward() Pipeline Order

**Wave 2 agents must follow this exact order**:

1. **Calculate P&L** (existing) → `pnl_reward`
2. **Subtract transaction costs** (Wave2-A1) → `cost_penalty`
3. **Subtract slippage** (Wave2-A2) → `slippage_penalty`
4. **Subtract risk penalty** (Wave2-A3) → `risk_penalty`
5. **Apply reward shaping** (Wave2-A4) → `shaped_reward`
6. **Update running stats** (Wave2-A4) → `running_mean`, `running_std`
7. **Normalize reward** (Wave2-A4) → `z_score = (reward - mean) / std`
8. **Return** → `normalized_reward`

**Conflict resolution**: If agents implement different orders, enforce this canonical pipeline.

### 3. RewardConfig Fields

**Potential conflict**: Wave 2 agents may add new config fields

**Current fields** (lines 20-36):
- `pnl_weight: Decimal`
- `risk_weight: Decimal`
- `cost_weight: Decimal`
- `hold_reward: Decimal`
- `movement_threshold: Decimal`
- `hold_penalty_weight: Decimal`
- `diversity_weight: Decimal`

**Expected additions**:
- Wave2-A1: `market_impact_weight: Decimal` (0.05 default)
- Wave2-A2: `slippage_weight: Decimal` (0.10 default)
- Wave2-A3: `var_weight: Decimal`, `sharpe_weight: Decimal`, `drawdown_weight: Decimal`
- Wave2-A4: `normalization_window: usize` (1000 default), `enable_shaping: bool` (true default)

---

## Integration Test Plan

Once all 4 agents complete, I will create `ml/tests/wave2_reward_integration_tests.rs` with these tests:

### 1. test_full_reward_pipeline_realistic_trade()
- Scenario: Buy 5 ES contracts, Market order, Aggressive urgency
- Market: spread 0.25, depth 500, vol 1%, neutral book
- Position: $100k portfolio, currently flat
- Expected: P&L - costs - slippage - risk_penalty, then normalized

### 2. test_passive_vs_aggressive_order_costs()
- Compare: LimitMaker (passive) vs Market (aggressive)
- Expected: Cost difference ~0.5-1.0% of trade value

### 3. test_high_volatility_slippage_penalty()
- Compare: 0.5% vol vs 2.5% vol
- Expected: Slippage ~5× higher in high vol regime

### 4. test_risk_metrics_integration()
- Scenario: 20-period return history with -15% drawdown
- Expected: Risk penalty applied correctly

### 5. test_reward_normalization_stability()
- Feed 1000 random rewards to running stats
- Expected: mean ≈ 0, std ≈ 1, no NaN/Inf

### 6. test_backward_compatibility_simple_reward()
- Old code path: normalization = None, shaping = false
- Expected: Match original reward calculation (Wave 1)

---

## Smoke Test Plan

After integration, run 5-epoch training test:

```bash
cargo run -p ml --example train_dqn --release --features cuda -- \
  --parquet-file test_data/ES_FUT_180d.parquet \
  --epochs 5 \
  --output-dir /tmp/ml_training/wave2_integration_test \
  2>&1 | tee /tmp/ml_training/wave2_integration_test.log
```

**Success criteria**:
- ✅ No panics
- ✅ No NaN rewards
- ✅ Q-values in reasonable range (not exploding/collapsing)
- ✅ Action diversity > 10%
- ✅ Reward normalization operational (mean ≈ 0, std ≈ 1)

---

## Monitoring Strategy

I will check for Wave 2 agent outputs every 15 minutes by monitoring:

1. **Git status**: New `.md` files in root directory
2. **Temp directory**: `/tmp/ml_training/wave2_agent*`
3. **Test files**: `ml/tests/wave2_*_test.rs`
4. **Modified files**: `ml/src/dqn/reward.rs` changes

**Once ANY agent completes**: Start reviewing their work immediately
**Once ALL 4 agents complete**: Begin integration and conflict resolution

---

## Files to Monitor

| File | Expected Changes | Responsible Agent |
|------|-----------------|-------------------|
| `ml/src/dqn/reward.rs` | +4 MarketData fields, enhanced cost/slippage/risk calculations | A1, A2, A3 |
| `ml/src/dqn/reward.rs` | +normalization/shaping logic, running stats | A4 |
| `ml/tests/wave2_transaction_cost_tests.rs` | NEW | A1 |
| `ml/tests/wave2_slippage_tests.rs` | NEW | A2 |
| `ml/tests/wave2_risk_metrics_tests.rs` | NEW | A3 |
| `ml/tests/wave2_normalization_tests.rs` | NEW | A4 |

---

## Next Actions

1. ✅ **Baseline documented** - Current state of reward.rs captured
2. ✅ **Integration plan prepared** - Conflict resolution strategy defined
3. ✅ **Test plan created** - 6 integration tests + 1 smoke test planned
4. ⏳ **Wait for agents** - Monitor for Wave2-A1, A2, A3, A4 outputs
5. ⏳ **Begin integration** - Once all 4 agents complete

---

**Status**: 🟡 **STANDING BY**
**Next Update**: When first Wave 2 agent completes
**ETA**: Unknown (agents not yet launched)

---

**Generated**: 2025-11-11
**Agent**: Wave2-A5 (Integration Coordinator)
**Task**: Monitor and integrate Wave 2 reward enhancements