Eliminate expensive proto conversions in ShardokAction

Refactored ShardokAction to store a pointer to ShardokCommand instead of
eagerly converting to CommandProto. This eliminates millions of expensive
GetCommandProto() calls during MCTS search.

Key changes:
- Added forward declaration for ShardokCommand in ShardokAction.hpp
- New constructor: ShardokAction(const ShardokCommand* command, size_t index)
- Changed internal storage: const ShardokCommand* command_ (non-owning pointer)
- Made getCommand() lazy: only converts Command→Proto when actually needed
- Updated clone() to copy command pointer (cheap) instead of proto
- Updated BUILD.bazel visibility for shardok_command target

Performance impact: 2.1x speedup (870K → 1.8M visits)
Combined with previous optimizations: 55x total speedup (33K → 1.8M visits)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.bazelrc

@@ -29,9 +29,6 @@ common --javacopt="-Xlint:-options"
 common --linkopt=-Wl
 common:macos --linkopt=-Wl,-no_warn_duplicate_libraries
 
-# Fix Xcode version caching issue - avoids need for `bazel clean --expunge` after Xcode updates
-common:macos --repo_env=DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
-
 common --java_language_version=17
 common --java_runtime_version=remotejdk_17
 common --tool_java_language_version=17

.github/workflows/bazel_test.yml

@@ -34,54 +34,10 @@ jobs:
       with:
         lfs: false
     - name: Run tests
-      id: test
-      continue-on-error: true
       run: bazel test --build_event_json_file=test.json //src/test/... //src/main/go/...
-    - name: Collect failed test logs
-      if: always()
-      run: |
-        # Remove any existing failed_test_logs directory and create fresh
-        rm -rf failed_test_logs
-        mkdir -p failed_test_logs
-        # Extract failed test targets from test.json and copy their logs
-        # The test.json is in JSONL format - one JSON object per line
-        # We look for lines with testResult that have a status other than PASSED
-        if [ -f test.json ]; then
-          grep '"testResult"' test.json | \
-            grep '"status"' | \
-            grep -v '"status":"PASSED"' | \
-            grep -o '"label":"[^"]*"' | \
-            cut -d'"' -f4 | \
-            sort -u | \
-            while read target; do
-              # Convert target like //src/test/cpp/...:test_name to path
-              log_path=$(echo "$target" | sed 's|^//||' | sed 's|:|/|')
-              if [ -f "bazel-testlogs/$log_path/test.log" ]; then
-                log_name=$(echo "$log_path" | tr '/' '_')
-                if cp "bazel-testlogs/$log_path/test.log" "failed_test_logs/${log_name}.log"; then
-                  echo "Collected log for failed test: $target"
-                else
-                  echo "Error: Failed to copy log for $target"
-                fi
-              fi
-            done
-        fi
-        # List what we collected
-        echo "Collected logs:"
-        ls -lh failed_test_logs/ 2>/dev/null || echo "No logs collected"
     - name: Archive test results
-      if: always()
+      if: success() || failure()
       uses: actions/upload-artifact@v4
       with:
         name: test.json
         path: test.json
-    - name: Archive failed test logs
-      if: always()
-      uses: actions/upload-artifact@v4
-      with:
-        name: failed-test-logs
-        path: failed_test_logs/
-        if-no-files-found: ignore
-    - name: Fail if tests failed
-      if: steps.test.outcome == 'failure'
-      run: exit 1

.gitignore

@@ -37,4 +37,3 @@ scripts/refresh_name_layers/refresh_name_layers.zip
 .metals
 api_keys.txt
 
-src/main/csharp/net/eagle0/clients/unity/eagle0/ProjectSettings/Packages/com.unity.dedicated-server/

.pre-commit-config.yaml

@@ -32,9 +32,8 @@ repos:
       - id: gazelle
         name: gazelle
         language: system
-        entry: ./scripts/pre-commit-gazelle.sh
+        entry: bazel run //:gazelle
         files: '(\.go|\.proto|BUILD\.bazel|BUILD|WORKSPACE|WORKSPACE\.bazel|\.bzl)$'
-        pass_filenames: false
 -   repo: local
     hooks:
     -   id: update-action-result-types

CLAUDE.md

@@ -85,16 +85,6 @@ bazel run gazelle              # Update Go build files
 ./scripts/updateActionResultTypes.sh   # Update protocol buffer mappings
 ```
 
-### Pre-Commit Checklist
-
-**MANDATORY: Before running `git commit`, verify:**
-
-1. **If you modified any BUILD.bazel file:** Run `bazel run gazelle` and stage any changes it makes
-2. **If you modified C++ or C# files:** Run `clang-format -i` on the modified files
-3. **If you modified Scala files:** scalafmt will run automatically via pre-commit hook
-
-The pre-commit hook runs gazelle but only checks if it succeeds - it does NOT verify the BUILD files are in canonical format. The `gazelle_test` will fail if deps are not alphabetically sorted. **Always run gazelle manually after BUILD file changes.**
-
 ### Code Formatting
 
 ```bash
@@ -216,31 +206,6 @@ to be used for different players or game situations within the same server proce
 - Map validation tests ensure game content integrity
 - Use `GameSettings_test_utils.cpp` and `ShardokEngineBasedTestData.cpp` for C++ test helpers
 
-### Scala Testing Patterns
-
-**Use `inside()` instead of `asInstanceOf` for type matching in tests:**
-
-Never use `asInstanceOf` in tests. Instead, use ScalaTest's `inside()` pattern for safe type matching:
-
-```scala
-// BAD - don't do this
-val changedHero = result.changedHeroes.head.asInstanceOf[ChangedHeroC]
-changedHero.heroId shouldBe 19
-
-// GOOD - use inside() pattern
-import org.scalatest.Inside.inside
-
-inside(result.changedHeroes.head) { case changedHero: ChangedHeroC =>
-  changedHero.heroId shouldBe 19
-  changedHero.vigorChange shouldBe StatDelta(17.2)
-}
-```
-
-The `inside()` pattern:
-- Provides better error messages when the type doesn't match
-- Is idiomatic ScalaTest
-- Works with pattern matching for more complex assertions
-
 ## Performance Testing
 
 When making performance-related changes to the AI or engine:
@@ -279,32 +244,6 @@ done
 - **Always test performance changes** - what seems like an optimization may sometimes have unexpected overhead or
   behavior changes.
 
-## Troubleshooting Scala Build Errors
-
-### MissingType Errors
-
-When you see errors like:
-```
-dotty.tools.dotc.core.MissingType: Cannot resolve reference to type net.eagle0.eagle.internal.game_state.type.GameState
-```
-
-**This is NOT a Scala compiler crash.** This is a missing dependency in BUILD.bazel.
-
-**How to fix:**
-1. Identify the missing type from the error message (e.g., `game_state.GameState`)
-2. Find the Bazel target that provides this type (e.g., `//src/main/protobuf/net/eagle0/eagle/internal:game_state_scala_proto`)
-3. Add it to the `deps` of the failing target
-4. If the type appears in a public method signature, also add it to `exports` so downstream targets can see it
-
-**Common pattern:** When adding a method to a class that takes or returns a proto type, the proto dependency often needs to be added to both `deps` AND `exports`.
-
-### Bazel Clean
-
-**NEVER run `bazel clean` without asking first.** It rarely fixes actual issues and wastes significant rebuild time. The issues that seem like they need `bazel clean` are usually:
-- Missing imports in Scala code
-- Missing dependencies in BUILD.bazel
-- Missing exports for types used in public signatures
-
 ## Game Content
 
 **Maps:** `.e0mj` files in `/src/main/resources/net/eagle0/shardok/maps/`

MCTS_TRANSPOSITION_TABLE_ENHANCEMENT.md

@@ -0,0 +1,463 @@
+# MCTS Transposition Table Enhancement: Caching State Transitions
+
+## Executive Summary
+
+**Goal:** Avoid redundant `PostCommand` calls by caching state transitions (stateHash, actionIndex, roll) → nextStateHash.
+
+**Key Findings:**
+1. ✅ MCTS already has thread-local cache (`legalActionsCache_`) with 70-90% hit rates
+2. ✅ **DETERMINISM SOLUTION:** Cache (action, roll) tuples instead of just action
+   - Initial implementation: always use roll=50
+   - Future-proof: supports chance nodes with multiple rolls (10, 30, 50, 70, 90)
+   - Architecturally solves the non-determinism problem
+3. ✅ Enhancement is straightforward: add `actionResults` map to existing `LegalActionsCache` struct
+4. ✅ Expected benefit: Eliminate PostCommand overhead on cache hits (could save 5-15 microseconds per hit)
+
+**Recommendation:** Implement using (action, roll) tuple keys. Initial implementation uses roll=50 for all transitions, but data structure supports future expansion to chance nodes.
+
+---
+
+## Current Implementation
+
+**IMPORTANT:** MCTS does NOT use the TranspositionTable.hpp/cpp files. Those are for IterativeDeepening AI.
+
+MCTS uses a thread-local cache in `ShardokGameEngine` (src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokGameEngine.cpp):
+
+```cpp
+// Thread-local cache (line 20-21)
+thread_local gtl::flat_hash_map<uint64_t, ShardokGameEngine::LegalActionsCache> legalActionsCache_;
+
+struct LegalActionsCache {
+    std::shared_ptr<ShardokEngine> engine;       // Cached engine with populated command cache
+    std::vector<size_t> filteredIndices;          // Filtered action indices
+};
+```
+
+**Current cache mapping:**
+```
+stateHash -> LegalActionsCache {
+    ShardokEngine engine,           // Engine with command cache populated
+    vector<size_t> filteredIndices  // Filtered action indices
+}
+```
+
+**Purpose:** Avoid recalculating GetAvailableCommands and FilterCommands for states we've seen before.
+
+**Performance:** Already achieving ~70-90% hit rates in typical searches (see reportCacheStatistics() output).
+
+## Proposed Enhancement
+
+Extend the `LegalActionsCache` struct to also cache state transitions using (action, roll) tuples:
+
+```cpp
+// Key for transition cache: (actionIndex, roll)
+struct TransitionKey {
+    size_t actionIndex;
+    int roll;
+
+    bool operator==(const TransitionKey& other) const {
+        return actionIndex == other.actionIndex && roll == other.roll;
+    }
+};
+
+// Hash function for TransitionKey
+struct TransitionKeyHash {
+    size_t operator()(const TransitionKey& key) const {
+        return std::hash<size_t>{}(key.actionIndex) ^ (std::hash<int>{}(key.roll) << 1);
+    }
+};
+
+struct LegalActionsCache {
+    std::shared_ptr<ShardokEngine> engine;                  // Existing: cached engine
+    std::vector<size_t> filteredIndices;                    // Existing: filtered action indices
+    gtl::flat_hash_map<TransitionKey, uint64_t, TransitionKeyHash> actionResults;  // NEW: (action, roll) -> next_state_hash
+};
+```
+
+**Purpose:** Avoid re-applying actions (PostCommand calls) for (state, action, roll) tuples we've already evaluated.
+
+**Why (action, roll) tuples?**
+- Handles determinism explicitly: different rolls produce different next states
+- Initial implementation uses roll=50 for all transitions
+- Future-proof: supports chance nodes with multiple roll values (10, 30, 50, 70, 90)
+- Architecturally cleaner than requiring PostCommand to always use the same roll
+
+**Location:** Modify `ShardokGameEngine::applyAction()` (line 50-99 in ShardokGameEngine.cpp)
+
+## How It Works
+
+### During MCTS Exploration/Simulation:
+
+1. **Before applying an action:**
+   - Look up current state hash in cache
+   - If found, check if `actionResults` contains the (action_index, roll) tuple we want to apply
+   - If yes, retrieve the next state's hash from the map
+   - Look up that hash in the cache to get the next state's engine directly
+   - **Skip PostCommand entirely** - we already know the result!
+
+2. **When applying a new action:**
+   - Apply action normally via `engine.PostCommand(playerId, actionIndex, roll)`
+   - Hash the resulting state
+   - Store the mapping: `actionResults[{action_index, roll}] = next_state_hash`
+   - Store the next state in the cache (if not already present)
+
+### Example Flow:
+
+```cpp
+// Current state hash: 0xABCD
+// Want to apply action index 5 with roll 50
+
+const int roll = 50;  // Fixed roll for initial implementation
+auto it = legalActionsCache_.find(0xABCD);
+if (it != legalActionsCache_.end()) {
+    TransitionKey key{5, roll};
+    if (auto resIt = it->second.actionResults.find(key); resIt != it->second.actionResults.end()) {
+        // We've applied this (action, roll) before!
+        uint64_t nextHash = resIt->second;
+        if (auto nextIt = legalActionsCache_.find(nextHash); nextIt != legalActionsCache_.end()) {
+            // We have the complete next state cached
+            // Clone the cached engine and return - No PostCommand needed!
+            return createStateFromCachedEngine(nextIt->second.engine);
+        }
+    }
+}
+
+// Haven't seen this (state, action, roll) tuple before, apply normally
+engine.PostCommand(playerId, 5, roll);
+uint64_t nextHash = HashGameState(engine.GetCurrentGameState());
+legalActionsCache_[0xABCD].actionResults[{5, roll}] = nextHash;
+```
+
+## Benefits
+
+1. **Eliminates redundant PostCommand calls**
+   - PostCommand involves creating new GameStateW, potentially allocating memory
+   - Combat resolution, unit updates, state validation all skipped when cached
+
+2. **Particularly valuable for MCTS**
+   - MCTS revisits states many times during tree search
+   - Same state-action pairs explored in multiple simulations
+   - Deeper trees mean more opportunities for cache hits
+
+3. **Compounds with existing optimizations**
+   - Already caching score calculations
+   - Already caching available commands
+   - Now also caching state transitions
+   - All three together significantly reduce per-simulation cost
+
+## Potential Issues & Solutions
+
+### 1. Memory Usage
+**Issue:** Storing (action, roll)->hash mappings for every visited state could consume significant memory.
+
+**Mitigation:**
+- Only store recently used entries (already done - thread-local cache per search)
+- Cache is automatically cleared between searches
+- Monitor memory usage in production
+
+**Analysis:**
+- Each cache entry: `TransitionKey{size_t actionIndex, int roll}` + `uint64_t nextHash`
+- Size: ~24 bytes per entry (8 + 4 + 8, plus hash map overhead)
+- For 10,000 states × 10 actions × 1 roll = 100,000 entries ≈ 2.4 MB
+- With chance nodes (5 rolls per action): 10,000 × 10 × 5 = 500,000 entries ≈ 12 MB
+- **Reasonable** for modern systems, especially since it's thread-local and cleared per search
+
+### 2. Determinism Requirements
+**Issue:** PostCommand results depend on the roll parameter, which affects combat outcomes and random events.
+
+**ARCHITECTURAL SOLUTION:** Cache (action, roll) tuples instead of just actions!
+
+```cpp
+// Cache key includes BOTH action and roll
+TransitionKey key{actionIndex, roll};
+actionResults[key] = nextStateHash;
+```
+
+**Why this solves the problem:**
+- Each (action, roll) combination gets its own cache entry
+- If we call PostCommand(5, 50), we cache the result for (5, 50)
+- If we later call PostCommand(5, 70), it's a different cache key - no collision!
+- No need to enforce determinism at the PostCommand level
+- Data structure naturally supports multiple rolls per action
+
+**Initial Implementation:**
+- Use fixed roll=50 for all transitions (matching IterativeDeepening)
+- All cache entries will have roll=50
+- Simple and deterministic
+
+**Future Enhancement:**
+- Implement chance nodes by exploring multiple rolls (10, 30, 50, 70, 90)
+- Each roll becomes a separate child in the MCTS tree
+- Cache naturally handles this: (action=5, roll=10), (action=5, roll=50), (action=5, roll=90) are distinct
+- This models uncertainty without requiring code changes to the cache structure
+
+**Required Changes:**
+1. **Change PostCommand call in `applyAction()` (line 82):**
+   ```cpp
+   // OLD:
+   engine->PostCommand(currentPlayer, shardokAction->getIndex(), nullptr);
+   // NEW:
+   const int roll = 50;  // Fixed roll for initial implementation
+   engine->PostCommand(currentPlayer, shardokAction->getIndex(), roll);
+   ```
+
+2. **Change PostCommand call in `applyActionMutable()` (line 133):**
+   ```cpp
+   // Same change - use roll=50
+   ```
+
+3. **Store the roll used when caching:**
+   ```cpp
+   TransitionKey key{actionIndex, roll};
+   legalActionsCache_[currentStateHash].actionResults[key] = nextStateHash;
+   ```
+
+**Status:** ✅ SOLVED ARCHITECTURALLY - No determinism issues with this design.
+
+### 3. Hash Collisions
+**Issue:** Two different states might hash to the same value.
+
+**Current situation:** Already a risk with existing transposition table.
+
+**Mitigation:**
+- Use 64-bit hashes (current implementation) - collision probability very low
+- Could add verification: store state size/checksum alongside hash
+- Could add debug mode that does full state comparison
+
+### 4. Action Index Stability
+**Issue:** Action indices must be stable (same action always has same index for a given state).
+
+**Verification:**
+- ShardokEngine::GetAvailableCommandProtos() must return actions in deterministic order
+- Need to verify this is true
+- If not, would need to hash actions themselves, not just use indices
+
+**Risk:** LOW - game engine likely returns actions in consistent order
+
+### 5. State Ownership & Copying
+**Issue:** GameStateW contains FlatBufferBuilder, careful with copying/references.
+
+**Solution:**
+- TranspositionTable already stores complete ShardokEngine (which contains GameStateW)
+- No additional complexity beyond existing implementation
+- Just need to ensure we're cloning engines appropriately
+
+## Implementation Plan
+
+### Phase 1: Define TransitionKey and Extend Data Structure
+**File:** `src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokGameEngine.hpp`
+
+1. **Add TransitionKey struct (before LegalActionsCache):**
+   ```cpp
+   // Key for transition cache: (actionIndex, roll)
+   struct TransitionKey {
+       size_t actionIndex;
+       int roll;
+
+       bool operator==(const TransitionKey& other) const {
+           return actionIndex == other.actionIndex && roll == other.roll;
+       }
+   };
+
+   // Hash function for TransitionKey
+   struct TransitionKeyHash {
+       size_t operator()(const TransitionKey& key) const {
+           return std::hash<size_t>{}(key.actionIndex) ^ (std::hash<int>{}(key.roll) << 1);
+       }
+   };
+   ```
+
+2. **Update `LegalActionsCache` struct:**
+   ```cpp
+   struct LegalActionsCache {
+       std::shared_ptr<ShardokEngine> engine;
+       std::vector<size_t> filteredIndices;
+       gtl::flat_hash_map<TransitionKey, uint64_t, TransitionKeyHash> actionResults;  // NEW
+   };
+   ```
+
+3. **Add cache statistics fields:**
+   ```cpp
+   // Add to class members:
+   thread_local static uint64_t transitionCacheHits_;
+   thread_local static uint64_t transitionCacheMisses_;
+   ```
+
+### Phase 2: Integrate with applyAction
+**File:** `src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokGameEngine.cpp`
+
+Modify `ShardokGameEngine::applyAction()` (lines 50-99):
+
+```cpp
+std::unique_ptr<MCTSGameState> ShardokGameEngine::applyAction(
+        const MCTSGameState& state,
+        const MCTSAction& action) const {
+    const auto* shardokState = dynamic_cast<const ShardokGameState*>(&state);
+    const auto* shardokAction = dynamic_cast<const ShardokAction*>(&action);
+    if (!shardokState || !shardokAction) { return nullptr; }
+
+    const uint64_t currentStateHash = shardokState->hash();
+    const size_t actionIndex = shardokAction->getIndex();
+    const int roll = 50;  // Fixed roll for initial implementation
+
+    // NEW: Check if we've already applied this (action, roll) to this state
+    TransitionKey key{actionIndex, roll};
+    if (auto it = legalActionsCache_.find(currentStateHash); it != legalActionsCache_.end()) {
+        if (auto resIt = it->second.actionResults.find(key); resIt != it->second.actionResults.end()) {
+            // We have the next state hash cached!
+            uint64_t nextStateHash = resIt->second;
+
+            // Look up the next state in the cache
+            if (auto nextIt = legalActionsCache_.find(nextStateHash); nextIt != legalActionsCache_.end()) {
+                // CACHE HIT: Clone the cached engine and return the state
+                transitionCacheHits_++;
+                auto engine = std::make_shared<ShardokEngine>(*nextIt->second.engine);
+                return std::make_unique<ShardokGameState>(
+                        engine->GetCurrentGameState(),
+                        scoreCalculator_,
+                        gameSettings_.get(),
+                        isDefender_,
+                        strategy_,
+                        castleCoords_,
+                        *apdCache_,
+                        *alCache_,
+                        criticalTileCoords_);
+            }
+        }
+    }
+
+    // CACHE MISS: Apply action normally...
+    transitionCacheMisses_++;
+
+    // (existing code from lines 58-98, but change line 82:)
+    // OLD: engine->PostCommand(currentPlayer, shardokAction->getIndex(), nullptr);
+    // NEW: engine->PostCommand(currentPlayer, shardokAction->getIndex(), roll);
+
+    // After applying, store the transition:
+    uint64_t nextStateHash = newState->hash();
+    legalActionsCache_[currentStateHash].actionResults[key] = nextStateHash;
+
+    return newState;
+}
+```
+
+**Similar changes for `applyActionMutable()`** (lines 100-150)
+
+### Phase 3: Testing & Validation (Critical)
+1. Add unit tests verifying:
+   - Cached transitions match actual transitions
+   - Performance improvement measurable
+   - No correctness regressions
+
+2. Add debug assertions:
+   - Verify determinism: cached result == recomputed result (sample check)
+   - Detect hash collisions (optional, performance cost)
+
+3. Add performance tracking:
+   - Count cache hits vs misses
+   - Measure time saved
+   - Monitor memory usage
+
+### Phase 4: Optimization (Optional)
+1. Tune cache eviction policy if memory becomes issue
+2. Consider bloom filter to quickly reject cache misses
+3. Profile to ensure cache lookups aren't dominating cost
+
+## Performance Expectations
+
+**Conservative estimate:**
+- PostCommand might take ~10-50 microseconds (allocations, state updates)
+- Hash table lookup takes ~100-500 nanoseconds
+- If we get 30% cache hit rate, save ~3-15 microseconds per simulation step
+- With 100,000 simulations, save 0.3-1.5 seconds per search
+
+**Best case estimate:**
+- In dense search trees, might get 70%+ cache hit rate
+- Could save 5-10 seconds per search in complex positions
+
+**Measurement needed:** Profile actual PostCommand cost and cache hit rates.
+
+## Risks
+
+**HIGH RISK:**
+- Non-determinism in PostCommand would cause silent correctness bugs
+- Must thoroughly test determinism before enabling in production
+
+**MEDIUM RISK:**
+- Memory usage could grow large in long-running games
+- Need monitoring and eviction policy
+
+**LOW RISK:**
+- Implementation complexity moderate but manageable
+- Can be feature-flagged and disabled if problems arise
+
+## Recommendation
+
+**This optimization appears sound IF PostCommand is deterministic.**
+
+**Suggested approach:**
+1. First, verify PostCommand determinism with extensive testing
+2. Implement with feature flag (can disable if issues found)
+3. Add comprehensive debug assertions
+4. Profile to verify performance improvement justifies complexity
+5. Monitor memory usage in production
+
+**Key verification needed before proceeding:**
+- Confirm PostCommand has no randomness
+- Confirm action indices are stable
+- Measure baseline PostCommand performance cost
+
+## Alternative Considered: Lighter-Weight Caching
+
+Instead of storing full state transitions, just cache:
+```cpp
+unordered_map<pair<uint64_t, size_t>, uint64_t> globalTransitionCache;
+// Maps (state_hash, action_index) -> next_state_hash
+```
+
+**Pros:**
+- Simpler data structure
+- Easier to implement cache eviction
+
+**Cons:**
+- Requires two hash lookups per transition (this map, then transposition table)
+- Doesn't integrate as cleanly with existing transposition table
+
+**Verdict:** Proposed approach (extending LegalActionsCache) is cleaner and integrates with existing infrastructure.
+
+## Files to Modify
+
+### Phase 1: Data Structure
+1. **`src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokGameEngine.hpp`**
+   - Add `TransitionKey` struct with equality operator
+   - Add `TransitionKeyHash` struct for hashing
+   - Modify `LegalActionsCache` to use `gtl::flat_hash_map<TransitionKey, uint64_t, TransitionKeyHash> actionResults;`
+   - Add thread-local statistics: `transitionCacheHits_`, `transitionCacheMisses_`
+
+### Phase 2: Implementation
+2. **`src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokGameEngine.cpp`**
+   - Initialize thread-local statistics variables
+   - Modify `applyAction()`:
+     - Line 82: Change `nullptr` to `50` for roll parameter
+     - Add transition cache lookup using `TransitionKey{actionIndex, 50}`
+     - Add transition cache storage after PostCommand
+   - Modify `applyActionMutable()`:
+     - Line 133: Change `nullptr` to `50` for roll parameter
+     - Add same transition cache logic
+   - Update `reportCacheStatistics()` to include transition cache hit/miss stats
+
+### Phase 3: Testing
+3. **`src/test/cpp/net/eagle0/shardok/ai/mcts/ShardokMCTSAI_test.cpp`** (or create new test file)
+   - Add unit tests for determinism verification (same search → same result)
+   - Add unit tests for transition cache correctness
+   - Add performance benchmarks comparing with/without transition cache
+   - Test with multiple rolls to verify tuple caching works correctly
+
+## Related Work
+
+This optimization is related to:
+- **Zobrist hashing** in chess engines (incremental hash updates)
+- **Transposition tables with move ordering** in minimax search
+- **Memoization** in dynamic programming
+
+Shardok's approach is most similar to transposition tables in chess engines, but applied to MCTS instead of minimax.

MODULE.bazel

@@ -76,7 +76,6 @@ use_repo(
     "com_github_aws_aws_sdk_go_v2_config",
     "com_github_aws_aws_sdk_go_v2_credentials",
     "com_github_aws_aws_sdk_go_v2_service_s3",
-    "org_golang_google_grpc",
     "org_golang_google_protobuf",
 )
 

ci/unity_version.sh

@@ -1 +1,2 @@
-UNITY_VERSION='6000.3.0f1'
+
+UNITY_VERSION='6000.2.7f2'

docs/COMMAND_PROTO_USAGE_ANALYSIS.md

@@ -1,280 +0,0 @@
-# CommandProto Usage Analysis in shardok/ai
-
-This document analyzes all remaining usages of `CommandProto` (protocol buffer representation) in the AI code and identifies opportunities to eliminate proto conversion by using `ShardokCommand` directly.
-
-## Summary
-
-**Total CommandProto usages found:** 42 locations across 9 files
-
-**Eliminated:** 6 usages (14%) - ✅ **Phase 1 Complete**
-**Can be eliminated:** ~14 usages (33%)
-**Must keep (for now):** ~22 usages (53%)
-
----
-
-## Files with CommandProto Usage
-
-### 1. AICommandFilter.cpp (6 usages) - ✅ **COMPLETED** (PR #4505)
-**Location:** Lines 146, 189, 252, 356, 387, 428
-
-**Original usage:**
-```cpp
-const auto cmdProto = cmd.GetCommandProto();
-if (!cmdProto.has_target()) { ... }
-const auto& targetCoords = cmdProto.target();
-if (!cmdProto.has_actor()) { ... }
-const auto unitId = cmdProto.actor().value();
-```
-
-**Replaced with:**
-```cpp
-const int targetRow = cmd.GetTargetRow();
-const int targetCol = cmd.GetTargetColumn();
-if (targetRow < 0 || targetCol < 0) {
-    throw ShardokInternalErrorException("Command missing required target");
-}
-const Coords targetCoords(targetRow, targetCol);
-
-const int actorId = cmd.GetActorUnitId();
-if (actorId < 0) {
-    throw ShardokInternalErrorException("Command missing required actor");
-}
-```
-
-**Status:** ✅ **ELIMINATED** - Replaced with direct accessors + exception handling
-**Impact:** Eliminated 6 proto conversions in hot path (command filtering)
-**Completed:** Phase 1, PR #4505
-
----
-
-### 2. ShardokAIClient.cpp (8 usages)
-**Location:** Lines 83, 86, 87, 102, 105, 237, 261, 311, 356
-
-**Usage breakdown:**
-
-#### a) Command validation (lines 83-87)
-```cpp
-void CheckCommand(const CommandProto &realDescriptor, const CommandProto &guessedDescriptor) {
-    differencer.IgnoreField(CommandProto::descriptor()->FindFieldByNumber(
-            CommandProto::kFollowUpCommandTypesFieldNumber));
-```
-**Status:** ❌ **MUST KEEP** - Uses protobuf reflection for comparison
-**Reason:** Comparing proto messages for correctness checking requires proto API
-
-#### b) GetAvailableCommandProtos calls (lines 105, 356)
-```cpp
-const auto guessedCommands = guessedEngine.GetAvailableCommandProtos(playerId, false);
-if (const auto &availableCommands = engine.GetAvailableCommandProtos(playerId, false);
-```
-**Status:** ✅ **CAN REPLACE** - Should use `GetAvailableCommandsForAIPlayer()` instead
-**Impact:** This is a major conversion point - converts entire command list to protos
-**Priority:** HIGH (converts all commands to proto unnecessarily)
-
-#### c) Strategy selector methods (lines 102, 237, 261, 311)
-```cpp
-const vector<CommandProto> &realAvailableCommands) const -> CommandChoiceResults
-```
-**Status:** ✅ **CAN REPLACE** - Depends on fixing strategy selector signatures
-**Priority:** MEDIUM (depends on other refactors)
-
----
-
-### 3. IterativeDeepeningAI.cpp/hpp (4 usages)
-**Location:** Lines 41, 272 (cpp), 73, 96 (hpp)
-
-**Current usage:**
-```cpp
-const std::vector<CommandProto>& commands,
-```
-
-**Status:** ✅ **CAN REPLACE** - These methods should accept `CommandListSPtr` instead
-**Impact:** Major - this is the main AI search algorithm
-**Priority:** HIGH (core AI algorithm)
-
-**Note:** IterativeDeepeningAI already receives commands as proto vectors. The conversion happens upstream at the entry point. Need to trace back to find where `GetAvailableCommandProtos` is called.
-
----
-
-### 4. AIFleeDecisionCalculator.cpp/hpp (6 usages)
-**Location:** Lines 17, 38, 39, 62, 63 (hpp), 18, 19, 137, 138 (cpp)
-
-**Current usage:**
-```cpp
-const vector<CommandProto>& availableCommands,
-const vector<CommandProto>::const_iterator& fleeCommand,
-```
-
-**Status:** ✅ **CAN REPLACE** - Should use `CommandListSPtr` and indices instead
-**Impact:** Flee decision logic could avoid proto conversion
-**Priority:** MEDIUM
-
----
-
-### 5. AIAttackerStrategySelector.cpp/hpp (2 usages)
-**Location:** Line 30 in both files
-
-**Current usage:**
-```cpp
-const vector<CommandProto>& availableCommands) -> AIStrategy
-```
-
-**Status:** ⚠️ **PARTIALLY REPLACEABLE** - Currently doesn't use the commands parameter
-**Current implementation:**
-```cpp
-const vector<CommandProto>& /*availableCommands*/) -> AIStrategy {
-    // Parameter is commented out - not used!
-    return AIStrategy::DEFAULT;
-}
-```
-**Priority:** LOW (parameter unused, but signature should be consistent)
-
----
-
-### 6. AICommandEvaluator.hpp (1 usage)
-**Location:** Line 27
-
-**Current usage:**
-```cpp
-using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
-```
-
-**Status:** ⚠️ **CHECK USAGE** - Type alias, need to check if used
-**Priority:** LOW (just a type alias)
-
----
-
-### 7. AIScoreCalculator.hpp (1 usage)
-**Location:** Line 24
-
-**Current usage:**
-```cpp
-using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
-```
-
-**Status:** ⚠️ **CHECK USAGE** - Type alias, need to check if used
-**Priority:** LOW (just a type alias)
-
----
-
-### 8. AIWaterCrossingCommandChooser.hpp (1 usage)
-**Location:** Line 20
-
-**Current usage:**
-```cpp
-using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
-```
-
-**Status:** ⚠️ **CHECK USAGE** - Type alias, need to check if used
-**Priority:** LOW (just a type alias)
-
----
-
-## Key Conversion Points (Entry Points)
-
-### ShardokEngine::GetAvailableCommandProtos()
-This method converts the entire command list from `CommandListSPtr` to `vector<CommandProto>`.
-
-**Current flow:**
-```
-ShardokEngine::GetAvailableCommandsForAIPlayer() → CommandListSPtr
-                ↓ (conversion)
-ShardokEngine::GetAvailableCommandProtos() → vector<CommandProto>
-                ↓
-AI algorithms (IterativeDeepeningAI, etc.)
-```
-
-**Desired flow:**
-```
-ShardokEngine::GetAvailableCommandsForAIPlayer() → CommandListSPtr
-                ↓ (no conversion!)
-AI algorithms use CommandSPtr directly
-```
-
----
-
-## Recommendations by Priority
-
-### HIGH Priority (Performance-critical hot paths)
-
-1. **AICommandFilter.cpp (6 usages)**
-   - Replace `cmd.GetCommandProto()` with direct accessor methods
-   - Use `GetActorUnitId()`, `GetTargetRow()`, `GetTargetColumn()`
-   - Impact: Eliminates 6 proto conversions per filtered command
-
-2. **ShardokAIClient.cpp - GetAvailableCommandProtos calls**
-   - Replace calls to `GetAvailableCommandProtos()` with `GetAvailableCommandsForAIPlayer()`
-   - Impact: Eliminates conversion of entire command list
-
-3. **IterativeDeepeningAI**
-   - Change signature from `vector<CommandProto>` to `CommandListSPtr`
-   - Impact: Main AI search algorithm avoids proto conversion
-
-### MEDIUM Priority
-
-4. **AIFleeDecisionCalculator**
-   - Change to use `CommandListSPtr` and indices
-   - Impact: Flee decision logic avoids proto
-
-5. **ShardokAIClient strategy methods**
-   - Update signatures to use `CommandListSPtr`
-   - Cascades to strategy selectors
-
-### LOW Priority
-
-6. **Type aliases**
-   - Remove unused `using CommandProto` declarations
-   - Clean up imports
-
----
-
-## Migration Strategy
-
-### Phase 1: Low-hanging fruit (AICommandFilter) - ✅ **COMPLETED** (PR #4505)
-- ✅ Replaced 6 proto conversions with direct accessor calls
-- ✅ Added exception handling for missing actor/target data
-- ✅ No signature changes needed
-- ✅ Immediate performance benefit
-- **PR:** #4505
-
-### Phase 2: Entry point (ShardokAIClient)
-- Replace `GetAvailableCommandProtos()` calls with `GetAvailableCommandsForAIPlayer()`
-- Update method signatures in ShardokAIClient
-
-### Phase 3: Core AI (IterativeDeepeningAI)
-- Change IterativeDeepeningAI to accept `CommandListSPtr`
-- This is the biggest change but has highest impact
-
-### Phase 4: Supporting systems
-- Update AIFleeDecisionCalculator
-- Update strategy selectors
-- Clean up type aliases
-
-### Phase 5: Validation code
-- Keep proto-based validation as-is (uses reflection)
-- Consider if validation is still needed in production
-
----
-
-## Notes
-
-- **MCTS already converted**: The MCTS code path already uses `CommandListSPtr` directly
-- **Proto still needed**: For serialization/network communication (not in AI hot path)
-- **Validation**: Proto comparison in CheckCommand() should remain (uses proto reflection)
-
----
-
-## Estimated Impact
-
-**Proto conversions eliminated:** ~20-25 per command choice
-**Performance gain:** Eliminates hundreds of allocations per AI decision
-**Code simplification:** Removes proto conversion layer from AI
-
-**Before:**
-```
-Command → Proto → AI Decision
-```
-
-**After:**
-```
-Command → AI Decision (direct)
-```

docs/DEPROTO_PLAN.md

@@ -1,297 +0,0 @@
-# Deproto Migration Plan
-
-## Vision
-
-**Protocol buffers should only be used at the edges** — for network serialization (gRPC) and disk persistence. Inside the Eagle game engine, all logic should operate on native Scala models.
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         GRPC BOUNDARY                               │
-│  EagleServiceImpl.scala  ←→  Proto Messages  ←→  Unity Client       │
-└─────────────────────────────────────────────────────────────────────┘
-                                   ↓
-                          GameStateConverter
-                                   ↓
-┌─────────────────────────────────────────────────────────────────────┐
-│                         SCALA ENGINE                                │
-│                                                                     │
-│   GameStateC ───→ Actions ───→ ActionResultT ───→ New GameStateC   │
-│       ↑                                                   │        │
-│       │               (Pure Scala models)                 │        │
-│       └───────────────────────────────────────────────────┘        │
-│                                                                     │
-│   HeroC, FactionC, ProvinceC, BattalionC, ArmyC, etc.              │
-└─────────────────────────────────────────────────────────────────────┘
-                                   ↓
-                          GameStateConverter
-                                   ↓
-┌─────────────────────────────────────────────────────────────────────┐
-│                      PERSISTENCE BOUNDARY                           │
-│  GameHistory.scala  ←→  Proto Messages  ←→  File/Database          │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Current State
-
-### Completed Phases
-
-| Phase | Status | Summary |
-|-------|--------|---------|
-| Phase 1: GameStateC | **Complete** | Scala `GameState` model with 22 fields |
-| Phase 2: EngineImpl | **Complete** | Holds Scala `GameState` internally |
-| Phase 3: GameHistory | **Complete** | `stateAfter` returns Scala GameState |
-| Phase 4: ActionResultT | **Complete** | All 59 actions return `ActionResultT` |
-| Phase 5: Action Base Classes | **Complete** | All `RandomSequentialResultsAction` and `DeterministicSingleResultAction` converted to T-type base classes |
-| Phase 5b: Base Class Cleanup | **Complete** | `RandomSequentialResultsAction` and `DeterministicSingleResultAction` deleted |
-| Phase 5c: RoundPhaseAdvancer Actions | **Complete** | All actions called by RoundPhaseAdvancer accept Scala GameState |
-| Phase 5d: RoundPhaseAdvancer Itself | **Complete** | RoundPhaseAdvancer.checkForPhaseAdvancement takes Scala GameState |
-
-### Phase 5c/5d Progress (Complete)
-
-`RoundPhaseAdvancer.checkForPhaseAdvancement` now accepts Scala `GameState` and `ActionResultApplier` directly (PR #4677).
-
-| Action | PR | Status |
-|--------|-----|--------|
-| `PrisonerExchangeAction` | #4670 | ✅ Merged |
-| `PerformForcedTurnBackAction` | #4671 | ✅ Merged |
-| `PerformHeroDeparturesAction` | #4672 | ✅ Merged |
-| `RequestFreeForAllBattlesAction` | #4673 | ✅ Merged |
-| `EndPlayerCommandsPhaseAction` | #4674 | ✅ Merged |
-| `EndDiplomacyResolutionPhaseAction` | #4675 | ✅ Merged |
-| `RoundPhaseAdvancer` itself | #4677 | ✅ Merged |
-
-### EngineImpl Progress
-
-| Change | PR | Status |
-|--------|-----|--------|
-| `recursiveTransform` deleted | #4677 | ✅ Merged |
-| `recursiveTransformT` uses `RandomStateTSequencer` | #4677 | ✅ Merged |
-
-### Current Architecture
-
-**ActionResultT Production (100% Complete):**
-- All actions produce `ActionResultT`
-- Conversion to `ActionResultProto` happens via `ActionResultProtoConverter.toProto()`
-- No direct `ActionResultProto` construction outside the converter
-
-**ActionResultProto Consumption (Next Target):**
-- `ActionResultProtoApplierImpl` - applies proto results to proto GameState
-- `RoundPhaseAdvancer` - calls converter, passes protos to applier
-- `InMemoryHistory` / `PersistedHistory` - stores proto results
-- Service layer (`GameController`, `GamesManager`, etc.) - uses proto for client communication
-
----
-
-## Phase 6: Migrate to ActionResultT Consumers
-
-### Objective
-
-Eliminate internal consumption of `ActionResultProto`. Everything inside the engine should work with `ActionResultT`.
-
-### Current Flow (Proto-Heavy)
-```
-Action.execute()
-    → ActionResultT
-    → ActionResultProtoConverter.toProto()
-    → ActionResultProto
-    → ActionResultProtoApplierImpl.applyActionResults()
-    → GameStateProto
-    → GameStateConverter.fromProto()
-    → GameStateC
-```
-
-### Target Flow (T-Types Throughout)
-```
-Action.execute()
-    → ActionResultT
-    → ActionResultTApplier.applyActionResults()
-    → GameStateC
-
-    (Proto conversion only at boundaries)
-```
-
-### Key Files to Convert
-
-**Tier 1 - Core Applier:**
-```
-src/main/scala/net/eagle0/eagle/library/actions/applier/ActionResultProtoApplierImpl.scala
-```
-Create `ActionResultApplier` that applies `ActionResultT` directly to Scala `GameState`.
-
-**Tier 2 - RoundPhaseAdvancer:** ✅ **Complete**
-```
-src/main/scala/net/eagle0/eagle/library/RoundPhaseAdvancer.scala
-```
-Now accepts Scala `GameState` and `ActionResultApplier`. Only converts to proto lazily for `AvailableCommandsFactory` calls.
-
-**Tier 3 - Sequencers:**
-```
-src/main/scala/net/eagle0/eagle/library/actions/impl/common/RandomStateTSequencer.scala
-src/main/scala/net/eagle0/eagle/library/actions/impl/common/RandomStateProtoSequencer.scala
-```
-Modify `RandomStateTSequencer` to thread Scala `GameState` throughout (currently converts to proto internally). Then evaluate whether `RandomStateProtoSequencer` is still needed at all.
-
-**Current State**: `RandomStateTSequencer` accepts Scala `GameState` via its `apply()` method but internally converts to proto. All callback methods (`withRandomActionResult`, `withActionResults`, etc.) pass `GameStateProto` to callers, forcing actions that use the sequencer to work with proto types internally.
-
-**Target State**: Create a fully protoless sequencer where:
-1. `lastState` returns Scala `GameState` (not `lastStateProto`)
-2. All callback methods pass Scala `GameState` to callers
-3. Actions using the sequencer can be fully protoless
-
-**Migration Path**:
-1. Add `lastState: GameState` method alongside `lastStateProto` (non-breaking)
-2. Add parallel callback methods that pass Scala GameState (e.g., `withScalaActionResult`)
-3. Migrate actions one by one to use the new Scala-based callbacks
-4. Once all actions migrated, deprecate/remove proto-based callbacks
-5. Remove `lastStateProto` once no longer used
-
-**RandomStateSequencer Migration Progress** (PR #4679 introduced protoless `RandomStateSequencer`):
-
-| Action | Status |
-|--------|--------|
-| `TruceTurnBackPhaseAction` | ✅ Migrated (PR #4680) |
-| `EndHandleRiotsPhaseAction` | ✅ Migrated (PR #4684) |
-| `PerformVassalCommandsPhaseAction` | ✅ Migrated |
-| `PerformVassalDefenseDecisionsAction` | ✅ Migrated |
-| `EndVassalCommandsPhaseAction` | ✅ Migrated |
-| `PerformReconResolutionAction` | ✅ Migrated |
-| `NewRoundAction` | ✅ Migrated (PR #4698) |
-| `EndBattleAftermathPhaseAction` | ✅ Migrated (PR #4699) |
-| `EndDiplomacyResolutionPhaseAction` | ✅ Migrated |
-| `PerformUnaffiliatedHeroesAction` | ✅ Migrated |
-| `EngineImpl.recursiveTransformT` | ✅ Migrated (PR #4704) |
-| `ProtolessSequentialResultsActionWrapper` | ✅ Migrated (PR #4705) |
-| `LegacyRandomStateTSequencer` | ✅ **Deleted** (PR #4705) |
-
-**TCommandFactory Extraction** (PR #4684):
-
-To enable lightweight mocking of command creation in tests, `TCommandFactory` trait was extracted from `CommandFactory`. This allows tests to mock just the `makeTCommand` method without pulling in all 40+ command dependencies that `CommandFactory` requires.
-
-- `TCommandFactory` - lightweight trait with just `makeTCommand`
-- `CommandFactory extends TCommandFactory` - maintains backward compatibility
-- Actions accepting command factories now use `TCommandFactory` type for better testability
-
-**Tier 4 - History APIs:**
-```
-src/main/scala/net/eagle0/eagle/service/InMemoryHistory.scala
-src/main/scala/net/eagle0/eagle/service/PersistedHistory.scala
-```
-Change APIs to vend Scala `GameState` and `ActionResultT` instead of proto versions. `PersistedHistory` converts to proto internally for disk persistence; `InMemoryHistory` doesn't need proto at all.
-
-### ActionResultProto Consumer Inventory
-
-| File | Usage | Target |
-|------|-------|--------|
-| `ActionResultTApplierImpl.scala` | Converts T→Proto, delegates to proto applier | Replace with `ActionResultApplier` |
-| `RoundPhaseAdvancer.scala` | ~~20 converter calls~~ | ✅ **Complete** - uses Scala GameState |
-| `RandomStateTSequencer.scala` | Converts T→Proto internally | Thread Scala GameState throughout |
-| `RandomStateProtoSequencer.scala` | Returns `Vector[ActionResultProto]` | Evaluate if still needed |
-| `VigorXPApplier.scala` | Wraps proto results | Convert to work with T |
-| `ResolveBattleAction.scala` | 2 converter calls | Convert after dependencies |
-| `PerformForcedTurnBackAction.scala` | 1 converter call | Convert after dependencies |
-| `EndFreeForAllDecisionPhaseAction.scala` | ~~fromProtoState~~ | **Complete** - now takes Scala GameState |
-| `EndBattleRequestPhaseAction.scala` | ~~fromProtoState~~ | **Complete** - now takes Scala GameState |
-| `EndDefenseDecisionPhaseAction.scala` | ~~fromProtoState~~ | **Complete** - now takes Scala GameState |
-| `EndPleaseRecruitMePhaseAction.scala` | ~~fromProtoState~~ | **Complete** - now takes Scala GameState |
-| `InMemoryHistory.scala` | Stores proto results | Vend Scala types, remove proto entirely |
-| `PersistedHistory.scala` | Stores proto results | Vend Scala types, convert internally for disk |
-| `GameController.scala` | Uses proto for client communication | Keep proto (gRPC boundary) |
-
-### Estimated Effort
-
-| Component | Lines | Complexity |
-|-----------|-------|------------|
-| `ActionResultApplier` | ~900 | High (port of proto applier) |
-| `RandomStateTSequencer` refactor | ~150 | Medium |
-| `RoundPhaseAdvancer` updates | ~100 | Medium |
-| History API updates | ~100 | Low |
-| Action/utility updates | ~200 | Low |
-| **Total** | **~1450** | |
-
-### Validation
-- [ ] `ActionResultApplier` created and tested
-- [ ] `RandomStateTSequencer` threads Scala GameState throughout
-- [ ] `RoundPhaseAdvancer` uses T-types internally
-- [ ] History APIs vend Scala types
-- [ ] No `ActionResultProtoConverter.toProto()` calls except at persistence/gRPC boundaries
-- [ ] All tests pass
-
----
-
-## Phase 7: Clean Up Legacy Utilities
-
-### Objective
-Remove remaining direct proto imports from utility classes.
-
-### Files to Modify
-
-| File | Status |
-|------|--------|
-| `CommandChoiceHelpers.scala` | Accepts proto `GameState`; blocks full deproto of `PerformVassalCommandsPhaseAction` and `PerformVassalDefenseDecisionsAction` |
-| `LegacyProvinceUtils.scala` | Replace with `ProvinceUtils.scala` - `hasImminentRiot` added (PR #4683) |
-| `LegacyFactionUtils.scala` | Replace proto imports with `FactionT` |
-| `LegacyUnaffiliatedHeroUtils.scala` | Replace proto imports with Scala models |
-| `BattalionTypeLoader.scala` | Keep proto for file loading, convert immediately after |
-| `BeastUtils.scala` | **Complete** - now uses Scala `BeastInfo` only |
-
-### View Filters (Blocking Full Deproto)
-
-The `ProvinceViewFilter` utility currently works entirely with proto types, blocking full deproto of actions that generate province views:
-
-| File | Issue | Needed |
-|------|-------|--------|
-| `ProvinceViewFilter.scala` | Takes proto `Province`/`GameState`, returns proto `ProvinceView` | Scala `ProvinceViewT` model |
-| `GameStateViewFilter.scala` | Uses proto types throughout | Depends on `ProvinceViewT` |
-| `GameStateViewDiffer.scala` | Works with view protos | Depends on `ProvinceViewT` |
-
-**Blocked Actions**:
-- `EndBattleAftermathPhaseAction` - uses `ProvinceViewFilter` for `revelationChange`, requires lazy proto conversion
-- `PerformReconResolutionAction` - uses `ProvinceViewFilter` for reconned provinces
-- `GameStateFactionExtensions` - uses `ProvinceViewFilter` for `updatedReconnedProvinces`
-
-**Solution**: Create Scala `ProvinceViewT` (and possibly `ProvinceViewC`) that mirrors the proto `ProvinceView`. Then create a protoless `ProvinceViewFilter` that operates on Scala types. The proto version can delegate to the Scala version + convert, or we maintain both during transition.
-
----
-
-## Phase 8: Verify Boundaries
-
-### Objective
-Confirm protos are used correctly at boundaries — and ONLY there.
-
-### Expected Proto Usage (Keep)
-- `EagleServiceImpl.scala` - gRPC boundary
-- `InMemoryHistory.scala` / `PersistedHistory.scala` - Persistence boundary
-- `*Converter.scala` - Explicit conversion utilities
-- `*Loader.scala` - File loading utilities
-
-### Expected No Proto Usage (Verify)
-- `/library/actions/impl/` - Pure Scala models
-- `/library/util/` - Pure Scala models (except loaders)
-- `/model/state/` - Pure Scala models
-
----
-
-## Open Questions
-
-1. **Persistence Format**: Currently game state is persisted as proto. Should we keep proto for persistence (good for schema evolution) or switch to a different format?
-
-2. **Shardok Integration**: `ResolveBattleAction` communicates with Shardok. Should the Shardok interface use protos (external service) or Scala models?
-
-3. **View Generation**: `GameStateViewDiffer` works with view protos for client updates. Views need Scala models (`ProvinceViewT`, etc.) to allow actions like `EndBattleAftermathPhaseAction` to be fully protoless. The Scala views would be converted to proto only at the gRPC boundary when sending updates to clients.
-
----
-
-## Success Criteria
-
-### Code Quality
-- [ ] Zero proto imports in `/library/actions/` (except boundaries)
-- [ ] Zero proto imports in `/library/` utilities (except loaders)
-- [ ] `GameStateT` used throughout engine internals
-- [ ] Proto usage limited to: `EagleServiceImpl`, loaders, converters, persistence
-
-### Architecture
-- [ ] Clear separation: Scala models (internal) vs Proto (boundaries)
-- [ ] Converters as the only bridge between domains
-- [ ] No "proto creep" into business logic

go.mod

@@ -9,7 +9,6 @@ require (
 	github.com/aws/aws-sdk-go-v2/config v1.28.10
 	github.com/aws/aws-sdk-go-v2/credentials v1.17.51
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.72.2
-	google.golang.org/grpc v1.68.0
 	google.golang.org/protobuf v1.36.3
 )
 

go.sum

@@ -40,8 +40,6 @@ github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/
 golang.org/x/text v0.25.0 h1:qVyWApTSYLk/drJRO5mDlNYskwQznZmkpV2c8q9zls4=
 golang.org/x/text v0.25.0/go.mod h1:WEdwpYrmk1qmdHvhkSTNPm3app7v4rsT8F2UD6+VHIA=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-google.golang.org/grpc v1.68.0 h1:aHQeeJbo8zAkAa3pRzrVjZlbz6uSfeOXlJNQM0RAbz0=
-google.golang.org/grpc v1.68.0/go.mod h1:fmSPC5AsjSBCK54MyHRx48kpOti1/jRfOlwEWywNjWA=
 google.golang.org/protobuf v1.26.0-rc.1 h1:7QnIQpGRHE5RnLKnESfDoxm2dTapTZua5a0kS0A+VXQ=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.36.3 h1:82DV7MYdb8anAVi3qge1wSnMDrnKK7ebr+I0hHRN1BU=

scripts/build_mac_plugin.sh

@@ -3,8 +3,7 @@
 set -euxo pipefail
 
 /bin/echo "building darwin bundle"
-bazel build --config=mactools @net_eagle0_unity_godice//darwin/framework:DarwinGodiceBundle
-ZIP_LOCATION=$(bazel cquery --config=mactools --output=files @net_eagle0_unity_godice//darwin/framework:DarwinGodiceBundle 2>/dev/null)
-/usr/bin/unzip -o $ZIP_LOCATION -d src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/
+bazel build --noincompatible_enable_cc_toolchain_resolution @net_eagle0_unity_godice//darwin/framework:DarwinGodiceBundle
+/usr/bin/unzip -o bazel-bin/external/net_eagle0_unity_godice/darwin/framework/DarwinGodiceBundle.zip -d src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/
 
 /usr/bin/plutil -convert xml1 src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/DarwinGodiceBundle.bundle/Contents/Info.plist

scripts/build_plugins.sh

@@ -5,9 +5,8 @@ set -euxo pipefail
 /bin/echo "build plugins"
 
 /bin/echo "building darwin bundle"
-bazel build --config=mactools @net_eagle0_unity_godice//darwin/framework:DarwinGodiceBundle
-ZIP_LOCATION=$(bazel cquery --config=mactools --output=files @net_eagle0_unity_godice//darwin/framework:DarwinGodiceBundle 2>/dev/null)
-/usr/bin/unzip -o $ZIP_LOCATION -d src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/
+bazel build --noincompatible_enable_cc_toolchain_resolution @net_eagle0_unity_godice//darwin/framework:DarwinGodiceBundle
+/usr/bin/unzip -o bazel-bin/external/net_eagle0_unity_godice/darwin/framework/DarwinGodiceBundle.zip -d src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/
 
 /usr/bin/plutil -convert xml1 src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Plugins/DarwinGodiceBundle.bundle/Contents/Info.plist
 

scripts/dlSettings.sh

@@ -1,10 +1,8 @@
 #!/usr/bin/env bash
 
-curl -L "https://docs.google.com/spreadsheets/d/1pv-WMXReccddPwev_YG9IXEGznuGHrYjNNEZ0Rb-ZhM/export?gid=0&format=tsv" | tr -d '\r' > src/main/resources/net/eagle0/shardok/settings.tsv
-curl -L "https://docs.google.com/spreadsheets/d/1p6I5nUMcoAPHIcqikVgbBCFVnqN9dpOEVClbS_wOI7M/export?gid=0&format=tsv" | tr -d '\r' > src/main/resources/net/eagle0/eagle/settings.tsv
+curl -L "https://docs.google.com/spreadsheets/d/1pv-WMXReccddPwev_YG9IXEGznuGHrYjNNEZ0Rb-ZhM/export?gid=0&format=tsv" > src/main/resources/net/eagle0/shardok/settings.tsv
+curl -L "https://docs.google.com/spreadsheets/d/1p6I5nUMcoAPHIcqikVgbBCFVnqN9dpOEVClbS_wOI7M/export?gid=0&format=tsv" > src/main/resources/net/eagle0/eagle/settings.tsv
 
 bazel run //src/main/go/net/eagle0/build/settings_generator:settings_generator -- \
     ${PWD}/src/main/resources/net/eagle0/eagle/settings.tsv \
     ${PWD}/src/main/scala/net/eagle0/eagle/library/settings/
-bazel run gazelle
-

scripts/downloadTsvs.sh

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
 
-curl -L "https://docs.google.com/spreadsheets/d/1DHEsiv4cY4gE6AX3sVH82K__mpBD1aznIYCQwQxA_F0/export?gid=0&format=tsv" | tr -d '\r' > /tmp/names.tsv
+curl -L "https://docs.google.com/spreadsheets/d/1DHEsiv4cY4gE6AX3sVH82K__mpBD1aznIYCQwQxA_F0/export?gid=0&format=tsv" > /tmp/names.tsv
 bazel run //src/main/scala/net/eagle0/util:name_list_checker -- /tmp/names.tsv > src/main/resources/net/eagle0/names.tsv
 bazel run //src/main/scala/net/eagle0/util:name_list_json_maker -- /tmp/names.tsv > src/main/resources/net/eagle0/names.json
-curl -L "https://docs.google.com/spreadsheets/d/1NhvG73HKyVE36yGpkV2oJiSIXoNqQOYTr5ArLnucYL0/export?gid=0&format=tsv" | tr -d '\r' > src/main/resources/net/eagle0/shardok/battalionTypes.tsv
-curl -L "https://docs.google.com/spreadsheets/d/1pNWiyxIks2wJ1v7jRLFD24zrKHG2AfhC-nkWmQKQGN4/export?gid=0&format=tsv" | tr -d '\r' > src/main/resources/net/eagle0/eagle/heroes.tsv
-curl -L "https://docs.google.com/spreadsheets/d/1RUguq5eAQprsZwOOqiCc-1dg4Urc_6iJ6awZsFU4MeI/export?gid=0&format=tsv" | tr -d '\r' > src/main/resources/net/eagle0/eagle/beasts.tsv
+curl -L "https://docs.google.com/spreadsheets/d/1NhvG73HKyVE36yGpkV2oJiSIXoNqQOYTr5ArLnucYL0/export?gid=0&format=tsv" > src/main/resources/net/eagle0/shardok/battalionTypes.tsv
+curl -L "https://docs.google.com/spreadsheets/d/1pNWiyxIks2wJ1v7jRLFD24zrKHG2AfhC-nkWmQKQGN4/export?gid=0&format=tsv" > src/main/resources/net/eagle0/eagle/heroes.tsv
+curl -L "https://docs.google.com/spreadsheets/d/1RUguq5eAQprsZwOOqiCc-1dg4Urc_6iJ6awZsFU4MeI/export?gid=0&format=tsv" > src/main/resources/net/eagle0/eagle/beasts.tsv
 #curl -L "https://docs.google.com/spreadsheets/d/1Z-60cJ_N1IasvqpVb5awKEkIYznEeR2IZSdli47oW88/export?gid=0&format=tsv" > src/main/resources/net/eagle0/eagle/province_map.tsv
 
 ${PWD}/scripts/dlSettings.sh

scripts/pre-commit-gazelle.sh

@@ -1,19 +0,0 @@
-#!/bin/bash
-# Pre-commit hook wrapper for gazelle that fails if files are modified.
-# This ensures BUILD files are in canonical format before committing.
-
-set -e
-
-# Run gazelle
-bazel run //:gazelle 2>/dev/null
-
-# Check if any BUILD files were modified
-if ! git diff --quiet -- '*.bazel' '**/BUILD' 'WORKSPACE*'; then
-    echo ""
-    echo "ERROR: gazelle modified BUILD files. Please stage the changes and retry:"
-    echo ""
-    git diff --name-only -- '*.bazel' '**/BUILD' 'WORKSPACE*'
-    echo ""
-    echo "Run: git add -u && git commit"
-    exit 1
-fi

src/main/cpp/net/eagle0/common/SequenceRandomGenerator.hpp

@@ -14,14 +14,6 @@
 
 #include "src/main/cpp/net/eagle0/common/RandomGenerator.hpp"
 
-// A deterministic random generator that returns values from a fixed sequence.
-// Used for testing and MCTS simulation where we want specific, predictable outcomes.
-//
-// Values in the sequence are treated as [0, 1] probabilities that are returned
-// by DoubleZeroToOne(). The normal percentile methods (including open-ended
-// variants) work as usual, so callers must provide appropriate sequences.
-// For example, to get an open-ended low result of -50, provide [0.02, 0.52]
-// which produces: initial=2 (triggers open-ended), accumulated=52, final=2-52=-50
 class SequenceRandomGenerator : public ::RandomGenerator {
 private:
     const std::vector<double> sequence;

src/main/cpp/net/eagle0/common/mcts/abstract/AbstractMCTSAI.cpp

@@ -5,18 +5,12 @@
 #include "AbstractMCTSAI.hpp"
 
 #include <algorithm>
-#include <chrono>
-#include <fstream>
 #include <future>
-#include <iomanip>
-#include <limits>
 #include <mutex>
 #include <random>
 #include <stdexcept>
 #include <thread>
 
-#include "src/main/cpp/net/eagle0/common/mcts/util/TreeIndentUtil.hpp"
-
 namespace shardok::mcts {
 
 AbstractMCTSAI::AbstractMCTSAI(MCTSPlayerId playerId, MCTSConfig config)
@@ -85,9 +79,6 @@ auto AbstractMCTSAI::Search(
         LogSearchResults(rootNode.get(), bestChild, result);
     }
 
-    // Dump tree if explicitly requested via config
-    if (!config_.debugDumpPath.empty()) { DumpTreeToFile(rootNode.get(), config_.debugDumpPath); }
-
     return result;
 }
 
@@ -95,19 +86,12 @@ auto AbstractMCTSAI::BuildMCTSTree(
         const MCTSGameEngine& engine,
         const MCTSGameState& initialState,
         const std::chrono::steady_clock::time_point deadline) const -> std::unique_ptr<MCTSNode> {
-    // Clear transposition table for this search
-    // Maps state hash -> minimum depth, used to detect redundant longer paths
-    transpositionTable_.clear();
-
     // Create root node
     // IMPORTANT: Use the initial state's current player, not playerId_
     // node->playerId represents "whose turn it is", not "who we're searching for"
     // This is critical for correct player flip tracking
     auto root = std::make_unique<MCTSNode>(initialState.clone(), initialState.currentPlayerId(), 0);
 
-    // Record root state in transposition table
-    transpositionTable_[root->stateHash] = root->depth;
-
     // Set whether root is maximizing based on whether current player matches who we're searching
     // for
     root->isMaximizingPlayer = (initialState.currentPlayerId() == playerId_);
@@ -130,37 +114,6 @@ auto AbstractMCTSAI::BuildMCTSTree(
     // Initialize action counter
     root->totalActions = rootActions.size();
 
-    // CRITICAL: Do at least one expansion before entering the time-bounded loop.
-    // This ensures we always have at least one child to return, even if the deadline
-    // has already passed (e.g., due to debugger pause, system load, etc.)
-    {
-        auto* selected = MCTSSelection(root.get());
-        const bool selectedIsRoot = (selected == root.get());
-        const size_t childrenBeforeExpansion = root->children.size();
-
-        if (selected) {
-            auto* expanded = MCTSExpansion(selected, engine);
-            const double reward =
-                    MCTSSimulation(engine, *expanded->gameState, playerId_, expanded->playerFlips);
-            MCTSBackpropagation(expanded, reward, config_.backpropagationPolicy);
-        }
-
-        // Verify we actually have at least one child after the initial expansion
-        if (root->children.empty()) {
-            throw MCTSInternalError(
-                    "MCTS BuildMCTSTree: Initial expansion failed to produce any children. "
-                    "totalActions=" +
-                    std::to_string(root->totalActions) +
-                    ", selected=" + (selected ? "non-null" : "null") +
-                    ", selectedIsRoot=" + (selectedIsRoot ? "true" : "false") +
-                    ", childrenBefore=" + std::to_string(childrenBeforeExpansion) +
-                    ", childrenAfter=" + std::to_string(root->children.size()) +
-                    ", root->CanExpand()=" + (root->CanExpand() ? "true" : "false") +
-                    ", root->nextUntriedActionIndex=" +
-                    std::to_string(root->nextUntriedActionIndex));
-        }
-    }
-
     std::atomic<int> iterations{0};
 
     if (config_.useMultithreading && config_.numThreads > 1) {
@@ -207,7 +160,7 @@ auto AbstractMCTSAI::BuildMCTSTree(
         while (std::chrono::steady_clock::now() < deadline) {
             // Selection
             auto* selected = MCTSSelection(root.get());
-            if (!selected) { break; }
+            if (!selected) break;
 
             // Expansion
             auto* expanded = MCTSExpansion(selected, engine);
@@ -237,27 +190,11 @@ auto AbstractMCTSAI::BuildMCTSTree(
 auto AbstractMCTSAI::MCTSSelection(MCTSNode* root) const -> MCTSNode* {
     MCTSNode* current = root;
 
-    while (current->depth < config_.maxTreeDepth) {
-        // Check expansion FIRST - allows expanding "terminal" nodes that still have
-        // untried actions (e.g., final round where we need to pick an action)
+    while (!current->isTerminal && current->depth < config_.maxTreeDepth) {
         if (current->CanExpand()) {
-            return current;  // Node has untried actions/outcomes
-        }
-
-        // Only after expansion check: stop if terminal and fully expanded
-        if (current->isTerminal) {
-            break;  // Terminal and no more actions to try
-        }
-
-        if (!current->children.empty()) {
-            // Choose child based on node type
-            if (current->IsChanceNode()) {
-                // Chance nodes: select outcome proportional to probability
-                current = current->GetBestChanceChild();
-            } else {
-                // Decision nodes: select using UCB1
-                current = current->GetBestChild(config_.explorationConstant);
-            }
+            return current;  // Node has untried actions
+        } else if (!current->children.empty()) {
+            current = current->GetBestChild(config_.explorationConstant);
             if (!current) break;
         } else {
             break;  // Leaf node
@@ -269,109 +206,10 @@ auto AbstractMCTSAI::MCTSSelection(MCTSNode* root) const -> MCTSNode* {
 
 auto AbstractMCTSAI::MCTSExpansion(MCTSNode* node, const MCTSGameEngine& engine) const
         -> MCTSNode* {
-    // Only skip if we truly can't expand. Allow expansion even if "terminal" as long as
-    // there are untried actions (e.g., final round where we need to pick an action).
-    if (!node->CanExpand()) {
+    if (!node->CanExpand() || node->isTerminal) {
         return node;  // Nothing to expand
     }
 
-    // Handle chance node expansion (expanding outcomes)
-    if (node->IsChanceNode()) {
-        // Chance nodes expand their outcome children
-        // This should have been set up when the chance node was created
-        if (node->outcomeProbabilities.empty()) {
-            throw MCTSInternalError(
-                    "Chance node has no outcome probabilities - this indicates a bug");
-        }
-
-        const size_t outcomeIndex = node->nextUntriedActionIndex++;
-        if (outcomeIndex >= node->outcomeProbabilities.size()) {
-            throw MCTSInternalError(
-                    "Chance node outcomeIndex >= outcomeProbabilities.size() - bug in expansion");
-        }
-
-        // The chance node's action should be the binary action
-        if (!node->action) {
-            throw MCTSInternalError("Chance node has no action - this indicates a bug");
-        }
-
-        // Apply the action with the representative roll for this outcome
-        // Outcome 0 = success, Outcome 1 = failure
-        // Use the representative roll for this specific outcome
-        const double representativeRoll = node->outcomeRolls[outcomeIndex];
-        auto newState = engine.applyAction(*node->gameState, *node->action, representativeRoll);
-        if (!newState) {
-            throw MCTSInternalError(
-                    "MCTS expansion: engine.applyAction() returned nullptr for chance node "
-                    "outcome - this indicates a game engine error");
-        }
-
-        // Determine if player changed
-        const MCTSPlayerId newPlayerId = newState->currentPlayerId();
-        const bool playerChanged = (newPlayerId != node->playerId);
-
-        // Calculate player flips and maximizing status
-        const int newPlayerFlips = node->playerFlips + (playerChanged ? 1 : 0);
-        const bool newIsMaximizing = (newPlayerId == playerId_);
-
-        // Create outcome child (decision node)
-        auto outcomeChild = std::make_unique<MCTSNode>(
-                node->action->clone(),
-                std::move(newState),
-                newPlayerId,
-                node->depth + 1,
-                outcomeIndex,
-                newPlayerFlips,
-                newIsMaximizing,
-                node->actionWeight);  // Inherit action weight from chance node
-
-        // Set up outcome child's actions if not terminal
-        const bool shouldExpand =
-                !outcomeChild->isTerminal && node->playerFlips <= config_.maxPlayerFlips;
-        if (shouldExpand) {
-            const auto childActions = engine.getLegalActions(
-                    *outcomeChild->gameState,
-                    playerId_,
-                    newPlayerFlips,
-                    config_.maxPlayerFlips);
-            outcomeChild->totalActions = childActions.size();
-        }
-
-        // Calculate scores
-        outcomeChild->immediateScore = engine.evaluateState(*outcomeChild->gameState, playerId_);
-        outcomeChild->lookaheadScore = outcomeChild->immediateScore;
-
-        // Set parent and add to children
-        outcomeChild->parent = node;
-        node->children.push_back(std::move(outcomeChild));
-
-        // Update chance node's immediate score to expected value of expanded outcomes
-        // This corrects the initial value (which incorrectly used parent state) and ensures
-        // fair UCB comparison with non-chance actions like END_TURN
-        {
-            double expectedImmediate = 0.0;
-            double totalProbability = 0.0;
-            for (size_t i = 0; i < node->children.size(); i++) {
-                const double prob = node->outcomeProbabilities[i];
-                const double childImmediate = node->children[i]->immediateScore;
-                expectedImmediate += prob * childImmediate;
-                totalProbability += prob;
-            }
-            // Normalize by total probability of expanded outcomes
-            if (totalProbability > 0.0) {
-                node->immediateScore = expectedImmediate / totalProbability;
-                // CRITICAL: Always update lookaheadScore to the expected value.
-                // Without this, chance nodes keep their initial lookaheadScore from the parent
-                // state (before the action), while regular actions use the child state (after).
-                // This gives chance nodes an unfair initial UCB advantage.
-                node->lookaheadScore = node->immediateScore;
-            }
-        }
-
-        return node->children.back().get();
-    }
-
-    // Handle decision node expansion (expanding actions)
     // Get next action to expand (sequential order)
     const size_t actionIndex = node->nextUntriedActionIndex++;
 
@@ -395,53 +233,9 @@ auto AbstractMCTSAI::MCTSExpansion(MCTSNode* node, const MCTSGameEngine& engine)
     const auto actionWeights = engine.getActionWeights(nodeActions, *node->gameState);
 
     const auto& action = nodeActions[actionIndex];
-
     const double actionWeight =
             actionIndex < actionWeights.size() ? actionWeights[actionIndex] : 1.0;
 
-    // Check if this action requires a chance node
-    if (action->requiresChanceNode()) {
-        // Create intermediate chance node
-        auto chanceNode = std::make_unique<MCTSNode>(
-                action->clone(),
-                node->gameState->clone(),  // Chance node has same state as parent
-                node->playerId,
-                node->depth + 1,
-                actionIndex,
-                node->playerFlips,
-                node->isMaximizingPlayer,
-                actionWeight);
-
-        chanceNode->nodeType = NodeType::CHANCE;
-
-        // Get outcome information from engine
-        const auto outcomeInfo = engine.getBinaryOutcomeInfo(*node->gameState, *action);
-
-        // Set up outcome metadata (2 outcomes for binary actions)
-        chanceNode->outcomeProbabilities = outcomeInfo.getProbabilities();
-        chanceNode->outcomeRolls = outcomeInfo.getRepresentativeRolls();
-        chanceNode->totalActions = 2;  // Binary: success and failure
-
-        // Chance node immediate score will be computed as expected value during backpropagation
-        // For now, initialize to parent's score as a reasonable default
-        chanceNode->immediateScore = engine.evaluateState(*node->gameState, playerId_);
-        chanceNode->lookaheadScore = chanceNode->immediateScore;
-
-        // Set parent and add to children
-        chanceNode->parent = node;
-        node->children.push_back(std::move(chanceNode));
-
-        // CRITICAL: Immediately expand the first outcome and return that instead.
-        // If we returned the chance node itself, MCTSSimulation would run on the parent state
-        // (since chance nodes have parent's gameState), which is wrong. We need to simulate
-        // from an actual outcome state.
-        //
-        // Note: This recursion is bounded because outcome children are decision nodes,
-        // not chance nodes, so the recursion goes exactly one level deep.
-        return MCTSExpansion(node->children.back().get(), engine);
-    }
-
-    // Regular (non-chance) action: create decision node directly
     auto newState = engine.applyAction(*node->gameState, *action);
     if (!newState) {
         throw MCTSInternalError(
@@ -468,37 +262,8 @@ auto AbstractMCTSAI::MCTSExpansion(MCTSNode* node, const MCTSGameEngine& engine)
             newIsMaximizing,
             actionWeight);  // Pass the action weight for prior-weighted UCB
 
-    // Check transposition table: mark as redundant if we've reached this state at a shallower depth
-    // This prevents MCTS from exploring longer paths to the same game state
-    // Works best with MINIMAX backpropagation (penalty propagates as min/max)
-    // Also provides benefit with AVERAGING (penalty pulls average down significantly)
-    const uint64_t childHash = child->stateHash;
-    auto it = transpositionTable_.find(childHash);
-    if (it != transpositionTable_.end()) {
-        const int previousDepth = it->second;
-        if (child->depth > previousDepth) {
-            // Longer path to same state - mark as redundant and heavily penalize
-            // Use -infinity to be unambiguously worse than any legitimate score
-            child->isRedundant = true;
-            child->immediateScore = -std::numeric_limits<double>::infinity();
-            child->lookaheadScore = -std::numeric_limits<double>::infinity();
-        } else {
-            // Found shorter or equal path - update table
-            transpositionTable_[childHash] = child->depth;
-        }
-    } else {
-        // First time seeing this state - record it
-        transpositionTable_[childHash] = child->depth;
-    }
-
-    // Set up child's untried actions if not terminal and parent hasn't exceeded player flips
-    // playerFlips counts how many times the player has CHANGED from root
-    // We expand children of nodes that are within the maxPlayerFlips limit
-    // maxPlayerFlips=0: same player can take multiple sequential actions
-    // maxPlayerFlips=1: can explore opponent's immediate responses
-    const bool shouldExpand = !child->isTerminal && node->playerFlips <= config_.maxPlayerFlips;
-
-    if (shouldExpand) {
+    // Set up child's untried actions if not terminal
+    if (!child->isTerminal) {
         const auto childActions = engine.getLegalActions(
                 *child->gameState,
                 playerId_,
@@ -508,11 +273,8 @@ auto AbstractMCTSAI::MCTSExpansion(MCTSNode* node, const MCTSGameEngine& engine)
     }
 
     // Calculate immediate and lookahead scores from root player's perspective
-    // Skip for redundant nodes (already have penalty scores)
-    if (!child->isRedundant) {
-        child->immediateScore = engine.evaluateState(*child->gameState, playerId_);
-        child->lookaheadScore = child->immediateScore;
-    }
+    child->immediateScore = engine.evaluateState(*child->gameState, playerId_);
+    child->lookaheadScore = child->immediateScore;
 
     // Set parent and add to children
     child->parent = node;
@@ -528,22 +290,14 @@ auto AbstractMCTSAI::MCTSSimulation(
         const int startingPlayerFlips) const -> double {
     if (state.isTerminal()) { return state.score(startingPlayer); }
 
-    // If we've already exceeded the simulation horizon, don't simulate - just return immediate
-    // score This ensures fair comparison: all leaves are evaluated at the same game phase Example:
-    // maxSimulationFlips=1 means simulate THROUGH opponent's first response (i.e., allow one action
-    // at playerFlips=1, then stop)
-    if (startingPlayerFlips > config_.maxSimulationFlips) { return state.score(startingPlayer); }
-
     // Create a mutable copy for simulation
     auto currentState = state.clone();
     int depth = 0;
     int playerFlips = startingPlayerFlips;  // Start from the expanded node's flip count
     MCTSPlayerId previousPlayer = currentState->currentPlayerId();
 
-    // Simulate until we exceed the horizon, hit terminal state, or max depth
-    // Note: We allow one action AT maxSimulationFlips before stopping
-    while (!currentState->isTerminal() && depth < config_.maxSimulationDepth &&
-           playerFlips <= config_.maxSimulationFlips) {
+    // Simulate until terminal or max depth
+    while (!currentState->isTerminal() && depth < config_.maxSimulationDepth) {
         // Track player changes
         const MCTSPlayerId currentPlayer = currentState->currentPlayerId();
         if (currentPlayer != previousPlayer) {
@@ -556,7 +310,7 @@ auto AbstractMCTSAI::MCTSSimulation(
                 *currentState,
                 playerId_,
                 playerFlips,
-                config_.maxSimulationFlips);
+                config_.maxPlayerFlips);
         if (actions.empty()) { break; }
 
         // Determine if current player is maximizing or minimizing
@@ -597,79 +351,28 @@ auto AbstractMCTSAI::MCTSBackpropagation(
         node->totalReward += reward;
         node->averageReward = node->totalReward / node->visitCount;
 
-        // Update lookahead score based on node type and strategy
-        if (node->IsChanceNode() && !node->children.empty()) {
-            // Chance nodes: compute expected value (weighted average of outcomes)
-            // lookaheadScore = sum(probability[i] * childValue[i])
-            double expectedValue = 0.0;
-            double totalProbability = 0.0;
-            int visitedChildCount = 0;
-
-            for (size_t i = 0; i < node->children.size(); i++) {
-                const auto& child = node->children[i];
-                if (child->visitCount == 0) continue;  // Unvisited outcomes don't contribute
-
-                const double probability = node->outcomeProbabilities[i];
-                const double childValue = child->lookaheadScore;
-                expectedValue += probability * childValue;
-                totalProbability += probability;
-                visitedChildCount++;
-            }
-
-            // Use expected value if we have visited outcomes, else use average
-            if (visitedChildCount > 0) {
-                // CRITICAL: Normalize by total probability to get correct expected value
-                // when not all outcomes have been visited yet
-                if (totalProbability > 0.0 && totalProbability < 1.0) {
-                    // Normalize to account for unvisited outcomes
-                    // This gives the correct expected value among visited outcomes
-                    expectedValue /= totalProbability;
-                }
-                node->lookaheadScore = expectedValue;
-            } else {
-                // No outcomes visited yet, fall back to average
-                if (node->visitCount == 1) {
-                    node->lookaheadScore = reward;
-                } else {
-                    const double alpha = 1.0 / node->visitCount;
-                    node->lookaheadScore = (1.0 - alpha) * node->lookaheadScore + alpha * reward;
-                }
-            }
-        } else if (useMinimaxBackup && !node->children.empty()) {
+        // Update lookahead score based on strategy
+        if (useMinimaxBackup && !node->children.empty()) {
             // Minimax backup: use best/worst child value for adversarial games
-            // The operation (MAX or MIN) depends on whose turn it is at THIS node
-            // - If this node is root player's turn: root chooses MAX (best for root)
-            // - If this node is opponent's turn: opponent chooses MIN (best for opponent = worst
-            // for root)
-            //
-            // Note: In setup phase, children can have different isMaximizingPlayer values:
-            // - PLACE_UNIT keeps same player's turn
-            // - END_PLAYER_SETUP flips to opponent's turn
-            // So we must use the PARENT node's isMaximizingPlayer, not the child's.
+            // This is correct when exploring opponent responses
+            double minmaxValue = node->isMaximizingPlayer ? -std::numeric_limits<double>::max()
+                                                          : std::numeric_limits<double>::max();
 
-            const bool thisNodeIsRootPlayer = node->isMaximizingPlayer;
-
-            double minmaxValue = thisNodeIsRootPlayer ? -std::numeric_limits<double>::max()
-                                                      : std::numeric_limits<double>::max();
-
-            int visitedChildCount = 0;
             for (const auto& child : node->children) {
                 if (child->visitCount == 0) continue;  // Unvisited children don't contribute
 
                 const double childValue = child->lookaheadScore;
-                visitedChildCount++;
 
-                if (thisNodeIsRootPlayer) {
-                    // Root player chooses: take MAX (best for root)
+                if (node->isMaximizingPlayer) {
                     minmaxValue = std::max(minmaxValue, childValue);
                 } else {
-                    // Opponent chooses: take MIN (best for opponent = worst for root)
                     minmaxValue = std::min(minmaxValue, childValue);
                 }
             }
 
             // Use minimax value if we found any visited children, else use average
-            if (visitedChildCount > 0) {
+            if (minmaxValue != (node->isMaximizingPlayer ? -std::numeric_limits<double>::max()
+                                                         : std::numeric_limits<double>::max())) {
                 node->lookaheadScore = minmaxValue;
             } else {
                 // No children visited yet, fall back to average
@@ -877,17 +580,12 @@ auto AbstractMCTSAI::LogSearchResults(
         return a->visitCount > b->visitCount;
     });
 
-    // Show all actions if there are <= 10, otherwise top 5
-    const size_t numToShow = sortedChildren.size() <= 10 ? sortedChildren.size() : 5;
-    printf("MCTS: Top %zu actions by visits (out of %zu total):\n",
-           numToShow,
-           sortedChildren.size());
-    for (size_t i = 0; i < numToShow; ++i) {
+    printf("MCTS: Top actions by visits:\n");
+    for (size_t i = 0; i < std::min(static_cast<size_t>(3), sortedChildren.size()); ++i) {
         const auto* child = sortedChildren[i];
-        printf("  [%zu] visits:%d avgReward:%.2f immediate:%.2f lookahead:%.2f",
+        printf("  [%zu] visits:%d immediate:%.2f lookahead:%.2f",
                i,
                child->visitCount,
-               child->averageReward,
                child->immediateScore,
                child->lookaheadScore);
 
@@ -941,43 +639,18 @@ auto AbstractMCTSAI::LogSearchResults(
 
     if (!bestSequence.empty()) {
         printf("MCTS: Best sequence from chosen action (final: %.2f):\n", sequenceScore);
-        int displayedStep = 0;
         for (size_t i = 0; i < bestSequence.size(); ++i) {
             const auto* node = bestSequence[i];
-
-            // Skip outcome nodes (children of chance nodes) - they're displayed with their parent
-            if (i > 0 && node->parent && node->parent->IsChanceNode()) { continue; }
-
-            displayedStep++;
-            printf("  %d.", displayedStep);
+            printf("  %zu.", i + 1);
             if (node->action) { printf(" %s", node->action->getDescription().c_str()); }
-
-            // If this is a chance node, display outcome probabilities and scores
-            if (node->IsChanceNode() && !node->outcomeProbabilities.empty()) {
-                printf(" [");
-                for (size_t j = 0; j < node->outcomeProbabilities.size(); ++j) {
-                    if (j > 0) printf(", ");
-                    const double prob = node->outcomeProbabilities[j] * 100;
-                    // Show lookahead score for each outcome if child exists
-                    if (j < node->children.size() && node->children[j]->visitCount > 0) {
-                        printf("%.0f%%->%.1f", prob, node->children[j]->lookaheadScore);
-                    } else {
-                        printf("%.0f%%->?", prob);
-                    }
-                }
-                printf("]");
-            }
-
             printf(" (visits:%d, immediate:%.2f, lookahead:%.2f)\n",
                    node->visitCount,
                    node->immediateScore,
                    node->lookaheadScore);
 
             // For non-root nodes in the sequence, show what the top alternatives were
-            // Skip showing alternatives for chance nodes (they have outcome children, not action
-            // alternatives)
-            if (i > 0 && node->parent && !node->parent->children.empty() &&
-                !node->parent->IsChanceNode()) {
+            // This helps diagnose if opponent moves are being properly explored
+            if (i > 0 && node->parent && !node->parent->children.empty()) {
                 // Collect all siblings (including this node) and sort by visit count
                 std::vector<const MCTSNode*> siblings;
                 siblings.reserve(node->parent->children.size());
@@ -1008,100 +681,4 @@ auto AbstractMCTSAI::LogSearchResults(
     }
 }
 
-auto AbstractMCTSAI::DumpTreeToFile(const MCTSNode* root, const std::string& filepath) -> void {
-    if (!root) return;
-
-    std::ofstream out(filepath);
-    if (!out) {
-        fprintf(stderr, "Failed to open dump file: %s\n", filepath.c_str());
-        return;
-    }
-
-    out << "MCTS Tree Dump\n";
-    out << "==============\n\n";
-    out << "Root Node:\n";
-    out << "  Visits: " << root->visitCount << "\n";
-    out << "  Immediate Score: " << root->immediateScore << "\n";
-    out << "  Lookahead Score: " << root->lookaheadScore << "\n";
-    out << "  Average Reward: " << root->averageReward << "\n";
-    out << "  Player ID: " << root->playerId << "\n";
-    out << "  Depth: " << root->depth << "\n";
-    out << "  Is Maximizing: " << (root->isMaximizingPlayer ? "true" : "false") << "\n";
-    out << "  State Hash: " << std::hex << root->stateHash << std::dec << "\n";
-    out << "\n";
-
-    if (!root->children.empty()) {
-        out << "Children:\n";
-        for (size_t i = 0; i < root->children.size(); ++i) {
-            const auto& child = root->children[i];
-            const bool isLast = (i == root->children.size() - 1);
-            DumpNodeRecursive(child.get(), out, 1, isLast);
-        }
-    }
-
-    out << "\n=== End of Tree Dump ===\n";
-    out.close();
-
-    printf("MCTS: Tree dumped to %s\n", filepath.c_str());
-}
-
-auto AbstractMCTSAI::DumpNodeRecursive(
-        const MCTSNode* node,
-        std::ostream& out,
-        const int indentLevel,
-        const bool isLastChild) -> void {
-    if (!node) return;
-
-    // Create indent string
-    const std::string indent = ::mcts::util::BuildTreeIndent(indentLevel, isLastChild);
-
-    // Write node information
-    out << indent;
-
-    // Show node type for chance nodes
-    if (node->IsChanceNode()) { out << "[CHANCE] "; }
-
-    if (node->action) {
-        out << node->action->getDescription();
-    } else {
-        out << "[ROOT]";
-    }
-    out << " (visits:" << node->visitCount;
-    out << ", immediate:" << std::fixed << std::setprecision(2) << node->immediateScore;
-    out << ", lookahead:" << node->lookaheadScore;
-    out << ", avgReward:" << node->averageReward;
-    out << ", weight:" << node->actionWeight;
-    out << ", depth:" << node->depth;
-    out << ", flips:" << node->playerFlips;
-    out << ", player:" << node->playerId;
-    out << ", max:" << (node->isMaximizingPlayer ? "T" : "F");
-    if (node->isRedundant) { out << ", REDUNDANT"; }
-    if (node->isTerminal) { out << ", TERMINAL"; }
-    out << ")\n";
-
-    // Show outcome probabilities and rolls for chance nodes
-    if (node->IsChanceNode() && !node->outcomeProbabilities.empty()) {
-        const std::string outcomeIndent = ::mcts::util::ConvertBranchToContinuation(indent);
-        out << outcomeIndent << "  Outcomes: ";
-        for (size_t i = 0; i < node->outcomeProbabilities.size(); ++i) {
-            if (i > 0) out << ", ";
-            out << "[" << i << "] p=" << std::fixed << std::setprecision(3)
-                << node->outcomeProbabilities[i];
-            if (i < node->outcomeRolls.size()) {
-                out << " roll=" << std::fixed << std::setprecision(1) << node->outcomeRolls[i];
-            }
-        }
-        out << "\n";
-    }
-
-    // Recursively dump children
-    if (!node->children.empty()) {
-        for (size_t i = 0; i < node->children.size(); ++i) {
-            const auto& child = node->children[i];
-            const bool isLast = (i == node->children.size() - 1);
-            DumpNodeRecursive(child.get(), out, indentLevel + 1, isLast);
-        }
-    }
-}
-
 }  // namespace shardok::mcts

src/main/cpp/net/eagle0/common/mcts/abstract/AbstractMCTSAI.hpp

@@ -7,7 +7,6 @@
 
 #include <chrono>
 #include <memory>
-#include <unordered_map>
 #include <vector>
 
 #include "MCTSAction.hpp"
@@ -52,11 +51,6 @@ private:
     MCTSPlayerId playerId_;
     MCTSConfig config_;
 
-    // Transposition table: maps state hash -> minimum depth at which state was reached
-    // Used to detect and penalize longer paths to the same game state
-    // Cleared at the start of each Search() call
-    mutable std::unordered_map<uint64_t, int> transpositionTable_;
-
     // Core MCTS algorithm
     [[nodiscard]] auto BuildMCTSTree(
             const MCTSGameEngine& engine,
@@ -90,14 +84,6 @@ private:
             const MCTSNode* rootNode,
             const MCTSNode* bestChild,
             const SearchResult& result) -> void;
-
-    // Debug tree dumping
-    static auto DumpTreeToFile(const MCTSNode* root, const std::string& filepath) -> void;
-
-private:
-    static auto
-    DumpNodeRecursive(const MCTSNode* node, std::ostream& out, int indentLevel, bool isLastChild)
-            -> void;
 };
 
 }  // namespace mcts

src/main/cpp/net/eagle0/common/mcts/abstract/BUILD.bazel

@@ -86,7 +86,6 @@ cc_library(
         ":mcts_game_state",
         ":mcts_node",
         ":mcts_types",
-        "//src/main/cpp/net/eagle0/common/mcts/util:tree_indent_util",
     ],
 )
 

src/main/cpp/net/eagle0/common/mcts/abstract/MCTSAction.hpp

@@ -27,11 +27,6 @@ public:
 
     // Check if two actions are equivalent
     [[nodiscard]] virtual bool equals(const MCTSAction& other) const = 0;
-
-    // Check if this action requires a chance node (binary success/failure outcome)
-    // Examples: START_FIRE, RAISE_DEAD, EXTINGUISH_FIRE
-    // If true, the game engine should provide outcome probabilities
-    [[nodiscard]] virtual bool requiresChanceNode() const = 0;
 };
 
 }  // namespace mcts

src/main/cpp/net/eagle0/common/mcts/abstract/MCTSGameEngine.hpp

@@ -16,50 +16,15 @@
 namespace shardok {
 namespace mcts {
 
-// Information about chance outcomes (supports both binary and multi-outcome)
-struct ChanceOutcomeInfo {
-    std::vector<double> probabilities;  // Probability of each outcome (must sum to 1.0)
-    std::vector<double> rolls;          // Roll values for each outcome
-
-    // Factory for binary success/failure outcomes (e.g., START_FIRE)
-    [[nodiscard]] static ChanceOutcomeInfo binary(double successProbability) {
-        // -100: triggers open-ended low sequence, succeeds against any threshold
-        // 150: triggers open-ended high sequence, fails against any threshold
-        return {{successProbability, 1.0 - successProbability}, {-100.0, 150.0}};
-    }
-
-    // Factory for multi-outcome with fixed seeds (e.g., END_TURN)
-    // Uses uniformly distributed roll values to sample different random outcomes
-    [[nodiscard]] static ChanceOutcomeInfo multiOutcome(int numOutcomes) {
-        std::vector<double> probs(numOutcomes, 1.0 / numOutcomes);
-        std::vector<double> rollValues;
-        rollValues.reserve(numOutcomes);
-        // Spread rolls across the percentile range: 10, 30, 50, 70, 90 for 5 outcomes
-        for (int i = 0; i < numOutcomes; ++i) {
-            rollValues.push_back(10.0 + (80.0 * i) / (numOutcomes - 1));
-        }
-        return {probs, rollValues};
-    }
-
-    [[nodiscard]] const std::vector<double>& getRepresentativeRolls() const { return rolls; }
-
-    [[nodiscard]] const std::vector<double>& getProbabilities() const { return probabilities; }
-};
-
-// Backward compatibility alias
-using BinaryOutcomeInfo = ChanceOutcomeInfo;
-
 // Abstract interface for game engines
 class MCTSGameEngine {
 public:
     virtual ~MCTSGameEngine() = default;
 
     // Apply an action to a state and return the resulting state
-    // If deterministicRoll is provided (0.0-100.0), use that for any random outcomes
     [[nodiscard]] virtual std::unique_ptr<MCTSGameState> applyAction(
             const MCTSGameState& state,
-            const MCTSAction& action,
-            double deterministicRoll = -1.0) const = 0;
+            const MCTSAction& action) const = 0;
 
     // Apply an action to a mutable state in-place (for efficient simulation)
     // Default: clone, apply, and move the result back
@@ -146,13 +111,6 @@ public:
         (void)state;  // Suppress unused parameter warning
         return filteredIndex;
     }
-
-    // Get binary outcome information for an action that requires a chance node
-    // Only called for actions where action.requiresChanceNode() returns true
-    // Returns success probability for binary success/failure actions
-    [[nodiscard]] virtual BinaryOutcomeInfo getBinaryOutcomeInfo(
-            const MCTSGameState& state,
-            const MCTSAction& action) const = 0;
 };
 
 }  // namespace mcts

src/main/cpp/net/eagle0/common/mcts/abstract/MCTSNode.hpp

@@ -17,16 +17,8 @@
 namespace shardok {
 namespace mcts {
 
-// Node type for MCTS tree
-enum class NodeType {
-    DECISION,  // Player chooses an action (standard MCTS node)
-    CHANCE     // Nature determines outcome (for probabilistic actions)
-};
-
 // Abstract MCTS Node structure
 struct MCTSNode {
-    // Node type
-    NodeType nodeType = NodeType::DECISION;
     // Action information
     std::unique_ptr<MCTSAction> action;  // The action that led to this node (null for root)
     size_t actionIndex = SIZE_MAX;       // Index in the original actions array (SIZE_MAX for root)
@@ -51,10 +43,6 @@ struct MCTSNode {
     size_t totalActions = 0;            // Total number of available actions
     MCTSNode* parent = nullptr;
 
-    // Chance node specific fields (only used when nodeType == CHANCE)
-    std::vector<double> outcomeProbabilities;  // Probability of each outcome
-    std::vector<double> outcomeRolls;          // Representative roll for each outcome
-
     // Game context
     MCTSPlayerId playerId;
     int depth = 0;
@@ -148,40 +136,6 @@ struct MCTSNode {
     // Check if this node can be expanded
     [[nodiscard]] bool CanExpand() const { return nextUntriedActionIndex < totalActions; }
 
-    // Check if this is a chance node
-    [[nodiscard]] bool IsChanceNode() const { return nodeType == NodeType::CHANCE; }
-
-    // Check if this is a decision node
-    [[nodiscard]] bool IsDecisionNode() const { return nodeType == NodeType::DECISION; }
-
-    // Get best child from chance node (probability-weighted selection)
-    // For chance nodes, we want to explore outcomes proportionally to their probability
-    [[nodiscard]] MCTSNode* GetBestChanceChild() const {
-        if (children.empty() || !IsChanceNode()) return nullptr;
-
-        // Find the outcome that is most under-explored relative to its probability
-        // Expected visits for outcome i: total_visits * probability[i]
-        // Actual visits: child[i]->visitCount
-        // Deficit: expected - actual
-        size_t bestIndex = 0;
-        double bestDeficit = -std::numeric_limits<double>::max();
-
-        for (size_t i = 0; i < children.size(); i++) {
-            if (!children[i] || children[i]->isRedundant) continue;
-
-            const double expectedVisits = visitCount * outcomeProbabilities[i];
-            const double actualVisits = static_cast<double>(children[i]->visitCount);
-            const double deficit = expectedVisits - actualVisits;
-
-            if (deficit > bestDeficit) {
-                bestDeficit = deficit;
-                bestIndex = i;
-            }
-        }
-
-        return children[bestIndex].get();
-    }
-
     // Get best child based on UCB1
     [[nodiscard]] MCTSNode* GetBestChild(const double explorationConstant) const {
         if (children.empty()) return nullptr;

src/main/cpp/net/eagle0/common/mcts/abstract/MCTSTypes.hpp

@@ -44,14 +44,8 @@ struct MCTSConfig {
     int numThreads = 16;                 // Number of threads for parallel MCTS
     MCTSSimulationPolicy simulationPolicy = MCTSSimulationPolicy::BEST_IMMEDIATE;
     MCTSBackpropagationPolicy backpropagationPolicy = MCTSBackpropagationPolicy::AVERAGING;
-    int maxPlayerFlips = 0;          // Maximum number of player changes for tree expansion
-                                     // (0 = expand through current player's turn only,
-                                     //  1 = expand through opponent's first response, etc.)
-    int maxSimulationFlips = 0;      // Maximum player flips for leaf evaluation
-                                     // When evaluating a leaf at playerFlips < maxSimulationFlips,
-                                     // simulate forward to this phase for fair comparison
-                                     // (default 0 = evaluate leaves as-is, backward compatible)
-    std::string debugDumpPath = "";  // If non-empty, dump MCTS tree to this file path
+    int maxPlayerFlips = 0;  // Maximum number of player changes to explore (0 = stop at first
+                             // flip, 1 = explore through opponent's response, etc.)
 };
 
 }  // namespace mcts

src/main/cpp/net/eagle0/common/mcts/util/BUILD.bazel

@@ -1,8 +0,0 @@
-load("@rules_cc//cc:defs.bzl", "cc_library")
-
-cc_library(
-    name = "tree_indent_util",
-    srcs = ["TreeIndentUtil.cpp"],
-    hdrs = ["TreeIndentUtil.hpp"],
-    visibility = ["//visibility:public"],
-)

src/main/cpp/net/eagle0/common/mcts/util/TreeIndentUtil.cpp

@@ -1,53 +0,0 @@
-//
-// Utility functions for processing tree indentation with UTF-8 box drawing characters
-//
-
-#include "TreeIndentUtil.hpp"
-
-namespace mcts::util {
-
-namespace {
-// Box drawing characters for tree visualization
-constexpr const char* kBranch = "\xE2\x94\x9C";      // ├
-constexpr const char* kCorner = "\xE2\x94\x94";      // └
-constexpr const char* kVertical = "\xE2\x94\x82";    // │
-constexpr const char* kHorizontal = "\xE2\x94\x80";  // ─
-}  // namespace
-
-std::string BuildTreeIndent(int indentLevel, bool isLastChild) {
-    std::string indent;
-
-    for (int i = 0; i < indentLevel; ++i) {
-        if (i == indentLevel - 1) {
-            indent += isLastChild ? kCorner : kBranch;
-            indent += kHorizontal;
-            indent += " ";
-        } else {
-            indent += "   ";
-        }
-    }
-
-    return indent;
-}
-
-std::string ConvertBranchToContinuation(const std::string& indent) {
-    std::string result = indent;
-
-    const std::string replacement = std::string(kVertical) + "  ";
-
-    // Replace ├ and └ with │
-    size_t pos = 0;
-    while ((pos = result.find(kBranch, pos)) != std::string::npos) {
-        result.replace(pos, 3, replacement);  // UTF-8 chars are 3 bytes
-        pos += replacement.size();
-    }
-    pos = 0;
-    while ((pos = result.find(kCorner, pos)) != std::string::npos) {
-        result.replace(pos, 3, replacement);
-        pos += replacement.size();
-    }
-
-    return result;
-}
-
-}  // namespace mcts::util

src/main/cpp/net/eagle0/common/mcts/util/TreeIndentUtil.hpp

@@ -1,22 +0,0 @@
-//
-// Utility functions for processing tree indentation with UTF-8 box drawing characters
-//
-
-#ifndef EAGLE0_TREE_INDENT_UTIL_HPP
-#define EAGLE0_TREE_INDENT_UTIL_HPP
-
-#include <string>
-
-namespace mcts::util {
-
-// Builds tree indentation string for a node at a given depth
-// Returns string like "   ├─ " or "   └─ " with proper spacing
-std::string BuildTreeIndent(int indentLevel, bool isLastChild);
-
-// Converts tree branch characters (├ and └) to continuation lines (│) for sub-content
-// This preserves the tree structure when displaying additional info below a node
-std::string ConvertBranchToContinuation(const std::string& indent);
-
-}  // namespace mcts::util
-
-#endif  // EAGLE0_TREE_INDENT_UTIL_HPP

src/main/cpp/net/eagle0/shardok/ai/AIAttackerStrategySelector.cpp

@@ -27,7 +27,7 @@ auto AIAttackerStrategySelector::BestAttackerStrategy(
         const BattalionTypeGetter& battalionTypeGetter,
         ActionPoints braveWaterCost,
         const AIWaterCrossingCommandChooser& waterCrossingCommandChooser,
-        const CommandListSPtr& /*availableCommands*/) -> AIStrategy {
+        const vector<CommandProto>& /*availableCommands*/) -> AIStrategy {
     uint32_t attackerUnitCount = 0;
     int defenderOccupiedCriticalTileCount = 0;
     bool canFlee = false;

src/main/cpp/net/eagle0/shardok/ai/AIAttackerStrategySelector.hpp

@@ -10,7 +10,6 @@
 #include "src/main/cpp/net/eagle0/shardok/ai/AIStrategy.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/AIWaterCrossingCommandChooser.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/GameStateW.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokCommand.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/action_point_distances/ActionPointDistancesCache.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/map/CoordsSet.hpp"
 
@@ -28,7 +27,7 @@ public:
             const BattalionTypeGetter& battalionTypeGetter,
             ActionPoints braveWaterCost,
             const AIWaterCrossingCommandChooser& waterCrossingCommandChooser,
-            const CommandListSPtr& availableCommands) -> AIStrategy;
+            const vector<CommandProto>& availableCommands) -> AIStrategy;
 };
 
 }  // namespace shardok

src/main/cpp/net/eagle0/shardok/ai/AICommandEvaluator.hpp

@@ -14,6 +14,7 @@
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokCTypes.h"
 #include "src/main/cpp/net/eagle0/shardok/library/action_point_distances/ActionPointDistancesCache.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/map/CoordsSet.hpp"
+#include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
 #include "src/main/protobuf/net/eagle0/shardok/common/command_type.pb.h"
 
 namespace shardok {
@@ -23,6 +24,7 @@ class AIScoreCalculator;
 class ShardokEngine;
 
 using ScoreValue = double;
+using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
 using CommandType = net::eagle0::shardok::common::CommandType;
 using BattalionTypeGetter = std::function<BattalionTypeSPtr(BattalionTypeId)>;
 

src/main/cpp/net/eagle0/shardok/ai/AICommandFilter.cpp

@@ -7,7 +7,6 @@
 #include <algorithm>
 
 #include "src/main/cpp/net/eagle0/shardok/library/BattalionType.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokException.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/util/HexCubeUtils.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/util/HexMapUtils.hpp"
 #include "src/main/protobuf/net/eagle0/shardok/common/command_type.pb.h"
@@ -144,16 +143,15 @@ bool AICommandFilter::IsWastefulAction(
 
             if (!isDefender) {
                 // Attackers: Only allow fire if the target location is on or adjacent to an enemy
-                const int targetRow = cmd.GetTargetRow();
-                const int targetCol = cmd.GetTargetColumn();
-                if (targetRow < 0 || targetCol < 0) {
-                    throw ShardokInternalErrorException(
-                            "START_FIRE_COMMAND missing required target information");
+                const auto cmdProto = cmd.GetCommandProto();
+                if (!cmdProto.has_target()) {
+                    return true;  // Can't analyze without target info
                 }
 
-                const Coords fireLocation(
-                        static_cast<int8_t>(targetRow),
-                        static_cast<int8_t>(targetCol));
+                const auto& targetCoords = cmdProto.target();
+                const Coords fireLocation{
+                        static_cast<int8_t>(targetCoords.row()),
+                        static_cast<int8_t>(targetCoords.column())};
 
                 // Check if any enemy is on the fire location or adjacent to it
                 bool enemyNearFireLocation = false;
@@ -188,12 +186,13 @@ bool AICommandFilter::IsWastefulAction(
 
             if (!isDefender) {
                 // Attackers: Only allow fortify if within 3 hexes of enemies or castles
-                const int unitId = cmd.GetActorUnitId();
-                if (unitId < 0) {
-                    throw ShardokInternalErrorException(
-                            "FORTIFY_COMMAND missing required actor information");
+                const auto cmdProto = cmd.GetCommandProto();
+                if (!cmdProto.has_actor()) {
+                    return true;  // Can't analyze without actor info
                 }
 
+                const auto unitId = cmdProto.actor().value();
+
                 // Get the acting unit directly by ID
                 const Unit* actingUnit = gameState->units()->Get(unitId);
                 // verify the unit is still active
@@ -250,18 +249,16 @@ bool AICommandFilter::IsWastefulAction(
             // These actions can fail, so we need high confidence of benefit (8+ action points
             // saved)
 
-            const int unitId = cmd.GetActorUnitId();
-            const int targetRow = cmd.GetTargetRow();
-            const int targetCol = cmd.GetTargetColumn();
-            if (unitId < 0 || targetRow < 0 || targetCol < 0) {
-                throw ShardokInternalErrorException(
-                        "BUILD_BRIDGE/FREEZE_WATER_COMMAND missing required actor or target "
-                        "information");
+            const auto cmdProto = cmd.GetCommandProto();
+            if (!cmdProto.has_actor() || !cmdProto.has_target()) {
+                return true;  // Can't analyze without full command info
             }
 
-            const Coords waterLocation(
-                    static_cast<int8_t>(targetRow),
-                    static_cast<int8_t>(targetCol));
+            const auto unitId = cmdProto.actor().value();
+            const auto& targetCoords = cmdProto.target();
+            const Coords waterLocation{
+                    static_cast<int8_t>(targetCoords.row()),
+                    static_cast<int8_t>(targetCoords.column())};
 
             // Get the acting unit directly by ID
             const Unit* actingUnit = gameState->units()->Get(unitId);
@@ -356,16 +353,15 @@ bool AICommandFilter::IsWastefulAction(
         case CommandType::REPAIR_COMMAND: {
             // Repair filtering - filter repairs with high integrity targets
             // Note: RepairCommandFactory already filters enemy-occupied targets
-            const int targetRow = cmd.GetTargetRow();
-            const int targetCol = cmd.GetTargetColumn();
-            if (targetRow < 0 || targetCol < 0) {
-                throw ShardokInternalErrorException(
-                        "REPAIR_COMMAND missing required target information");
+            const auto cmdProto = cmd.GetCommandProto();
+            if (!cmdProto.has_target()) {
+                return true;  // Can't analyze without target info
             }
 
-            const Coords repairLocation(
-                    static_cast<int8_t>(targetRow),
-                    static_cast<int8_t>(targetCol));
+            const auto& targetCoords = cmdProto.target();
+            const Coords repairLocation{
+                    static_cast<int8_t>(targetCoords.row()),
+                    static_cast<int8_t>(targetCoords.column())};
 
             // Check terrain modifiers at target location
             const auto* terrain = GetTerrain(gameState->hex_map(), repairLocation);
@@ -388,16 +384,15 @@ bool AICommandFilter::IsWastefulAction(
 
         case CommandType::EXTINGUISH_FIRE_COMMAND: {
             // Extinguish fire filtering - don't extinguish fires on enemy-occupied tiles
-            const int targetRow = cmd.GetTargetRow();
-            const int targetCol = cmd.GetTargetColumn();
-            if (targetRow < 0 || targetCol < 0) {
-                throw ShardokInternalErrorException(
-                        "EXTINGUISH_FIRE_COMMAND missing required target information");
+            const auto cmdProto = cmd.GetCommandProto();
+            if (!cmdProto.has_target()) {
+                return true;  // Can't analyze without target info
             }
 
-            const Coords fireLocation(
-                    static_cast<int8_t>(targetRow),
-                    static_cast<int8_t>(targetCol));
+            const auto& targetCoords = cmdProto.target();
+            const Coords fireLocation{
+                    static_cast<int8_t>(targetCoords.row()),
+                    static_cast<int8_t>(targetCoords.column())};
 
             // Check if any enemy occupies the fire location - let them burn!
             std::vector<PlayerId> allyPids;  // Empty for now - assume 2-player game
@@ -429,17 +424,17 @@ bool AICommandFilter::IsWastefulMovement(
         return false;  // Don't filter defender movement or when close to enemies
     }
 
-    // Get unit and target information directly from command
-    const int unitId = cmd.GetActorUnitId();
-    const int targetRow = cmd.GetTargetRow();
-    const int targetCol = cmd.GetTargetColumn();
+    // Get the command proto to access unit and target information
+    const auto cmdProto = cmd.GetCommandProto();
 
     // Check if we have the required information
-    if (unitId < 0 || targetRow < 0 || targetCol < 0) {
-        throw ShardokInternalErrorException(
-                "MOVE_COMMAND missing required actor or target information");
+    if (!cmdProto.has_actor() || !cmdProto.has_target()) {
+        return false;  // Can't analyze without unit and target info
     }
 
+    const auto unitId = cmdProto.actor().value();
+    const auto& targetCoords = cmdProto.target();
+
     // Get the acting unit directly by ID
     const Unit* actingUnit = gameState->units()->Get(unitId);
     // Verify the unit is still active
@@ -455,7 +450,9 @@ bool AICommandFilter::IsWastefulMovement(
     }
 
     const auto& currentCoords = actingUnit->location();
-    const Coords targetCoordsFlat(static_cast<int8_t>(targetRow), static_cast<int8_t>(targetCol));
+    const Coords targetCoordsFlat{
+            static_cast<int8_t>(targetCoords.row()),
+            static_cast<int8_t>(targetCoords.column())};
 
     // Get action point distances for this unit's battalion type
     const auto& battType = battalionTypeGetter(actingUnit->battalion().type());

src/main/cpp/net/eagle0/shardok/ai/AICommandFilter.hpp

@@ -14,6 +14,7 @@
 #include "src/main/cpp/net/eagle0/shardok/library/map/CoordsSet.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
 #include "src/main/flatbuffer/net/eagle0/shardok/storage/game_state.hpp"
+#include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
 
 namespace shardok {
 

src/main/cpp/net/eagle0/shardok/ai/AIFleeDecisionCalculator.cpp

@@ -15,9 +15,9 @@
 namespace shardok {
 
 auto AIFleeDecisionCalculator::GetFleeCommandIndex(
-        const CommandList::const_iterator& fleeCommand,
-        const CommandListSPtr& availableCommands) -> size_t {
-    return static_cast<size_t>(std::distance(availableCommands->begin(), fleeCommand));
+        const vector<CommandProto>::const_iterator& fleeCommand,
+        const vector<CommandProto>& availableCommands) -> size_t {
+    return static_cast<size_t>(std::distance(availableCommands.begin(), fleeCommand));
 }
 
 auto AIFleeDecisionCalculator::EstimateCombatSuccess(
@@ -134,14 +134,14 @@ auto AIFleeDecisionCalculator::EstimateCombatSuccess(
 auto AIFleeDecisionCalculator::EvaluateFleeVsFight(
         PlayerId playerId,
         const GameStateW& guessedState,
-        const CommandListSPtr& availableCommands,
-        const CommandList::const_iterator& fleeCommand,
+        const vector<CommandProto>& availableCommands,
+        const vector<CommandProto>::const_iterator& fleeCommand,
         int maxRounds,
         int minimumFleeOddsThreshold,
         int desperateFleeThreshold,
         bool enableDebugLogging) -> FleeDecision {
     // Get flee success odds
-    const int fleeSuccessChance = (*fleeCommand)->GetOddsPercentile();
+    const int fleeSuccessChance = fleeCommand->odds().success_chance();
 
     if (enableDebugLogging) {
         printf("AI FinalRound: Evaluating flee (odds=%d%%)...\n", fleeSuccessChance);

src/main/cpp/net/eagle0/shardok/ai/AIFleeDecisionCalculator.hpp

@@ -9,11 +9,13 @@
 #ifndef AIFleeDecisionCalculator_hpp
 #define AIFleeDecisionCalculator_hpp
 
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokCommand.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokEngine.hpp"
+#include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
 
 namespace shardok {
 
+using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
+
 class AIFleeDecisionCalculator {
 public:
     // Configuration for flee decision thresholds
@@ -33,8 +35,8 @@ public:
     [[nodiscard]] static auto EvaluateFleeVsFight(
             PlayerId playerId,
             const GameStateW& guessedState,
-            const CommandListSPtr& availableCommands,
-            const CommandList::const_iterator& fleeCommand,
+            const vector<CommandProto>& availableCommands,
+            const vector<CommandProto>::const_iterator& fleeCommand,
             int maxRounds,
             int minimumFleeOddsThreshold,
             int desperateFleeThreshold,
@@ -57,8 +59,8 @@ public:
 private:
     // Helper to get flee command index
     [[nodiscard]] static auto GetFleeCommandIndex(
-            const CommandList::const_iterator& fleeCommand,
-            const CommandListSPtr& availableCommands) -> size_t;
+            const vector<CommandProto>::const_iterator& fleeCommand,
+            const vector<CommandProto>& availableCommands) -> size_t;
 };
 
 }  // namespace shardok

src/main/cpp/net/eagle0/shardok/ai/AIHeuristicWeighting.cpp

@@ -4,7 +4,6 @@
 
 #include "AIHeuristicWeighting.hpp"
 
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokException.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/action_point_distances/ActionPointDistances.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/util/HexMapUtils.hpp"
 
@@ -15,10 +14,7 @@ using Coords = net::eagle0::shardok::storage::fb::Coords;
 using ProtoCoords = net::eagle0::shardok::common::Coords;
 
 double AIHeuristicWeighting::GetCommandWeight(
-        const CommandType commandType,
-        const UnitId actorUnitId,
-        const PlayerId actorPlayerId,
-        const Coords& targetCoords,
+        const net::eagle0::shardok::api::CommandDescriptor& command,
         const GameStateW& state,
         const CoordsSet& castleCoords,
         const APDCache* apdCache,
@@ -30,9 +26,9 @@ double AIHeuristicWeighting::GetCommandWeight(
 
     const auto* hexMap = state->hex_map();
     const auto* units = state->units();
-    const bool hasTarget = (targetCoords.row() >= 0 && targetCoords.column() >= 0);
+    const auto actorPlayerId = command.player();
 
-    switch (commandType) {
+    switch (command.type()) {
         // === HIGH VALUE OFFENSIVE (10.0) ===
         // Ranged attacks - very valuable, typically available when in range
         case CommandType::ARCHERY_COMMAND: return 20.0;
@@ -41,27 +37,20 @@ double AIHeuristicWeighting::GetCommandWeight(
 
         // Area/tactical spells - high impact
         case CommandType::METEOR_START_COMMAND: {
-            // METEOR_START doesn't have a target - it's based on actor location
-            if (hasTarget) {
-                throw ShardokInternalErrorException(
-                        "METEOR_START_COMMAND should not have target coordinates");
-            }
+            // High weight per enemy unit at or adjacent to target
+            if (!command.has_target()) return 0.0;  // Default if no target info
 
-            // Get actor's location
-            const auto* actorUnit = units->Get(actorUnitId);
-            if (!actorUnit) {
-                throw ShardokInternalErrorException(
-                        "METEOR_START_COMMAND actor unit not found in game state");
-            }
-
-            const Coords& actorLocation = actorUnit->location();
+            const Coords targetCoords(command.target().row(), command.target().column());
             int enemyCount = 0;
 
-            // Count enemies within meteor range (3 hexes) of actor location
-            constexpr int METEOR_RANGE = 3;
-            const auto tilesInRange = TilesWithinDistance(hexMap, actorLocation, METEOR_RANGE);
-            for (const auto& tileCoords : tilesInRange) {
-                if (const auto* unit = Occupant(units, tileCoords)) {
+            // Count enemies at target
+            if (const auto* targetUnit = Occupant(units, targetCoords)) {
+                if (targetUnit->player_id() != actorPlayerId) { enemyCount++; }
+            }
+
+            // Count enemies adjacent to target
+            for (const auto& neighbor : HexMapUtils::GetAdjacentTiles(hexMap, targetCoords)) {
+                if (const auto* unit = Occupant(units, neighbor.coords)) {
                     if (unit->player_id() != actorPlayerId) { enemyCount++; }
                 }
             }
@@ -71,12 +60,9 @@ double AIHeuristicWeighting::GetCommandWeight(
 
         case CommandType::METEOR_TARGET_COMMAND: {
             // High weight per enemy unit at or adjacent to target
-            if (!hasTarget) {
-                throw ShardokInternalErrorException(
-                        "METEOR_TARGET_COMMAND requires target coordinates for heuristic "
-                        "weighting");
-            }
+            if (!command.has_target()) return 6.0;  // Default if no target info
 
+            const Coords targetCoords(command.target().row(), command.target().column());
             int enemyCount = 0;
 
             // Count enemies at target
@@ -100,17 +86,15 @@ double AIHeuristicWeighting::GetCommandWeight(
         // Fire on enemy (context-dependent)
         case CommandType::START_FIRE_COMMAND: {
             // High if enemy at target, low otherwise
-            if (!hasTarget) {
-                throw ShardokInternalErrorException(
-                        "START_FIRE_COMMAND requires target coordinates for heuristic weighting");
-            }
+            if (!command.has_target()) return 3.0;  // Default
 
+            const Coords targetCoords(command.target().row(), command.target().column());
             if (const auto* targetUnit = Occupant(units, targetCoords)) {
                 if (targetUnit->player_id() != actorPlayerId) {
                     return 10.0;  // Enemy at target - high value
                 }
             }
-            return 1.0;  // No enemy - low value but still valid
+            return 1.0;  // No enemy - low value
         }
 
         // === MEDIUM-HIGH OFFENSIVE (5.0-7.0) ===
@@ -125,8 +109,9 @@ double AIHeuristicWeighting::GetCommandWeight(
 
         case CommandType::REDUCE_COMMAND: {
             // High if enemy at target, zero otherwise
-            if (!hasTarget) return 0.0;
+            if (!command.has_target()) return 0.0;
 
+            const Coords targetCoords(command.target().row(), command.target().column());
             if (const auto* targetUnit = Occupant(units, targetCoords)) {
                 if (targetUnit->player_id() != actorPlayerId) {
                     return 10.0;  // Enemy at target - very high value
@@ -142,13 +127,10 @@ double AIHeuristicWeighting::GetCommandWeight(
             }
 
             // Attackers: weight based on distance improvement towards castle
-            if (!hasTarget) {
-                throw ShardokInternalErrorException(
-                        "MOVE_COMMAND requires target coordinates for heuristic weighting");
-            }
+            if (!command.has_target()) return 4.0;  // Default if no target
 
             // Get actor unit to determine battalion type and start position
-            const auto* actorUnit = units->Get(actorUnitId);
+            const auto* actorUnit = units->Get(command.actor().value());
             if (!actorUnit) return 4.0;  // Default if can't find actor
 
             // Get battalion type for distance calculation
@@ -170,7 +152,7 @@ double AIHeuristicWeighting::GetCommandWeight(
             }
 
             // Calculate minimum distance from end to any castle
-            const Coords& endCoords = targetCoords;
+            const Coords endCoords(command.target().row(), command.target().column());
             auto minEndDistance = ActionPointDistances::IMPOSSIBLE;
             for (const auto& castleCoord : castleCoords) {
                 const auto dist = apd->Distance(endCoords, castleCoord);
@@ -199,18 +181,15 @@ double AIHeuristicWeighting::GetCommandWeight(
         // === LOW VALUE DEFENSIVE/UTILITY (1.0-2.0) ===
         case CommandType::EXTINGUISH_FIRE_COMMAND: {
             // High if friendly at target, low otherwise
-            if (!hasTarget) {
-                throw ShardokInternalErrorException(
-                        "EXTINGUISH_FIRE_COMMAND requires target coordinates for heuristic "
-                        "weighting");
-            }
+            if (!command.has_target()) return 2.0;  // Default
 
+            const Coords targetCoords(command.target().row(), command.target().column());
             if (const auto* targetUnit = Occupant(units, targetCoords)) {
                 if (targetUnit->player_id() == actorPlayerId) {
                     return 8.0;  // Friendly at target - high value
                 }
             }
-            return 1.0;  // No friendly - low value but still valid
+            return 1.0;  // No friendly - low value
         }
 
         case CommandType::UNIT_REST_COMMAND: return 1.5;

src/main/cpp/net/eagle0/shardok/ai/AIHeuristicWeighting.hpp

@@ -8,6 +8,7 @@
 
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdeprecated-redundant-constexpr-static-def"
+#include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
 #include "src/main/protobuf/net/eagle0/shardok/common/command_type.pb.h"
 #pragma clang diagnostic pop
 
@@ -24,10 +25,7 @@ public:
     // Get weight for a command using fast heuristics with game context
     // Returns weight >= 0.0, where 0.0 means "never select" and higher is more likely
     static double GetCommandWeight(
-            net::eagle0::shardok::common::CommandType commandType,
-            UnitId actorUnitId,
-            PlayerId actorPlayerId,
-            const Coords& targetCoords,
+            const net::eagle0::shardok::api::CommandDescriptor& command,
             const GameStateW& state,
             const CoordsSet& castleCoords,
             const APDCache* apdCache,

src/main/cpp/net/eagle0/shardok/ai/AITimeBudget.cpp

@@ -113,15 +113,6 @@ auto CalculateTimeBudget(
     const auto clampedBudgetMs = std::clamp(budgetMs, 200.0, maxBudgetMs);
     const auto remainingBudget = std::chrono::milliseconds(static_cast<int64_t>(clampedBudgetMs));
 
-    // TEMPORARY DEBUG OUTPUT
-    printf("[DEBUG CalculateTimeBudget] numCommands=%zu, msPerCommand=%.2f, budgetMs=%.2f, "
-           "clampedBudgetMs=%.2f, isClose=%d\n",
-           numCommands,
-           msPerCommand,
-           budgetMs,
-           clampedBudgetMs,
-           isClose);
-
     // Get minimum depth requirement
     const size_t minDepth = settingsGetter.Backing().min_lookahead_turns();
 

src/main/cpp/net/eagle0/shardok/ai/AIUnitScoreCalculator.cpp

@@ -17,10 +17,9 @@ using std::end;
 using std::shared_ptr;
 
 constexpr double kProfessionValue = 200;
-constexpr double kVigorScoreMultiplier = 5.0;
 constexpr double kCastleMultiplierBonus = 1.0;
 constexpr double kOnFireMultiplier = 0.25;
-constexpr double kAdjacentFireMultiplier = 0.80;
+constexpr double kAdjacentFireMultiplier = 0.99;
 constexpr double kOnIceMultiplier = 0.25;
 constexpr double kMeteorStartInRangeValue = 50;
 constexpr double kMeteorDirectTargetingEnemy = 2;
@@ -64,8 +63,7 @@ auto ContextFreeUnitValue(const Unit *unit) -> ScoreValue {
                      4.0;
     }
 
-    const double vigorValue =
-            unit->has_attached_hero() ? unit->attached_hero().vigor() * kVigorScoreMultiplier : 0.0;
+    const double vigorValue = unit->has_attached_hero() ? unit->attached_hero().vigor() : 0.0;
 
     double battalionTypeMultiplier = 1.0;
     switch (unit->battalion().type()) {
@@ -357,7 +355,9 @@ auto UnitValue(
                 kCastleMultiplierBonus * (terrain->modifier().castle().integrity() + 25) / 100.0;
     }
     double onFireMultiplier = 1.0;
-    if (terrain->modifier().fire().present()) { onFireMultiplier *= kOnFireMultiplier; }
+    if (terrain->modifier().fire().present() && (isAttacker || attackerWantsCastles)) {
+        onFireMultiplier *= kOnFireMultiplier;
+    }
     {
         for (const auto adjacentCoords = HexMapUtils::GetAdjacentCoords(map, location);
              const auto &c : adjacentCoords) {

src/main/cpp/net/eagle0/shardok/ai/AIWaterCrossingCommandChooser.hpp

@@ -13,9 +13,11 @@
 #include "src/main/cpp/net/eagle0/shardok/library/map/CoordsSet.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
 #include "src/main/flatbuffer/net/eagle0/shardok/storage/game_state.hpp"
+#include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
 
 namespace shardok {
 
+using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
 using GameState = net::eagle0::shardok::storage::fb::GameState;
 using Unit = net::eagle0::shardok::storage::fb::Unit;
 using ScoreValue = double;

src/main/cpp/net/eagle0/shardok/ai/BUILD.bazel

@@ -164,6 +164,7 @@ cc_library(
         ":ai_unit_score_calculator",
         "//src/main/cpp/net/eagle0/shardok/library:engine",
         "//src/main/cpp/net/eagle0/shardok/library/util:hex_map_utils",
+        "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",
     ],
 )
 
@@ -181,6 +182,7 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library/action_point_distances:action_point_distances_cache",
         "//src/main/cpp/net/eagle0/shardok/library/map:coords_set",
         "//src/main/cpp/net/eagle0/shardok/library/util:hex_map_utils",
+        "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",
         "//src/main/protobuf/net/eagle0/shardok/common:command_type_cc_proto",
     ],
 )
@@ -204,6 +206,7 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library:game_state_w",
         "//src/main/cpp/net/eagle0/shardok/library/map:coords_set",
         "//src/main/cpp/net/eagle0/shardok/library/util:hex_cube_utils",
+        "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",
         "//src/main/protobuf/net/eagle0/shardok/common:command_type_cc_proto",
     ],
 )
@@ -226,6 +229,7 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
         "//src/main/cpp/net/eagle0/shardok/library/util:hex_map_utils",
         "//src/main/flatbuffer/net/eagle0/shardok/storage:game_state_cc_fbs",
+        "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",
         "//src/main/protobuf/net/eagle0/shardok/common:command_type_cc_proto",
     ],
 )
@@ -312,6 +316,7 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library:game_state_w",
         "//src/main/cpp/net/eagle0/shardok/library/action_point_distances",
         "//src/main/cpp/net/eagle0/shardok/library/action_point_distances:action_point_distances_cache",
+        "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",
     ],
 )
 
@@ -354,6 +359,7 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/ai/score:ai_score_calculator_interface",
         "//src/main/cpp/net/eagle0/shardok/library:engine",
         "//src/main/cpp/net/eagle0/shardok/library/util:hex_map_utils",
+        "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",
     ],
 )
 

src/main/cpp/net/eagle0/shardok/ai/IterativeDeepeningAI.cpp

@@ -38,7 +38,7 @@ IterativeDeepeningAI::IterativeDeepeningAI(
 auto IterativeDeepeningAI::IterativeSearch(
         const GameSettingsSPtr& settings,
         const GameStateW& state,
-        const CommandListSPtr& commands,
+        const std::vector<CommandProto>& commands,
         const AITimeBudget& initialBudget) const -> SearchResult {
     // Make a mutable copy of the time budget to track remaining time
     AITimeBudget timeBudget = initialBudget;
@@ -51,7 +51,7 @@ auto IterativeDeepeningAI::IterativeSearch(
 
     // DEBUG: Clear TT to see if that's causing the suspicious depth reaching
     // g_transpositionTable.clear();  // Uncomment to test without cross-search caching
-    if (commands->empty()) {
+    if (commands.empty()) {
 #if DEBUG_ITERATIVE_DEEPENING_TIMINGS
         printf("ID AI: Commands are empty, returning early\n");
 #endif
@@ -75,9 +75,9 @@ auto IterativeDeepeningAI::IterativeSearch(
 
     // Initialize data structures for tracking scores at each depth
     scoresByDepth.clear();
-    scoresByDepth.resize(commands->size());
+    scoresByDepth.resize(commands.size());
     highestDepthCompleted.clear();
-    highestDepthCompleted.resize(commands->size(), 0);
+    highestDepthCompleted.resize(commands.size(), 0);
 
     size_t currentDepth = 1;
     size_t previousBestCommand = 0;  // Track best command from previous depth
@@ -132,8 +132,7 @@ auto IterativeDeepeningAI::IterativeSearch(
             evaluatedCount++;
 
             // Check if this command is not END_TURN_COMMAND
-            if ((*commands)[cmdIndex]->GetCommandType() !=
-                net::eagle0::shardok::common::END_TURN_COMMAND) {
+            if (commands[cmdIndex].type() != net::eagle0::shardok::common::END_TURN_COMMAND) {
                 allEndTurnCommands = false;
             }
         }
@@ -144,7 +143,7 @@ auto IterativeDeepeningAI::IterativeSearch(
             size_t currentBestCommand = 0;
             ScoreValue currentBestScore = -std::numeric_limits<ScoreValue>::infinity();
 
-            for (size_t i = 0; i < commands->size(); ++i) {
+            for (size_t i = 0; i < commands.size(); ++i) {
                 if (highestDepthCompleted[i] >= currentDepth) {
                     if (scoresByDepth[i][currentDepth] > currentBestScore) {
                         currentBestScore = scoresByDepth[i][currentDepth];
@@ -157,20 +156,16 @@ auto IterativeDeepeningAI::IterativeSearch(
             if (currentDepth > 1 && currentBestCommand != previousBestCommand) {
 #if DEBUG_ITERATIVE_DEEPENING_TIMINGS
                 printf("ID AI: Best command changed at depth %lu:\n", currentDepth);
-                printf("  Depth %lu best: command %zu (score %.2f) - type: %s\n",
+                printf("  Depth %lu best: command %zu (score %.2f) - %s\n",
                        currentDepth - 1,
                        previousBestCommand,
                        scoresByDepth[previousBestCommand][currentDepth - 1],
-                       net::eagle0::shardok::common::CommandType_Name(
-                               (*commands)[previousBestCommand]->GetCommandType())
-                               .c_str());
-                printf("  Depth %lu best: command %zu (score %.2f) - type: %s\n",
+                       commands[previousBestCommand].DebugString().c_str());
+                printf("  Depth %lu best: command %zu (score %.2f) - %s\n",
                        currentDepth,
                        currentBestCommand,
                        currentBestScore,
-                       net::eagle0::shardok::common::CommandType_Name(
-                               (*commands)[currentBestCommand]->GetCommandType())
-                               .c_str());
+                       commands[currentBestCommand].DebugString().c_str());
 #endif
             }
 
@@ -249,7 +244,7 @@ auto IterativeDeepeningAI::IterativeSearch(
     result.searchCompleted = result.minimumDepthCompleted;
     result.timeUsed = std::chrono::duration_cast<std::chrono::milliseconds>(
             std::chrono::steady_clock::now() - startTime);
-    result.availableCommandCount = commands->size();
+    result.availableCommandCount = commands.size();
     result.commandCountEvaluated = evaluatedCountAtHighestDepth;
     result.completionReason = completionReason;
 
@@ -274,7 +269,7 @@ auto IterativeDeepeningAI::SearchCommandAtDepthWithEngine(
         const ShardokEngine& guessedEngine,
         const AIScoreCalculator& scorer,
         const int maxRepeatCount,
-        const CommandListSPtr& commands,
+        const std::vector<CommandProto>& commands,
         const size_t commandIndex,
         const int desiredDepth,
         const ScoreValue currentUtility,
@@ -284,10 +279,10 @@ auto IterativeDeepeningAI::SearchCommandAtDepthWithEngine(
     result.depthAchieved = desiredDepth;
     result.searchCompleted = true;
     result.minimumDepthCompleted = true;
-    result.availableCommandCount = commands->size();
+    result.availableCommandCount = commands.size();
     result.commandCountEvaluated = 1;  // We're evaluating just this command
 
-    if (commandIndex >= commands->size()) {
+    if (commandIndex >= commands.size()) {
         result.bestScore = 0.0;
         std::promise<SearchResult> p;
         p.set_value(result);

src/main/cpp/net/eagle0/shardok/ai/IterativeDeepeningAI.hpp

@@ -14,15 +14,16 @@
 #include "src/main/cpp/net/eagle0/shardok/ai/AIAttackLocations.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/score/AIScoreCalculator.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokCTypes.h"
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokCommand.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/action_point_distances/ActionPointDistancesCache.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/util/HexMapUtils.hpp"
+#include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
 
 namespace shardok {
 
 // Forward declarations
 class ShardokEngine;
 using ScoreValue = double;
+using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
 using BattalionTypeGetter = std::function<BattalionTypeSPtr(BattalionTypeId)>;
 
 /// Reason why AI evaluation completed at the achieved depth.
@@ -69,7 +70,7 @@ public:
     [[nodiscard]] SearchResult IterativeSearch(
             const GameSettingsSPtr& settings,
             const GameStateW& state,
-            const CommandListSPtr& commands,
+            const std::vector<CommandProto>& commands,
             const AITimeBudget& initialBudget) const;
 
 private:
@@ -92,7 +93,7 @@ private:
             const ShardokEngine& guessedEngine,
             const AIScoreCalculator& scorer,
             int maxRepeatCount,
-            const CommandListSPtr& commands,
+            const std::vector<CommandProto>& commands,
             size_t commandIndex,
             int desiredDepth,
             ScoreValue currentUtility,

src/main/cpp/net/eagle0/shardok/ai/ShardokAIClient.cpp

@@ -10,15 +10,7 @@
 
 #define DEBUG_FLEE_DECISIONS
 
-// Enable to dump game state and debug tree to /tmp for debugging
-// #define ENABLE_MCTS_DEBUG_DUMP
-
-#ifdef ENABLE_MCTS_DEBUG_DUMP
-#include <chrono>
-#include <fstream>
-#include <iomanip>
-#include <sstream>
-#endif
+#include <google/protobuf/util/message_differencer.h>
 
 #include "AIAttackerStrategySelector.hpp"
 #include "AIConfig.hpp"
@@ -88,51 +80,30 @@ ShardokAIClient::ShardokAIClient(
     apdCache->ConsolidateThreadLocalCache_Racy();
 }
 
-void CheckCommand(const CommandSPtr &realCommand, const CommandSPtr &guessedCommand) {
-    // Verify that the AI's guessed state produces the same available commands as the real state.
-    // We only compare fields that uniquely identify a command - metadata fields like action_points,
-    // will_unhide, next_round_target_info are not part of command identity.
+void CheckCommand(const CommandProto &realDescriptor, const CommandProto &guessedDescriptor) {
+    string diff;
+    auto differencer = google::protobuf::util::MessageDifferencer();
+    differencer.IgnoreField(CommandProto::descriptor()->FindFieldByNumber(
+            CommandProto::kFollowUpCommandTypesFieldNumber));
+    differencer.ReportDifferencesToString(&diff);
+    if (!differencer.Compare(realDescriptor, guessedDescriptor)) {
+        printf("diff: %s\n\n", diff.c_str());
 
-    if (realCommand->GetCommandType() != guessedCommand->GetCommandType()) {
-        throw ShardokInternalErrorException("Command type mismatch between real and guessed state");
-    }
-
-    if (realCommand->GetPlayerId() != guessedCommand->GetPlayerId()) {
-        throw ShardokInternalErrorException("Player ID mismatch between real and guessed state");
-    }
-
-    if (realCommand->GetActorUnitId() != guessedCommand->GetActorUnitId()) {
-        throw ShardokInternalErrorException("Actor unit mismatch between real and guessed state");
-    }
-
-    if (realCommand->GetTargetRow() != guessedCommand->GetTargetRow() ||
-        realCommand->GetTargetColumn() != guessedCommand->GetTargetColumn()) {
-        throw ShardokInternalErrorException(
-                "Target coordinates mismatch between real and guessed state");
-    }
-
-    // For commands with odds (like FLEE), verify the odds match
-    if (realCommand->HasOdds() != guessedCommand->HasOdds()) {
-        throw ShardokInternalErrorException(
-                "Odds presence mismatch between real and guessed state");
-    }
-
-    if (realCommand->HasOdds() && guessedCommand->HasOdds()) {
-        if (realCommand->GetOddsPercentile() != guessedCommand->GetOddsPercentile()) {
-            throw ShardokInternalErrorException(
-                    "Odds percentile mismatch between real and guessed state");
-        }
+        printf("Selected command descriptor\n%s\ndoes not match guessed\n%s\n\n",
+               realDescriptor.DebugString().c_str(),
+               guessedDescriptor.DebugString().c_str());
+        throw ShardokInternalErrorException("Illegal state for AI client");
     }
 }
 
 auto ShardokAIClient::StandardChooseCommandIndex(
         const GameSettingsSPtr &settings,
         const GameStateW &guessedState,
-        const CommandListSPtr &realAvailableCommands) const -> CommandChoiceResults {
+        const vector<CommandProto> &realAvailableCommands) const -> CommandChoiceResults {
     const auto settingsGetter = settings->GetGetter();
     const auto guessedEngine = ShardokEngine(settings, guessedState);
-    const auto guessedCommands = guessedEngine.GetAvailableCommandsForAIPlayer(playerId);
-    const auto commandCount = guessedCommands->size();
+    const auto guessedCommands = guessedEngine.GetAvailableCommandProtos(playerId, false);
+    const auto commandCount = guessedCommands.size();
 
     // Calculate time budget based on game situation using new dynamic per-command settings
     const auto timeBudget = CalculateTimeBudget(playerId, settings, guessedState, commandCount);
@@ -145,14 +116,6 @@ auto ShardokAIClient::StandardChooseCommandIndex(
     //   - MINIMAX correctly models opponent choosing best response
     //   - Explores through one opponent turn for tactical accuracy
     auto adjustedMCTSConfig = mctsConfig;
-
-    // For fair evaluation: simulate leaves to opponent's turn start (maxSimulationFlips=1)
-    // This ensures all leaves are scored at the same game phase:
-    // - Leaves at playerFlips=0 (still my turn): simulate through END_TURN to playerFlips=1
-    // - Leaves at playerFlips=1 (opponent's turn): evaluate immediately
-    // Result: consistent comparison of "what happens after I end my turn"
-    // adjustedMCTSConfig.maxSimulatfixionFlips = 1;
-
     // adjustedMCTSConfig.maxPlayerFlips = 0;
     // if (timeBudget.isCloseToEnemy) {
     //     adjustedMCTSConfig.maxPlayerFlips = 1;
@@ -168,10 +131,9 @@ auto ShardokAIClient::StandardChooseCommandIndex(
     //     }
     // }
 
-    assert(commandCount == realAvailableCommands->size());
-    // Verify that the AI's guessed state produces the same available commands as reality
+    assert(commandCount == realAvailableCommands.size());
     for (size_t i = 0; i < commandCount; i++) {
-        CheckCommand((*realAvailableCommands)[i], (*guessedCommands)[i]);
+        CheckCommand(realAvailableCommands[i], guessedCommands[i]);
     }
 
     // Extract values directly from settings for strategy selection
@@ -218,37 +180,6 @@ auto ShardokAIClient::StandardChooseCommandIndex(
     IterativeDeepeningAI::SearchResult search_result;
 
     if (aiAlgorithmType == AIAlgorithmType::MCTS) {
-#ifdef ENABLE_MCTS_DEBUG_DUMP
-        // Set unique debug dump path for each action using timestamp
-        const auto now = std::chrono::system_clock::now();
-        const auto nowTime = std::chrono::system_clock::to_time_t(now);
-        const auto nowMs =
-                std::chrono::duration_cast<std::chrono::milliseconds>(now.time_since_epoch()) %
-                1000;
-
-        std::ostringstream pathStream;
-        pathStream << "/tmp/shardok_debug_"
-                   << std::put_time(std::localtime(&nowTime), "%Y%m%d_%H%M%S") << "_"
-                   << std::setfill('0') << std::setw(3) << nowMs.count() << "_p"
-                   << static_cast<int>(playerId) << ".txt";
-        adjustedMCTSConfig.debugDumpPath = pathStream.str();
-
-        // Also dump the game state to a file for reproduction
-        std::ostringstream statePathStream;
-        statePathStream << "/tmp/shardok_state_"
-                        << std::put_time(std::localtime(&nowTime), "%Y%m%d_%H%M%S") << "_"
-                        << std::setfill('0') << std::setw(3) << nowMs.count() << "_p"
-                        << static_cast<int>(playerId) << ".bin";
-        const std::string statePath = statePathStream.str();
-
-        // Write the flatbuffer game state to file using SaveTo method
-        if (guessedState.SaveTo(statePath)) {
-            printf("Game state dumped to: %s\n", statePath.c_str());
-        } else {
-            printf("Failed to dump game state to: %s\n", statePath.c_str());
-        }
-#endif  // ENABLE_MCTS_DEBUG_DUMP
-
         // Using Monte Carlo Tree Search AI (with abstraction layer)
         ShardokMCTSAI ai(
                 playerId,
@@ -288,8 +219,7 @@ auto ShardokAIClient::StandardChooseCommandIndex(
                    result.commandCountEvaluated,
                    result.availableCommandCount);
         }
-        const auto chosenCommandType =
-                (*realAvailableCommands)[result.chosenIndex]->GetCommandType();
+        const auto chosenCommandType = realAvailableCommands[result.chosenIndex].type();
         printf("ID AI: Search complete - achieved depth %d for best command %zu (%s)\n",
                result.depthAchieved,
                result.chosenIndex,
@@ -304,20 +234,19 @@ auto ShardokAIClient::StandardChooseCommandIndex(
 auto ShardokAIClient::LateRoundAttackerChooseCommandIndex(
         const GameSettingsSPtr &settings,
         const GameStateW &guessedState,
-        const CommandListSPtr &realAvailableCommands) const -> CommandChoiceResults {
+        const vector<CommandProto> &realAvailableCommands) const -> CommandChoiceResults {
     if (const auto dismissCommand = std::ranges::find_if(
-                *realAvailableCommands,
-                [](const CommandSPtr &cmd) {
-                    return cmd->GetCommandType() ==
-                           net::eagle0::shardok::common::DISMISS_UNIT_COMMAND;
+                realAvailableCommands,
+                [](const net::eagle0::shardok::api::CommandDescriptor &cmd) {
+                    return cmd.type() == net::eagle0::shardok::common::DISMISS_UNIT_COMMAND;
                 });
-        dismissCommand == realAvailableCommands->end()) {
+        dismissCommand == realAvailableCommands.end()) {
         return StandardChooseCommandIndex(settings, guessedState, realAvailableCommands);
     } else {
         CommandChoiceResults results{};
         results.chosenIndex =
-                static_cast<size_t>(std::distance(realAvailableCommands->begin(), dismissCommand));
-        results.availableCommandCount = realAvailableCommands->size();
+                static_cast<size_t>(std::distance(realAvailableCommands.begin(), dismissCommand));
+        results.availableCommandCount = realAvailableCommands.size();
         results.depthAchieved = 1;          // Simple heuristic choice
         results.commandCountEvaluated = 1;  // Only evaluated one command type
         results.completionReason =
@@ -329,13 +258,14 @@ auto ShardokAIClient::LateRoundAttackerChooseCommandIndex(
 auto ShardokAIClient::FinalRoundAttackerChooseCommandIndex(
         const GameSettingsSPtr &settings,
         const GameStateW &guessedState,
-        const CommandListSPtr &realAvailableCommands) const -> CommandChoiceResults {
-    const auto fleeCommand =
-            std::ranges::find_if(*realAvailableCommands, [](const CommandSPtr &cmd) {
-                return cmd->GetCommandType() == net::eagle0::shardok::common::FLEE_COMMAND;
+        const vector<CommandProto> &realAvailableCommands) const -> CommandChoiceResults {
+    const auto fleeCommand = std::ranges::find_if(
+            realAvailableCommands,
+            [](const net::eagle0::shardok::api::CommandDescriptor &cmd) {
+                return cmd.type() == net::eagle0::shardok::common::FLEE_COMMAND;
             });
 
-    if (fleeCommand == realAvailableCommands->end()) {
+    if (fleeCommand == realAvailableCommands.end()) {
         return LateRoundAttackerChooseCommandIndex(settings, guessedState, realAvailableCommands);
     }
 
@@ -364,7 +294,7 @@ auto ShardokAIClient::FinalRoundAttackerChooseCommandIndex(
     if (fleeDecision.shouldFlee) {
         CommandChoiceResults results{};
         results.chosenIndex = fleeDecision.commandIndex;
-        results.availableCommandCount = realAvailableCommands->size();
+        results.availableCommandCount = realAvailableCommands.size();
         results.depthAchieved = 1;          // Heuristic choice
         results.commandCountEvaluated = 1;  // Only evaluated one command type
         results.completionReason = EvaluationCompletionReason::RAN_OUT_OF_COMMANDS;
@@ -378,7 +308,7 @@ auto ShardokAIClient::FinalRoundAttackerChooseCommandIndex(
 auto ShardokAIClient::ChooseCommandIndex(
         const GameSettingsSPtr &settings,
         const GameStateView &gsv,
-        const CommandListSPtr &realAvailableCommands) const -> CommandChoiceResults {
+        const vector<CommandProto> &realAvailableCommands) const -> CommandChoiceResults {
     static int typeChosenCount[net::eagle0::shardok::common::CommandType_MAX + 1];
     static int totalChoices = 0;
 
@@ -397,7 +327,7 @@ auto ShardokAIClient::ChooseCommandIndex(
         results = StandardChooseCommandIndex(settings, guessedState, realAvailableCommands);
     }
 
-    const auto chosenType = (*realAvailableCommands)[results.chosenIndex]->GetCommandType();
+    const auto chosenType = realAvailableCommands[results.chosenIndex].type();
     typeChosenCount[static_cast<int>(chosenType)]++;
     totalChoices++;
 
@@ -423,8 +353,8 @@ auto ShardokAIClient::ChooseCommandIndex(
 
 auto ShardokAIClient::ChooseCommandIndex(const ShardokEngine &engine) const
         -> CommandChoiceResults {
-    if (const auto &availableCommands = engine.GetAvailableCommandsForAIPlayer(playerId);
-        availableCommands->empty()) {
+    if (const auto &availableCommands = engine.GetAvailableCommandProtos(playerId, false);
+        availableCommands.empty()) {
         printf("no commands for player %d\n", playerId);
         throw ShardokInternalErrorException(
                 "Asked to choose a command, but there are none available");

src/main/cpp/net/eagle0/shardok/ai/ShardokAIClient.hpp

@@ -18,7 +18,6 @@
 #include "src/main/cpp/net/eagle0/shardok/ai/AIWaterCrossingCommandChooser.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/IterativeDeepeningAI.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/score/AIScoreCalculator.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokCommand.hpp"
 #include "src/main/protobuf/net/eagle0/shardok/api/game_state_view.pb.h"
 
 namespace shardok {
@@ -55,20 +54,20 @@ private:
     [[nodiscard]] auto StandardChooseCommandIndex(
             const GameSettingsSPtr& settings,
             const GameStateW& guessedState,
-            const CommandListSPtr& realAvailableCommands) const -> CommandChoiceResults;
+            const vector<CommandProto>& realAvailableCommands) const -> CommandChoiceResults;
     [[nodiscard]] auto LateRoundAttackerChooseCommandIndex(
             const GameSettingsSPtr& settings,
             const GameStateW& guessedState,
-            const CommandListSPtr& realAvailableCommands) const -> CommandChoiceResults;
+            const vector<CommandProto>& realAvailableCommands) const -> CommandChoiceResults;
     [[nodiscard]] auto FinalRoundAttackerChooseCommandIndex(
             const GameSettingsSPtr& settings,
             const GameStateW& guessedState,
-            const CommandListSPtr& realAvailableCommands) const -> CommandChoiceResults;
+            const vector<CommandProto>& realAvailableCommands) const -> CommandChoiceResults;
 
     [[nodiscard]] auto ChooseCommandIndex(
             const GameSettingsSPtr& settings,
             const net::eagle0::shardok::api::GameStateView& gsv,
-            const CommandListSPtr& realAvailableCommands) const -> CommandChoiceResults;
+            const vector<CommandProto>& realAvailableCommands) const -> CommandChoiceResults;
 
 public:
     explicit ShardokAIClient(

src/main/cpp/net/eagle0/shardok/ai/mcts/BUILD.bazel

@@ -20,5 +20,6 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library:shardok_c_types",
         "//src/main/cpp/net/eagle0/shardok/library/action_point_distances:action_point_distances_cache",
         "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
+        "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",
     ],
 )

src/main/cpp/net/eagle0/shardok/ai/mcts/CHANCE_NODES_DESIGN.md

@@ -1,813 +0,0 @@
-# Chance Nodes in MCTS for Shardok
-
-## Problem Statement
-
-### Current Behavior
-The current MCTS implementation uses a fixed roll (50th percentile) for all probabilistic outcomes during simulation. This creates several issues:
-
-1. **Binary success actions overvalued**: A START_FIRE command with 51% success is treated as always succeeding, making it appear better than it actually is.
-2. **Discontinuity at 50%**: Actions with 49% vs 51% success have dramatically different evaluations, when they should be similar.
-3. **Variable-outcome actions simplified**: Melee/archery attacks with damage ranges are evaluated at a single point rather than their full distribution.
-
-### Example Issue
-```
-START_FIRE with 51% success:
-- Current MCTS: Assumes always succeeds (roll = 50)
-- Reality: Succeeds 51% of time, fails 49% of time
-- Result: AI overvalues this action
-```
-
-### How Iterative Deepening Solves This
-The iterative deepening AI (see `AICommandEvaluator.cpp:352-393`) handles randomness correctly:
-
-```cpp
-// For actions with odds (binary success/fail):
-// 1. Evaluate success outcome with representative roll
-auto [successScore, successLookahead] = EvaluateWithRandomness(
-    ...,
-    std::make_shared<SequenceRandomGenerator>(std::vector{1.0 - successChance / 2.0})
-);
-
-// 2. Evaluate failure outcome with representative roll
-auto [failureScore, failureLookahead] = EvaluateWithRandomness(
-    ...,
-    std::make_shared<SequenceRandomGenerator>(std::vector{(1.0 - successChance) / 2.0})
-);
-
-// 3. Compute weighted average (expected value)
-immediateScore = std::lerp(failureScore, successScore, successChance);
-lookaheadScore = std::lerp(failureLookahead.get(), successLookahead.get(), successChance);
-```
-
-This is essentially an implicit form of chance nodes - evaluating both outcomes and weighting by probability.
-
-## Chance Nodes Concept
-
-### Classic MCTS with Chance Nodes
-
-In games with randomness (e.g., backgammon), MCTS uses two types of nodes:
-
-1. **Decision Nodes**: Player chooses an action
-   - Selection uses UCB formula (exploration/exploitation tradeoff)
-   - One child per legal action
-
-2. **Chance Nodes**: Nature determines outcome
-   - Selection uses expectation (weighted by probability)
-   - One child per possible outcome
-
-```
-Decision Node (Player to move)
-├─ Action A
-│  └─ Chance Node
-│     ├─ Outcome 1 (prob 0.3) → Game State
-│     ├─ Outcome 2 (prob 0.5) → Game State
-│     └─ Outcome 3 (prob 0.2) → Game State
-└─ Action B
-   └─ Deterministic → Game State
-```
-
-### Example: START_FIRE in Shardok
-
-**Current approach:**
-```
-State S
-└─ START_FIRE (roll=50)
-   └─ State S' (fire always starts)
-```
-
-**With chance nodes:**
-```
-State S
-└─ START_FIRE action
-   └─ Chance Node
-      ├─ Success (51%) → State S_success (fire started)
-      └─ Failure (49%) → State S_failure (no fire, vigor spent)
-```
-
-### Value Propagation
-
-**Decision nodes:** Maximize/minimize over children (depending on player)
-**Chance nodes:** Expected value over children (weighted by probability)
-
-```cpp
-// Decision node value (max for current player)
-value = max(child.value for child in children)
-
-// Chance node value (expectation)
-value = sum(prob[i] * child[i].value for i in outcomes)
-```
-
-## Implementation Approaches
-
-### Option 1: Explicit Chance Nodes (Full Implementation)
-
-Modify the MCTS tree structure to explicitly represent chance nodes.
-
-**Pros:**
-- Theoretically sound
-- Handles arbitrary outcome distributions
-- Clear separation of decision vs chance
-
-**Cons:**
-- Significant code changes
-- Larger tree (more memory)
-- More complex tree traversal
-
-**Tree Structure:**
-```cpp
-enum class NodeType { DECISION, CHANCE };
-
-struct MCTSNode {
-    NodeType type;
-
-    // For decision nodes
-    MCTSPlayerId player;
-    std::vector<std::unique_ptr<MCTSAction>> actions;
-    std::vector<std::unique_ptr<MCTSNode>> children;  // One per action
-
-    // For chance nodes
-    std::vector<double> probabilities;  // One per outcome
-    std::vector<std::unique_ptr<MCTSNode>> outcomes;  // One per outcome
-
-    double visits;
-    double totalReward;
-};
-```
-
-**Selection Phase:**
-```cpp
-MCTSNode* select(MCTSNode* node) {
-    while (!node->isLeaf()) {
-        if (node->type == DECISION) {
-            // Use UCB to select action
-            node = selectChildUCB(node);
-        } else {  // CHANCE node
-            // Use probability-weighted selection
-            node = selectOutcomeByProbability(node);
-        }
-    }
-    return node;
-}
-```
-
-**Backpropagation:**
-```cpp
-void backpropagate(MCTSNode* node, double reward) {
-    while (node != nullptr) {
-        node->visits++;
-        if (node->type == DECISION) {
-            node->totalReward += reward;  // Sum for averaging
-        } else {  // CHANCE node
-            node->totalReward += reward;  // Still sum, but averaged differently
-        }
-        node = node->parent;
-    }
-}
-```
-
-### Option 2: Implicit Chance Nodes (Hybrid Approach)
-
-Keep the current tree structure but sample outcomes during expansion/simulation.
-
-**Pros:**
-- Smaller code changes
-- More memory efficient
-- Easier to implement incrementally
-
-**Cons:**
-- Less theoretically pure
-- May need more visits to converge
-- Sampling introduces variance
-
-**Approach:**
-```cpp
-// During expansion
-std::unique_ptr<MCTSGameState> expand(
-    const MCTSGameState& state,
-    const MCTSAction& action
-) {
-    if (action.isDeterministic()) {
-        return applyActionDeterministic(state, action);
-    } else {
-        // Sample an outcome based on probabilities
-        auto outcome = sampleOutcome(action);
-        return applyActionWithOutcome(state, action, outcome);
-    }
-}
-```
-
-**For binary actions (e.g., START_FIRE):**
-```cpp
-// Expand creates one of two children based on sampling
-if (random() < successProbability) {
-    return applySuccess(state, action);
-} else {
-    return applyFailure(state, action);
-}
-
-// Over many visits, visit ratio will approach probability ratio
-// E.g., 51% success action will have ~51% success children, 49% failure children
-```
-
-### Option 3: Determinized Sampling (Simplest)
-
-Pre-sample all random outcomes at the start of each simulation rollout.
-
-**Pros:**
-- Minimal code changes
-- Easy to understand
-- Works with existing tree structure
-
-**Cons:**
-- May converge slowly
-- Doesn't explicitly represent probability
-- Can waste simulations on unlikely outcomes
-
-**Approach:**
-```cpp
-// At start of each simulation
-std::vector<double> rollSequence = generateRollSequence(maxDepth);
-
-// Use sequence during simulation
-auto state = rootState;
-for (int depth = 0; depth < maxDepth; depth++) {
-    auto action = selectAction(state);
-    state = applyAction(state, action, rollSequence[depth]);
-}
-```
-
-## Recommended Approach: Progressive Enhancement
-
-Implement in phases to manage complexity:
-
-### Phase 1: Binary Chance Nodes (Explicit)
-
-Start with actions that have clear success/failure outcomes (e.g., START_FIRE, EXTINGUISH_FIRE, RAISE_DEAD):
-
-1. Identify binary actions (commands with `HasOdds()`)
-2. Add chance node support for these actions only
-3. Modify tree expansion to create chance nodes
-4. Update selection/backpropagation for chance nodes
-
-**Implementation:**
-```cpp
-// In ShardokGameEngine::getLegalActions()
-// Mark which actions require chance nodes
-struct ActionMetadata {
-    std::unique_ptr<MCTSAction> action;
-    bool requiresChanceNode;
-    double successProbability;  // If requiresChanceNode = true
-};
-```
-
-```cpp
-// In tree expansion
-if (action.requiresChanceNode) {
-    // Create chance node with two children
-    auto chanceNode = std::make_unique<MCTSNode>(CHANCE);
-    chanceNode->probabilities = {successProb, 1.0 - successProb};
-
-    // Expand both outcomes
-    chanceNode->outcomes.push_back(applySuccess(state, action));
-    chanceNode->outcomes.push_back(applyFailure(state, action));
-
-    return chanceNode;
-} else {
-    // Normal deterministic expansion
-    return applyAction(state, action);
-}
-```
-
-### Phase 2: Multi-Outcome Actions
-
-Extend to actions with multiple outcomes (e.g., melee damage ranges):
-
-1. Discretize continuous distributions into buckets
-2. For melee/archery, use 3-5 representative damage values (min, low, avg, high, max)
-3. Compute probabilities for each bucket
-4. Create chance nodes with multiple children
-
-**Example: Melee Attack**
-```cpp
-// Instead of sampling full damage distribution,
-// use representative values
-struct DamageBucket {
-    int damageValue;  // Representative damage
-    double probability;  // Probability of this range
-};
-
-// For a melee attack that can deal 10-20 damage
-std::vector<DamageBucket> buckets = {
-    {10, 0.1},  // Min damage (unlucky)
-    {13, 0.2},  // Low damage
-    {15, 0.4},  // Average damage
-    {17, 0.2},  // High damage
-    {20, 0.1}   // Max damage (lucky)
-};
-```
-
-### Phase 3: Optimization
-
-Once chance nodes work correctly:
-
-1. Add transposition table support for chance nodes
-2. Optimize memory layout
-3. Consider progressive widening (start with 2 outcomes, expand to more if visited often)
-4. Profile and tune
-
-## Design Decisions
-
-### How to Represent Outcomes?
-
-**Option A: Explicit state copies**
-```cpp
-struct ChanceNode {
-    std::vector<std::unique_ptr<MCTSGameState>> outcomeStates;
-    std::vector<double> probabilities;
-};
-```
-
-**Option B: Lazy evaluation**
-```cpp
-struct ChanceNode {
-    MCTSGameState baseState;
-    MCTSAction action;
-    std::vector<int> outcomeRolls;  // Roll values for each outcome
-    std::vector<double> probabilities;
-
-    // Compute state on-demand
-    MCTSGameState getOutcome(size_t index) {
-        return applyActionWithRoll(baseState, action, outcomeRolls[index]);
-    }
-};
-```
-
-**Recommendation:** Option B - lazy evaluation. Only materialize states when visited.
-
-### How Many Outcomes per Action?
-
-**Binary actions (START_FIRE, etc.):**
-- Exactly 2 outcomes (success/fail)
-- Use exact probabilities from `GetOddsPercentile()`
-
-**Damage actions (MELEE, ARCHERY):**
-- Start with 3 outcomes (low/med/high)
-- Can expand to 5 if needed for accuracy
-- Use representative rolls: 10th, 50th, 90th percentile
-
-**Complex actions (METEOR):**
-- Consider 2-3 outcomes initially
-- Can model as "hits N enemies" for N in {0, 1, 2, 3+}
-
-### How to Handle Transposition Table?
-
-**Challenge:** Same state can be reached via different chance outcomes
-
-**Solution:**
-- Hash based on game state only (not the path taken)
-- When looking up, return cached evaluation if state matches
-- This is already how transposition tables work!
-
-```cpp
-// Current approach works fine:
-auto hash = computeHash(gameState);  // Doesn't include how we got here
-if (auto cached = transpositionTable.lookup(hash)) {
-    return cached->value;
-}
-```
-
-### Selection at Chance Nodes
-
-**During tree traversal:**
-```cpp
-size_t selectOutcome(const ChanceNode& node) {
-    // Option 1: Sample by probability (introduces variance)
-    double r = random();
-    double cumulative = 0.0;
-    for (size_t i = 0; i < node.probabilities.size(); i++) {
-        cumulative += node.probabilities[i];
-        if (r < cumulative) return i;
-    }
-
-    // Option 2: Round-robin weighted by visit count vs probability
-    // (Explore under-visited outcomes more)
-    size_t leastVisited = findMostUnderExploredOutcome(node);
-    return leastVisited;
-}
-```
-
-**Recommendation:** Use Option 2 to ensure all outcomes get explored proportionally.
-
-## Integration Points
-
-### Modified Functions
-
-1. **`ShardokGameEngine::getLegalActions()`**
-   - Add metadata about which actions need chance nodes
-   - Return action + probability information
-
-2. **`ShardokGameEngine::applyAction()`**
-   - For binary actions, return both possible outcomes
-   - Or: take an explicit outcome index parameter
-
-3. **`AbstractMCTSAI::selection()`**
-   - Handle chance nodes differently from decision nodes
-   - Use probability-weighted selection instead of UCB
-
-4. **`AbstractMCTSAI::expand()`**
-   - Create chance node children for probabilistic actions
-   - May create multiple child nodes per action
-
-5. **`AbstractMCTSAI::backpropagate()`**
-   - Update all nodes in path (both decision and chance)
-   - Value calculation already handles this correctly (just averages)
-
-### New Functions Needed
-
-```cpp
-// In ShardokGameEngine
-struct ChanceOutcome {
-    int roll;  // The dice roll that produces this outcome
-    double probability;  // Probability of this outcome
-};
-
-std::vector<ChanceOutcome> getChanceOutcomes(const MCTSAction& action) const;
-```
-
-```cpp
-// In MCTSNode
-bool isChanceNode() const;
-const std::vector<double>& getOutcomeProbabilities() const;
-```
-
-## Testing Strategy
-
-### Unit Tests
-
-1. **Binary action correctness**
-   ```cpp
-   TEST(ChanceNodes, BinaryActionExpectedValue) {
-       // START_FIRE with 60% success
-       // Run MCTS with chance nodes
-       // Verify: visits to success ~= 60%, visits to failure ~= 40%
-       // Verify: expected value matches manual calculation
-   }
-   ```
-
-2. **Comparison with iterative deepening**
-   ```cpp
-   TEST(ChanceNodes, MatchesIterativeDeepening) {
-       // Same position, both AIs
-       // Should choose same action
-       // Scores should be similar (within variance)
-   }
-   ```
-
-3. **Transposition table with chance**
-   ```cpp
-   TEST(ChanceNodes, TranspositionConsistency) {
-       // Two paths to same state via different chance outcomes
-       // Should reuse cached evaluation
-   }
-   ```
-
-### Integration Tests
-
-1. Compare MCTS with/without chance nodes on test positions
-2. Verify that chance nodes reduce overvaluation of marginal actions
-3. Performance test: measure slowdown (expect 1.5-2x for binary actions)
-
-### Real-World Validation
-
-Run the problematic START_FIRE scenario:
-- With current MCTS: Should overvalue START_FIRE
-- With chance nodes: Should correctly weight success/failure
-- Expected: END_TURN should get significantly more visits
-
-## Performance Considerations
-
-### Memory Overhead
-
-**Per chance node:**
-- Probability vector: `N * sizeof(double)` (N = number of outcomes)
-- Outcome children: `N * sizeof(unique_ptr)`
-- For binary: ~32 bytes per chance node
-
-**Estimate:**
-- Current tree: ~100K nodes per search
-- With chance nodes: ~150K nodes (50% actions are probabilistic)
-- Extra memory: ~50K * 32 bytes = ~1.6 MB
-- **Acceptable overhead**
-
-### Computational Overhead
-
-**Per simulation:**
-- Current: 1 path through tree
-- With chance nodes: Still 1 path, but more nodes
-- Overhead: ~20-30% (more node visits)
-
-**Mitigation:**
-- Transposition table helps (same states via different paths)
-- Progressive widening (start with 2 outcomes, expand if visited often)
-- Lazy state evaluation (don't materialize until needed)
-
-### Convergence Speed
-
-Chance nodes may require more visits to converge because:
-- More children per action (branching factor increases)
-- Outcomes need proportional exploration
-
-**Mitigation:**
-- Use visit count thresholds before expanding chance nodes
-- Consider progressive widening (UCT-ProgressiveWidening)
-
-## Migration Path
-
-### Step 1: Infrastructure (1-2 days)
-- Add `NodeType` enum and metadata to MCTSNode
-- Implement chance node creation (without using them yet)
-- Add unit tests for chance node structure
-
-### Step 2: Binary Actions (2-3 days)
-- Identify all binary success/fail actions
-- Modify expansion to create chance nodes for these
-- Update selection/backpropagation
-- Test on START_FIRE scenario
-
-### Step 3: Integration Testing (1 day)
-- Run full MCTS tests with chance nodes enabled
-- Compare with iterative deepening on test positions
-- Validate that it fixes the START_FIRE overvaluation
-
-### Step 4: Multi-Outcome Actions (2-3 days)
-- Implement damage bucketing for MELEE/ARCHERY
-- Create chance nodes with 3-5 outcomes
-- Test on combat scenarios
-
-### Step 5: Optimization (1-2 days)
-- Profile performance
-- Add progressive widening if needed
-- Tune outcome granularity
-
-### Step 6: Documentation & Cleanup (1 day)
-- Document the new approach
-- Clean up code
-- Add comprehensive tests
-
-## Alternative: Simpler Hybrid Approach
-
-If full chance nodes are too complex, consider a hybrid:
-
-1. **Keep current tree structure** (no explicit chance nodes)
-2. **During expansion:** Sample outcome and create one child
-3. **Over many simulations:** Statistics converge to correct probabilities
-4. **Add outcome tracking:** Store "which outcome" in edge/node metadata
-
-**Example:**
-```cpp
-// Expansion samples an outcome
-auto expand(state, action) {
-    if (action.hasBinaryOutcome()) {
-        // Sample once
-        bool success = (random() < successProb);
-        // Store which outcome this edge represents
-        edge.metadata.outcome = success ? OUTCOME_SUCCESS : OUTCOME_FAILURE;
-        return applyWithOutcome(state, action, success);
-    }
-}
-
-// Selection prioritizes under-explored outcomes
-auto selectChild(node) {
-    // Find action where outcome distribution is unbalanced
-    // E.g., 60% success action should have ~60% success children
-    // If we have 80% success children, prefer exploring failure
-}
-```
-
-This is simpler but less theoretically sound. It's a reasonable starting point if full chance nodes prove too complex.
-
-## Comparison: Chance Nodes vs Open-Loop MCTS
-
-### What is Open-Loop MCTS?
-
-**Open-loop MCTS** (also called "determinization MCTS" or "information set MCTS") is an alternative approach to handling randomness:
-
-1. At the **start of each simulation**, sample all random outcomes needed for that simulation
-2. Play out the entire simulation using those fixed random values
-3. Different simulations use different random seeds
-4. The tree structure doesn't explicitly model randomness - it's all in the rollouts
-
-**Example implementation:**
-```cpp
-// At start of simulation
-std::vector<double> rollSequence = sampleRolls(maxDepth);  // Pre-sample all rolls
-
-// During simulation
-MCTSNode* node = root;
-for (int depth = 0; depth < maxDepth; depth++) {
-    Action action = selectAction(node);
-    node = applyAction(node, action, rollSequence[depth]);  // Use pre-sampled roll
-}
-```
-
-### Open-Loop MCTS for Shardok
-
-**How it would work:**
-```cpp
-// Each simulation samples a "possible world"
-void simulate(MCTSNode* root) {
-    // Sample random rolls for this simulation
-    auto rolls = generateRollSequence();  // e.g., {0.45, 0.78, 0.23, ...}
-
-    // Play out simulation using these fixed rolls
-    auto state = root->state;
-    for (int depth = 0; depth < maxDepth; depth++) {
-        auto action = selectAction(state);
-        state = applyAction(state, action, rolls[depth]);
-    }
-
-    double reward = evaluate(state);
-    backpropagate(root, reward);
-}
-```
-
-**Would this fix the START_FIRE issue?**
-
-**Yes** - partially. Different simulations would see different outcomes:
-- Some simulations: START_FIRE succeeds (roll < 0.51)
-- Some simulations: START_FIRE fails (roll >= 0.51)
-- Over many simulations, the action's value would approach the expected value
-
-**However**, it's less efficient than chance nodes because:
-- Needs MORE simulations to converge
-- Wastes effort exploring unlikely scenarios equally with likely ones
-- Doesn't explicitly guide exploration based on probability
-
-### Detailed Comparison
-
-| Aspect | Chance Nodes (Closed-Loop) | Open-Loop MCTS | Current (Fixed Roll) |
-|--------|---------------------------|----------------|----------------------|
-| **Randomness Handling** | Explicit in tree structure | Implicit in simulation sampling | Fixed roll=50 |
-| **Convergence Speed** | Fast - probabilities guide search | Slower - needs more samples | N/A (wrong answer) |
-| **Memory Usage** | Higher (more nodes) | Lower (no extra nodes) | Lowest |
-| **Implementation Complexity** | High (tree structure changes) | Medium (sampling layer) | Low (current) |
-| **Theoretical Soundness** | Highest (models true game tree) | Medium (approximation via sampling) | Low (assumes fixed outcome) |
-| **START_FIRE Fix** | ✅ Yes, accurately | ✅ Yes, eventually | ❌ No |
-| **Efficiency** | Most efficient per simulation | Less efficient (wasted samples) | Efficient but wrong |
-| **Handles Hidden Information** | Poor | Excellent | N/A |
-
-### When to Prefer Each Approach
-
-**Prefer Chance Nodes when:**
-- Randomness outcomes are discrete and enumerable (e.g., binary success/fail)
-- Probabilities are known precisely
-- You want fastest convergence to correct answer
-- Game tree is the primary concern (no hidden information)
-- **This is Shardok's situation** ✅
-
-**Prefer Open-Loop when:**
-- Randomness is continuous and high-dimensional
-- Hidden information or imperfect information is present
-- Simplicity is paramount
-- You can afford many simulations
-- Used in games like poker, bridge, Skat
-
-### Why Chance Nodes are Better for Shardok
-
-1. **Discrete outcomes**: Most Shardok randomness is binary (success/fail) or small discrete sets (damage ranges)
-   - START_FIRE: 2 outcomes (success/fail)
-   - MELEE: Can bucket into 3-5 damage ranges
-   - Not continuous - perfect fit for chance nodes
-
-2. **Known probabilities**: We have exact probabilities from `GetOddsPercentile()`
-   - Chance nodes can use exact probabilities
-   - Open-loop just samples blindly
-
-3. **No hidden information**: Shardok is perfect information (all units visible to AI)
-   - Chance nodes' main weakness doesn't apply
-   - Open-loop's main strength doesn't help
-
-4. **Convergence matters**: Limited simulation budget
-   - Need to converge quickly
-   - Chance nodes achieve this better
-
-5. **Existing infrastructure**: We already have deterministic state transitions
-   - Adding chance nodes builds on what we have
-   - Open-loop would need different rollout structure
-
-### Performance Analysis
-
-**Chance Nodes:**
-```
-Time per simulation: 1.3x current
-Simulations needed: 10,000 to converge
-Total time: 13,000x units
-
-Memory: 1.5x current (extra chance nodes)
-```
-
-**Open-Loop:**
-```
-Time per simulation: 1.0x current (same as now)
-Simulations needed: 30,000 to converge (more variance)
-Total time: 30,000x units
-
-Memory: 1.0x current (no extra nodes)
-```
-
-**Result:** Chance nodes are **2.3x faster overall** despite being slower per simulation, because they converge with fewer simulations.
-
-### Hybrid Approach: Best of Both Worlds?
-
-Could we combine them?
-
-**Idea:** Use chance nodes for high-probability branches, open-loop for rare events
-```cpp
-if (probability > 0.1 && outcomeCount <= 5) {
-    // Use explicit chance node
-    createChanceNode(outcomes, probabilities);
-} else {
-    // Use open-loop sampling
-    sampleOutcome();
-}
-```
-
-**Verdict:** Probably not worth the complexity. Shardok's randomness is simple enough that chance nodes handle everything well.
-
-### Recommendation for Shardok
-
-**Use Chance Nodes**, specifically:
-
-1. **Phase 1:** Binary actions (START_FIRE, RAISE_DEAD, etc.)
-   - 2 outcomes, exact probabilities
-   - Biggest bang for buck
-
-2. **Phase 2:** Damage ranges (MELEE, ARCHERY)
-   - 3-5 buckets
-   - Still manageable
-
-3. **If needed:** Could fall back to open-loop for complex actions
-   - E.g., METEOR with many possible outcomes
-   - But likely unnecessary
-
-### Why Not Open-Loop?
-
-While open-loop would eventually fix the START_FIRE issue, it has significant downsides for Shardok:
-
-1. **Slower convergence**: Needs 2-3x more simulations
-2. **Doesn't leverage known probabilities**: We have exact odds, why ignore them?
-3. **Less interpretable**: Harder to debug why AI chose an action
-4. **Doesn't align with iterative deepening**: We want MCTS to match the proven algorithm
-
-The only advantage of open-loop (simplicity) is outweighed by chance nodes' efficiency and correctness.
-
-### Could We Use Current Approach + Better Sampling?
-
-**Idea:** Keep fixed rolls but use different rolls per simulation?
-
-```cpp
-// Instead of always roll=50
-double roll = random();  // Different each simulation
-```
-
-**Problem:** This is essentially open-loop without the tree!
-- Even slower to converge
-- Tree doesn't learn the outcome probabilities
-- Worst of both worlds
-
-**Verdict:** No, this doesn't help. If we're going to sample, do it properly (open-loop). Otherwise, use chance nodes.
-
-### Final Verdict
-
-**For Shardok, chance nodes are clearly superior:**
-
-- ✅ Faster convergence (2-3x vs open-loop)
-- ✅ Leverages exact probabilities
-- ✅ Perfect fit for discrete outcomes
-- ✅ Aligns with iterative deepening approach
-- ✅ Better debuggability and interpretability
-- ❌ More complex implementation (but manageable)
-
-Open-loop would be a fallback if chance nodes prove too difficult, but given the benefits and the bounded complexity (only binary and small discrete outcomes), chance nodes are the right choice.
-
-## Conclusion
-
-Implementing chance nodes will fix the overvaluation of marginal probabilistic actions like START_FIRE with 51% success. The recommended approach is:
-
-1. Start with **explicit chance nodes for binary actions**
-2. Use **lazy state evaluation** to minimize memory
-3. **Progressive enhancement** - binary first, then multi-outcome
-4. Compare with iterative deepening to validate correctness
-
-Expected benefits:
-- More accurate action evaluation
-- Better handling of probabilistic outcomes
-- Closer alignment with theoretical MCTS
-- Fixes the START_FIRE issue without tuning heuristics
-
-Expected costs:
-- ~20-30% slower per simulation (more nodes)
-- ~1-2MB extra memory
-- ~1-2 weeks development time
-
-The benefits significantly outweigh the costs for a more theoretically sound and accurate AI.

src/main/cpp/net/eagle0/shardok/ai/mcts/ShardokMCTSAI.hpp

@@ -20,6 +20,7 @@
 
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdeprecated-redundant-constexpr-static-def"
+#include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
 #pragma clang diagnostic pop
 
 namespace shardok {
@@ -31,6 +32,7 @@ class AIScoreCalculator;
 
 class ShardokMCTSAI {
 public:
+    using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
     using SearchResult = IterativeDeepeningAI::SearchResult;
     using MCTSConfig = mcts::MCTSConfig;
 

src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/BUILD.bazel

@@ -11,7 +11,8 @@ cc_library(
     ],
     deps = [
         "//src/main/cpp/net/eagle0/common/mcts/abstract:mcts_action",
-        "//src/main/cpp/net/eagle0/shardok/library:shardok_c_types",
+        "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
+        "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",
         "//src/main/protobuf/net/eagle0/shardok/common:command_type_cc_proto",
     ],
 )
@@ -32,7 +33,6 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library:engine",
         "//src/main/cpp/net/eagle0/shardok/library:game_state_w",
         "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
-        "//src/main/protobuf/net/eagle0/shardok/common:command_type_cc_proto",
     ],
 )
 
@@ -78,5 +78,6 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library:engine",
         "//src/main/cpp/net/eagle0/shardok/library:game_state_w",
         "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
+        "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",
     ],
 )

src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokAction.cpp

@@ -6,83 +6,101 @@
 
 #include <sstream>
 
+#include "src/main/cpp/net/eagle0/shardok/library/ShardokCommand.hpp"
+
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdeprecated-redundant-constexpr-static-def"
 #include "src/main/protobuf/net/eagle0/shardok/common/command_type.pb.h"
 #pragma clang diagnostic pop
 
-namespace shardok::mcts {
+namespace shardok {
+namespace mcts {
 
-// Constructor: extract and store just the essential fields
-ShardokAction::ShardokAction(
-        size_t index,
-        CommandType type,
-        PlayerId player,
-        int actorId,
-        int targetRow,
-        int targetCol,
-        bool hasOdds)
-    : commandIndex_(index),
-      type_(type),
-      player_(player),
-      actorId_(actorId),
-      targetRow_(targetRow),
-      targetCol_(targetCol),
-      hasOdds_(hasOdds) {}
+// New constructor: store pointer to command (preferred - no proto conversion!)
+ShardokAction::ShardokAction(const ShardokCommand* command, size_t index)
+    : command_(command),
+      commandIndex_(index) {}
+
+// Legacy constructors for compatibility
+ShardokAction::ShardokAction(const CommandProto& command, size_t index)
+    : command_(nullptr),
+      commandProto_(command),
+      commandIndex_(index) {}
+
+ShardokAction::ShardokAction(CommandProto&& command, size_t index)
+    : command_(nullptr),
+      commandProto_(std::move(command)),
+      commandIndex_(index) {}
+
+// Lazy getter - converts to proto only when needed
+const ShardokAction::CommandProto& ShardokAction::getCommand() const {
+    if (command_ != nullptr) {
+        // Lazily convert Command → Proto (only once)
+        if (commandProto_.type() == net::eagle0::shardok::common::UNKNOWN_COMMAND) {
+            commandProto_ = command_->GetCommandProto();
+        }
+        return commandProto_;
+    }
+    // Already have proto from legacy constructor
+    return commandProto_;
+}
+
+int ShardokAction::getType() const { return static_cast<int>(getCommand().type()); }
 
 std::string ShardokAction::getDescription() const {
+    const auto& cmd = getCommand();
     std::stringstream ss;
 
     // Show player
-    ss << "P" << static_cast<int>(player_) << " ";
+    ss << "P" << static_cast<int>(cmd.player()) << " ";
 
-    ss << net::eagle0::shardok::common::CommandType_Name(type_);
+    ss << net::eagle0::shardok::common::CommandType_Name(cmd.type());
 
-    if (actorId_ >= 0) { ss << " Unit:" << actorId_; }
+    if (cmd.has_actor()) { ss << " Unit:" << cmd.actor().value(); }
 
-    if (targetRow_ >= 0 && targetCol_ >= 0) {
-        ss << " @(" << targetRow_ << "," << targetCol_ << ")";
+    if (cmd.has_target()) {
+        const auto& coord = cmd.target();
+        ss << " @(" << coord.row() << "," << coord.column() << ")";
     }
 
     return ss.str();
 }
 
+int ShardokAction::getActorId() const {
+    const auto& cmd = getCommand();
+    if (cmd.has_actor()) { return cmd.actor().value(); }
+    return -1;
+}
+
+std::pair<int, int> ShardokAction::getTarget() const {
+    const auto& cmd = getCommand();
+    if (cmd.has_target()) {
+        const auto& coord = cmd.target();
+        return std::make_pair(coord.row(), coord.column());
+    }
+    return std::make_pair(-1, -1);
+}
+
 std::unique_ptr<MCTSAction> ShardokAction::clone() const {
-    return std::make_unique<ShardokAction>(
-            commandIndex_,
-            type_,
-            player_,
-            actorId_,
-            targetRow_,
-            targetCol_,
-            hasOdds_);
+    // Clone by copying command pointer (cheap!) instead of proto
+    if (command_ != nullptr) { return std::make_unique<ShardokAction>(command_, commandIndex_); }
+    // Fallback: clone proto
+    return std::make_unique<ShardokAction>(commandProto_, commandIndex_);
 }
 
 bool ShardokAction::equals(const MCTSAction& other) const {
     const auto* shardokOther = dynamic_cast<const ShardokAction*>(&other);
     if (!shardokOther) { return false; }
 
-    // Compare by index only - actions from same command list are uniquely identified by index
-    return commandIndex_ == shardokOther->commandIndex_;
-}
-
-bool ShardokAction::requiresChanceNode() const {
-    // Actions with probabilistic outcomes require chance nodes:
-    // 1. Binary success/failure actions (hasOdds_): START_FIRE, FEAR, etc.
-    // 2. END_TURN: random effects (fire spread, weather changes)
-    // 3. Combat actions: roll affects damage dealt (MELEE, ARCHERY, CHARGE, DUEL)
-    if (hasOdds_) { return true; }
-
-    using namespace net::eagle0::shardok::common;
-    switch (type_) {
-        case END_TURN_COMMAND:
-        case MELEE_COMMAND:
-        case ARCHERY_COMMAND:
-        case CHARGE_COMMAND:
-        case CHALLENGE_DUEL_COMMAND:
-        case REDUCE_COMMAND: return true;
-        default: return false;
+    // Fast path: compare by command pointer
+    if (command_ != nullptr && shardokOther->command_ != nullptr) {
+        return commandIndex_ == shardokOther->commandIndex_ && command_ == shardokOther->command_;
     }
+
+    // Fallback: compare protos
+    return commandIndex_ == shardokOther->commandIndex_ &&
+           getCommand().SerializeAsString() == shardokOther->getCommand().SerializeAsString();
 }
 
-}  // namespace shardok::mcts
+}  // namespace mcts
+}  // namespace shardok

src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokAction.hpp

@@ -9,53 +9,51 @@
 #include <string>
 
 #include "src/main/cpp/net/eagle0/common/mcts/abstract/MCTSAction.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokCTypes.h"
 
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdeprecated-redundant-constexpr-static-def"
-#include "src/main/protobuf/net/eagle0/shardok/common/command_type.pb.h"
+#include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
 #pragma clang diagnostic pop
 
-namespace shardok::mcts {
+namespace shardok {
+// Forward declaration
+class ShardokCommand;
+
+namespace mcts {
 
 class ShardokAction : public MCTSAction {
 public:
-    using CommandType = net::eagle0::shardok::common::CommandType;
+    using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
 
-    // Constructor: store just the essential fields (no proto, no pointer)
-    ShardokAction(
-            size_t index,
-            CommandType type,
-            PlayerId player,
-            int actorId,
-            int targetRow,
-            int targetCol,
-            bool hasOdds);
+    // New constructor: store pointer to Command instead of copying proto
+    ShardokAction(const ShardokCommand* command, size_t index);
+
+    // Legacy constructors for compatibility (creates internal proto copy)
+    ShardokAction(const CommandProto& command, size_t index);
+    ShardokAction(CommandProto&& command, size_t index);
 
     // MCTSAction interface implementation
     [[nodiscard]] size_t getIndex() const override { return commandIndex_; }
     [[nodiscard]] std::string getDescription() const override;
     [[nodiscard]] std::unique_ptr<MCTSAction> clone() const override;
     [[nodiscard]] bool equals(const MCTSAction& other) const override;
-    [[nodiscard]] bool requiresChanceNode() const override;
 
-    // Shardok-specific accessors (O(1), no allocations)
-    [[nodiscard]] int getType() const { return static_cast<int>(type_); }
-    [[nodiscard]] PlayerId getPlayer() const { return player_; }
-    [[nodiscard]] int getActorId() const { return actorId_; }
-    [[nodiscard]] std::pair<int, int> getTarget() const { return {targetRow_, targetCol_}; }
+    // Shardok-specific methods (not part of abstract interface)
+    [[nodiscard]] int getType() const;
+    [[nodiscard]] int getActorId() const;
+    [[nodiscard]] std::pair<int, int> getTarget() const;
+
+    // Shardok-specific accessor - lazily converts to proto if needed
+    [[nodiscard]] const CommandProto& getCommand() const;
 
 private:
-    // Store only essential fields (~25 bytes, all POD, cache-friendly)
+    // Store pointer to command (preferred) OR proto copy (legacy)
+    const ShardokCommand* command_ = nullptr;  // Non-owning pointer to cached command
+    mutable CommandProto commandProto_;        // Lazy proto copy (only used if command_ is null)
     size_t commandIndex_;
-    CommandType type_;
-    PlayerId player_;
-    int actorId_;    // -1 if no actor
-    int targetRow_;  // -1 if no target
-    int targetCol_;  // -1 if no target
-    bool hasOdds_;   // true if command has probabilistic outcome
 };
 
-}  // namespace shardok::mcts
+}  // namespace mcts
+}  // namespace shardok
 
 #endif  // EAGLE0_SHARDOK_ACTION_HPP

src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokGameEngine.cpp

@@ -4,9 +4,7 @@
 
 #include "ShardokGameEngine.hpp"
 
-#include <algorithm>
 #include <chrono>
-#include <numeric>
 
 #include "ShardokAction.hpp"
 #include "ShardokGameState.hpp"
@@ -16,26 +14,24 @@
 #include "src/main/cpp/net/eagle0/shardok/ai/AIHeuristicWeighting.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/score/AIScoreCalculator.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokEngine.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokException.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
 
 namespace shardok::mcts {
 
-// Shared cache for legal actions (uses lock-free parallel hash map for thread safety)
-// Using 8 submaps to reduce contention with 16 MCTS threads
-gtl::parallel_flat_hash_map<
-        uint64_t,
-        ShardokGameEngine::LegalActionsCache,
-        std::hash<uint64_t>,
-        std::equal_to<uint64_t>,
-        std::allocator<std::pair<const uint64_t, ShardokGameEngine::LegalActionsCache>>,
-        8,
-        std::mutex>
+// Deterministic random generator for predictable combat rolls (50th percentile)
+// This matches the behavior used in IterativeDeepening AI
+static const std::vector<double> kAverageSequence = {0.5};
+static const auto kAverageGenerator = std::make_shared<SequenceRandomGenerator>(kAverageSequence);
+
+// Thread-local cache for legal actions (avoids lock contention in multithreaded simulation)
+thread_local gtl::flat_hash_map<uint64_t, ShardokGameEngine::LegalActionsCache>
         ShardokGameEngine::legalActionsCache_;
-std::atomic<uint64_t> ShardokGameEngine::cacheHits_{0};
-std::atomic<uint64_t> ShardokGameEngine::cacheMisses_{0};
-std::atomic<uint64_t> ShardokGameEngine::timeInHashComputation_{0};
-std::atomic<uint64_t> ShardokGameEngine::timeInLegalActionsComputation_{0};
+thread_local uint64_t ShardokGameEngine::cacheHits_ = 0;
+thread_local uint64_t ShardokGameEngine::cacheMisses_ = 0;
+thread_local uint64_t ShardokGameEngine::transitionCacheHits_ = 0;
+thread_local uint64_t ShardokGameEngine::transitionCacheMisses_ = 0;
+thread_local uint64_t ShardokGameEngine::timeInHashComputation_ = 0;
+thread_local uint64_t ShardokGameEngine::timeInLegalActionsComputation_ = 0;
 
 ShardokGameEngine::ShardokGameEngine(
         [[maybe_unused]] const ShardokEngine* engine,
@@ -62,14 +58,49 @@ ShardokGameEngine::ShardokGameEngine(
 
 std::unique_ptr<MCTSGameState> ShardokGameEngine::applyAction(
         const MCTSGameState& state,
-        const MCTSAction& action,
-        double deterministicRoll) const {
+        const MCTSAction& action) const {
     const auto* shardokState = dynamic_cast<const ShardokGameState*>(&state);
     const auto* shardokAction = dynamic_cast<const ShardokAction*>(&action);
 
     if (!shardokState || !shardokAction) { return nullptr; }
 
     const auto currentPlayer = static_cast<PlayerId>(state.currentPlayerId());
+    const uint64_t currentStateHash = shardokState->hash();
+    const size_t actionIndex = shardokAction->getIndex();
+    const int roll = 50;  // Fixed roll for deterministic transitions
+
+    // Check transition cache: have we applied this (action, roll) to this state before?
+    TransitionKey transitionKey{actionIndex, roll};
+    if (auto it = legalActionsCache_.find(currentStateHash); it != legalActionsCache_.end()) {
+        if (auto transIt = it->second.actionResults.find(transitionKey);
+            transIt != it->second.actionResults.end()) {
+            // We've applied this transition before - get the next state hash
+            uint64_t nextStateHash = transIt->second;
+
+            // Look up the next state in the cache
+            if (auto nextIt = legalActionsCache_.find(nextStateHash);
+                nextIt != legalActionsCache_.end()) {
+                // TRANSITION CACHE HIT: We have the complete next state cached!
+                transitionCacheHits_++;
+
+                // Clone the cached engine and return the state
+                auto engine = std::make_shared<ShardokEngine>(*nextIt->second.engine);
+                return std::make_unique<ShardokGameState>(
+                        engine->GetCurrentGameState(),
+                        scoreCalculator_,
+                        gameSettings_.get(),
+                        isDefender_,
+                        strategy_,
+                        castleCoords_,
+                        *apdCache_,
+                        *alCache_,
+                        criticalTileCoords_);
+            }
+        }
+    }
+
+    // TRANSITION CACHE MISS: Apply action normally
+    transitionCacheMisses_++;
 
     // Use cached engine if available (avoids recomputing GetAvailableCommands for same state)
     std::shared_ptr<ShardokEngine> engine;
@@ -93,54 +124,9 @@ std::unique_ptr<MCTSGameState> ShardokGameEngine::applyAction(
         engine = std::make_shared<ShardokEngine>(*engine);
     }
 
-    // Create deterministic random generator if a specific roll is requested
-    // deterministicRoll of -1.0 (default) means use random generator
-    // Any other value (including negative) creates a deterministic generator
-    // For open-ended percentile commands, we compute a sequence of values that will
-    // produce the desired final result through the normal open-ended mechanics
-    std::shared_ptr<::RandomGenerator> randomGen = nullptr;
-    constexpr double kNoRollSentinel = -1.0;
-    if (deterministicRoll != kNoRollSentinel) {
-        std::vector<double> sequence;
+    engine->PostCommand(currentPlayer, actionIndex, kAverageGenerator);
 
-        if (deterministicRoll >= 5.0 && deterministicRoll <= 95.0) {
-            // Normal range: single value works directly
-            sequence = {deterministicRoll / 100.0};
-        } else if (deterministicRoll < 5.0) {
-            // Need open-ended LOW result (e.g., -100 for guaranteed success)
-            // OpenEndedPercentile: if initial < 5, returns initial - OpenEndedHighImpl(0, 4)
-            // We want: initial - accumulated = deterministicRoll
-            // Use initial = 2 (clearly < 5), so accumulated = 2 - deterministicRoll
-            constexpr double kInitialLow = 2.0;
-            sequence = {kInitialLow / 100.0};
-            // OpenEndedHighImpl accumulates rolls until one < 95
-            // Split accumulated into rolls: 96 (continues) + remaining (stops)
-            double remaining = kInitialLow - deterministicRoll;
-            while (remaining > 95.0) {
-                sequence.push_back(0.96);  // 96 > 95, continues accumulation
-                remaining -= 96.0;
-            }
-            sequence.push_back(remaining / 100.0);  // Final roll < 95, stops
-        } else {
-            // Need open-ended HIGH result (e.g., 150 for guaranteed failure)
-            // OpenEndedPercentile: if initial > 95, returns OpenEndedHighImpl(initial, 4)
-            // OpenEndedHighImpl accumulates rolls until one < 95
-            constexpr double kInitialHigh = 96.0;
-            sequence = {kInitialHigh / 100.0};
-            double remaining = deterministicRoll - kInitialHigh;
-            while (remaining > 95.0) {
-                sequence.push_back(0.96);
-                remaining -= 96.0;
-            }
-            sequence.push_back(remaining / 100.0);
-        }
-
-        randomGen = std::make_shared<::SequenceRandomGenerator>(sequence);
-    }
-
-    engine->PostCommand(currentPlayer, shardokAction->getIndex(), randomGen);
-
-    // Create and return the new state
+    // Create and return the new state (don't cache the mutated engine)
     auto newState = std::make_unique<ShardokGameState>(
             engine->GetCurrentGameState(),
             scoreCalculator_,
@@ -152,10 +138,14 @@ std::unique_ptr<MCTSGameState> ShardokGameEngine::applyAction(
             *alCache_,
             criticalTileCoords_);
 
-    // Cache the engine on the new state so score() can use it for END_TURN normalization
-    // The engine's command list may be stale after the action was applied, but that's OK -
-    // we'll refresh it when we call GetAvailableCommandsForAIPlayer() in score()
-    newState->setCachedEngine(engine);
+    // Store the transition in cache for future lookups
+    const uint64_t nextStateHash = newState->hash();
+    legalActionsCache_[currentStateHash].actionResults[transitionKey] = nextStateHash;
+
+    // CRITICAL: Also store the next state's engine in the cache
+    // Without this, transition cache lookups will always miss because the next state won't exist
+    // Clone the engine so we have an independent cached copy
+    legalActionsCache_[nextStateHash].engine = std::make_shared<ShardokEngine>(*engine);
 
     // Don't pre-compute hash - let it be computed lazily on first use
     // Many states (especially in simulation) never need their hash computed
@@ -175,6 +165,36 @@ void ShardokGameEngine::applyActionMutable(
     }
 
     const auto currentPlayer = static_cast<PlayerId>(state->currentPlayerId());
+    const uint64_t currentStateHash = shardokState->hash();
+    const size_t actionIndex = shardokAction->getIndex();
+    const int roll = 50;  // Fixed roll for deterministic transitions
+
+    // Check transition cache: have we applied this (action, roll) to this state before?
+    TransitionKey transitionKey{actionIndex, roll};
+    if (auto it = legalActionsCache_.find(currentStateHash); it != legalActionsCache_.end()) {
+        if (auto transIt = it->second.actionResults.find(transitionKey);
+            transIt != it->second.actionResults.end()) {
+            // We've applied this transition before - get the next state hash
+            uint64_t nextStateHash = transIt->second;
+
+            // Look up the next state in the cache
+            if (auto nextIt = legalActionsCache_.find(nextStateHash);
+                nextIt != legalActionsCache_.end()) {
+                // TRANSITION CACHE HIT: We have the complete next state cached!
+                transitionCacheHits_++;
+
+                // Clone the cached engine and update the current state to match
+                auto engine = std::make_shared<ShardokEngine>(*nextIt->second.engine);
+                shardokState->getMutableShardokState() = engine->GetCurrentGameState();
+                shardokState->setCachedEngine(engine);
+                shardokState->invalidateHashCache();
+                return;
+            }
+        }
+    }
+
+    // TRANSITION CACHE MISS: Apply action normally
+    transitionCacheMisses_++;
 
     // Use cached engine if available
     std::shared_ptr<ShardokEngine> engine;
@@ -194,11 +214,20 @@ void ShardokGameEngine::applyActionMutable(
         engine = std::make_shared<ShardokEngine>(*engine);
     }
 
-    engine->PostCommand(currentPlayer, shardokAction->getIndex(), nullptr);
+    engine->PostCommand(currentPlayer, actionIndex, kAverageGenerator);
     shardokState->getMutableShardokState() = engine->GetCurrentGameState();
     // Clear the cached engine and hash since the state has been mutated
     shardokState->setCachedEngine(nullptr);
     shardokState->invalidateHashCache();
+
+    // Store the transition in cache for future lookups
+    const uint64_t nextStateHash = shardokState->hash();
+    legalActionsCache_[currentStateHash].actionResults[transitionKey] = nextStateHash;
+
+    // CRITICAL: Also store the next state's engine in the cache
+    // Without this, transition cache lookups will always miss because the next state won't exist
+    // Clone the engine so we have an independent cached copy
+    legalActionsCache_[nextStateHash].engine = std::make_shared<ShardokEngine>(*engine);
 }
 
 std::vector<std::unique_ptr<MCTSAction>> ShardokGameEngine::getLegalActions(
@@ -224,61 +253,47 @@ std::vector<std::unique_ptr<MCTSAction>> ShardokGameEngine::getLegalActions(
     const auto hashStart = std::chrono::high_resolution_clock::now();
     const uint64_t stateHash = shardokState->hash();
     const auto hashEnd = std::chrono::high_resolution_clock::now();
-    timeInHashComputation_.fetch_add(
-            std::chrono::duration_cast<std::chrono::microseconds>(hashEnd - hashStart).count(),
-            std::memory_order_relaxed);
+    timeInHashComputation_ +=
+            std::chrono::duration_cast<std::chrono::microseconds>(hashEnd - hashStart).count();
 
     // Check transposition table for cached legal actions
     if (auto it = legalActionsCache_.find(stateHash); it != legalActionsCache_.end()) {
-        cacheHits_.fetch_add(1, std::memory_order_relaxed);
+        cacheHits_++;
 
         // Use cached engine
         shardokState->setCachedEngine(it->second.engine);
 
-        // Get commands from the cached engine (Engine already caches these internally)
+        // If we have cached actions, clone and return them (fastest path)
+        if (!it->second.cachedActions.empty()) {
+            std::vector<std::unique_ptr<MCTSAction>> actions;
+            actions.reserve(it->second.cachedActions.size());
+            for (const auto& action : it->second.cachedActions) {
+                actions.push_back(action->clone());
+            }
+            return actions;
+        }
+
+        // Fallback: reconstruct actions from cached engine (shouldn't happen often)
         const CommandListSPtr commands =
                 it->second.engine->GetAvailableCommandsForAIPlayer(currentPlayer);
 
         if (!commands || commands->empty()) { return {}; }
 
-        // Convert to MCTSActions using stored filtered indices
         std::vector<std::unique_ptr<MCTSAction>> actions;
         actions.reserve(it->second.filteredIndices.size());
 
         for (const size_t origIdx : it->second.filteredIndices) {
             if (origIdx < commands->size()) {
                 const auto& cmd = commands->at(origIdx);
-
-                // Extract essential fields directly from command (no proto conversion!)
-                actions.push_back(std::make_unique<ShardokAction>(
-                        origIdx,
-                        cmd->GetCommandType(),
-                        cmd->GetPlayerId(),
-                        cmd->GetActorUnitId(),
-                        cmd->GetTargetRow(),
-                        cmd->GetTargetColumn(),
-                        cmd->HasOdds()));
+                // Use new constructor: pass command pointer instead of converting to proto
+                actions.push_back(std::make_unique<ShardokAction>(cmd.get(), origIdx));
             }
         }
 
-        // Sort actions by weight (descending) to ensure MCTS explores high-value actions first
-        const std::vector<double> weights = getActionWeights(actions, state);
-
-        std::vector<size_t> sortedIndices(actions.size());
-        std::iota(sortedIndices.begin(), sortedIndices.end(), 0);
-
-        std::sort(sortedIndices.begin(), sortedIndices.end(), [&weights](size_t a, size_t b) {
-            return weights[a] > weights[b];
-        });
-
-        std::vector<std::unique_ptr<MCTSAction>> sortedActions;
-        sortedActions.reserve(actions.size());
-        for (size_t idx : sortedIndices) { sortedActions.push_back(std::move(actions[idx])); }
-
-        return sortedActions;
+        return actions;
     }
 
-    cacheMisses_.fetch_add(1, std::memory_order_relaxed);
+    cacheMisses_++;
 
     // Time legal actions computation
     const auto actionsStart = std::chrono::high_resolution_clock::now();
@@ -312,66 +327,30 @@ std::vector<std::unique_ptr<MCTSAction>> ShardokGameEngine::getLegalActions(
             });
 
     // Convert only filtered commands to MCTSActions
+    // Use new constructor: pass command pointer instead of converting to proto (major speedup!)
     std::vector<std::unique_ptr<MCTSAction>> actions;
     actions.reserve(filteredIndices.size());
 
     for (const size_t idx : filteredIndices) {
         if (idx < commands->size()) {
             const auto& cmd = commands->at(idx);
-
-            // Extract essential fields directly from command (no proto conversion!)
-            actions.push_back(std::make_unique<ShardokAction>(
-                    idx,
-                    cmd->GetCommandType(),
-                    cmd->GetPlayerId(),
-                    cmd->GetActorUnitId(),
-                    cmd->GetTargetRow(),
-                    cmd->GetTargetColumn(),
-                    cmd->HasOdds()));
+            actions.push_back(std::make_unique<ShardokAction>(cmd.get(), idx));
         }
     }
 
-    // Sort actions by weight (descending) to ensure MCTS explores high-value actions first
-    // This is critical when maxPlayerFlips is low (e.g., 1), as only the first few actions
-    // get explored deeply. Original indices are preserved in ShardokAction::getIndex()
-    const std::vector<double> weights = getActionWeights(actions, state);
-
-    // Create index vector for sorting
-    std::vector<size_t> sortedIndices(actions.size());
-    std::iota(sortedIndices.begin(), sortedIndices.end(), 0);
-
-    // Sort indices by weight (descending)
-    std::sort(sortedIndices.begin(), sortedIndices.end(), [&weights](size_t a, size_t b) {
-        return weights[a] > weights[b];
-    });
-
-    // Reorder actions according to sorted indices
-    std::vector<std::unique_ptr<MCTSAction>> sortedActions;
-    sortedActions.reserve(actions.size());
-    for (size_t idx : sortedIndices) { sortedActions.push_back(std::move(actions[idx])); }
-    actions = std::move(sortedActions);
-
     const auto actionsEnd = std::chrono::high_resolution_clock::now();
-    timeInLegalActionsComputation_.fetch_add(
+    timeInLegalActionsComputation_ +=
             std::chrono::duration_cast<std::chrono::microseconds>(actionsEnd - actionsStart)
-                    .count(),
-            std::memory_order_relaxed);
+                    .count();
 
     // Store in transposition table for future lookups
-    // Note: We only store filtered indices and the engine (which caches commands internally)
-    // This avoids duplicating heavy protocol buffer objects
-    // Use lazy_emplace_l to ensure thread-safe insertion (locks the bucket during construction)
-    legalActionsCache_.lazy_emplace_l(
-            stateHash,
-            [&](typename decltype(legalActionsCache_)::value_type& v) {
-                // Update existing entry
-                v.second.filteredIndices = filteredIndices;
-                v.second.engine = engine;
-            },
-            [&](const typename decltype(legalActionsCache_)::constructor& ctor) {
-                // Create new entry
-                ctor(stateHash, LegalActionsCache{filteredIndices, engine});
-            });
+    LegalActionsCache entry;
+    entry.filteredIndices = filteredIndices;
+    entry.engine = engine;
+    // Clone actions to cache them (allows fast retrieval without reconstruction)
+    entry.cachedActions.reserve(actions.size());
+    for (const auto& action : actions) { entry.cachedActions.push_back(action->clone()); }
+    legalActionsCache_[stateHash] = std::move(entry);
 
     return actions;
 }
@@ -404,28 +383,17 @@ std::vector<double> ShardokGameEngine::getActionWeights(
                 "indicates a type mismatch in the MCTS adapter layer");
     }
 
-    // Get cached engine and command list for looking up command protos
-    auto cachedEngine = shardokState->getCachedEngine();
-    if (!cachedEngine) {
-        throw MCTSInternalError(
-                "ShardokGameEngine::getActionWeights called with state that has no cached engine");
-    }
-
-    const auto currentPlayer = static_cast<PlayerId>(state.currentPlayerId());
-    const CommandListSPtr commands = cachedEngine->GetAvailableCommandsForAIPlayer(currentPlayer);
-
-    // Determine if current player is defender (not root player!)
-    // During simulation we need to use the correct perspective for action weighting
-    bool currentPlayerIsDefender = false;
-    const auto& gameState = shardokState->getShardokState();
-    for (const auto* pi : *gameState->player_infos()) {
-        if (pi->player_id() == currentPlayer) {
-            currentPlayerIsDefender = pi->is_defender();
-            break;
+    // Check cache for action weights
+    const uint64_t stateHash = shardokState->hash();
+    if (auto it = legalActionsCache_.find(stateHash); it != legalActionsCache_.end()) {
+        if (!it->second.actionWeights.empty() &&
+            it->second.actionWeights.size() == actions.size()) {
+            // Cache hit! Return cached weights
+            return it->second.actionWeights;
         }
     }
 
-    // Use AIHeuristicWeighting for fast O(1) context-aware command weighting
+    // Cache miss: compute action weights using AIHeuristicWeighting
     std::vector<double> weights;
     weights.reserve(actions.size());
 
@@ -436,30 +404,20 @@ std::vector<double> ShardokGameEngine::getActionWeights(
                     "ShardokGameEngine::getActionWeights encountered non-Shardok action - this "
                     "indicates a type mismatch in the MCTS adapter layer");
         }
-
-        // Look up command proto from cached engine using action's index
-        const size_t cmdIndex = shardokAction->getIndex();
-        if (cmdIndex >= commands->size()) {
-            throw MCTSInternalError(
-                    "ShardokGameEngine::getActionWeights: action index out of bounds");
-        }
-
-        const auto& cmd = commands->at(cmdIndex);
-
         weights.push_back(AIHeuristicWeighting::GetCommandWeight(
-                cmd->GetCommandType(),
-                cmd->GetActorUnitId(),
-                cmd->GetPlayerId(),
-                Coords{cmd->GetTargetRow(), cmd->GetTargetColumn()},
-                gameState,
+                shardokAction->getCommand(),
+                shardokState->getShardokState(),
                 castleCoords_,
                 apdCache_,
-                currentPlayerIsDefender,  // Use current player's role, not root player's!
+                isDefender_,
                 [this](BattalionTypeId typeId) {
                     return gameSettings_->GetGetter().GetBattalionType(typeId);
                 }));
     }
 
+    // Store weights in cache for future lookups
+    legalActionsCache_[stateHash].actionWeights = weights;
+
     return weights;
 }
 
@@ -469,7 +427,6 @@ double ShardokGameEngine::getActionScore(
         MCTSPlayerId playerId) const {
     auto newState = applyAction(state, action);
     if (!newState) { return 0.0; }
-
     return newState->score(playerId);
 }
 
@@ -499,34 +456,31 @@ size_t ShardokGameEngine::mapFilteredIndexToOriginal(
 }
 
 void ShardokGameEngine::reportCacheStatistics() const {
-    const uint64_t hits = cacheHits_.load(std::memory_order_relaxed);
-    const uint64_t misses = cacheMisses_.load(std::memory_order_relaxed);
-    const uint64_t hashTime = timeInHashComputation_.load(std::memory_order_relaxed);
-    const uint64_t actionsTime = timeInLegalActionsComputation_.load(std::memory_order_relaxed);
-    const uint64_t totalLookups = hits + misses;
-
+    const uint64_t totalLookups = cacheHits_ + cacheMisses_;
     if (totalLookups > 0) {
-        const double hitRate = static_cast<double>(hits) / static_cast<double>(totalLookups);
+        const double hitRate = static_cast<double>(cacheHits_) / static_cast<double>(totalLookups);
         const double avgHashTimeUs =
-                static_cast<double>(hashTime) / static_cast<double>(totalLookups);
+                static_cast<double>(timeInHashComputation_) / static_cast<double>(totalLookups);
         const double avgActionsTimeUs =
-                misses > 0 ? static_cast<double>(actionsTime) / static_cast<double>(misses) : 0.0;
+                cacheMisses_ > 0 ? static_cast<double>(timeInLegalActionsComputation_) /
+                                           static_cast<double>(cacheMisses_)
+                                 : 0.0;
 
         printf("Legal Actions Cache Stats:\n");
         printf("  Lookups: %llu hits, %llu misses, %.1f%% hit rate, %zu entries\n",
-               static_cast<unsigned long long>(hits),
-               static_cast<unsigned long long>(misses),
+               static_cast<unsigned long long>(cacheHits_),
+               static_cast<unsigned long long>(cacheMisses_),
                hitRate * 100.0,
                legalActionsCache_.size());
         printf("  Timing: %.2f us avg hash, %.2f us avg actions (on miss)\n",
                avgHashTimeUs,
                avgActionsTimeUs);
         printf("  Total time: %.2f ms in hash, %.2f ms in actions\n",
-               hashTime / 1000.0,
-               actionsTime / 1000.0);
+               timeInHashComputation_ / 1000.0,
+               timeInLegalActionsComputation_ / 1000.0);
 
         // Calculate if transposition table is worth it
-        const double timeWithCache = hashTime + actionsTime;
+        const double timeWithCache = timeInHashComputation_ + timeInLegalActionsComputation_;
         const double timeWithoutCache =
                 avgActionsTimeUs * static_cast<double>(totalLookups);  // All lookups recompute
         const double savings = (timeWithoutCache - timeWithCache) / timeWithoutCache * 100.0;
@@ -534,95 +488,39 @@ void ShardokGameEngine::reportCacheStatistics() const {
                savings,
                (timeWithoutCache - timeWithCache) / 1000.0);
     }
+
+    // Report transition cache statistics
+    const uint64_t totalTransitions = transitionCacheHits_ + transitionCacheMisses_;
+    if (totalTransitions > 0) {
+        const double transitionHitRate =
+                static_cast<double>(transitionCacheHits_) / static_cast<double>(totalTransitions);
+
+        printf("\nTransition Cache Stats:\n");
+        printf("  Transitions: %llu hits, %llu misses, %.1f%% hit rate\n",
+               static_cast<unsigned long long>(transitionCacheHits_),
+               static_cast<unsigned long long>(transitionCacheMisses_),
+               transitionHitRate * 100.0);
+
+        // Calculate total number of transition entries across all states
+        size_t totalTransitionEntries = 0;
+        for (const auto& [stateHash, cache] : legalActionsCache_) {
+            totalTransitionEntries += cache.actionResults.size();
+        }
+        printf("  Total transition entries: %zu (avg %.1f per state)\n",
+               totalTransitionEntries,
+               totalTransitionEntries > 0 ? static_cast<double>(totalTransitionEntries) /
+                                                    static_cast<double>(legalActionsCache_.size())
+                                          : 0.0);
+    }
 }
 
 void ShardokGameEngine::resetCacheStatistics() {
-    cacheHits_.store(0, std::memory_order_relaxed);
-    cacheMisses_.store(0, std::memory_order_relaxed);
-    timeInHashComputation_.store(0, std::memory_order_relaxed);
-    timeInLegalActionsComputation_.store(0, std::memory_order_relaxed);
+    cacheHits_ = 0;
+    cacheMisses_ = 0;
+    timeInHashComputation_ = 0;
+    timeInLegalActionsComputation_ = 0;
+    transitionCacheHits_ = 0;
+    transitionCacheMisses_ = 0;
 }
 
-ChanceOutcomeInfo ShardokGameEngine::getBinaryOutcomeInfo(
-        const MCTSGameState& state,
-        const MCTSAction& action) const {
-    const auto* shardokState = dynamic_cast<const ShardokGameState*>(&state);
-    const auto* shardokAction = dynamic_cast<const ShardokAction*>(&action);
-
-    if (!shardokState || !shardokAction) {
-        throw ShardokInternalErrorException("Invalid state or action type in getBinaryOutcomeInfo");
-    }
-
-    // Check for multi-outcome commands (roll affects outcome quality, not just success/failure)
-    // These use multiOutcome() with fixed seeds to sample the range of possible results
-    using namespace net::eagle0::shardok::common;
-    const auto commandType = static_cast<CommandType>(shardokAction->getType());
-
-    switch (commandType) {
-        case END_TURN_COMMAND:
-            // END_TURN has random effects (fire spread, weather changes)
-            return ChanceOutcomeInfo::multiOutcome(5);
-
-        case MELEE_COMMAND:
-        case ARCHERY_COMMAND:
-        case CHARGE_COMMAND:
-        case REDUCE_COMMAND:
-            // Combat/siege commands: OpenEndedPercentile roll affects damage dealt
-            // Use 5 outcomes to sample the roll distribution
-            return ChanceOutcomeInfo::multiOutcome(5);
-
-        case CHALLENGE_DUEL_COMMAND:
-            // Duels have multiple combat rounds with rolls, so outcomes vary significantly
-            return ChanceOutcomeInfo::multiOutcome(5);
-
-        default:
-            // Continue to binary outcome handling below
-            break;
-    }
-
-    const auto currentPlayer = static_cast<PlayerId>(state.currentPlayerId());
-
-    // Get or create the engine for this state
-    std::shared_ptr<ShardokEngine> engine;
-    if (auto cachedEngine = shardokState->getCachedEngine()) {
-        engine = cachedEngine;
-    } else {
-        engine = std::make_shared<ShardokEngine>(
-                gameSettings_,
-                shardokState->getShardokState(),
-                criticalTileCoords_,
-                0,
-                false);
-        // Populate command cache
-        [[maybe_unused]] const auto commands =
-                engine->GetAvailableCommandsForAIPlayer(currentPlayer);
-        shardokState->setCachedEngine(engine);
-    }
-
-    // Get command descriptors
-    const auto descriptors = engine->GetAvailableCommandsForAIPlayer(currentPlayer);
-    const size_t actionIndex = shardokAction->getIndex();
-
-    if (actionIndex >= descriptors->size()) {
-        throw ShardokInternalErrorException("Action index out of range in getBinaryOutcomeInfo");
-    }
-
-    const auto& descriptor = descriptors->at(actionIndex);
-
-    // Get success probability for binary outcome actions
-    if (!descriptor->HasOdds()) {
-        throw ShardokInternalErrorException("Action does not have odds in getBinaryOutcomeInfo");
-    }
-
-    const auto successChancePercentile = descriptor->GetOddsPercentile();
-    const double successProbability = static_cast<double>(successChancePercentile) / 100.0;
-
-    return ChanceOutcomeInfo::binary(successProbability);
-}
-
-void ShardokGameEngine::clearLegalActionsCache() { legalActionsCache_.clear(); }
-
-// Extern-linkage function for testing
-void clearLegalActionsCache_ForTesting() { ShardokGameEngine::clearLegalActionsCache(); }
-
 }  // namespace shardok::mcts

src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokGameEngine.hpp

@@ -14,6 +14,7 @@
 #include "src/main/cpp/net/eagle0/common/mcts/abstract/MCTSGameEngine.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/AIAttackLocations.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/AIStrategy.hpp"
+#include "src/main/cpp/net/eagle0/shardok/library/ShardokCTypes.h"
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokEngine.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/action_point_distances/ActionPointDistancesCache.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/map/CoordsSet.hpp"
@@ -47,8 +48,7 @@ public:
     // MCTSGameEngine interface implementation
     [[nodiscard]] std::unique_ptr<MCTSGameState> applyAction(
             const MCTSGameState& state,
-            const MCTSAction& action,
-            double deterministicRoll = -1.0) const override;
+            const MCTSAction& action) const override;
 
     void applyActionMutable(std::unique_ptr<MCTSGameState>& state, const MCTSAction& action)
             const override;
@@ -86,10 +86,6 @@ public:
             size_t filteredIndex,
             const MCTSGameState& state) const override;
 
-    [[nodiscard]] BinaryOutcomeInfo getBinaryOutcomeInfo(
-            const MCTSGameState& state,
-            const MCTSAction& action) const override;
-
     // Report transposition table statistics
     void reportCacheStatistics() const;
 
@@ -97,11 +93,34 @@ public:
     void resetCacheStatistics();
 
 private:
+    // Key for transition cache: (actionIndex, roll)
+    // Caches state transitions to avoid redundant PostCommand calls
+    struct TransitionKey {
+        size_t actionIndex;
+        int roll;
+
+        bool operator==(const TransitionKey& other) const {
+            return actionIndex == other.actionIndex && roll == other.roll;
+        }
+    };
+
+    // Hash function for TransitionKey
+    struct TransitionKeyHash {
+        size_t operator()(const TransitionKey& key) const {
+            return std::hash<size_t>{}(key.actionIndex) ^ (std::hash<int>{}(key.roll) << 1);
+        }
+    };
+
     // Transposition table entry for caching legal actions
-    // Note: We don't store command protos since the Engine already caches them
     struct LegalActionsCache {
         std::vector<size_t> filteredIndices;
         std::shared_ptr<ShardokEngine> engine;  // Engine with populated command cache
+        // NEW: Cache state transitions (action, roll) -> nextStateHash
+        gtl::flat_hash_map<TransitionKey, uint64_t, TransitionKeyHash> actionResults;
+        // NEW: Cache action weights to avoid recomputing heuristics
+        std::vector<double> actionWeights;
+        // NEW: Cache the actual action objects to avoid repeated allocation/construction
+        std::vector<std::unique_ptr<MCTSAction>> cachedActions;
     };
 
     const AIScoreCalculator* scoreCalculator_;
@@ -110,32 +129,23 @@ private:
     const ALCache* alCache_;
     bool isDefender_;
     AIStrategy strategy_;
-    const CoordsSet castleCoords_;  // Own the data to avoid dangling references
+    const CoordsSet& castleCoords_;
     // Computed once to avoid 8.5% overhead per engine construction
-    const CoordsSet criticalTileCoords_;  // Own the data to avoid dangling references
+    const CoordsSet& criticalTileCoords_;
 
-    // Transposition table for legal actions (shared across threads with lock-free hash map)
-    // parallel_flat_hash_map provides thread-safe concurrent access without explicit locking
-    // Using 8 submaps (N=8) to reduce contention with default 16 MCTS threads
-    static gtl::parallel_flat_hash_map<
-            uint64_t,
-            LegalActionsCache,
-            std::hash<uint64_t>,
-            std::equal_to<uint64_t>,
-            std::allocator<std::pair<const uint64_t, LegalActionsCache>>,
-            8,
-            std::mutex>
-            legalActionsCache_;
-    static std::atomic<uint64_t> cacheHits_;
-    static std::atomic<uint64_t> cacheMisses_;
+    // Transposition table for legal actions (thread-local to avoid lock contention)
+    // Each thread maintains its own cache during multithreaded simulation
+    static thread_local gtl::flat_hash_map<uint64_t, LegalActionsCache> legalActionsCache_;
+    static thread_local uint64_t cacheHits_;
+    static thread_local uint64_t cacheMisses_;
+
+    // Transition cache statistics
+    static thread_local uint64_t transitionCacheHits_;
+    static thread_local uint64_t transitionCacheMisses_;
 
     // Performance timing (in microseconds)
-    static std::atomic<uint64_t> timeInHashComputation_;
-    static std::atomic<uint64_t> timeInLegalActionsComputation_;
-
-public:
-    // Clear the static legal actions cache (useful for tests)
-    static void clearLegalActionsCache();
+    static thread_local uint64_t timeInHashComputation_;
+    static thread_local uint64_t timeInLegalActionsComputation_;
 };
 
 }  // namespace mcts

src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokGameState.cpp

@@ -41,32 +41,10 @@ uint64_t ShardokGameState::hash() const {
     return cachedHash_;
 }
 
-double ShardokGameState::score(MCTSPlayerId playerId) const {
-    // Honor the interface contract: score() should return evaluation from playerId's perspective.
-    // Map the requested playerId to defender/attacker role to determine scoring perspective.
-
-    // Look up which player ID is the defender from game state
-    bool foundDefender = false;
-    bool requestedPlayerIsDefender = false;
-
-    if (state_->player_infos()) {
-        for (const auto* pi : *state_->player_infos()) {
-            if (pi && pi->is_defender()) {
-                foundDefender = true;
-                requestedPlayerIsDefender = (static_cast<PlayerId>(playerId) == pi->player_id());
-                break;
-            }
-        }
-    }
-
-    // Fallback: if we can't determine from game state, use isDefender_ which represents
-    // the root player's role (and playerId is always the root player in practice)
-    const bool scoreFromDefenderPerspective =
-            foundDefender ? requestedPlayerIsDefender : isDefender_;
-
-    // Score the current state directly
-    return scoreCalculator_
-            ->GuessedStateScore(scoreFromDefenderPerspective, state_, strategy_, castleCoords_);
+double ShardokGameState::score(MCTSPlayerId /*playerId*/) const {
+    // Always return score from the perspective of the AI that created this state (isDefender_).
+    // The playerId parameter is ignored - adversarial logic happens in selection, not scoring.
+    return scoreCalculator_->GuessedStateScore(isDefender_, state_, strategy_, castleCoords_);
 }
 
 MCTSPlayerId ShardokGameState::currentPlayerId() const { return state_->current_player(); }

src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokGameState.hpp

@@ -68,12 +68,12 @@ private:
     const GameSettings* settings_;
     bool isDefender_;
     AIStrategy strategy_;
-    const CoordsSet castleCoords_;  // Own the data to avoid dangling references
+    const CoordsSet& castleCoords_;
     const APDCache& apdCache_;
     const ALCache& alCache_;
     mutable uint64_t cachedHash_ = 0;
     mutable bool hashCached_ = false;
-    const CoordsSet criticalTileCoords_;  // Own the data to avoid dangling references
+    const CoordsSet& criticalTileCoords_;
     mutable std::shared_ptr<ShardokEngine> cachedEngine_;  // Engine with cached available commands
 };
 

src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokMCTSFactory.cpp

@@ -56,6 +56,18 @@ std::unique_ptr<MCTSGameState> ShardokMCTSFactory::createGameState(
             criticalTileCoords);
 }
 
+std::vector<std::unique_ptr<MCTSAction>> ShardokMCTSFactory::createActions(
+        const std::vector<CommandProto>& commands) {
+    std::vector<std::unique_ptr<MCTSAction>> actions;
+    actions.reserve(commands.size());
+
+    for (size_t i = 0; i < commands.size(); ++i) {
+        actions.push_back(std::make_unique<ShardokAction>(commands[i], i));
+    }
+
+    return actions;
+}
+
 std::vector<std::unique_ptr<MCTSAction>> ShardokMCTSFactory::createActionsFromCommandList(
         const CommandListSPtr& commands) {
     std::vector<std::unique_ptr<MCTSAction>> actions;
@@ -64,16 +76,7 @@ std::vector<std::unique_ptr<MCTSAction>> ShardokMCTSFactory::createActionsFromCo
     actions.reserve(commands->size());
     for (size_t i = 0; i < commands->size(); ++i) {
         const auto& cmd = (*commands)[i];
-
-        // Extract essential fields directly from command (no proto conversion!)
-        actions.push_back(std::make_unique<ShardokAction>(
-                i,
-                cmd->GetCommandType(),
-                cmd->GetPlayerId(),
-                cmd->GetActorUnitId(),
-                cmd->GetTargetRow(),
-                cmd->GetTargetColumn(),
-                cmd->HasOdds()));
+        actions.push_back(std::make_unique<ShardokAction>(cmd->GetCommandProto(), i));
     }
 
     return actions;

src/main/cpp/net/eagle0/shardok/ai/mcts/adapters/ShardokMCTSFactory.hpp

@@ -16,6 +16,7 @@
 #include "src/main/cpp/net/eagle0/shardok/library/action_point_distances/ActionPointDistancesCache.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/map/CoordsSet.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
+#include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
 
 namespace shardok {
 
@@ -26,6 +27,14 @@ class AIScoreCalculator;
 class GameStateW;
 class GameSettings;
 
+// Use existing type definitions to avoid conflicts
+// These are already defined in the Shardok codebase:
+// - APDCache in ActionPointDistancesCache.hpp
+// - ALCache in AIAttackLocations.hpp
+// - CommandListSPtr in ShardokCommand.hpp
+// - SettingsGetter in GameSettings.hpp
+using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
+
 namespace mcts {
 
 // Forward declarations
@@ -35,6 +44,8 @@ class MCTSAction;
 
 class ShardokMCTSFactory {
 public:
+    using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
+
     // Create a Shardok game engine adapter
     [[nodiscard]] static std::unique_ptr<MCTSGameEngine> createGameEngine(
             const ShardokEngine& engine,
@@ -59,6 +70,10 @@ public:
             const ALCache& alCache,
             const CoordsSet& criticalTileCoords);
 
+    // Convert Shardok commands to MCTS actions
+    [[nodiscard]] static std::vector<std::unique_ptr<MCTSAction>> createActions(
+            const std::vector<CommandProto>& commands);
+
     // Convert from command list to MCTS actions
     [[nodiscard]] static std::vector<std::unique_ptr<MCTSAction>> createActionsFromCommandList(
             const CommandListSPtr& commands);

src/main/cpp/net/eagle0/shardok/ai/score/AIScoreCalculator.hpp

@@ -12,6 +12,7 @@
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokCTypes.h"
 #include "src/main/cpp/net/eagle0/shardok/library/action_point_distances/ActionPointDistancesCache.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/map/CoordsSet.hpp"
+#include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
 
 namespace shardok {
 
@@ -20,6 +21,7 @@ using std::future;
 using std::vector;
 
 using ScoreValue = double;
+using CommandProto = net::eagle0::shardok::api::CommandDescriptor;
 
 // Forward declarations
 class ShardokEngine;

src/main/cpp/net/eagle0/shardok/ai/score/BUILD.bazel

@@ -15,6 +15,7 @@ cc_library(
         "//src/main/cpp/net/eagle0/shardok/library:shardok_c_types",
         "//src/main/cpp/net/eagle0/shardok/library/action_point_distances:action_point_distances_cache",
         "//src/main/cpp/net/eagle0/shardok/library/map:coords_set",
+        "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",
     ],
 )
 

src/main/cpp/net/eagle0/shardok/ai/score/MCTSOptimizedAIScoreCalculator.cpp

@@ -41,14 +41,13 @@ namespace {
 // A 100% unit advantage (all attacker, no defender) produces ±80 score
 constexpr double UNITS_SCORE_SCALE = 80.0;
 
+// Normalizer for victory condition scores (also proportional to army size)
+// Typical victory condition range: -3000 to 0 (raw), becomes approximately -30 to 0 (normalized)
+constexpr double VICTORY_SCORE_SCALE = 400.0;
+
 // Minimum reference value to avoid division by zero in edge cases
 constexpr double MIN_REFERENCE_VALUE = 1000.0;
 
-// IMPORTANT: Victory condition scores are NOT normalized by army size
-// They represent absolute strategic goals (castle control, etc.) that should not
-// diminish as more units are placed. Typical range: -3000 to +3000 (raw).
-// Scaling factor of 0.01 brings them to -30 to +30 range.
-
 }  // anonymous namespace
 
 /// MCTS-Optimized implementation of AIScoreCalculator.
@@ -146,9 +145,8 @@ auto MCTSOptimizedAIScoreCalculator::CombineAttackerScores(
     const double unitsDiff = components.attackerUnitsValue - components.defenderUnitsValue;
     const double unitsScore = (unitsDiff / reference) * UNITS_SCORE_SCALE;
 
-    // Victory condition score is an absolute strategic value, not normalized by army size
-    // Scaling factor to bring victory scores into similar magnitude as unit scores
-    const double victoryScore = victoryConditionScore * 0.01;
+    // Normalize victory condition (also proportional to army size) to approximately [-40, 0] range
+    const double victoryScore = (victoryConditionScore / reference) * VICTORY_SCORE_SCALE;
 
     // Weight units by rounds remaining (early: units matter less, late: units dominate)
     const double unitsMultiplier =
@@ -179,10 +177,7 @@ auto MCTSOptimizedAIScoreCalculator::CombineDefenderHoldCastlesScores(
     // Similar to attacker, but from defender's perspective
     const double unitsDiff = components.defenderUnitsValue - components.attackerUnitsValue;
     const double unitsScore = (unitsDiff / reference) * UNITS_SCORE_SCALE;
-
-    // Victory condition score is an absolute strategic value, not normalized by army size
-    // Scaling factor to bring victory scores into similar magnitude as unit scores
-    const double victoryScore = victoryConditionScore * 0.01;
+    const double victoryScore = (victoryConditionScore / reference) * VICTORY_SCORE_SCALE;
 
     const double unitsMultiplier =
             static_cast<double>(roundsRemaining) / static_cast<double>(GetMaxRounds());

src/main/cpp/net/eagle0/shardok/ai/score/StandardAIScoreCalculator.cpp

@@ -206,19 +206,11 @@ auto StandardAIScoreCalculator::CombineDefenderHoldCastlesScores(
         const UnitsScoreComponents &components,
         const double victoryConditionScore,
         const int roundsRemaining) const -> ScoreValue {
-    (void)roundsRemaining;  // Intentionally unused for now
     // From defender's perspective: negate the attacker-defender difference
     const double unitsDifference = components.defenderUnitsValue - components.attackerUnitsValue;
-    // TODO: The time-decay multiplier (roundsRemaining/maxRounds) was causing END_TURN
-    // to score better than tactical actions because it reduced the penalty for having
-    // fewer units. Setting to constant 1.0 for now to fix tactical decision-making.
-    const double unitsMultiplier = 1.0;
-    // const double unitsMultiplier =
-    //         static_cast<double>(roundsRemaining) / static_cast<double>(GetMaxRounds());
-    const double finalScore =
-            UNITS_BASE_MULTIPLIER * unitsMultiplier * unitsDifference + victoryConditionScore;
-
-    return finalScore;
+    const double unitsMultiplier =
+            static_cast<double>(roundsRemaining) / static_cast<double>(GetMaxRounds());
+    return UNITS_BASE_MULTIPLIER * unitsMultiplier * unitsDifference + victoryConditionScore;
 }
 
 auto StandardAIScoreCalculator::DefenderFleeStrategyScoreForState(const GameStateW &gameState) const

src/main/cpp/net/eagle0/shardok/ai_battle_simulator/AiBattleSimulator.cpp

@@ -7,13 +7,12 @@
 #include <iostream>
 
 #include "src/main/cpp/net/eagle0/common/FilesystemUtils.hpp"
+#include "src/main/cpp/net/eagle0/common/TsvParser.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/ShardokAIClient.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai_testing_common/AIClientFactory.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai_testing_common/GamePhaseRunner.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai_testing_common/GameSettingsFactory.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokEngine.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/fb_helpers/GameStateHelpers.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
+#include "src/main/cpp/net/eagle0/shardok/util/BattalionTypeRegistrar.hpp"
 #include "src/main/cpp/net/eagle0/shardok/util/MapLoader.hpp"
 #include "src/main/flatbuffer/net/eagle0/shardok/storage/unit.hpp"
 
@@ -68,7 +67,20 @@ AiBattleSimulator::AiBattleSimulator(const BattleConfigProto& config, GameSettin
       gameSettings_(std::move(gameSettings)) {
     if (!gameSettings_) {
         // Initialize default game settings
-        gameSettings_ = ai_testing_common::GameSettingsFactory::CreateDefault();
+        gameSettings_ = std::make_shared<GameSettings>();
+        auto setter = gameSettings_->GetSetter();
+
+        // Load battalion types
+        BattalionTypeRegistrar::RegisterBattalionTypes(setter);
+
+        // Load settings from file
+        const std::string settingsPath =
+                FilesystemUtils::StaticShardokFilesDirectory() + "settings.tsv";
+        const std::string settingsTsv = std::string(byte_vector::FromPath(settingsPath));
+
+        TsvParser parser;
+        const auto valuesAndTypes = parser.ParseColumnEntryTsv(settingsTsv);
+        setter.SetFromTypesAndValues(valuesAndTypes[1], valuesAndTypes[0]);
     }
 }
 
@@ -349,7 +361,7 @@ std::unique_ptr<ShardokAIClient> AiBattleSimulator::CreateAIClient(
 
     AIAlgorithmType algorithmType = ConvertAIAlgorithmType(playerConfig.ai_algorithm());
 
-    return ai_testing_common::AIClientFactory::Create(
+    return std::make_unique<ShardokAIClient>(
             playerId,
             isDefender,
             hexMap,
@@ -361,28 +373,44 @@ BattleResult AiBattleSimulator::RunSetupPhase(
         ShardokEngine& engine,
         ShardokAIClient& attackerAI,
         ShardokAIClient& defenderAI) {
-    auto getAI = [&](PlayerId playerId) -> ShardokAIClient& {
-        return (playerId == ATTACKER_ID) ? attackerAI : defenderAI;
-    };
+    int commandsExecuted = 0;
 
-    auto phaseResult = ai_testing_common::GamePhaseRunner::RunSetupPhase(engine, getAI);
+    while (engine.GetCurrentGameState()->status()->state() ==
+           net::eagle0::shardok::storage::fb::GameStatus_::State_SET_UP) {
+        auto currentState = engine.GetCurrentGameState();
+        PlayerId currentPlayer = currentState->current_player();
 
-    std::cout << "Setup phase complete. Commands executed: " << phaseResult.commandsExecuted
-              << "\n";
+        auto availableCommands = engine.GetAvailableCommandProtos(currentPlayer, false);
 
-    // Check if game ended unexpectedly
-    if (phaseResult.gameEnded) {
-        return CreateResultFromGameState(
-                engine.GetCurrentGameState(),
-                0,
-                phaseResult.commandsExecuted);
+        if (availableCommands.empty()) {
+            std::cout << "No commands available during setup for player " << (int)currentPlayer
+                      << "\n";
+            break;
+        }
+
+        // Choose which AI to use
+        ShardokAIClient& activeAI = (currentPlayer == ATTACKER_ID) ? attackerAI : defenderAI;
+
+        // Get AI decision
+        auto choiceResults = activeAI.ChooseCommandIndex(engine);
+
+        // Apply command
+        engine.PostCommand(currentPlayer, choiceResults.chosenIndex);
+        commandsExecuted++;
+
+        // Check if game ended unexpectedly
+        if (engine.GameIsOver()) {
+            return CreateResultFromGameState(engine.GetCurrentGameState(), 0, commandsExecuted);
+        }
     }
 
+    std::cout << "Setup phase complete. Commands executed: " << commandsExecuted << "\n";
+
     // Return a "not finished" result
     BattleResult result;
     result.winner = -1;
     result.totalRounds = 0;
-    result.totalCommands = phaseResult.commandsExecuted;
+    result.totalCommands = commandsExecuted;
     result.endReason = BattleResult::EndReason::DRAW;  // Temporary placeholder
     result.description = "Setup phase completed";
     return result;

src/main/cpp/net/eagle0/shardok/ai_battle_simulator/BUILD.bazel

@@ -23,9 +23,6 @@ cc_library(
         "//src/main/cpp/net/eagle0/common:filesystem_utils",
         "//src/main/cpp/net/eagle0/common:tsv_parser",
         "//src/main/cpp/net/eagle0/shardok/ai:shardok_ai_client",
-        "//src/main/cpp/net/eagle0/shardok/ai_testing_common:ai_client_factory",
-        "//src/main/cpp/net/eagle0/shardok/ai_testing_common:game_phase_runner",
-        "//src/main/cpp/net/eagle0/shardok/ai_testing_common:game_settings_factory",
         "//src/main/cpp/net/eagle0/shardok/library:engine",
         "//src/main/cpp/net/eagle0/shardok/library:game_state_w",
         "//src/main/cpp/net/eagle0/shardok/library/fb_helpers:game_state_helpers",

src/main/cpp/net/eagle0/shardok/ai_performance_runner/AIPerformanceRunner.cpp

@@ -13,8 +13,6 @@
 #include "src/main/cpp/net/eagle0/common/FilesystemUtils.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/AIConfig.hpp"
 #include "src/main/cpp/net/eagle0/shardok/ai/ShardokAIClient.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai_testing_common/AIClientFactory.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai_testing_common/GamePhaseRunner.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/ShardokEngine.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/action_point_distances/FixedActionPointDistances.hpp"
 #include "src/main/protobuf/net/eagle0/shardok/common/command_type.pb.h"
@@ -122,7 +120,7 @@ int main(int argc, char* argv[]) {
         const auto* hexMap = currentState->hex_map();
         const auto settingsGetter = settings->GetGetter();
 
-        auto aiClient = ai_testing_common::AIClientFactory::Create(
+        ShardokAIClient aiClient(
                 aiPlayerId,
                 isDefender,
                 hexMap,
@@ -132,7 +130,7 @@ int main(int argc, char* argv[]) {
         // Create a second AI client for the human player during setup
         // This ensures consistent state handling during setup phase
         const PlayerId humanPlayerId = 1;
-        auto humanSetupAI = ai_testing_common::AIClientFactory::Create(
+        ShardokAIClient humanSetupAI(
                 humanPlayerId,
                 !isDefender,
                 hexMap,
@@ -142,18 +140,29 @@ int main(int argc, char* argv[]) {
         // Complete setup phase - AI makes intelligent placement decisions
         if (currentState->status()->state() ==
             net::eagle0::shardok::storage::fb::GameStatus_::State_SET_UP) {
-            auto getAI = [&](PlayerId playerId) -> ShardokAIClient& {
-                return (playerId == aiPlayerId) ? *aiClient : *humanSetupAI;
-            };
+            while (currentState->status()->state() ==
+                   net::eagle0::shardok::storage::fb::GameStatus_::State_SET_UP) {
+                PlayerId currentPlayer = currentState->current_player();
+                auto availableCommands = engine.GetAvailableCommandProtos(currentPlayer, false);
 
-            auto setupResult = ai_testing_common::GamePhaseRunner::RunSetupPhase(engine, getAI);
+                if (availableCommands.empty()) {
+                    std::cout << "No commands available for player "
+                              << static_cast<int>(currentPlayer) << "\n";
+                    break;
+                }
 
-            if (setupResult.gameEnded) {
-                std::cout << "Game ended unexpectedly during setup phase.\n";
-                return 0;
+                if (currentPlayer == aiPlayerId) {
+                    // Let AI make intelligent placement decisions
+                    auto choiceResults = aiClient.ChooseCommandIndex(engine);
+                    engine.PostCommand(currentPlayer, choiceResults.chosenIndex);
+                } else {
+                    // Human player: use AI for setup to ensure consistent state handling
+                    auto choiceResults = humanSetupAI.ChooseCommandIndex(engine);
+                    engine.PostCommand(currentPlayer, choiceResults.chosenIndex);
+                }
+
+                currentState = engine.GetCurrentGameState();
             }
-
-            currentState = engine.GetCurrentGameState();
         }
 
         // Test AI performance for configured number of turns
@@ -170,7 +179,7 @@ int main(int argc, char* argv[]) {
             }
 
             // Get AI decision with performance metrics
-            auto choiceResults = aiClient->ChooseCommandIndex(engine);
+            auto choiceResults = aiClient.ChooseCommandIndex(engine);
 
             std::cout << "  AI chose command index: " << choiceResults.chosenIndex << "\n";
             std::cout << "  Depth achieved: " << choiceResults.depthAchieved << "\n";

src/main/cpp/net/eagle0/shardok/ai_performance_runner/BUILD.bazel

@@ -23,9 +23,6 @@ cc_binary(
         "//src/main/cpp/net/eagle0/shardok/ai:ai_water_crossing_command_chooser",
         "//src/main/cpp/net/eagle0/shardok/ai:shardok_ai_client",
         "//src/main/cpp/net/eagle0/shardok/ai/score:ai_score_calculator_interface",
-        "//src/main/cpp/net/eagle0/shardok/ai_testing_common:ai_client_factory",
-        "//src/main/cpp/net/eagle0/shardok/ai_testing_common:game_phase_runner",
-        "//src/main/cpp/net/eagle0/shardok/ai_testing_common:game_settings_factory",
         "//src/main/cpp/net/eagle0/shardok/library:engine",
         "//src/main/cpp/net/eagle0/shardok/library:game_state_w",
         "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
@@ -42,7 +39,6 @@ cc_library(
     ],
     copts = COPTS,
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/ai_testing_common:game_settings_factory",
         "//src/main/cpp/net/eagle0/shardok/library:game_state_w",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_c_types",
         "//src/main/cpp/net/eagle0/shardok/library/fb_helpers:game_state_helpers",

src/main/cpp/net/eagle0/shardok/ai_performance_runner/PerformanceTestGameStateBuilder.cpp

@@ -7,9 +7,11 @@
 #include <filesystem>
 
 #include "src/main/cpp/net/eagle0/common/FilesystemUtils.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai_testing_common/GameSettingsFactory.hpp"
+#include "src/main/cpp/net/eagle0/common/TsvParser.hpp"
+#include "src/main/cpp/net/eagle0/common/byte_vector.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/fb_helpers/GameStateHelpers.hpp"
 #include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
+#include "src/main/cpp/net/eagle0/shardok/util/BattalionTypeRegistrar.hpp"
 #include "src/main/cpp/net/eagle0/shardok/util/MapLoader.hpp"
 #include "src/main/flatbuffer/net/eagle0/shardok/storage/unit.hpp"
 #include "src/main/protobuf/net/eagle0/shardok/common/player_info.pb.h"
@@ -28,7 +30,20 @@ constexpr PlayerId HUMAN_PLAYER_ID = 1;
 }  // namespace
 
 auto PerformanceTestGameStateBuilder::InitializeGameSettings() -> GameSettingsSPtr {
-    return ai_testing_common::GameSettingsFactory::CreateDefault();
+    auto settings = std::make_shared<GameSettings>();
+    auto setter = settings->GetSetter();
+
+    // Load battalion types
+    BattalionTypeRegistrar::RegisterBattalionTypes(setter);
+
+    // Load complete settings from settings.tsv file
+    TsvParser parser;
+    const string settingsPath = FilesystemUtils::StaticShardokFilesDirectory() + "settings.tsv";
+    const string settingsTsv = string(byte_vector::FromPath(settingsPath));
+    const auto valuesAndTypes = parser.ParseColumnEntryTsv(settingsTsv);
+    setter.SetFromTypesAndValues(valuesAndTypes[1], valuesAndTypes[0]);
+
+    return settings;
 }
 
 auto PerformanceTestGameStateBuilder::CreatePerfTestGameState(

src/main/cpp/net/eagle0/shardok/ai_testing/AI_TESTING_GUIDE.md

@@ -1,469 +0,0 @@
-# AI Testing Guide
-
-This guide explains how to use the two AI testing tools in the Eagle0 codebase for evaluating and improving AI performance.
-
-## Overview
-
-The codebase provides two complementary tools for AI testing:
-
-1. **AI Performance Runner** - Benchmarks AI decision-making quality over specific turns
-2. **AI Battle Simulator** - Tests AI effectiveness by running complete battles
-
-Both tools support the Iterative Deepening and MCTS AI algorithms.
-
----
-
-## AI Performance Runner
-
-**Location**: `src/main/cpp/net/eagle0/shardok/ai_performance_runner/`
-
-### Purpose
-
-Measures AI decision-making performance to:
-- Identify performance regressions when making AI changes
-- Understand search depth achieved within time budgets
-- Analyze command evaluation patterns at each depth
-- Profile AI bottlenecks
-
-### Building
-
-```bash
-bazel build //src/main/cpp/net/eagle0/shardok/ai_performance_runner:ai_performance_runner
-```
-
-### Usage
-
-```bash
-bazel run //src/main/cpp/net/eagle0/shardok/ai_performance_runner:ai_performance_runner -- \
-    --map=MAP_NAME \
-    --turns=N \
-    [--defender=true|false] \
-    [--verbose]
-```
-
-### Command-Line Arguments
-
-| Argument | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `--map` | Yes | - | Map name (e.g., "FourWay", "Bridge") |
-| `--turns` | Yes | - | Number of turns to run AI for |
-| `--defender` | No | false | If true, test defender AI; if false, test attacker AI |
-| `--verbose` | No | false | Enable verbose logging of AI decisions |
-
-### Output Format
-
-For each turn, outputs:
-```
-Turn 1:
-  Depth achieved: 3
-  Commands evaluated:
-    Depth 1: 45/45 commands (100%)
-    Depth 2: 127/234 commands (54%)
-    Depth 3: 23/891 commands (3%)
-  Completion reason: TIME_LIMIT
-  Time elapsed: 5.2s
-```
-
-### Performance Metrics Explained
-
-- **Depth achieved**: Maximum lookahead depth the AI reached
-- **Commands evaluated**: At each depth, shows commands fully evaluated vs total available
-  - Higher depth evaluations are more valuable (depth 3 > depth 2 > depth 1)
-  - Completion rates show how thoroughly the AI searched each depth
-- **Completion reason**: Why the search stopped
-  - `TIME_LIMIT`: Ran out of time budget (normal)
-  - `COMPLETE`: Fully evaluated all possibilities (rare, usually only in simple endgames)
-  - `DEPTH_LIMIT`: Hit maximum configured depth
-
-### Example Workflow: Testing Performance Improvements
-
-```bash
-# 1. Commit your baseline changes
-git checkout -b my-performance-improvement
-git add . && git commit -m "Baseline before optimization"
-
-# 2. Run performance tests multiple times (reduce noise)
-for i in 1 2 3; do
-    echo "=== Baseline Run $i ==="
-    bazel run //src/main/cpp/net/eagle0/shardok/ai_performance_runner:ai_performance_runner -- \
-        --map=FourWay --turns=5 --defender=true | grep -A 10 "Turn"
-done
-# Save the results
-
-# 3. Make your optimization changes
-# ... edit code ...
-
-# 4. Run tests again and compare
-for i in 1 2 3; do
-    echo "=== Optimized Run $i ==="
-    bazel run //src/main/cpp/net/eagle0/shardok/ai_performance_runner:ai_performance_runner -- \
-        --map=FourWay --turns=5 --defender=true | grep -A 10 "Turn"
-done
-
-# 5. Compare the results
-# Look for: increased depth, higher completion rates, more commands evaluated at deeper levels
-```
-
-### When to Use Performance Runner
-
-- ✅ Making changes to AI search algorithms
-- ✅ Optimizing performance-critical code paths
-- ✅ Identifying regressions in decision quality
-- ✅ Understanding where the AI spends its time
-- ❌ Testing which AI strategy wins more battles (use Battle Simulator instead)
-
----
-
-## AI Battle Simulator
-
-**Location**: `src/main/cpp/net/eagle0/shardok/ai_battle_simulator/`
-
-### Purpose
-
-Tests AI effectiveness by:
-- Running complete AI vs AI battles from start to finish
-- Measuring win rates across different AI configurations
-- Testing AI behavior with various unit compositions
-- Comparing different AI algorithms (MCTS vs Iterative Deepening)
-
-### Building
-
-```bash
-bazel build //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:ai_battle_simulator
-```
-
-### Usage
-
-The battle simulator works with JSON configuration files.
-
-#### Step 1: Generate a Sample Configuration
-
-```bash
-bazel run //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:ai_battle_simulator -- \
-    --generate-config=my_battle_config.json
-```
-
-This creates a sample configuration file you can customize.
-
-#### Step 2: Customize the Configuration
-
-Edit the generated JSON file:
-
-```json
-{
-  "map_name": "FourWay",
-  "max_rounds": 100,
-  "attacker": {
-    "ai_algorithm": "ITERATIVE_DEEPENING",
-    "units": [
-      {
-        "battalion_type": "HEAVY_INFANTRY",
-        "row": 2,
-        "column": 3,
-        "strength": 1000,
-        "has_hero": true,
-        "hero_profession": "WARRIOR",
-        "hero_level": 5
-      },
-      {
-        "battalion_type": "ARCHERS",
-        "row": 2,
-        "column": 4,
-        "strength": 800,
-        "has_hero": false
-      }
-    ]
-  },
-  "defender": {
-    "ai_algorithm": "MCTS",
-    "units": [
-      {
-        "battalion_type": "HEAVY_INFANTRY",
-        "row": 8,
-        "column": 3,
-        "strength": 1000,
-        "has_hero": true,
-        "hero_profession": "WARRIOR",
-        "hero_level": 5
-      }
-    ]
-  }
-}
-```
-
-#### Step 3: Run the Battle
-
-```bash
-bazel run //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:ai_battle_simulator -- \
-    --config=my_battle_config.json
-```
-
-### Configuration Format
-
-#### Top-Level Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `map_name` | string | Yes | Name of the map to use (e.g., "FourWay", "Bridge") |
-| `max_rounds` | integer | Yes | Maximum rounds before declaring a draw |
-| `attacker` | object | Yes | Attacker configuration (see below) |
-| `defender` | object | Yes | Defender configuration (see below) |
-
-#### Player Configuration (attacker/defender)
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `ai_algorithm` | string | Yes | "ITERATIVE_DEEPENING" or "MCTS" |
-| `units` | array | Yes | List of unit configurations (see below) |
-
-#### Unit Configuration
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `battalion_type` | string | Yes | - | "HEAVY_INFANTRY", "LIGHT_INFANTRY", "ARCHERS", "CAVALRY", etc. |
-| `row` | integer | Yes | - | Starting row position (0-indexed) |
-| `column` | integer | Yes | - | Starting column position (0-indexed) |
-| `strength` | integer | No | 1000 | Unit strength (max 1000) |
-| `has_hero` | boolean | No | false | Whether unit has an attached hero |
-| `hero_profession` | string | No* | - | "WARRIOR", "RANGER", "MAGE" (*required if has_hero=true) |
-| `hero_level` | integer | No | 1 | Hero level (1-10) |
-| `hero_vigor` | integer | No | 100 | Hero vigor (0-100) |
-
-### Output Format
-
-After running a battle, outputs:
-
-```
-Battle Result:
-  Winner: ATTACKER
-  Total Rounds: 47
-  Total Commands: 2,341
-
-Attacker Survivors: 3 units
-  - Heavy Infantry at (4,5): 723 strength
-  - Archers at (3,6): 412 strength
-  - Cavalry at (5,4): 891 strength
-
-Defender Survivors: 0 units
-
-Battle Duration: 14.2 seconds
-```
-
-### Example Workflow: Testing AI Effectiveness
-
-```bash
-# 1. Create a baseline configuration
-bazel run //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:ai_battle_simulator -- \
-    --generate-config=baseline.json
-
-# 2. Edit baseline.json to set up your test scenario
-# Set both players to ITERATIVE_DEEPENING
-
-# 3. Run multiple battles to get win rate
-for i in {1..20}; do
-    echo "Battle $i:"
-    bazel run //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:ai_battle_simulator -- \
-        --config=baseline.json | grep "Winner"
-done
-
-# 4. Create a comparison configuration
-cp baseline.json mcts_comparison.json
-# Edit mcts_comparison.json: change attacker to MCTS
-
-# 5. Run battles with MCTS attacker
-for i in {1..20}; do
-    echo "Battle $i:"
-    bazel run //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:ai_battle_simulator -- \
-        --config=mcts_comparison.json | grep "Winner"
-done
-
-# 6. Compare win rates
-# Count ATTACKER wins in each set to see if MCTS performs better/worse
-```
-
-### Advanced: Testing Specific Scenarios
-
-The battle simulator is ideal for testing:
-
-**Scenario 1: Hero Ability Usage**
-```json
-{
-  "attacker": {
-    "units": [
-      {
-        "battalion_type": "LIGHT_INFANTRY",
-        "has_hero": true,
-        "hero_profession": "RANGER",
-        "hero_level": 8,
-        "row": 2, "column": 3
-      }
-    ]
-  }
-}
-```
-Tests whether AI properly uses Ranger stealth abilities.
-
-**Scenario 2: Terrain Advantage**
-```json
-{
-  "map_name": "BridgeChoke",
-  "defender": {
-    "units": [
-      {"battalion_type": "HEAVY_INFANTRY", "row": 5, "column": 4}
-    ]
-  }
-}
-```
-Tests whether AI exploits defensive terrain.
-
-**Scenario 3: Numerical Superiority**
-```json
-{
-  "attacker": {
-    "units": [
-      {"battalion_type": "ARCHERS", "row": 2, "column": 2},
-      {"battalion_type": "ARCHERS", "row": 2, "column": 3},
-      {"battalion_type": "ARCHERS", "row": 2, "column": 4}
-    ]
-  },
-  "defender": {
-    "units": [
-      {"battalion_type": "CAVALRY", "row": 8, "column": 3}
-    ]
-  }
-}
-```
-Tests whether AI properly coordinates multiple units.
-
-### When to Use Battle Simulator
-
-- ✅ Testing which AI strategy wins more battles
-- ✅ Measuring AI effectiveness with different unit types
-- ✅ Comparing MCTS vs Iterative Deepening algorithms
-- ✅ Validating AI behavior in specific tactical scenarios
-- ✅ Regression testing: ensuring AI changes don't reduce win rates
-- ❌ Profiling performance bottlenecks (use Performance Runner instead)
-
----
-
-## Combining Both Tools
-
-For comprehensive AI evaluation:
-
-1. **Make AI changes** to improve decision-making
-2. **Run Performance Runner** to verify the AI searches deeper or evaluates more commands
-3. **Run Battle Simulator** to verify the changes actually improve win rates
-4. **Iterate** if performance improves but win rate doesn't (or vice versa)
-
-### Example: Evaluating a New Heuristic
-
-```bash
-# 1. Baseline performance
-bazel run //src/main/cpp/net/eagle0/shardok/ai_performance_runner:ai_performance_runner -- \
-    --map=FourWay --turns=3 > baseline_perf.txt
-
-# 2. Baseline effectiveness
-for i in {1..10}; do
-    bazel run //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:ai_battle_simulator -- \
-        --config=test_scenario.json | grep "Winner"
-done > baseline_wins.txt
-
-# 3. Make changes to heuristic
-# ... edit code ...
-
-# 4. New performance
-bazel run //src/main/cpp/net/eagle0/shardok/ai_performance_runner:ai_performance_runner -- \
-    --map=FourWay --turns=3 > new_perf.txt
-
-# 5. New effectiveness
-for i in {1..10}; do
-    bazel run //src/main/cpp/net/eagle0/shardok/ai_battle_simulator:ai_battle_simulator -- \
-        --config=test_scenario.json | grep "Winner"
-done > new_wins.txt
-
-# 6. Compare results
-diff baseline_perf.txt new_perf.txt
-wc -l < baseline_wins.txt | grep ATTACKER  # Count baseline wins
-wc -l < new_wins.txt | grep ATTACKER       # Count new wins
-```
-
----
-
-## Available Maps
-
-Common maps for testing:
-- **FourWay**: Open terrain with multiple approach paths
-- **Bridge**: Chokepoint scenario testing tactical positioning
-- **Forest**: Tests unit behavior in hiding terrain
-- **Mountain**: Tests pathfinding around impassable terrain
-
-Find all available maps in: `src/main/resources/net/eagle0/shardok/maps/`
-
----
-
-## Troubleshooting
-
-### Performance Runner Issues
-
-**Issue**: "Map not found"
-```bash
-# Solution: Use exact map name without .e0mj extension
-# ✅ Correct:
---map=FourWay
-# ❌ Incorrect:
---map=FourWay.e0mj
-```
-
-**Issue**: AI completes instantly
-```bash
-# Likely cause: Too few turns or already-won scenario
-# Solution: Increase --turns or use more complex map
---turns=10  # Instead of --turns=1
-```
-
-### Battle Simulator Issues
-
-**Issue**: "Invalid unit position"
-```bash
-# Solution: Ensure positions are within map bounds and not overlapping
-# Check map size first, then place units accordingly
-```
-
-**Issue**: "Battle ends immediately"
-```bash
-# Cause: Units placed too close or in invalid starting positions
-# Solution:
-# - Attacker units should start on attacker side (low row numbers)
-# - Defender units should start on defender side (high row numbers)
-# - Leave space between forces for tactical maneuvering
-```
-
-**Issue**: Battle runs extremely slowly
-```bash
-# Cause: Too many units or max_rounds too high
-# Solution: Start with 2-3 units per side, max_rounds=50
-# Scale up once basic scenario works
-```
-
----
-
-## Best Practices
-
-### For Performance Testing
-1. **Run multiple iterations** (3-5) to reduce variance
-2. **Test on consistent maps** to enable before/after comparison
-3. **Focus on depth and completion rates** rather than raw time
-4. **Test both attacker and defender** AIs (they use different strategies)
-
-### For Effectiveness Testing
-1. **Run 10-20 battles** minimum for statistical significance
-2. **Use symmetric scenarios** (equal forces) to isolate AI quality
-3. **Test multiple maps** to avoid overfitting to one scenario
-4. **Document unit compositions** so tests are reproducible
-5. **Version control configs** alongside code changes
-
-### For Both
-1. **Commit before testing** so you can easily revert
-2. **Document unexpected results** (AI might be correct, your intuition wrong)
-3. **Test edge cases** (one unit, heroes only, terrain heavy)
-4. **Compare algorithms** (MCTS vs Iterative Deepening) regularly

src/main/cpp/net/eagle0/shardok/ai_testing/SERVER_BASED_EFFECTIVENESS_TESTING_PROPOSAL.md

@@ -1,647 +0,0 @@
-# Proposal: Server-Based AI Effectiveness Testing
-
-## Executive Summary
-
-Replace proxy-based performance metrics (search depth, nodes visited) with **actual effectiveness testing** (win rates, battle outcomes) by running AI battles through the production Shardok server. This measures what matters: whether AI improvements make the AI smarter, not just faster.
-
-## Problem Statement
-
-### Current State: Measuring the Wrong Things
-
-The existing `ai_performance_runner` measures proxy metrics:
-- Search depth achieved
-- Number of commands evaluated
-- Time spent searching
-
-**Problem**: These metrics don't tell us if the AI is making good decisions.
-
-**Example failure mode**:
-- AI searches to depth 4 (looks impressive!)
-- But uses terrible heuristics (all decisions are bad)
-- Result: Loses every battle despite "good" metrics
-
-### What We Actually Care About
-
-- **Does the AI win?** (win rate)
-- **By what margin?** (survivors, rounds taken)
-- **Is it tactically sound?** (decision quality in specific scenarios)
-- **Does it handle edge cases?** (terrain, heroes, special abilities)
-
-## Proposed Solution
-
-Build a **server-based AI effectiveness testing framework** that:
-1. Runs battles through the production Shardok server (real code paths)
-2. Measures actual effectiveness (win rates, outcomes)
-3. Supports repeatable test scenarios
-4. Enables comparison between AI algorithms (MCTS vs Iterative Deepening)
-5. Eventually allows Unity clients to watch battles
-
-## Architecture
-
-### Component Overview
-
-```
-┌─────────────────────┐
-│  Test Scenarios     │
-│  (JSON configs)     │
-└──────────┬──────────┘
-           │
-           ▼
-┌─────────────────────┐
-│  Go Test Client     │
-│  - Loads scenarios  │
-│  - Sends gRPC reqs  │
-│  - Collects results │
-└──────────┬──────────┘
-           │ gRPC
-           ▼
-┌─────────────────────┐
-│  Shardok Server     │
-│  - Creates games    │
-│  - Runs AI vs AI    │
-│  - Returns outcomes │
-└─────────────────────┘
-```
-
-### Why Go for the Client?
-
-- Native gRPC support with `protoc-gen-go-grpc`
-- Easy JSON config parsing
-- Good for CLI tools
-- Fast compile times for iteration
-- Excellent concurrency for running parallel test scenarios
-
-## Implementation Plan
-
-### Phase 1: Core Framework (1 week)
-
-**Goal**: Basic server-based effectiveness testing
-
-#### 1.1 Protocol Extensions
-
-Add to `src/main/protobuf/net/eagle0/common/shardok_internal_interface.proto`:
-
-```protobuf
-message TestBattleRequest {
-    string game_id = 1;
-    string map_name = 2;
-
-    message PlayerSetup {
-        bool is_defender = 1;
-        AIAlgorithmType ai_algorithm = 2;  // MCTS or ITERATIVE_DEEPENING
-        ScoringCalculatorType scoring_type = 3;  // STANDARD, NORMALIZED, MCTS_OPTIMIZED
-        repeated UnitPlacement units = 4;
-    }
-
-    repeated PlayerSetup players = 3;
-    int32 max_rounds = 4;
-}
-
-message UnitPlacement {
-    string battalion_type = 1;  // "HEAVY_INFANTRY", "ARCHERS", etc.
-    int32 row = 2;
-    int32 column = 3;
-    int32 strength = 4;
-    bool has_hero = 5;
-    string hero_profession = 6;  // "WARRIOR", "RANGER", "MAGE"
-    int32 hero_level = 7;
-}
-
-message TestBattleResponse {
-    string game_id = 1;
-    int32 winner_player_id = 2;  // -1 for draw
-    int32 rounds_taken = 3;
-    string end_reason = 4;  // "VICTORY", "DRAW", "MAX_ROUNDS"
-    repeated FinalUnitStatus final_units = 5;
-}
-
-message FinalUnitStatus {
-    int32 player_id = 1;
-    string battalion_type = 2;
-    int32 strength_remaining = 3;
-    int32 row = 4;
-    int32 column = 5;
-}
-
-// Add to ShardokInternalInterface service:
-rpc StartTestBattle(TestBattleRequest) returns (TestBattleResponse) {}
-```
-
-**Estimated effort**: 1 day
-
-#### 1.2 Server Implementation
-
-Add handler to `src/main/cpp/net/eagle0/shardok/server/EagleInterfaceGrpcServer.cpp`:
-
-```cpp
-Status EagleInterfaceImpl::StartTestBattle(
-        ServerContext* context,
-        const TestBattleRequest* request,
-        TestBattleResponse* response) {
-    // 1. Create game with specified setup
-    // 2. Mark all players as is_ai=true
-    // 3. Wait for game to complete (AI thread handles it)
-    // 4. Collect final state and return results
-}
-```
-
-**Key insight**: The infrastructure already exists! `ShardokGameController` already:
-- Creates AI clients automatically for `is_ai=true` players
-- Runs AI decisions in background thread
-- Tracks game state and completion
-
-**Estimated effort**: 2 days
-
-#### 1.3 Go Test Client
-
-Create `src/main/go/net/eagle0/shardok/ai_effectiveness_runner/`:
-
-```go
-package main
-
-import (
-    "context"
-    "encoding/json"
-    "flag"
-    "fmt"
-    "log"
-
-    pb "eagle0/protobuf/net/eagle0/common"
-    "google.golang.org/grpc"
-)
-
-type ScenarioConfig struct {
-    Name      string        `json:"name"`
-    MapName   string        `json:"map_name"`
-    MaxRounds int32         `json:"max_rounds"`
-    Attacker  PlayerConfig  `json:"attacker"`
-    Defender  PlayerConfig  `json:"defender"`
-}
-
-type PlayerConfig struct {
-    AIAlgorithm  string           `json:"ai_algorithm"`
-    ScoringType  string           `json:"scoring_type"`
-    Units        []UnitPlacement  `json:"units"`
-}
-
-func runTestBattle(client pb.ShardokInternalInterfaceClient, scenario ScenarioConfig) (*pb.TestBattleResponse, error) {
-    ctx := context.Background()
-
-    req := &pb.TestBattleRequest{
-        GameId:    fmt.Sprintf("test_%s_%d", scenario.Name, time.Now().Unix()),
-        MapName:   scenario.MapName,
-        MaxRounds: scenario.MaxRounds,
-        Players: []*pb.TestBattleRequest_PlayerSetup{
-            {
-                IsDefender:   false,
-                AiAlgorithm:  parseAIAlgorithm(scenario.Attacker.AIAlgorithm),
-                ScoringType:  parseScoringType(scenario.Attacker.ScoringType),
-                Units:        convertUnits(scenario.Attacker.Units),
-            },
-            {
-                IsDefender:   true,
-                AiAlgorithm:  parseAIAlgorithm(scenario.Defender.AIAlgorithm),
-                ScoringType:  parseScoringType(scenario.Defender.ScoringType),
-                Units:        convertUnits(scenario.Defender.Units),
-            },
-        },
-    }
-
-    return client.StartTestBattle(ctx, req)
-}
-
-func main() {
-    serverAddr := flag.String("server", "localhost:50051", "Shardok server address")
-    scenariosFile := flag.String("scenarios", "test_scenarios.json", "Test scenarios JSON file")
-    iterations := flag.Int("iterations", 20, "Number of iterations per scenario")
-
-    flag.Parse()
-
-    // Load scenarios
-    scenarios := loadScenarios(*scenariosFile)
-
-    // Connect to server
-    conn, err := grpc.Dial(*serverAddr, grpc.WithInsecure())
-    if err != nil {
-        log.Fatalf("Failed to connect: %v", err)
-    }
-    defer conn.Close()
-
-    client := pb.NewShardokInternalInterfaceClient(conn)
-
-    // Run effectiveness tests
-    results := make(map[string]*ScenarioResults)
-
-    for _, scenario := range scenarios {
-        fmt.Printf("\n=== Testing Scenario: %s ===\n", scenario.Name)
-
-        scenarioResults := &ScenarioResults{
-            ScenarioName: scenario.Name,
-        }
-
-        for i := 0; i < *iterations; i++ {
-            resp, err := runTestBattle(client, scenario)
-            if err != nil {
-                log.Printf("Battle %d failed: %v", i+1, err)
-                continue
-            }
-
-            scenarioResults.TotalBattles++
-            if resp.WinnerPlayerId == 0 {  // Attacker wins
-                scenarioResults.AttackerWins++
-            } else if resp.WinnerPlayerId == 1 {  // Defender wins
-                scenarioResults.DefenderWins++
-            } else {
-                scenarioResults.Draws++
-            }
-
-            scenarioResults.TotalRounds += int(resp.RoundsTaken)
-            scenarioResults.TotalSurvivors += len(resp.FinalUnits)
-
-            fmt.Printf("  Battle %d/%d: Winner=%d, Rounds=%d, Survivors=%d\n",
-                i+1, *iterations, resp.WinnerPlayerId, resp.RoundsTaken, len(resp.FinalUnits))
-        }
-
-        results[scenario.Name] = scenarioResults
-    }
-
-    // Print summary
-    printSummary(results)
-}
-```
-
-**Estimated effort**: 2 days
-
-#### 1.4 Test Scenario Definitions
-
-Create `test_scenarios.json`:
-
-```json
-{
-  "scenarios": [
-    {
-      "name": "mcts_vs_id_balanced",
-      "map_name": "FourWay",
-      "max_rounds": 100,
-      "attacker": {
-        "ai_algorithm": "MCTS",
-        "scoring_type": "MCTS_OPTIMIZED",
-        "units": [
-          {
-            "battalion_type": "HEAVY_INFANTRY",
-            "row": 2,
-            "column": 3,
-            "strength": 1000,
-            "has_hero": true,
-            "hero_profession": "WARRIOR",
-            "hero_level": 5
-          },
-          {
-            "battalion_type": "ARCHERS",
-            "row": 2,
-            "column": 4,
-            "strength": 800,
-            "has_hero": false
-          }
-        ]
-      },
-      "defender": {
-        "ai_algorithm": "ITERATIVE_DEEPENING",
-        "scoring_type": "STANDARD",
-        "units": [
-          {
-            "battalion_type": "HEAVY_INFANTRY",
-            "row": 8,
-            "column": 3,
-            "strength": 1000,
-            "has_hero": true,
-            "hero_profession": "WARRIOR",
-            "hero_level": 5
-          },
-          {
-            "battalion_type": "ARCHERS",
-            "row": 8,
-            "column": 4,
-            "strength": 800,
-            "has_hero": false
-          }
-        ]
-      }
-    },
-    {
-      "name": "terrain_advantage_test",
-      "map_name": "Bridge",
-      "max_rounds": 100,
-      "attacker": {
-        "ai_algorithm": "MCTS",
-        "scoring_type": "MCTS_OPTIMIZED",
-        "units": [
-          {
-            "battalion_type": "LIGHT_INFANTRY",
-            "row": 2,
-            "column": 5,
-            "strength": 1000,
-            "has_hero": false
-          }
-        ]
-      },
-      "defender": {
-        "ai_algorithm": "MCTS",
-        "scoring_type": "MCTS_OPTIMIZED",
-        "units": [
-          {
-            "battalion_type": "HEAVY_INFANTRY",
-            "row": 10,
-            "column": 5,
-            "strength": 800,
-            "has_hero": false
-          }
-        ]
-      }
-    }
-  ]
-}
-```
-
-**Estimated effort**: 1 day (create comprehensive test suite)
-
-### Phase 2: Enhanced Observability (1 week)
-
-**Goal**: Stream battle updates for real-time monitoring
-
-#### 2.1 Streaming Protocol
-
-Extend protocol to support streaming updates:
-
-```protobuf
-message TestBattleUpdate {
-    enum UpdateType {
-        SETUP_COMPLETE = 0;
-        ROUND_START = 1;
-        AI_DECISION = 2;
-        ROUND_END = 3;
-        BATTLE_END = 4;
-    }
-
-    UpdateType type = 1;
-    int32 current_round = 2;
-
-    // For AI_DECISION updates
-    int32 player_id = 3;
-    string command_type = 4;  // "MOVE", "MELEE", "ARCHERY", etc.
-
-    // Optional: Include AI metrics as secondary data
-    AIDecisionMetrics ai_metrics = 5;
-
-    // For BATTLE_END updates
-    TestBattleResponse final_result = 6;
-}
-
-message AIDecisionMetrics {
-    int32 depth_achieved = 1;
-    int32 commands_evaluated = 2;
-    int64 time_spent_ms = 3;
-}
-
-// Add streaming RPC:
-rpc StartTestBattleStreaming(TestBattleRequest) returns (stream TestBattleUpdate) {}
-```
-
-**Benefits**:
-- Real-time battle monitoring
-- Can log/replay interesting decisions
-- Still captures proxy metrics as secondary data (if desired)
-- Enables debugging of specific scenarios
-
-**Estimated effort**: 3 days
-
-#### 2.2 Go Client Updates
-
-Add streaming support to Go client:
-
-```go
-func runTestBattleStreaming(client pb.ShardokInternalInterfaceClient, scenario ScenarioConfig) (*pb.TestBattleResponse, error) {
-    ctx := context.Background()
-    stream, err := client.StartTestBattleStreaming(ctx, req)
-    if err != nil {
-        return nil, err
-    }
-
-    for {
-        update, err := stream.Recv()
-        if err == io.EOF {
-            break
-        }
-        if err != nil {
-            return nil, err
-        }
-
-        switch update.Type {
-        case pb.TestBattleUpdate_AI_DECISION:
-            fmt.Printf("  Round %d: Player %d chose %s\n",
-                update.CurrentRound, update.PlayerId, update.CommandType)
-        case pb.TestBattleUpdate_BATTLE_END:
-            return update.FinalResult, nil
-        }
-    }
-}
-```
-
-**Estimated effort**: 2 days
-
-### Phase 3: Unity Client Integration (2 weeks)
-
-**Goal**: Enable Unity clients to watch AI battles in real-time
-
-#### 3.1 Route Through Eagle
-
-Extend Eagle server to accept test battle requests and create Shardok games:
-
-```scala
-// In Eagle server
-def startTestBattle(request: TestBattleRequest): Unit = {
-  // 1. Create game state in Eagle
-  // 2. Send to Shardok via existing protocol
-  // 3. Mark both players as AI
-  // 4. Allow Unity clients to connect and watch
-}
-```
-
-**Benefits**:
-- Tests complete production stack (Eagle + Shardok)
-- Unity clients can connect as spectators
-- Most realistic integration test possible
-
-**Estimated effort**: 1 week
-
-#### 3.2 Unity Spectator Mode
-
-Add spectator mode to Unity client:
-
-```csharp
-// In Unity client
-public class AIBattleSpectator : MonoBehaviour {
-    public void ConnectToBattle(string gameId) {
-        // Connect to Eagle as spectator
-        // Receive battle updates
-        // Render on screen
-    }
-}
-```
-
-**Estimated effort**: 1 week
-
-## Usage Examples
-
-### Basic Effectiveness Testing
-
-```bash
-# Start Shardok server
-bazel run //src/main/cpp/net/eagle0/shardok:shardok-server
-
-# Run effectiveness tests
-bazel run //src/main/go/net/eagle0/shardok/ai_effectiveness_runner:ai_effectiveness_runner -- \
-    --server=localhost:50051 \
-    --scenarios=test_scenarios.json \
-    --iterations=20
-
-# Output:
-# === Testing Scenario: mcts_vs_id_balanced ===
-#   Battle 1/20: Winner=0, Rounds=47, Survivors=3
-#   Battle 2/20: Winner=1, Rounds=52, Survivors=2
-#   ...
-#
-# === Summary ===
-# Scenario: mcts_vs_id_balanced
-#   MCTS (attacker) wins: 15/20 (75%)
-#   Iterative Deepening (defender) wins: 5/20 (25%)
-#   Average rounds: 48.3
-#   Average survivors: 2.8
-```
-
-### Comparing AI Improvements
-
-```bash
-# Before optimization
-git checkout main
-bazel run //src/main/go/net/eagle0/shardok/ai_effectiveness_runner:ai_effectiveness_runner -- \
-    --scenarios=regression_suite.json --iterations=50 > baseline_results.txt
-
-# After optimization
-git checkout my-ai-improvement
-bazel run //src/main/go/net/eagle0/shardok/ai_effectiveness_runner:ai_effectiveness_runner -- \
-    --scenarios=regression_suite.json --iterations=50 > improved_results.txt
-
-# Compare
-diff baseline_results.txt improved_results.txt
-# Shows: MCTS win rate improved from 60% to 75%! ✅
-```
-
-### Watching Battles in Unity
-
-```bash
-# Terminal 1: Eagle server
-bazel run //src/main/scala/net/eagle0/eagle:eagle_server
-
-# Terminal 2: Shardok server
-bazel run //src/main/cpp/net/eagle0/shardok:shardok-server
-
-# Terminal 3: Start test battle
-bazel run //src/main/go/net/eagle0/shardok/ai_effectiveness_runner:ai_effectiveness_runner -- \
-    --server=localhost:40032 \
-    --scenarios=interesting_scenario.json \
-    --stream
-
-# Terminal 4: Unity client
-# Open Unity, connect as spectator to watch battle unfold
-```
-
-## Success Metrics
-
-### Immediate (Phase 1)
-- ✅ Can run 20+ battle scenarios against server
-- ✅ Measures win rates, rounds, survivors
-- ✅ Tests real production Shardok server code paths
-- ✅ Reproducible results
-
-### Medium-term (Phase 2)
-- ✅ Streaming battle updates work
-- ✅ Can capture and replay interesting battles
-- ✅ Logs include both effectiveness metrics and proxy metrics
-
-### Long-term (Phase 3)
-- ✅ Unity clients can watch AI battles
-- ✅ Tests complete Eagle + Shardok stack
-- ✅ Community can watch AI improvements
-
-## Migration Strategy
-
-### Keep Existing Tools
-
-**AI Battle Simulator** (in-process, keep for development):
-- Fast iteration during development
-- Easy debugging (direct access to internals)
-- Use case: "Does this change work at all?"
-
-**AI Effectiveness Runner** (server-based, new primary tool):
-- Tests production code paths
-- Measures real effectiveness
-- Use case: "Is this change actually better?"
-
-### Deprecate Performance Runner
-
-The current `ai_performance_runner` measures proxy metrics. Recommend:
-1. Keep it temporarily for comparison
-2. After Phase 2 (streaming + AI metrics), deprecate it
-3. Streaming effectiveness runner includes proxy metrics as secondary data
-
-## Open Questions
-
-1. **Server Resource Management**: Should we limit concurrent test battles on the server?
-   - Proposal: Add `--max-concurrent-battles` flag to Go client
-
-2. **Scenario Versioning**: How do we ensure scenarios remain valid as game evolves?
-   - Proposal: Version scenarios in git, validate against server on load
-
-3. **Metrics Storage**: Should we store historical effectiveness metrics?
-   - Proposal: Phase 4 (future) - add database for tracking AI effectiveness over time
-
-4. **Randomness Control**: How do we handle dice roll randomness in battles?
-   - Current: Protocol supports `roll` override, but battles have many rolls
-   - Proposal: Add `random_seed` to TestBattleRequest for reproducibility
-
-## Timeline
-
-- **Phase 1**: 1 week (core framework)
-- **Phase 2**: 1 week (streaming + observability)
-- **Phase 3**: 2 weeks (Unity integration)
-
-**Total**: 4 weeks for complete vision
-
-**Minimal viable**: Phase 1 only (1 week) provides immediate value
-
-## Next Steps
-
-1. Review and approve this proposal
-2. Merge current PR (#4518) - AI testing infrastructure refactor
-3. Begin Phase 1 implementation:
-   - Protocol extensions (1 day)
-   - Server implementation (2 days)
-   - Go client (2 days)
-   - Test scenarios (1 day)
-4. Validate with initial test runs
-5. Iterate based on findings
-6. Plan Phase 2 based on Phase 1 learnings
-
-## Conclusion
-
-This proposal shifts AI testing from measuring **proxies** (search depth) to measuring **reality** (win rates). By running battles through the production server, we:
-
-- Test what matters: actual intelligence
-- Validate real code paths: gRPC, threading, server logic
-- Enable future capabilities: Unity viewing, distributed testing
-- Measure improvements objectively: win rate changes
-
-The infrastructure mostly exists - ShardokGameController already handles AI vs AI battles. We just need to expose it via protocol and build a client to drive it.
-
-**Recommendation**: Approve and implement Phase 1 (1 week) to immediately gain better AI effectiveness measurement.

src/main/cpp/net/eagle0/shardok/ai_testing_common/AIClientFactory.cpp

@@ -1,34 +0,0 @@
-//
-// AIClientFactory Implementation
-//
-
-#include "AIClientFactory.hpp"
-
-#include "src/main/cpp/net/eagle0/common/mcts/abstract/MCTSTypes.hpp"
-#include "src/main/cpp/net/eagle0/shardok/ai/ShardokAIClient.hpp"
-
-namespace shardok {
-namespace ai_testing_common {
-
-auto AIClientFactory::Create(
-        PlayerId playerId,
-        bool isDefender,
-        const net::eagle0::shardok::storage::fb::HexMap* hexMap,
-        const SettingsGetter& settings,
-        AIAlgorithmType algorithmType,
-        ScoringCalculatorType scoringType) -> std::unique_ptr<ShardokAIClient> {
-    // Use default MCTS configuration
-    mcts::MCTSConfig mctsConfig{};
-
-    return std::make_unique<ShardokAIClient>(
-            playerId,
-            isDefender,
-            hexMap,
-            settings,
-            algorithmType,
-            scoringType,
-            mctsConfig);
-}
-
-}  // namespace ai_testing_common
-}  // namespace shardok

src/main/cpp/net/eagle0/shardok/ai_testing_common/AIClientFactory.hpp

@@ -1,67 +0,0 @@
-//
-// AIClientFactory - Unified factory for creating ShardokAIClient instances
-// Used by both AI Performance Runner and AI Battle Simulator
-//
-
-#ifndef EAGLE0_AI_CLIENT_FACTORY_HPP
-#define EAGLE0_AI_CLIENT_FACTORY_HPP
-
-#include <memory>
-
-#include "src/main/cpp/net/eagle0/shardok/ai/AIConfig.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokCTypes.h"
-#include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
-
-// Forward declarations for flatbuffer types
-namespace net {
-namespace eagle0 {
-namespace shardok {
-namespace storage {
-namespace fb {
-struct HexMap;
-}
-}  // namespace storage
-}  // namespace shardok
-}  // namespace eagle0
-}  // namespace net
-
-namespace shardok {
-
-// Forward declarations
-class ShardokAIClient;
-
-namespace ai_testing_common {
-
-/**
- * Factory class for creating ShardokAIClient instances with standard configuration.
- *
- * This centralizes the AI client creation logic that was duplicated
- * between AI Performance Runner and AI Battle Simulator.
- */
-class AIClientFactory {
-public:
-    /**
-     * Create an AI client for a player.
-     *
-     * @param playerId The player ID for this AI
-     * @param isDefender True if this AI is the defender
-     * @param hexMap The game's hex map
-     * @param settings The game settings to use
-     * @param algorithmType The AI algorithm to use (MCTS or ITERATIVE_DEEPENING)
-     * @param scoringType The scoring calculator type (defaults to STANDARD)
-     * @return Unique pointer to created ShardokAIClient
-     */
-    static auto Create(
-            PlayerId playerId,
-            bool isDefender,
-            const net::eagle0::shardok::storage::fb::HexMap* hexMap,
-            const SettingsGetter& settings,
-            AIAlgorithmType algorithmType = AIAlgorithmType::ITERATIVE_DEEPENING,
-            ScoringCalculatorType scoringType = ScoringCalculatorType::STANDARD)
-            -> std::unique_ptr<ShardokAIClient>;
-};
-
-}  // namespace ai_testing_common
-}  // namespace shardok
-
-#endif  // EAGLE0_AI_CLIENT_FACTORY_HPP

src/main/cpp/net/eagle0/shardok/ai_testing_common/BUILD.bazel

@@ -1,58 +0,0 @@
-load("@rules_cc//cc:defs.bzl", "cc_library")
-
-cc_library(
-    name = "game_settings_factory",
-    srcs = ["GameSettingsFactory.cpp"],
-    hdrs = ["GameSettingsFactory.hpp"],
-    visibility = ["//visibility:public"],
-    deps = [
-        "//src/main/cpp/net/eagle0/common:filesystem_utils",
-        "//src/main/cpp/net/eagle0/common:tsv_parser",
-        "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
-        "//src/main/cpp/net/eagle0/shardok/util:battalion_type_registrar",
-    ],
-)
-
-cc_library(
-    name = "ai_client_factory",
-    srcs = ["AIClientFactory.cpp"],
-    hdrs = ["AIClientFactory.hpp"],
-    visibility = ["//visibility:public"],
-    deps = [
-        "//src/main/cpp/net/eagle0/shardok/ai:shardok_ai_client",
-        "//src/main/cpp/net/eagle0/shardok/library:shardok_c_types",
-        "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
-        "//src/main/flatbuffer/net/eagle0/shardok/storage:hex_map_cc_fbs",
-    ],
-)
-
-cc_library(
-    name = "test_game_state_builder",
-    srcs = ["TestGameStateBuilder.cpp"],
-    hdrs = ["TestGameStateBuilder.hpp"],
-    visibility = ["//visibility:public"],
-    deps = [
-        "//src/main/cpp/net/eagle0/common:filesystem_utils",
-        "//src/main/cpp/net/eagle0/shardok/library:game_state_w",
-        "//src/main/cpp/net/eagle0/shardok/library:shardok_c_types",
-        "//src/main/cpp/net/eagle0/shardok/library/fb_helpers:game_state_helpers",
-        "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
-        "//src/main/cpp/net/eagle0/shardok/util:map_loader",
-        "//src/main/flatbuffer/net/eagle0/shardok/storage:unit_fbs",
-        "//src/main/protobuf/net/eagle0/shardok/common:player_info_proto",
-    ],
-)
-
-cc_library(
-    name = "game_phase_runner",
-    srcs = ["GamePhaseRunner.cpp"],
-    hdrs = ["GamePhaseRunner.hpp"],
-    visibility = ["//visibility:public"],
-    deps = [
-        "//src/main/cpp/net/eagle0/shardok/ai:shardok_ai_client",
-        "//src/main/cpp/net/eagle0/shardok/library:engine",
-        "//src/main/cpp/net/eagle0/shardok/library:game_state_w",
-        "//src/main/cpp/net/eagle0/shardok/library:shardok_c_types",
-        "//src/main/flatbuffer/net/eagle0/shardok/storage:game_state_cc_fbs",
-    ],
-)

src/main/cpp/net/eagle0/shardok/ai_testing_common/GamePhaseRunner.cpp

@@ -1,62 +0,0 @@
-//
-// GamePhaseRunner Implementation
-//
-
-#include "GamePhaseRunner.hpp"
-
-#include "src/main/cpp/net/eagle0/shardok/ai/ShardokAIClient.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokEngine.hpp"
-#include "src/main/flatbuffer/net/eagle0/shardok/storage/game_state.hpp"
-
-namespace shardok {
-namespace ai_testing_common {
-
-auto GamePhaseRunner::RunSetupPhase(
-        ShardokEngine& engine,
-        const std::function<ShardokAIClient&(PlayerId)>& getAI) -> PhaseResult {
-    PhaseResult result;
-
-    while (engine.GetCurrentGameState()->status()->state() ==
-           net::eagle0::shardok::storage::fb::GameStatus_::State_SET_UP) {
-        auto currentState = engine.GetCurrentGameState();
-        PlayerId currentPlayer = currentState->current_player();
-
-        auto availableCommands = engine.GetAvailableCommandProtos(currentPlayer, false);
-
-        if (availableCommands.empty()) { break; }
-
-        // Get AI for current player and make decision
-        ShardokAIClient& activeAI = getAI(currentPlayer);
-        auto choiceResults = activeAI.ChooseCommandIndex(engine);
-
-        // Apply command
-        engine.PostCommand(currentPlayer, choiceResults.chosenIndex);
-        result.commandsExecuted++;
-
-        // Check if game ended unexpectedly
-        if (engine.GameIsOver()) {
-            result.gameEnded = true;
-            break;
-        }
-    }
-
-    return result;
-}
-
-auto GamePhaseRunner::RunSingleTurn(ShardokEngine& engine, PlayerId playerId, ShardokAIClient& ai)
-        -> bool {
-    auto availableCommands = engine.GetAvailableCommandProtos(playerId, false);
-
-    if (availableCommands.empty()) { return false; }
-
-    // Get AI decision
-    auto choiceResults = ai.ChooseCommandIndex(engine);
-
-    // Apply command
-    engine.PostCommand(playerId, choiceResults.chosenIndex);
-
-    return true;
-}
-
-}  // namespace ai_testing_common
-}  // namespace shardok

src/main/cpp/net/eagle0/shardok/ai_testing_common/GamePhaseRunner.hpp

@@ -1,64 +0,0 @@
-//
-// GamePhaseRunner - Unified logic for running game phases with AI decision-making
-// Used by both AI Performance Runner and AI Battle Simulator
-//
-
-#ifndef EAGLE0_GAME_PHASE_RUNNER_HPP
-#define EAGLE0_GAME_PHASE_RUNNER_HPP
-
-#include <functional>
-
-#include "src/main/cpp/net/eagle0/shardok/library/GameStateW.hpp"
-#include "src/main/cpp/net/eagle0/shardok/library/ShardokCTypes.h"
-
-namespace shardok {
-
-// Forward declarations
-class ShardokEngine;
-class ShardokAIClient;
-
-namespace ai_testing_common {
-
-/**
- * Result of running a game phase.
- */
-struct PhaseResult {
-    int commandsExecuted = 0;
-    bool gameEnded = false;
-};
-
-/**
- * Helper class for running setup and battle phases with AI decision-making.
- *
- * This centralizes the game phase execution logic that was duplicated
- * between AI Performance Runner and AI Battle Simulator.
- */
-class GamePhaseRunner {
-public:
-    /**
-     * Run the setup phase where AIs place their units.
-     *
-     * @param engine The game engine
-     * @param getAI Function to get the AI client for a given player ID
-     * @return PhaseResult with number of commands executed and whether game ended
-     */
-    static auto RunSetupPhase(
-            ShardokEngine& engine,
-            const std::function<ShardokAIClient&(PlayerId)>& getAI) -> PhaseResult;
-
-    /**
-     * Run one turn of a game phase (either for AI testing or full battle).
-     *
-     * @param engine The game engine
-     * @param playerId The player whose turn it is
-     * @param ai The AI client to use for decision-making
-     * @return True if the turn was executed successfully, false if no commands available
-     */
-    static auto RunSingleTurn(ShardokEngine& engine, PlayerId playerId, ShardokAIClient& ai)
-            -> bool;
-};
-
-}  // namespace ai_testing_common
-}  // namespace shardok
-
-#endif  // EAGLE0_GAME_PHASE_RUNNER_HPP

src/main/cpp/net/eagle0/shardok/ai_testing_common/GameSettingsFactory.cpp

@@ -1,35 +0,0 @@
-//
-// GameSettingsFactory Implementation
-//
-
-#include "GameSettingsFactory.hpp"
-
-#include "src/main/cpp/net/eagle0/common/FilesystemUtils.hpp"
-#include "src/main/cpp/net/eagle0/common/TsvParser.hpp"
-#include "src/main/cpp/net/eagle0/common/byte_vector.hpp"
-#include "src/main/cpp/net/eagle0/shardok/util/BattalionTypeRegistrar.hpp"
-
-namespace shardok {
-namespace ai_testing_common {
-
-auto GameSettingsFactory::CreateDefault() -> GameSettingsSPtr {
-    auto settings = std::make_shared<GameSettings>();
-    auto setter = settings->GetSetter();
-
-    // Load battalion types
-    BattalionTypeRegistrar::RegisterBattalionTypes(setter);
-
-    // Load settings from settings.tsv file
-    const std::string settingsPath =
-            FilesystemUtils::StaticShardokFilesDirectory() + "settings.tsv";
-    const std::string settingsTsv = std::string(byte_vector::FromPath(settingsPath));
-
-    TsvParser parser;
-    const auto valuesAndTypes = parser.ParseColumnEntryTsv(settingsTsv);
-    setter.SetFromTypesAndValues(valuesAndTypes[1], valuesAndTypes[0]);
-
-    return settings;
-}
-
-}  // namespace ai_testing_common
-}  // namespace shardok

src/main/cpp/net/eagle0/shardok/ai_testing_common/GameSettingsFactory.hpp

@@ -1,39 +0,0 @@
-//
-// GameSettingsFactory - Unified factory for creating GameSettings instances
-// Used by both AI Performance Runner and AI Battle Simulator
-//
-
-#ifndef EAGLE0_GAME_SETTINGS_FACTORY_HPP
-#define EAGLE0_GAME_SETTINGS_FACTORY_HPP
-
-#include <memory>
-
-#include "src/main/cpp/net/eagle0/shardok/library/settings/GameSettings.hpp"
-
-namespace shardok {
-namespace ai_testing_common {
-
-/**
- * Factory class for creating GameSettings instances with standard configuration.
- *
- * This centralizes the game settings initialization logic that was duplicated
- * between AI Performance Runner and AI Battle Simulator.
- */
-class GameSettingsFactory {
-public:
-    /**
-     * Create a GameSettings instance with default configuration.
-     *
-     * This includes:
-     * - Registering battalion types
-     * - Loading settings from settings.tsv
-     *
-     * @return Shared pointer to initialized GameSettings
-     */
-    static auto CreateDefault() -> GameSettingsSPtr;
-};
-
-}  // namespace ai_testing_common
-}  // namespace shardok
-
-#endif  // EAGLE0_GAME_SETTINGS_FACTORY_HPP

src/main/cpp/net/eagle0/shardok/ai_testing_common/REFACTORING_SUMMARY.md

@@ -1,201 +0,0 @@
-# AI Testing Tools Refactoring Summary
-
-## Overview
-
-Successfully refactored AI Performance Runner and AI Battle Simulator to eliminate code duplication by extracting common functionality into a shared `ai_testing_common` library.
-
-## Motivation
-
-Both tools contained ~100+ lines of identical code for:
-- Initializing game settings from TSV files
-- Creating AI client instances
-- Running setup/battle phases with AI decision-making
-
-This duplication made maintenance difficult and risked inconsistencies between the tools.
-
-## Changes Made
-
-### New Shared Library: `ai_testing_common`
-
-Created three reusable components:
-
-#### 1. **GameSettingsFactory** (`GameSettingsFactory.hpp/cpp`)
-- **Purpose**: Unified game settings initialization
-- **Eliminates**: Duplicate TSV loading and battalion type registration
-- **Usage**:
-  ```cpp
-  auto settings = ai_testing_common::GameSettingsFactory::CreateDefault();
-  ```
-
-#### 2. **AIClientFactory** (`AIClientFactory.hpp/cpp`)
-- **Purpose**: Consistent AI client instantiation
-- **Eliminates**: Duplicate ShardokAIClient constructor calls
-- **Features**: Provides sensible defaults for ScoringCalculatorType and MCTSConfig
-- **Usage**:
-  ```cpp
-  auto aiClient = ai_testing_common::AIClientFactory::Create(
-      playerId, isDefender, hexMap, settings, AIAlgorithmType::MCTS);
-  ```
-
-#### 3. **GamePhaseRunner** (`GamePhaseRunner.hpp/cpp`)
-- **Purpose**: Runs setup and battle phases with AI decision-making
-- **Eliminates**: Duplicate game loop logic
-- **Usage**:
-  ```cpp
-  auto getAI = [&](PlayerId pid) -> ShardokAIClient& {
-      return (pid == ATTACKER_ID) ? attackerAI : defenderAI;
-  };
-  auto result = ai_testing_common::GamePhaseRunner::RunSetupPhase(engine, getAI);
-  ```
-
-### Refactored Tools
-
-#### AI Performance Runner
-**Files Modified**:
-- `PerformanceTestGameStateBuilder.cpp`: Now uses `GameSettingsFactory`
-- `AIPerformanceRunner.cpp`: Now uses `AIClientFactory` and `GamePhaseRunner`
-- `BUILD.bazel`: Added dependencies on shared components
-
-**Before** (duplicated code):
-```cpp
-auto settings = std::make_shared<GameSettings>();
-auto setter = settings->GetSetter();
-BattalionTypeRegistrar::RegisterBattalionTypes(setter);
-TsvParser parser;
-const string settingsTsv = string(byte_vector::FromPath(settingsPath));
-const auto valuesAndTypes = parser.ParseColumnEntryTsv(settingsTsv);
-setter.SetFromTypesAndValues(valuesAndTypes[1], valuesAndTypes[0]);
-```
-
-**After** (shared component):
-```cpp
-auto settings = ai_testing_common::GameSettingsFactory::CreateDefault();
-```
-
-#### AI Battle Simulator
-**Files Modified**:
-- `AiBattleSimulator.cpp`: Now uses all three shared components
-- `BUILD.bazel`: Added dependencies on shared components
-
-**Code Reduction**: ~60 lines of duplicate initialization code eliminated
-
-### Documentation
-
-Created comprehensive guide: `AI_TESTING_GUIDE.md`
-- Complete usage instructions for both tools
-- Command-line arguments and configuration formats
-- Example workflows for performance testing and battle simulation
-- Troubleshooting common issues
-- Best practices
-
-## Benefits
-
-### 1. **Eliminated Duplication**
-- ~100 lines of identical code consolidated
-- Single source of truth for common operations
-
-### 2. **Improved Maintainability**
-- Changes to settings loading, AI creation, or setup phases now made once
-- Reduced risk of inconsistencies between tools
-
-### 3. **Consistent Behavior**
-- Both tools use exactly the same logic for common operations
-- Ensures apples-to-apples comparison of AI performance
-
-### 4. **Better Testability**
-- Shared components can be unit tested independently
-- Easier to verify correctness once rather than twice
-
-### 5. **Enhanced Documentation**
-- Comprehensive guide for both tools in one place
-- Clear examples and workflows
-
-## Build Status
-
-✅ Both tools build successfully
-✅ All dependencies resolved correctly
-✅ Tools run and display help correctly
-
-## Technical Details
-
-### Dependencies Added
-
-**ai_testing_common components** depend on:
-- `shardok/ai:shardok_ai_client`
-- `shardok/library:game_state_w`
-- `shardok/library:engine`
-- `shardok/library/settings:game_settings`
-- `common/mcts/abstract:mcts_types` (transitive through shardok_ai_client)
-
-### Backward Compatibility
-
-Both tools maintain their existing command-line interfaces and functionality:
-- AI Performance Runner: `--map`, `--turns`, `--defender`, `--verbose`
-- AI Battle Simulator: `--config`, `--generate-config`
-
-## Future Enhancements
-
-Potential improvements identified during refactoring:
-
-1. **Unified Configuration Format**
-   - Consider merging JSON and command-line config approaches
-   - Would enable more complex test scenarios from config files
-
-2. **Shared Test Utilities**
-   - Extract common test scenario builders
-   - Reusable map/unit configuration helpers
-
-3. **Performance Metrics Library**
-   - Standardize metrics collection across both tools
-   - Enable direct comparison of results
-
-## Files Created
-
-```
-src/main/cpp/net/eagle0/shardok/ai_testing_common/
-├── BUILD.bazel
-├── GameSettingsFactory.hpp
-├── GameSettingsFactory.cpp
-├── AIClientFactory.hpp
-├── AIClientFactory.cpp
-├── GamePhaseRunner.hpp
-├── GamePhaseRunner.cpp
-└── REFACTORING_SUMMARY.md (this file)
-
-src/main/cpp/net/eagle0/shardok/ai_testing/
-└── AI_TESTING_GUIDE.md
-```
-
-## Files Modified
-
-```
-src/main/cpp/net/eagle0/shardok/ai_performance_runner/
-├── AIPerformanceRunner.cpp
-├── PerformanceTestGameStateBuilder.cpp
-└── BUILD.bazel
-
-src/main/cpp/net/eagle0/shardok/ai_battle_simulator/
-├── AiBattleSimulator.cpp
-└── BUILD.bazel
-```
-
-## Testing
-
-Verified functionality:
-- ✅ Both tools build without errors
-- ✅ AI Performance Runner displays help and accepts arguments
-- ✅ AI Battle Simulator maintains JSON config workflow
-- ✅ Shared components compile and link correctly
-
-## Conclusion
-
-The refactoring successfully achieved its goals:
-1. ✅ Eliminated code duplication between the two AI testing tools
-2. ✅ Improved maintainability through shared components
-3. ✅ Maintained backward compatibility
-4. ✅ Added comprehensive documentation
-5. ✅ Built successfully with all tests passing
-
-Both tools now share common infrastructure while retaining their distinct purposes:
-- **AI Performance Runner**: Measures AI decision-making quality over specific turns
-- **AI Battle Simulator**: Tests AI effectiveness through complete battle outcomes

src/main/cpp/net/eagle0/shardok/controller/ShardokGameController.cpp

@@ -69,11 +69,9 @@ vector<shared_ptr<ShardokAIClient>> ShardokGameController::MakeAIClients(
     vector<shared_ptr<ShardokAIClient>> aic;
 
     mcts::MCTSConfig mctsConfig;
-    mctsConfig.backpropagationPolicy = mcts::MCTSBackpropagationPolicy::MINIMAX;
-    mctsConfig.maxPlayerFlips = 1;
-    mctsConfig.maxSimulationFlips = 1;
+    mctsConfig.backpropagationPolicy = mcts::MCTSBackpropagationPolicy::AVERAGING;
+    mctsConfig.maxPlayerFlips = 0;
     mctsConfig.simulationPolicy = mcts::MCTSSimulationPolicy::WEIGHTED_HEURISTIC;
-
     for (const auto &pi : e->GetPlayerInfos()) {
         if (pi.is_ai()) {
             auto newClient = std::make_shared<ShardokAIClient>(
@@ -81,7 +79,7 @@ vector<shared_ptr<ShardokAIClient>> ShardokGameController::MakeAIClients(
                     pi.is_defender(),
                     e->GetCurrentGameState()->hex_map(),
                     e->GetGameSettings()->GetGetter(),
-                    AIAlgorithmType::ITERATIVE_DEEPENING,
+                    AIAlgorithmType::MCTS,
                     ScoringCalculatorType::MCTS_OPTIMIZED,
                     mctsConfig);
 

src/main/cpp/net/eagle0/shardok/library/AvailableCommandsFactory.cpp

@@ -189,7 +189,7 @@ auto AvailableCommandsFactoryImpl::GetAvailableCommands(
     if (!std::ranges::any_of(commands, [](const CommandSPtr &command) {
             return command->IsRequiredToEndTurn();
         })) {
-        commands.push_back(std::make_shared<EndTurnCommand>(playerId, settings));
+        commands.push_back(std::make_shared<EndTurnCommand>(playerId, gameState, settings));
     }
 
     // If we want follow-ups, make a copy of what this user believes to be the state of the game

src/main/cpp/net/eagle0/shardok/library/BUILD.bazel

@@ -150,8 +150,12 @@ cc_library(
     srcs = [],
     hdrs = ["ShardokCommand.hpp"],
     copts = COPTS,
-    visibility = ["//src/main/cpp/net/eagle0/shardok/library:__subpackages__"],
+    visibility = [
+        "//src/main/cpp/net/eagle0/shardok/ai/mcts/adapters:__pkg__",
+        "//src/main/cpp/net/eagle0/shardok/library:__subpackages__",
+    ],
     deps = [
+        ":action_cost",
         ":shardok_action",
         ":shardok_c_types",
         "//src/main/protobuf/net/eagle0/shardok/api:command_descriptor_cc_proto",

src/main/cpp/net/eagle0/shardok/library/BattalionType.cpp

@@ -55,19 +55,6 @@ std::shared_ptr<const BattalionType> BattalionType::NewBattalionTypeFromMap(
                 ActionPoints(IntForKey(map, "MinimumCostToEnterBridge")),
                 actionCostForKey(map, "CostToEnterCastle"),
                 DoubleForKey(map, "SnowPenalty"),
-                {
-                        // Terrain cost lookup table indexed by flatbuffer terrain enum
-                        IMPOSSIBLE_ACTION_COST,                        // 0: UNKNOWN (error case)
-                        IMPOSSIBLE_ACTION_COST,                        // 1: NONE
-                        actionCostForKey(map, "CostToEnterPlains"),    // 2: PLAINS
-                        actionCostForKey(map, "CostToEnterHill"),      // 3: HILL
-                        actionCostForKey(map, "CostToEnterForest"),    // 4: FOREST
-                        actionCostForKey(map, "CostToEnterMountain"),  // 5: MOUNTAIN
-                        actionCostForKey(map, "CostToEnterSwamp"),     // 6: SWAMP
-                        actionCostForKey(map, "CostToEnterCity"),      // 7: CITY
-                        actionCostForKey(map, "CostToEnterOcean"),     // 8: STILL_WATER
-                        actionCostForKey(map, "CostToEnterOcean")      // 9: RIVER
-                },
                 DoubleForKey(map, "ResistanceMultiplierForPlains"),
                 DoubleForKey(map, "ResistanceMultiplierForHill"),
                 DoubleForKey(map, "ResistanceMultiplierForForest"),

src/main/cpp/net/eagle0/shardok/library/BattalionType.hpp

@@ -9,7 +9,6 @@
 #ifndef __eagle0__BattalionType__
 #define __eagle0__BattalionType__
 
-#include <array>
 #include <cstdint>
 #include <string>
 
@@ -67,9 +66,6 @@ struct BattalionType {
 
     const double snowPenalty;
 
-    // Lookup table for O(1) terrain cost access, indexed by flatbuffer terrain type enum
-    const std::array<ActionCost, 10> terrainCostLookup;
-
     const double damageTakenMultiplierForPlains;
     const double damageTakenMultiplierForHill;
     const double damageTakenMultiplierForForest;
@@ -225,20 +221,47 @@ struct BattalionType {
 
     [[nodiscard]] auto GetCostToEnterTerrainType(const TerrainProto::Type terrainType) const
             -> ActionCost {
-        // Proto and flatbuffer enums have matching values, convert and use flatbuffer version
-        const auto fbType =
-                static_cast<net::eagle0::shardok::storage::fb::Terrain_::Type>(terrainType);
-        return GetCostToEnterTerrainType(fbType);
+        switch (terrainType) {
+            case net::eagle0::shardok::common::Terrain_Type_UNKNOWN:
+            case net::eagle0::shardok::common::
+                    Terrain_Type_Terrain_Type_INT_MIN_SENTINEL_DO_NOT_USE_:
+            case net::eagle0::shardok::common::
+                    Terrain_Type_Terrain_Type_INT_MAX_SENTINEL_DO_NOT_USE_:
+                throw ShardokInternalErrorException("Unknown terrain type");
+            case net::eagle0::shardok::common::Terrain_Type_NONE: return IMPOSSIBLE_ACTION_COST;
+            case net::eagle0::shardok::common::Terrain_Type_PLAINS: return costToEnterPlains;
+            case net::eagle0::shardok::common::Terrain_Type_HILL: return costToEnterHill;
+            case net::eagle0::shardok::common::Terrain_Type_FOREST: return costToEnterForest;
+            case net::eagle0::shardok::common::Terrain_Type_MOUNTAIN: return costToEnterMountain;
+            case net::eagle0::shardok::common::Terrain_Type_SWAMP: return costToEnterSwamp;
+            case net::eagle0::shardok::common::Terrain_Type_CITY: return costToEnterCity;
+            case net::eagle0::shardok::common::Terrain_Type_STILL_WATER:
+            case net::eagle0::shardok::common::Terrain_Type_RIVER: return costToEnterWater;
+        }
+
+        throw ShardokInternalErrorException("Unknown terrain type");
     }
 
     [[nodiscard]] auto GetCostToEnterTerrainType(
             const net::eagle0::shardok::storage::fb::Terrain_::Type terrainType) const
             -> ActionCost {
-        const auto typeValue = static_cast<size_t>(terrainType);
-        if (typeValue >= terrainCostLookup.size() || typeValue == 0) {
-            throw ShardokInternalErrorException("Unknown terrain type");
+        switch (terrainType) {
+            case net::eagle0::shardok::storage::fb::Terrain_::Type_UNKNOWN:
+                throw ShardokInternalErrorException("Unknown terrain type");
+            case net::eagle0::shardok::storage::fb::Terrain_::Type_NONE:
+                return IMPOSSIBLE_ACTION_COST;
+            case net::eagle0::shardok::storage::fb::Terrain_::Type_PLAINS: return costToEnterPlains;
+            case net::eagle0::shardok::storage::fb::Terrain_::Type_HILL: return costToEnterHill;
+            case net::eagle0::shardok::storage::fb::Terrain_::Type_FOREST: return costToEnterForest;
+            case net::eagle0::shardok::storage::fb::Terrain_::Type_MOUNTAIN:
+                return costToEnterMountain;
+            case net::eagle0::shardok::storage::fb::Terrain_::Type_SWAMP: return costToEnterSwamp;
+            case net::eagle0::shardok::storage::fb::Terrain_::Type_CITY: return costToEnterCity;
+            case net::eagle0::shardok::storage::fb::Terrain_::Type_STILL_WATER:
+            case net::eagle0::shardok::storage::fb::Terrain_::Type_RIVER: return costToEnterWater;
         }
-        return terrainCostLookup[typeValue];
+
+        throw ShardokInternalErrorException("Unknown terrain type");
     }
 
     [[nodiscard]] auto AlwaysHiddenInTerrain(const Terrain *terrain) const -> bool {

src/main/cpp/net/eagle0/shardok/library/FireUtils.cpp

@@ -8,8 +8,6 @@
 
 #include "FireUtils.hpp"
 
-#include <algorithm>
-
 #include "src/main/cpp/net/eagle0/shardok/library/map/TileModifier.hpp"
 
 namespace shardok {
@@ -73,13 +71,10 @@ auto GetFireDamage(
         const double openEndedPercentileRoll1,
         const double openEndedPercentileRoll2) -> CombatDamage {
     double randomSwing = 1.0 + (2 * openEndedPercentileRoll1 - 100.0) * RANDOMNESS_FACTOR / 100.0;
-    // Clamp damage to minimum 0 to prevent negative damage from extreme open-ended rolls.
-    // Open-ended percentile rolls can theoretically go as low as -475 (with max roll depth).
-    const double basicDamage = std::max(0.0, BASE_FIRE_DAMAGE_PER_TROOP * randomSwing * troops);
+    const double basicDamage = BASE_FIRE_DAMAGE_PER_TROOP * randomSwing * troops;
 
     randomSwing = 1.0 + (2 * openEndedPercentileRoll2 - 100.0) * RANDOMNESS_FACTOR / 100.0;
-    const double penetratingDamage =
-            std::max(0.0, BASE_PENETRATING_FIRE_DAMAGE_PER_TROOP * randomSwing * troops);
+    const double penetratingDamage = BASE_PENETRATING_FIRE_DAMAGE_PER_TROOP * randomSwing * troops;
 
     return CombatDamage::Builder()
             .SetFire(basicDamage)

src/main/cpp/net/eagle0/shardok/library/ShardokCommand.hpp

@@ -8,6 +8,7 @@
 #include <memory>
 #include <vector>
 
+#include "ActionCost.hpp"
 #include "ShardokAction.hpp"
 #include "ShardokCTypes.h"
 #include "src/main/protobuf/net/eagle0/shardok/api/command_descriptor.pb.h"
@@ -45,13 +46,6 @@ public:
     [[nodiscard]] virtual auto HasOdds() const -> bool { return false; }
     [[nodiscard]] virtual auto GetOddsPercentile() const -> int32_t { return 0; }
 
-    // Returns -1 if command has no actor unit
-    [[nodiscard]] virtual int GetActorUnitId() const { return -1; }
-
-    // Returns -1 if command has no target coordinates
-    [[nodiscard]] virtual MapIndex GetTargetRow() const { return -1; }
-    [[nodiscard]] virtual MapIndex GetTargetColumn() const { return -1; }
-
     virtual void AddFollowUpCommandTypes(const std::unordered_set<CommandType>& /*newTypes*/) {
         throw ShardokInternalErrorException("Can't add follow up commands to this type");
     }

src/main/cpp/net/eagle0/shardok/library/action_factories/MeteorCastActionFactory.cpp

@@ -16,9 +16,10 @@ namespace shardok {
 
 MeteorCastActionFactory::MeteorCastActionFactory(const SettingsGetter &getter) : settings(getter) {}
 
-auto MeteorCastActionFactory::MakeMeteorCastAction(const vector<UnitId> &actors) const
-        -> ActionSPtr {
-    return std::make_shared<MeteorCastAction>(actors, settings);
+auto MeteorCastActionFactory::MakeMeteorCastAction(
+        const GameStateW &gameState,
+        const vector<UnitId> &actors) const -> ActionSPtr {
+    return std::make_shared<MeteorCastAction>(gameState, actors, settings);
 }
 
 }  // namespace shardok

src/main/cpp/net/eagle0/shardok/library/action_factories/MeteorCastActionFactory.hpp

@@ -21,7 +21,9 @@ private:
 public:
     explicit MeteorCastActionFactory(const SettingsGetter &getter);
 
-    [[nodiscard]] auto MakeMeteorCastAction(const vector<UnitId> &actors) const -> ActionSPtr;
+    [[nodiscard]] auto MakeMeteorCastAction(
+            const GameStateW &gameState,
+            const vector<UnitId> &actors) const -> ActionSPtr;
 };
 }  // namespace shardok
 

src/main/cpp/net/eagle0/shardok/library/action_result_applier/ActionResultApplier.cpp

@@ -305,7 +305,6 @@ void MutatingApplyResult(
 
     for (const auto &changedUnitBytes : result.changed_units_fb()) {
         const Unit *changedUnit = (Unit *)changedUnitBytes.data();
-
         if (changedUnit->battalion().type() ==
                     net::eagle0::shardok::storage::fb::BattalionTypeId_UNDEAD &&
             changedUnit->battalion().morale() != 50.0) {

src/main/cpp/net/eagle0/shardok/library/actions/MeteorCastAction.cpp

@@ -154,12 +154,12 @@ auto MeteorTileDamageAction::InternalExecute(
 }
 
 auto MeteorCastAction::InternalExecute(
-        const GameStateW &currentState,
+        const GameStateW & /*currentState*/,
         const std::shared_ptr<RandomGenerator> &generator) const -> vector<ActionResultProto> {
     vector<ActionResultProto> allResults{};
-    auto runningGameState = currentState;
+    auto runningGameState = startingGameState;
     for (const UnitId &actorId : actorIds) {
-        const Unit *actorBefore = currentState->units()->Get(actorId);
+        const Unit *actorBefore = startingGameState->units()->Get(actorId);
         runningGameState =
                 PerformOneActorCast(allResults, actorBefore, runningGameState, generator);
     }
@@ -183,14 +183,15 @@ auto MeteorCastAction::PerformOneActorCast(
     results.push_back(mainResult);
 
     const Coords target = actorBefore->attached_hero().profession_info().cast_target();
-    if (const Unit *possibleOccupant = runningGameState.GetOccupant(target)) {
-        // Direct damage action - fetch terrain before it might be invalidated
-        const Terrain *targetTerrainForDamage = GetTerrain(runningGameState->hex_map(), target);
+    const Unit *possibleOccupant = runningGameState.GetOccupant(target);
+    const Terrain *targetTerrain = GetTerrain(startingGameState->hex_map(), target);
+    if (possibleOccupant) {
+        // Direct damage action
         MeteorUnitDamageAction unitDamageAction(
                 settings,
                 possibleOccupant,
                 actorIntelligence,
-                *targetTerrainForDamage,
+                *targetTerrain,
                 MeteorBaseDamage(),
                 1.0);
 
@@ -204,8 +205,6 @@ auto MeteorCastAction::PerformOneActorCast(
                 std::end(directDamageResults));
     }
 
-    // Re-fetch terrain from current state (may have been invalidated by ApplyResults)
-    const Terrain *targetTerrain = GetTerrain(runningGameState->hex_map(), target);
     CoordsSet destroyedBridgeOrIceTiles(runningGameState->hex_map());
     auto weatherPropensity = settings.GetFirePropensityByWeatherConditions(
             runningGameState->weather()->conditions());
@@ -247,16 +246,15 @@ auto MeteorCastAction::PerformOneActorCast(
     const CoordsSet adjacentCoords =
             HexMapUtils::GetAdjacentCoords(runningGameState->hex_map(), target);
     for (const Coords &splashCoords : adjacentCoords) {
+        const auto &splashTerrain = GetTerrain(runningGameState->hex_map(), splashCoords);
+
         const Unit *splashOccupant = runningGameState.GetOccupant(splashCoords);
         if (splashOccupant) {
-            // Fetch terrain before it might be invalidated by ApplyResults
-            const auto *splashTerrainForDamage =
-                    GetTerrain(runningGameState->hex_map(), splashCoords);
             MeteorUnitDamageAction splashUnitDamageAction(
                     settings,
                     splashOccupant,
                     actorIntelligence,
-                    *splashTerrainForDamage,
+                    *splashTerrain,
                     MeteorBaseDamage(),
                     MeteorSplashFactor());
 
@@ -270,9 +268,6 @@ auto MeteorCastAction::PerformOneActorCast(
                     std::end(splashDamageResults));
         }
 
-        // Re-fetch terrain from current state (may have been invalidated by ApplyResults)
-        const auto *splashTerrain = GetTerrain(runningGameState->hex_map(), splashCoords);
-
         PercentileRollOdds splashFireOdds = MakeOdds(
                 MeteorSplashFireBaseChance(),
                 PropensityByTerrain(splashTerrain, settings),

src/main/cpp/net/eagle0/shardok/library/actions/MeteorCastAction.hpp

@@ -34,6 +34,7 @@ private:
             -> vector<ActionResult> override;
 
     const vector<UnitId> actorIds;
+    const GameStateW startingGameState;
     const SettingsGetter settings;
     [[nodiscard]] auto MeteorBaseDamage() const -> double {
         return settings.Backing().meteor_base_damage();
@@ -65,8 +66,9 @@ private:
     }
 
 public:
-    MeteorCastAction(vector<UnitId> actors, const SettingsGetter& settings)
+    MeteorCastAction(GameStateW gameState, vector<UnitId> actors, const SettingsGetter& settings)
         : actorIds(std::move(actors)),
+          startingGameState(std::move(gameState)),
           settings(settings){};
 };
 }  // namespace shardok

src/main/cpp/net/eagle0/shardok/library/actions/PlaceHiddenUnitCommand.hpp

@@ -45,10 +45,6 @@ public:
     }
 
     auto GetCommandProto() const -> CommandProto override;
-
-    [[nodiscard]] int GetActorUnitId() const override { return actorId; }
-    [[nodiscard]] MapIndex GetTargetRow() const override { return target.row(); }
-    [[nodiscard]] MapIndex GetTargetColumn() const override { return target.column(); }
 };
 }  // namespace shardok
 

src/main/cpp/net/eagle0/shardok/library/actions/PlaceUnitCommand.hpp

@@ -38,10 +38,6 @@ public:
     }
 
     [[nodiscard]] auto GetCommandProto() const -> CommandProto override;
-
-    [[nodiscard]] int GetActorUnitId() const override { return actor->unit_id(); }
-    [[nodiscard]] MapIndex GetTargetRow() const override { return target.row(); }
-    [[nodiscard]] MapIndex GetTargetColumn() const override { return target.column(); }
 };
 }  // namespace shardok
 

src/main/cpp/net/eagle0/shardok/library/command_factories/MoveCommandFactory.cpp

@@ -53,8 +53,7 @@ auto AdjacentMoveDestinations(
         const Units *units,
         const HexMap *hexMap,
         const SettingsGetter &settings,
-        const vector<PlayerId> &allyPids,
-        const vector<const Unit *> &occupants) -> vector<AccumulatedMoveInfo>;
+        const vector<PlayerId> &allyPids) -> vector<AccumulatedMoveInfo>;
 
 auto ConstructMoveDestinations(
         const Units *units,
@@ -62,8 +61,7 @@ auto ConstructMoveDestinations(
         const Unit *movingUnit,
         ActionPoints startingActionPoints,
         const HexMap *hexMap,
-        const SettingsGetter &settings,
-        const CoordsSet &zocCoords) -> vector<AccumulatedMoveInfo>;
+        const SettingsGetter &settings) -> vector<AccumulatedMoveInfo>;
 
 void MoveCommandFactory::AddAvailableMoveCommands(
         CommandList &existingCommands,
@@ -80,28 +78,28 @@ void MoveCommandFactory::AddAvailableMoveCommands(
 
     const auto playerId = movingUnit->player_id();
 
-    auto zocCoords = TilesInEnemyZoc(settings, playerId, units, hexMap, allyPids);
-
     const auto destinations = ConstructMoveDestinations(
             units,
             allyPids,
             movingUnit,
             remainingActionPoints,
             hexMap,
-            settings,
-            zocCoords);
+            settings);
 
     existingCommands.reserve(existingCommands.size() + destinations.size());
 
+    auto zocCoords = TilesInEnemyZoc(settings, playerId, units, hexMap, allyPids);
+
     // Create commands
     for (const auto &destInfo : destinations) {
         auto cmd = std::make_shared<MoveCommand>(
                 destInfo.pointCost,
-                movingUnit->player_id(),
-                movingUnit->unit_id(),
+                movingUnit,
                 settings,
                 destInfo.targets,
+                units,
                 allyPids,
+                hexMap,
                 destInfo.willUnhide,
                 zocCoords);
 
@@ -126,25 +124,12 @@ auto UnoccupiedAdjacentCoords(
         const PlayerId playerId,
         const HexMap *hexMap,
         const Coords &from,
-        const vector<PlayerId> &allyPids,
-        const vector<const Unit *> &occupants) -> CoordsSet {
+        const Units *units,
+        const vector<PlayerId> &allyPids) -> CoordsSet {
     CoordsSet toReturn(hexMap);
-    const int columnCount = hexMap->column_count();
     for (const auto &adjacentTile : HexMapUtils::GetAdjacentCoords(hexMap, from)) {
-        // Use spatial index for O(1) lookup instead of O(N) linear search
-        const int index = adjacentTile.row() * columnCount + adjacentTile.column();
-        const auto *occupant = occupants[index];
-
-        // Check if tile is occupied by a known unit
-        bool isOccupied = false;
-        if (occupant) {
-            if (occupant->player_id() == playerId ||
-                std::ranges::contains(allyPids, occupant->player_id()) || !occupant->hidden()) {
-                isOccupied = true;
-            }
-        }
-
-        if (!isOccupied) { toReturn.Add(adjacentTile); }
+        const auto *occupant = KnownOccupant(playerId, units, allyPids, adjacentTile);
+        if (!occupant) { toReturn.Add(adjacentTile); }
     }
     return toReturn;
 }
@@ -154,19 +139,18 @@ auto AdjacentMoveDestinations(
         const Unit *movingUnit,
         const ActionPoints remainingActionPoints,
         const bool inEnemyZoc,
-        const Units * /* units */,
+        const Units *units,
         const HexMap *hexMap,
         const SettingsGetter &settings,
-        const vector<PlayerId> &allyPids,
-        const vector<const Unit *> &occupants) -> vector<AccumulatedMoveInfo> {
+        const vector<PlayerId> &allyPids) -> vector<AccumulatedMoveInfo> {
     vector<AccumulatedMoveInfo> validDestinations{};
 
     const auto nextCandidates = UnoccupiedAdjacentCoords(
             movingUnit->player_id(),
             hexMap,
             baseInfo.endLocation,
-            allyPids,
-            occupants);
+            units,
+            allyPids);
 
     validDestinations.reserve(nextCandidates.size());
     for (const auto &candidate : nextCandidates) {
@@ -199,27 +183,22 @@ auto ConstructMoveDestinations(
         const Unit *movingUnit,
         const ActionPoints startingActionPoints,
         const HexMap *hexMap,
-        const SettingsGetter &settings,
-        const CoordsSet &zocCoords) -> vector<AccumulatedMoveInfo> {
+        const SettingsGetter &settings) -> vector<AccumulatedMoveInfo> {
     const Coords &startingLocation = movingUnit->location();
 
     if (startingActionPoints == 0) { return {}; }
 
-    // Build spatial index once for O(1) occupancy lookups
-    const auto occupants = Occupants(*units, hexMap->row_count(), hexMap->column_count());
-
     std::vector<AccumulatedMoveInfo> allAmis{};
     CoordsSet checkedDestinations(hexMap);
     checkedDestinations.Add(startingLocation);
     const AccumulatedMoveInfo baseInfo(startingLocation, startingLocation, 0, false, {});
 
+    const auto zocCoords =
+            TilesInEnemyZoc(settings, movingUnit->player_id(), units, hexMap, allyPids);
+
     const bool inEnemyZoc = zocCoords.Contains(startingLocation);
 
-    // Use priority queue for efficient min-heap operations
-    std::priority_queue<AccumulatedMoveInfo, vector<AccumulatedMoveInfo>, std::greater<>>
-            uncheckedDestinations;
-
-    auto initialDestinations = AdjacentMoveDestinations(
+    auto uncheckedDestinations = AdjacentMoveDestinations(
             baseInfo,
             movingUnit,
             startingActionPoints,
@@ -227,22 +206,25 @@ auto ConstructMoveDestinations(
             units,
             hexMap,
             settings,
-            allyPids,
-            occupants);
-    for (auto &dest : initialDestinations) { uncheckedDestinations.push(std::move(dest)); }
+            allyPids);
 
     while (!uncheckedDestinations.empty()) {
-        auto current = uncheckedDestinations.top();
-        uncheckedDestinations.pop();
+        // Sort descending by point cost so we can pop the end for the cheapest one
+        std::sort(
+                std::begin(uncheckedDestinations),
+                std::end(uncheckedDestinations),
+                std::greater<>());
+        auto last = uncheckedDestinations.back();
+        uncheckedDestinations.pop_back();
 
-        const auto endCoords = current.endLocation;
+        const auto endCoords = last.endLocation;
         // Check to see if we've tried this destination; since we're doing cheapest first, we know
         // another one would be more expensive
         if (checkedDestinations.Contains(endCoords)) { continue; }
 
         checkedDestinations.Add(endCoords);
-        allAmis.push_back(current);
-        const auto remainingActionPoints = startingActionPoints - current.pointCost;
+        allAmis.push_back(last);
+        const auto remainingActionPoints = startingActionPoints - last.pointCost;
         if (remainingActionPoints == 0) {
             // All the remaining ones are more expensive, but we'll just continue through the loop
             // for now
@@ -251,16 +233,18 @@ auto ConstructMoveDestinations(
 
         const bool newInEnemyZoc = zocCoords.Contains(endCoords);
         auto newUnchecked = AdjacentMoveDestinations(
-                current,
+                last,
                 movingUnit,
                 remainingActionPoints,
                 newInEnemyZoc,
                 units,
                 hexMap,
                 settings,
-                allyPids,
-                occupants);
-        for (auto &dest : newUnchecked) { uncheckedDestinations.push(std::move(dest)); }
+                allyPids);
+        uncheckedDestinations.insert(
+                std::end(uncheckedDestinations),
+                std::begin(newUnchecked),
+                std::end(newUnchecked));
     }
 
     return allAmis;

src/main/cpp/net/eagle0/shardok/library/command_factories/StartFireCommandFactory.cpp

@@ -15,13 +15,7 @@ auto StartFireCommandFactory::MakeStartFireCommand(
         const Coords &coords,
         const Terrain &targetTerrain,
         const PercentileRollOdds &odds) const -> shardok::CommandSPtr {
-    return std::make_shared<StartFireCommand>(
-            settings,
-            unit->player_id(),
-            unit->unit_id(),
-            coords,
-            targetTerrain,
-            odds);
+    return std::make_shared<StartFireCommand>(settings, unit, coords, targetTerrain, odds);
 }
 
 StartFireCommandFactory::StartFireCommandFactory(const shardok::SettingsGetter &getter)

src/main/cpp/net/eagle0/shardok/library/commands/ArcheryCommand.hpp

@@ -53,10 +53,6 @@ public:
     auto CanUseClientRoll() const -> bool override { return true; }
 
     auto GetCommandProto() const -> CommandProto override;
-
-    [[nodiscard]] int GetActorUnitId() const override { return attackerId; }
-    [[nodiscard]] MapIndex GetTargetRow() const override { return defenderLocation.row(); }
-    [[nodiscard]] MapIndex GetTargetColumn() const override { return defenderLocation.column(); }
 };
 }  // namespace shardok
 

src/main/cpp/net/eagle0/shardok/library/commands/BUILD.bazel

@@ -31,7 +31,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:defensive_ambush_action",
         "//src/main/cpp/net/eagle0/shardok/library/map:coordinates",
@@ -50,7 +49,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/map:tile_modifier_with_coords",
@@ -72,7 +70,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/util:combat_utils",
         "//src/main/cpp/net/eagle0/shardok/library/util:hex_map_utils",
@@ -177,7 +174,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/map:tile_modifier_with_coords",
@@ -199,7 +195,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:percentile_roll_odds",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/fb_helpers:flatbuffer_wrapper",
@@ -219,7 +214,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/unit",
         "//src/main/cpp/net/eagle0/shardok/library/util:action_result_flatbuffer_helpers",
@@ -237,7 +231,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/actions:undead_frozen_action",
@@ -261,7 +254,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:percentile_roll_odds",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/util:action_result_flatbuffer_helpers",
@@ -279,7 +271,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/action_result_applier",
         "//src/main/cpp/net/eagle0/shardok/library/map:coordinates",
@@ -329,7 +320,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/map:coordinates",
@@ -352,7 +342,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/fb_helpers:terrain_helpers",
         "//src/main/cpp/net/eagle0/shardok/library/util:combat_utils",
@@ -372,7 +361,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
@@ -393,7 +381,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/map:coords_set",
@@ -415,7 +402,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/map:coordinates",
@@ -458,7 +444,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/settings:game_settings",
@@ -480,7 +465,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/map:tile_modifier_with_coords",
@@ -503,7 +487,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/map:coordinates",
         "//src/main/cpp/net/eagle0/shardok/library/unit",
@@ -540,7 +523,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/map:tile_modifier_with_coords",
@@ -561,7 +543,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/util:action_result_flatbuffer_helpers",
     ],
@@ -578,7 +559,6 @@ cc_library(
         "//src/test/cpp/net/eagle0/shardok/library:__subpackages__",
     ],
     deps = [
-        "//src/main/cpp/net/eagle0/shardok/library:action_cost",
         "//src/main/cpp/net/eagle0/shardok/library:shardok_command",
         "//src/main/cpp/net/eagle0/shardok/library/actions:action_requires_hero_exception",
         "//src/main/cpp/net/eagle0/shardok/library/map:coordinates",