# Trading Realism Conformance — Design Spec

## Problem

The model trains in a simplified simulation that doesn't match real market conditions. Every mismatch between simulation and reality erodes the model's edge in production. Seven items identified:

## Items

### 1. Market Hours (RTH vs ETH) — Feature Enhancement

**Status:** Time-of-day features exist in the 42-dim vector but the model doesn't explicitly distinguish RTH (9:30-16:00 ET, ~390 bars) from ETH (16:00-9:30, ~1050 bars).

**Implementation:** Add a binary feature `is_rth` to the feature vector. Also adjust spread and volatility scaling:
- ETH: wider effective spread (2-3x), lower volume, more noise
- RTH: tighter spread, higher volume, more signal
- The tx_cost in the kernel could multiply by `rth_cost_multiplier` (default 1.0 for RTH, 1.5 for ETH)

**Config:**
```toml
[market]
rth_start_minute = 570    # 9:30 ET = 570 minutes from midnight
rth_end_minute = 960      # 16:00 ET
eth_cost_multiplier = 1.5 # wider spreads during ETH
```

### 2. Correlation Risk — Architecture Note

**Status:** Not needed yet (single instrument ES). Architecture should support multi-instrument via per-instrument branching heads. Deferred.

### 3. Market Impact — DONE

**Status:** Implemented. Quadratic tx_cost scaling: `impact_scale = 1 + (|delta|/max_position)^2`. Commit ac61fbb8.

### 4. Order Book Depth → Fill Quality

**Status:** MBP-10 data (10 levels of bids/asks) is loaded and produces 8 OFI features. But fill simulation uses fixed probabilities per order type, not book-depth-adaptive ones.

**Implementation:** In the fill simulation kernel (`epsilon_greedy_routed`), adjust fill probability based on book imbalance:
- If `bid_volume > ask_volume * 1.5`: buy orders fill better (higher probability)
- If `ask_volume > bid_volume * 1.5`: sell orders fill better
- Symmetric: limit orders on the thick side of the book fill more reliably

The OFI features already encode book imbalance — expose the relevant feature (OFI[0] = best_bid_size - best_ask_size) to the fill simulation kernel.

### 5. Macro Events — Binary Feature

**Status:** Not implemented. Requires external data (economic calendar).

**Implementation:** Add a `macro_event_flag` feature (0 or 1) to the feature vector:
- 1 = scheduled macro event within next 30 minutes (FOMC, NFP, CPI, PPI, retail sales)
- 0 = no event scheduled

**Data source:** Download from FRED or Investing.com, precompute per-bar binary flag, include in DBN or as separate CSV.

**Config:**
```toml
[events]
macro_event_lookback_minutes = 30
macro_event_data_path = "data/macro_events.csv"
```

### 6. Weekend/Overnight Gap Risk

**Status:** Not implemented. Holding over Friday close → Monday open carries unhedged gap risk that per-bar data doesn't capture.

**Implementation:** In the reward kernel, when `time_of_day` is within last 30 minutes of Friday RTH:
- Multiply `dd_threshold` by 0.5 (tighter drawdown tolerance)
- Add a `weekend_risk_penalty = position_size * 0.01` per bar during this window
- The model learns to reduce position before weekend

**Config:**
```toml
[risk]
weekend_risk_window_minutes = 30  # last N minutes of Friday RTH
weekend_risk_penalty = 0.01       # per bar, per unit position
```

### 7. Margin Requirements

**Status:** max_position handles position limits but the model doesn't see margin utilization.

**Implementation:** Add `margin_util` as a feature:
```
margin_util = (|position| * margin_per_contract) / equity
```

With ES margin=$12,650 and equity=$35K:
- 1 contract: margin_util = 12650/35000 = 0.36
- 2 contracts: margin_util = 25300/35000 = 0.72
- 3 contracts: would exceed 100% (not allowed by max_position)

This teaches the model the cost of holding large positions (margin is locked, can't use it for other trades). Add as feature index 42 (extending the 42-dim market features to 43).

**Config:**
```toml
[margin]
margin_per_contract = 12650.0
maintenance_margin_ratio = 0.75  # maintenance = 75% of initial
```

## Priority Order

1. **#7 Margin util feature** — simple, high impact (model learns capital efficiency)
2. **#1 RTH/ETH cost multiplier** — moderate, teaches time-dependent behavior
3. **#6 Weekend risk** — moderate, prevents Friday holding
4. **#4 Book depth → fill quality** — moderate, more realistic execution
5. **#5 Macro events** — needs external data, defer to next iteration

Items 1, 6, 7 can be implemented as kernel-level changes. Item 4 requires modifying the fill simulation kernel. Item 5 requires data pipeline changes.

All values should be configurable via the existing TOML profile system (training_profile.rs) with sensible defaults.
