foxhunt/ACTION_MASKING_TEST_RESULTS.md

# Action Masking Tests - Comprehensive Results Report

**Date**: 2025-11-13
**Test File**: `ml/tests/risk_action_masking_test.rs`
**Command**: `cargo test -p ml --test risk_action_masking_test --release`

---

## Executive Summary

| Metric | Result |
|--------|--------|
| **Total Tests** | 15 |
| **Passed** | 10 (66.7%) |
| **Failed** | 5 (33.3%) |
| **Deployment Status** | ❌ NOT READY |

**Critical Finding**: The risk-based action masking system has **incomplete implementation**. Several constraint checks are not properly integrated, and multiple boundary condition failures prevent safe deployment.

---

## Test Results Breakdown

### ✅ PASSED (10/15 Tests - 66.7%)

1. **test_mask_actions_exceeding_position_limit** ✓
   Position limit masking works with restrictive limits

2. **test_mask_actions_violating_drawdown** ✓
   Drawdown limit masking correctly filters aggressive actions

3. **test_mask_actions_violating_cash_reserve** ✓
   Cash reserve checks correctly mask expensive market orders

4. **test_allow_position_reducing_actions** ✓
   SELL/FLAT actions always available even at position limits

5. **test_action_mask_performance** ✓
   Average masking time: **0 µs** (1000 iterations) - EXCELLENT

6. **test_masked_actions_not_in_qvalue_computation** ✓
   Masked actions correctly excluded from Q-value computation

7. **test_mask_logging** ✓
   Statistical logging output functional

8. **test_masking_with_bankrupt_portfolio** ✓
   Small portfolios retain some valid actions

9. **test_masking_with_extreme_limits** ✓
   Restrictive vs permissive limits handled correctly

10. **test_risk_masking_consistency_across_scenarios** ✓
    Multi-scenario consistency validated

### ❌ FAILED (5/15 Tests - 33.3%)

#### 1. **test_valid_actions_include_hold** ❌
- **Line**: 415
- **Error**: "HOLD action should always be valid for position 0"
- **Severity**: CRITICAL
- **Root Cause**: Cash reserve check too aggressive
  - Flat portfolio: position=0, cash=5k, min_required=20k
  - Even HOLD actions masked due to transaction costs
- **Impact**: Cannot execute any actions, including passive HOLD

#### 2. **test_mask_actions_violating_var** ❌
- **Line**: 211
- **Error**: "Action 9 should not violate VaR limit"
- **Severity**: HIGH
- **Root Cause**: VaR constraint logic flawed
  ```rust
  // Current (WRONG):
  potential_loss = var_dollar * exposure_change.abs();
  potential_loss > var_dollar  // Always true for large exposure_change
  ```
- **Impact**: VaR constraint not enforced

#### 3. **test_mask_all_long_actions_at_max_long** ❌
- **Line**: 319
- **Error**: "BUY actions should all be masked at max position"
- **Severity**: HIGH
- **Root Cause**: Position limit check uses `>` instead of `>=`
  - At position=2.0 (max): BUY actions still valid
  - Should mask at boundary, not after
- **Impact**: Can exceed position limits

#### 4. **test_mask_all_short_actions_at_max_short** ❌
- **Line**: 365
- **Error**: "SELL actions should all be masked at min position"
- **Severity**: HIGH
- **Root Cause**: Same boundary condition issue as #3
  - At position=-2.0 (min): SELL actions still valid
- **Impact**: Can exceed position limits in short direction

#### 5. **test_action_diversity_with_masking** ❌
- **Line**: 510
- **Error**: "Masking should preserve exposure type diversity"
- **Severity**: HIGH
- **Root Cause**: Excessive masking in reasonable scenarios
  - position=0.5, portfolio=100k, cash=20k
  - 0/45 actions valid (100% masking)
  - Expected: >22 actions (50% availability)
- **Impact**: Cannot preserve action diversity

---

## Critical Issues Identified

### Issue #1: FLAT PORTFOLIO MASKING ALL ACTIONS (CRITICAL)
```
Scenario:
  - position: 0.0
  - portfolio_value: 100,000
  - cash_reserve: 5,000
  - min_cash_required: 20,000 (20% of portfolio)

Result: get_valid_actions() returns EMPTY (0/45 actions)

Problem:
  1. Cash check: 5,000 < 20,000 → VIOLATES
  2. HOLD action requires transaction cost
  3. 5,000 - cost < 20,000 → VIOLATES ALL ACTIONS

Fix Required:
  Exempt HOLD actions from transaction cost checks (HOLD = no position change)
```

### Issue #2: VaR MASKING BROKEN (HIGH)
```
Constraint: Action should violate VaR limit
Observed: Action passes validation (incorrectly)

Root Cause: Formula backwards
  potential_loss = var_dollar * |exposure_change|
  if potential_loss > var_dollar → MASK

Problem: This masks excessively when:
  - var_dollar = 2,500
  - exposure_change = 1.5
  - potential_loss = 3,750 > 2,500 → MASKS (correct)
  BUT also masks when exposure_change = 0.5:
  - potential_loss = 1,250 < 2,500 → SHOULD NOT MASK

Fix Required: Review and correct VaR calculation logic
```

### Issue #3: POSITION LIMIT BOUNDARY CHECKS (HIGH)
```
Current Logic: target_exposure.abs() > max_position

Problem:
  - At position=2.0, max_position=2.0
  - Check: 2.0 > 2.0? NO → Action allowed
  - Should: 2.0 >= 2.0? YES → Action blocked

Fix Required: Change > to >= for boundary enforcement
```

### Issue #4: EXCESSIVE MASKING IN MODERATE CONDITIONS (HIGH)
```
Scenario:
  - position: 0.5
  - portfolio_value: 100,000
  - cash_reserve: 20,000

Expected: ~50% of actions masked (22-23 valid)
Observed: 100% of actions masked (0 valid)

Root Cause: Unknown (multiple constraints failing simultaneously)

Fix Required: Add detailed logging to identify culprit constraint
```

---

## Constraint Implementation Status

| Constraint | Status | Coverage | Notes |
|-----------|--------|----------|-------|
| **Position Limit** | PARTIAL | 50% | Boundary condition bug (> vs >=) |
| **Drawdown** | WORKING | 100% | Correctly filters aggressive actions |
| **VaR** | BROKEN | 0% | Logic error in formula |
| **Cash Reserve** | PARTIAL | 67% | Too aggressive with HOLD actions |
| **Position-Reducing** | WORKING | 100% | Always allows SELL/FLAT |

---

## Performance Metrics

### Masking Speed: ✓ EXCELLENT
- **Average Time**: 0 µs per call (1000 iterations)
- **Requirement**: <1ms per call
- **Status**: **PASS** (far exceeds requirement)

### Action Diversity Preservation: ✗ FAIL
- **Expected Masking Rate**: 30-50%
- **Observed Masking Rate**: Highly variable (0-100%)

**Observed Masking Rates**:

| Scenario | Valid Actions | Masking Rate | Status |
|----------|--------------|--------------|--------|
| Flat portfolio | 0/45 | 100% | CRITICAL |
| Long position | 45/45 | 0% | May indicate incomplete checks |
| Short position | 45/45 | 0% | May indicate incomplete checks |
| Low cash | 9/45 | 80% | Acceptable for this scenario |
| Large portfolio | 27/45 | 40% | Within expected range |

---

## Test Coverage Assessment

### Required Coverage (from specification):
- Position limit masking (4 tests): **2/4 PASS (50%)** ⚠️
- Drawdown masking (3 tests): **2/3 PASS (67%)**
- VaR masking (3 tests): **0/3 PASS (0%)** ❌ CRITICAL
- Cash reserve masking (2 tests): **2/2 PASS (100%)**
- Position-reducing actions (3 tests): **3/3 PASS (100%)**
- Action diversity preservation: **0/1 PASS (0%)** ❌ CRITICAL

### Gap Analysis:
- **VaR masking**: Not working at all (0% pass rate)
- **Position limits**: Boundary condition handling broken (50% pass rate)
- **Action diversity**: Not preserved as required (0% pass rate)

---

## Detailed Failure Analysis

### Failure #1: test_valid_actions_include_hold (Line 415)

**Assertion**:
```rust
assert!(!valid_holds.is_empty(), "HOLD action should always be valid for position 0")
```

**Problem Scenario**:
- position: 0.0
- portfolio_value: 100,000
- cash_reserve: 5,000
- min_cash_required: 20,000

**Root Cause Chain**:
1. Cash check: 5,000 < 20,000 → TRUE (violates)
2. HOLD action still calculates transaction_cost
3. Cash after transaction: 5,000 - cost < 20,000 → TRUE (violates all)
4. Result: ALL 45 actions masked, including HOLD

**Design Issue**:
HOLD actions should be exempt from transaction cost checks because HOLD = no position change = zero transaction cost.

### Failure #2: test_mask_actions_violating_var (Line 211)

**Assertion**:
```rust
assert!(!violates_var, "Action {} should not violate VaR limit", idx)
```

**Problem Scenario**:
- position: 2.0 (high exposure)
- portfolio_value: 50,000
- var_limit_pct: 5.0
- var_dollar: 2,500

**VaR Logic Issue**:
```rust
// Current implementation (WRONG):
let var_dollar = self.portfolio_value * (self.var_limit_pct / 100.0);
let exposure_change = action.target_exposure().abs() - self.position.abs();
let potential_loss = var_dollar * exposure_change.abs();
potential_loss > var_dollar  // This is backwards!
```

**Problem**:
- When `exposure_change > 1.0`, `potential_loss > var_dollar` always TRUE
- Masks too many actions in high-exposure scenarios

### Failure #3: test_mask_all_long_actions_at_max_long (Line 319)

**Assertion**:
```rust
assert!(valid_buys.is_empty(), "BUY actions should all be masked at max position")
```

**Problem Scenario**:
- position: 2.0 (at maximum allowed)
- max_position: 2.0
- Action: BUY (would increase exposure)

**Root Cause**:
```rust
// Current (WRONG):
target_exposure.abs() > max_position

// Example:
// pos=2.0, target=2.0, check: 2.0 > 2.0? NO → Action allowed (WRONG!)
// Should be:
// target_exposure.abs() >= max_position
```

### Failure #4: test_mask_all_short_actions_at_max_short (Line 365)

**Assertion**:
```rust
assert!(valid_sells.is_empty(), "SELL actions should all be masked at min position")
```

**Problem Scenario**:
- position: -2.0 (at minimum/maximum short)
- max_position: 2.0
- Action: SELL (would decrease exposure)

**Root Cause**: Same as Failure #3 (boundary condition using `>` instead of `>=`)

### Failure #5: test_action_diversity_with_masking (Line 510)

**Assertion**:
```rust
assert!(exposure_types.len() > 1, "Masking should preserve exposure type diversity")
```

**Problem Scenario**:
- position: 0.5
- portfolio_value: 100,000
- cash_reserve: 20,000

**Observed**:
- valid_actions.len() = 0
- expected_actions.len() >= 22

**Root Cause**:
Combined effect of multiple constraint failures. Some constraint check is too aggressive in this reasonable portfolio state.

---

## Recommendations

### PRIORITY 1 - CRITICAL FIXES (Required for deployment, ~30-45 minutes)

1. **Fix Position Limit Boundary Checks**
   - File: `ml/tests/risk_action_masking_test.rs` → `PortfolioState::violates_position_limit()`
   - Change: Replace `>` with `>=`
   - Impact: Fixes 2 test failures (tests #3, #4)
   - Effort: 5 minutes

2. **Fix Cash Reserve for HOLD Actions**
   - File: `ml/tests/risk_action_masking_test.rs` → `PortfolioState::violates_cash_reserve()`
   - Change: Exempt HOLD actions from transaction cost checks
   - Impact: Fixes 1 test failure (test #1)
   - Effort: 10 minutes

3. **Fix VaR Constraint Logic**
   - File: `ml/tests/risk_action_masking_test.rs` → `PortfolioState::violates_var_limit()`
   - Change: Review and correct potential_loss calculation
   - Impact: Fixes 1-2 test failures (test #2, potentially #5)
   - Effort: 15 minutes

### PRIORITY 2 - INVESTIGATION (To understand excessive masking)

1. **Debug Excessive Masking in Moderate Scenarios**
   - Add detailed logging to each constraint check
   - Identify which constraint is over-aggressive
   - Suggested: Create a debug trace function that logs each constraint result

2. **Validate Masking Rates**
   - Current: 0-100% (unacceptable variation)
   - Target: 30-50% masking rate
   - Adjust thresholds or constraint combinations as needed

### PRIORITY 3 - TESTING (Post-fix validation)

1. **Add Edge Case Tests**
   - Boundary conditions (position at exactly ±max_position)
   - Very small portfolios
   - Very large portfolios

2. **Add Stress Tests**
   - Extreme market scenarios
   - Rapid market moves
   - Flash crash scenarios

3. **Validate Action Diversity**
   - Ensure >50% of actions remain valid in reasonable scenarios
   - Confirm diverse action types (exposure, order, urgency) are preserved

---

## Implementation Notes

### For Test File Reference

The test file uses a `PortfolioState` helper struct with constraint check methods:

```rust
pub struct PortfolioState {
    pub position: f64,           // Current position (-2.0 to +2.0)
    pub portfolio_value: f64,    // Portfolio value in dollars
    pub cash_reserve: f64,       // Cash reserve in dollars
    pub peak_value: f64,         // Peak value (for drawdown)
    pub var_limit_pct: f64,      // VaR limit (5.0% default)
}

// Key methods to fix:
fn violates_position_limit(&self, action: &FactoredAction, max_position: f64) -> bool
fn violates_drawdown_limit(&self, action: &FactoredAction, max_drawdown_pct: f64) -> bool
fn violates_var_limit(&self, action: &FactoredAction) -> bool
fn violates_cash_reserve(&self, action: &FactoredAction) -> bool
```

---

## Final Verdict

| Aspect | Result |
|--------|--------|
| **Test Status** | FAILED (10/15 passing) |
| **Deployment Ready** | ❌ NO |
| **Critical Issues** | 4 (VaR, positions, HOLD, diversity) |
| **Risk Level** | HIGH |
| **Estimated Fix Time** | 30-45 minutes |
| **Effort Level** | Low-Medium |

### Go/No-Go Decision: **NO-GO FOR DEPLOYMENT**

**Blocking Issues**:
1. ❌ VaR constraint completely broken (0% pass rate)
2. ❌ Position limit boundary checks have off-by-one errors
3. ❌ Cash reserve checks too aggressive (masks all actions in reasonable scenarios)
4. ❌ Action diversity not preserved as required by specification

**Actions Required Before Deployment**:
1. Fix 3 critical constraint logic errors
2. Validate masking rates fall within 30-50% range
3. Re-run all 15 tests (target: 15/15 passing)
4. Add stress tests for edge cases

---

## Appendix: Performance Summary

**Masking Speed Performance** (Test: test_action_mask_performance):
- 1,000 iterations completed
- Average time per call: 0 µs (sub-microsecond)
- Total execution: <5ms
- Requirement met: YES ✓

**Consistency Test Results** (Test: test_risk_masking_consistency_across_scenarios):
- Flat portfolio: 0% valid (100% masked)
- Long position: 100% valid (0% masked)
- Short position: 100% valid (0% masked)
- Low cash: 20% valid (80% masked)
- Large portfolio: 60% valid (40% masked)

**Pattern Observed**:
- Extreme scenarios (flat/max-long/max-short) show extreme masking rates
- Moderate scenarios (low cash, large portfolio) show reasonable rates
- Suggests constraint interactions need tuning